This is an old version. The latest version is on the Wiki (in Swedish only). Continue.

FriBID: Javascript API

© 2009-2010 Samuel Lidén Borell.
This document may be distributed and/or modified freely.

Last updated: 2010-11-23
Document version: $Id: e8177a23b3dad7e1f6a9ff078dad4df16fc5fa85 $

Introduction

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.

Object elements

The Javascript API works by making function calls on <object> elements. There are a few different kinds of object elements that can be used:

DescriptionMIME Types
Versionapplication/x-personal-version
Authenticationapplication/x-personal-authentication
Signingapplication/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>

Version objects

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.

GetVersion()

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&

Authentication and Signing objects

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").

GetParam(name)

This method returns a parameter. If the parameter doesn't exist, then null is returned, and the error code is set to 8004.

ParameterContextIn/OutRequiredEncodingDescription
ChallengeAuthenticationInRequiredBase64The nonce value to include in the signed data
NonceSigningInRequiredBase64The nonce value to include in the signed data (same as above)
ServerTimeBothInOptionalIntegerA positive 32-bit, 10-digit integer that's included in the signature.
Policys (sic)BothInOptionalBase64Semicolon-separated list with OIDs of the root CAs that are accepted
SubjectsBothInOptionalBase64A name=value pair with an OID and a OID value. It's used to limit the identities that can be selected.
TextToBeSignedSigningInRequiredBase64Text to be signed. It's displayed to the user
NonVisibleDataSigningInOptionalBase64Additional information to include in the signed data. It's invisible, so it works just like the nonce value.
SignatureBothOut-Base64A digital signature

SetParam(name, value)

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.

PerformAction(name)

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://".

GetLastError()

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 codeMeaning
0No error
8002The user cancelled the operation
8004An invalid parameter name was passed to GetParam or SetParam
8008An invalid action name was passed to PerformAction
8014Invalid parameter value
8015The HTTPS protocol must be used
8016A parameter is missing
8018Parameter value too large