NativeMessagingAPI - open-eid/chrome-token-signing GitHub Wiki

Native Messaging API describes the extension-host JSON interface that the Chrome extension uses to communicate with the native host. This is internal for chrome-token-signing native host. See hwcrypto.js for web developer interface.

See RFC 2119 for MUST/SHOULD/MAY etc

API Interface

  • The native component:
    • Runs in loop, because
      • it maintains certificate selection binding (only user-confirmed certificate can be used for signing)
      • it checks for the same origin in all the messages after the first technically valid CERT request containing origin was sent
    • Uses origin for checking that the origin is secure
      • at least https: and file:
    • Rejects technically incorrect requests with technically correct JSON response indicating result: 'invalid_argument' together with API version and quits the process.
    • Supports messages up to 8192 bytes and rejects messages above this size on technical level
    • Supports GUI languages (at least et, en and ru). Defaults to en if language not set or not recognized
    • Supports backend selection on signing process on Windows (PKCS#11 vs CAPI) with forcePkcs11 and pkcs11ModulePath options.
  • The request:
    • MUST contain type
    • MUST contain nonce
    • MUST contain origin
    • MAY include other fields, not specified here
  • The response:
    • Has a result field (See: error handling)
    • Contains nonce (value from request echoed in response) if request contains it
    • Contains api version (this specification, echoed in response)
  • The logic:
    • VERSION message is always available without secure origin checks
    • Missing PKCS#11 module (or failure to C_Initialize) specified one results in "technical_error" error for operations that require PKCS#11 (SIGN and CERT)
    • Both PKCS#11 and GUI are initialized on demand (VERSION command succeeds in headless mode and PKCS#11 module is not listed before CERT command is received)

VERSION message

  • Request
  • MUST have type == "VERSION" (and origin and nonce)
  • Example: {"type": "VERSION", "nonce": "04jscvu39bm6vfju", "src": "page.js", "origin": "https://open-eid.github.io", "tab": 6}
  • Response
  • Has version (string in x.y.z format)
  • Example: {"api": 1, "nonce": "04jscvu39bm6vfju", "result": "ok", "version": "1.0.0.0" }

CERT message

  • Request
  • MUST have type == "CERT" (and origin and nonce)
  • MUST have lang
  • Example: {"type": "CERT", "lang": "en", "nonce": "lt3anao0u54dyq4x", "src": "page.js", "origin": "https://open-eid.github.io", "tab":6}
  • Response
  • Has cert (DER encoded certificate as hex string)
  • Example: {"api": 1, "cert": "308204FD308203E5...CDF738", "nonce": "lt3anao0u54dyq4x", "result": "ok"}

SIGN message

  • Request
  • MUST have type == "SIGN" (and origin and nonce)
  • MUST have cert (DER encoded certificate as hex string)
  • MUST have hash (plain SHA1/SHA-2 hash as hex string)
  • MUST have lang
  • MAY have "forcePkcs11":true to use PKCS#11 on Windows
  • MAY have pkcs11ModulePath to specify PKCS#11 module path on Windows if "forcePkcs11":true. May be full path or module file name. Defaults to opensc-pkcs11.dll.
  • Example: {"type": "SIGN", "cert": "308204FD308203E5...CDF738", "hash": "413140d543...dd54af2", "hashtype": "SHA-256", "lang": "en", "nonce": "hqq2npwiw4wekq78", "src": "page.js", "origin": "https://open-eid.github.io", "tab": 6, "forcePkcs11": true, "pkcs11ModulePath": "C:\\Downloads\\opensc-pkcs11.dll"}
  • Response
  • Has signature (resulting signature as hex string)
  • Example: {"api": 1, "nonce": "hqq2npwiw4wekq78", "result": "ok", "signature": "562112EB88E9513...E497313A8546"}

Error handling

  • Every response has a result field. "ok" is returned with successful responses and a relevant error code string otherwise.
  • Additional informational message is included with the "message" field if the result is not "ok"

Error codes

  • technical_error in case of any technical error, e.g.
  • PKCS#11 module could not be loaded.
  • Failed to open Cert Store
  • invalid_argument if the request contains invalid arguments, e.g.
  • invalid hash value.
  • The certificate was not previously selected by the user.
  • Request origin has changed between requests.
  • Invalid message length.
  • not_allowed if the origin is not secure, e.g doesn't start with https:.
  • user_cancel if the user has cancelled the operation, e.g. has pressed cancel on PIN dialog.
  • no_certificates if no certificates were found, e.g. smart card was not inserted into reader.
  • pin_blocked if maximum number of PIN entry attempts has been reached.

GUI requirements/considerations

  • If there are no suitable certificates (because there is no card or reader attached), a GUI window is not opened and "no_certificates" status is returned.
  • If there is an "inserted card" (definition depends on backend implementation) but all certificates have expired (notAfter is in past) "no_certificates" is returned.
  • All responses are sent back to the application after the GUI has been closed (no informative "fire and forget" messages, single serialized interaction)
  • Incorrect PIN results in a repeat PIN dialog until correct pin is entered ("ok"), "pin_blocked" or "user_cancel" has happened.

Development and testing

See DeveloperTips