© 2009-2010 Samuel Lidén Borell.
This document may be distributed and/or modified freely.
Last updated: 2010-11-23 (minor mobile adaption update 2020-11-17)
Document version: $Id: 5a453288f0d42bb754ec9feee86b7d3129a9f7b7 $
This is the Javascript API used by FriBID. It's intended to be bug compatible with the API of BankID Säkerhetsprogram and Nexus Personal. That is, this specification should match the behavior of the official software exactly, even if the behavior seems incorrect or is unwanted.
Many "exceptional cases" like when functions are given incorrect input haven't been tested with the official software, so FriBID might behave differently in these cases.
The Javascript API works by making function calls on <object>
elements. There are a few different kinds of object elements that can be used:
| Description | MIME Types |
|---|---|
| Version | application/x-personal-version |
| Authentication | application/x-personal-authentication |
| Signing | application/x-personal-signer2 |
The official software implements a few more types of objects, but this documentation doesn't cover these.
These three types are either non-interactive, or use separate windows to
interact with the user, so the <object> elements should
be invisible. This can be acheived by setting the with and height attributes
to zero:
<object id="signerPlugin" type="application/x-personal-signer2" width="0" height="0"></object>
A version object can be used to obtain the versions of various components of the client,
as well as a best before date. This information is stored as a string, in a format
that resembles HTTP query strings: The string consists of key-value pairs separated by
ampersands &. The key and value is separated with an equals sign
=. No space characters occur in the version string, and it's always terminated
with an ampersand.
The best before date is stored as an UNIX timestamp, and specifies when the client software expires. The client software connects to a server 14 days before it's expiry, and checks whether it can be used for another 30 days.
The format of the version string doesn't seem to account for multiple implementations. FriBID sends the same version string as the Linux version of Nexus Personal for maximum compatibility.
This method returns the version string of the client. The following version string is sent by FriBID (line breaks have been added to make it easier to read, the actual string is just one long line):
Personal=4.10.2.16&
libtokenapi_so=4.10.2.16&
libBranding_so=4.10.2.16&
libCardSetec_so=4.10.2.16&
libCardPrisma_so=4.10.2.16&
libCardSiemens_so=4.10.2.16&
libplugins_so=4.10.2.16&
libP11_so=4.10.2.16&
libai_so=4.10.2.16&
personal_bin=4.10.2.16&
platform=linux&
distribution=ubuntu&
os_version=8.04&
best_before=expiry timestamp&
An authentication object is used to show a dialog window where the user can select an identity. The identity, which may be protected with a password, is then used to sign a nonce value provided by the server, and pass the signature back to the server.
Signing objects work much like Authentication objects, but let's the server supply a message that will be signed in addition to the nonce and the other parameters that are signed.
To use these objects, set the necessary parameters with the SetParem
method. Then call PerformAction and get the signature with
GetParam("Signature").
This method returns a parameter. If the parameter doesn't exist,
then null is returned, and the error code is set to 8004.
| Parameter | Context | In/Out | Required | Encoding | Description |
|---|---|---|---|---|---|
Challenge | Authentication | In | Required | Base64 | The nonce value to include in the signed data |
Nonce | Signing | In | Required | Base64 | The nonce value to include in the signed data (same as above) |
ServerTime | Both | In | Optional | Integer | A positive 32-bit, 10-digit integer that's included in the signature. |
Policys (sic) | Both | In | Optional | Base64 | Semicolon-separated list with OIDs of the root CAs that are accepted |
Subjects | Both | In | Optional | Base64 | A name=value pair with an OID and a OID value. It's used to limit the identities that can be selected. |
TextToBeSigned | Signing | In | Required | Base64 | Text to be signed. It's displayed to the user |
NonVisibleData | Signing | In | Optional | Base64 | Additional information to include in the signed data. It's invisible, so it works just like the nonce value. |
Signature | Both | Out | - | Base64 | A digital signature |
This method sets a parameter. An error code, or zero if the action succeeded, is returned. The error code can also be retreived with the GetLastError() method
If the parameter name is unknown then the error code is 8004 returned. The parameter name and value must be strings. FriBID sets a limit of 10 MiB on the value when stored in the UTF-8 encoding.
This method performs an action identified by the name paremter. An error code, or zero if the action succeeded, is returned. The error code can also be retreived with the GetLastError() method.
The authentication and signing objects, support the Authenticate
and Sign actions, respectively.
The error code is set to 8008 if an invalid action name is passed to this function, or 8016 if a required parameter is unset.
Note: PerformAction can only be used when the web site is served using the HTTPS protocol. FriBID checks the URL of the window or tab that contains the object, and returns non-zero and sets the error code to 8015 if it doesn't start with "https://".
This method returns zero if no error occurred, or a non-zero error code. FriBID uses the value 1 for internal errors, or when no known error code is appropriate. The following error codes are common to FriBID and the official software:
| Error code | Meaning |
|---|---|
| 0 | No error |
| 8002 | The user cancelled the operation |
| 8004 | An invalid parameter name was passed to GetParam or SetParam |
| 8008 | An invalid action name was passed to PerformAction |
| 8014 | Invalid parameter value |
| 8015 | The HTTPS protocol must be used |
| 8016 | A parameter is missing |
| 8018 | Parameter value too large |