NativeMessagingAPI

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