This section discusses the context and the environment in which the BankID components are to be used.

Implementation overview

When implementing BankID in a merchant application the developer needs to integrate the existing merchant application, the BankID client interface and the BankID server interface. The figure below illustrates how the merchant BankID implementation relates to each other.
The code needed for this integration is illustrated as the BankID integration implementation in the figure below and is described in subsequent chapters in this document.

The use of BankID can be broken down into different steps. The next two chapters illustrate the different steps/tasks the merchant application needs to perform.

BankID on Mobile

Configuration and initialisation

Below is a list of the required tasks along with a reference to the applicable chapters that describe how to do the actual implementation.

Step 1: Configure the BankID server
Please refer to:

this document, 3.2.4.1 BankID server features
[ICSRV], 4. Configuration of BankID C server
[IJSRV], 3.1 Configuration of BankID J server

Step 2: Initialise the BankID server
Please refer to:

[ICSRV], 5.1 Application start-up code
[IJSRV], 4.1 Application start-up code

Authentication and Signing

Figure 12 below shows the tasks with a reference to the applicable chapters that describes how to do the actual implementation.

The end-user triggers a BankID on Mobile authentication or signing operation on the merchant web-page. The end-user is asked to enter mobile phone number and birthdate. The required GUI for a web-based sign operation is shown below.
NOTE: The GUI referred to below is only applicable to web-based services. For SMS-based services special rules apply. Please see "BankAxess; Regler for brukerdialoger", requirement M3.

M3

Kundens BankID brukernavn

For web-applikasjoner mv. skal Kunden alltid oppgi hele sitt BankID på mobil brukernavn, dvs mobilnummer og fødselsdato. For SMS-initierte applikasjoner er det ikke nødvendig å be Kunden oppgi sitt brukernavn hvis Kundens mobilnummer fremgår fra innledende dialog (Trinn 0).

A BankAxess operation is a variant of the sign operation and have similar dialogs. The operation identifier when invoking requestMobileAction is 'netPay'.

In case of authentication, two random words must be generated using the BankID server. These words are shown to the end-user as shown below.

The BankID server is used to start the transaction towards the end-users mobile phone via the BankID COI Mobile Gateway. The merchant may choose between synchronous and asynchronous operation. For details on the different modes of operation, see 3.4.4 Asynchronous communication and 3.2.3 Error handling.

The Mobile GW sends an initAuth or initSign message depending on the operation, to the merchant as shown below.


Parameter			Value	Value
Main	Decrypted	Inner	Value	Value
operation			initAuth	initSign
encKey			The base 64 encoded baseKey received from the Mobile GW to derive the sessionKey
encData			The base 64 encoded encrypted data received from the client
	clientChallenge		Mobile GW generated challenge. Used by the Mobile GW to authenticate the merchant.
	carrier		mobile
encAuth			A base64 encoded message authentication code over the rest of the main parameters
sid			Merchant specific session id
For further details see 3.4.1 Mobile parameters and values

The merchant application needs to perform the following actions:

Read the request parameters from the request object.
Create a session object.

Due to limitations in SIM Toolkit on mobile phones BankID Server has to filter and prepare the "text to sign" before sending it to the mobile phone. The following ASCII input characters are accepted;

[0-9] [a-z] [æ] [ø] [å] [A-Z] [Æ] [Ø] [Å] [CR] [LF] [#] [$] [%-&][(-?] [@]
[¡] [£] [¤] [¥] [§] [¿] [Ä] [Ç] [É] [Ñ] [Ö] [Ü] [ß] [à] [ä] [è] [é] [ì] [ñ] [ò] [ö] [ù]

To make the text compliant with GSM 03.38 characters outside the accepted ones will be deleted from the "text to sign" before it is sent to the mobile phone.

The theoretical limit for text to be signed in a SMS is 160 characters. Experiences at Telenor show that the recommended length is 120 characters. Two characters are reserved for the telecom operators, so in reality the maximum length of the text to be signed is 118 characters. The merchant name is limited in the RA interface to a maximum of 80 characters which leaves 38 characters to general text and random challenge value. Any characters beyond this limit will be trimmed by BankID Server. Note that the only supported MIME-type is text/plain.

The signed data bytes can be retrieved from the session object.

To complete the sequence the merchant must

Call the BankID server function InitTransaction, passing the session object as a parameter.
Store the session object returned by the function call.
Send the response from InitTransaction to the Mobile GW.

Parameter			Value	Value

Main	Decrypted	Inner	Value	Value
encData			The base 64 encoded encrypted data returned to the client
	serverChallenge		BankID server generated challenge. Used by the merchant to authenticate the Mobile GW.
	data			Data to be signed. Used during signing by both the Mobile GW and merchant.
	pkcs7		Merchant signature over the clientChallenge	Merchant signature over the data to be signed
	bssChannel
	bssChannelSignature		Merchant signature over the bssChannel
encAuth			A base64 encoded message authentication code over the encData parameter
For further details see 3.4.1 Mobile parameters and values

The mobile GW contacts the correct MNO and the enduser is requested to enter a PIN code to sign the text shown on the display.

The resulting client signature is returned to the merchant application in a request object along with, in case of a signing operation, a merchant certificate status instance (OCSP response).

Parameter			Value	Value

Main	Decrypted	Inner	Value	Value
operation			verifyAuth	verifySign
encKey			The base 64 encoded baseKey received from the client to derive the sessionKey
encData			The base 64 encoded encrypted data received from the client
	pkcs7		End-user signature over the serverChallenge	End-user signature over the data to be signed
	carrier		mobile
encAuth			A base64 encoded message authentication code over the rest of the main parameters
sid			Merchant specific session id
For further details see 3.4.1 Mobile parameters and values

The merchant application then needs to:

Read the request parameters from the request object.
Retrieve the stored session object.
Call the BankID server function VerifyTransactionRequest, passing the sessionObject as a parameter.

The merchant application then needs to continue with the following actions to authenticate the client:

Merchant application specific business logic to update internal state as needed.
Merchant application specific business logic updates e.g. associate the end-user with the customer database.

Finally the merchant application must:

Call the function VerifyTransactionResponse, passing the session object as a parameter.
Perform business logic updates.
Return the data from VerifyTransactionResponse back to the BankID Client.

Parameter			Value	Value

Main	Decrypted	Inner	Value	Value
encData			The base 64 encoded encrypted data returned to the client
	nextURL		Ignored
	vaPerf		The time, in milliseconds, the BankID server used to retrieve the certificate status from VA.
	errCode		If something fails
encAuth			A base64 encoded message authentication code over the encData parameter
For further details see 3.4.1 Mobile parameters and values

In case of a successful sign operation the merchant must show a confirmation dialog to the end-user as shown below.

For further details regarding authentication, please refer to:

[ICSRV], 5.4 Authentication process
[IJSRV], 4.2.1 Authentication process

Error handling

Should an error occur on the Mobile GW, the resulting error handling will depend on whether the merchant has invoked the operation synchronously or asynchronously. In the case of synchronous operations, the invocation of requestMobileAction will be terminated, and an error code will be returned to be handled by the merchant's BankID server implementation.

If, on the other hand, requestMobileAction was invoked asynchronously, the error reporting mechanisms are a little more complex. Errors caught during invocation validation are handled the same way as a synchronous invocation. If an error occurs during the subsequent processing, the Mobile GW will send a handleError operation to the merchant. The encrypted content transmitted to the server component is 'operation=handleError&errCode=<errorCode>'. The handleError operation is handled through the use of the BankID server mechanisms verifyTransactionRequest and verifyTransactionResponse, and the resulting response (which will contain the error code) should be returned to the Mobile GW as a confirmation. The web application may then want to redirect the end-user to another web page displaying relevant information, as the processing of the asynchronous requestMobileAction invocation is terminated.

BankID Server will encrypt the reply to the Mobile GW when processing a handleError request. If decryption fails for any reason, the merchant should reply with an unencrypted error message.

If the Mobile GW is unable to initiate communication with the merchant endpoint URL, merchants using asynchronous operation will not receive error notifications. It is therefore strongly suggested that merchants use synchronous operation until successful operation and communication has been verified.

Should an error occur on the merchant side, the BankID server must return errCode=<errorCode> in its response to the Mobile GW.

An error may occur at any time during Mobile GW to server callback communication. This message will therefore also apply to the previous sequence diagrams.

Features

This chapter describes the features available to the merchant.

BankID server features

BankID control and filtering

A merchant application may specify the types of BankIDs that it accepts. A company specific application may only accept Employee certificates and a public government site may only accept Person certificate. This is done using the concept of Policy OIDs. The merchant can achieve this control and filtering by specifying a single or a list of Policy OIDs that are compatible with the application using features in the BankID server.

Note that the certType parameters used in requestMobileAction is configured in BankID server.

For further details please refer to:

this document, 1.1.1 Mobile parameters and values
[ICSRV], 4. Configuration of BankID C server
[IJSRV], 3.1 Configuration of BankID J server

Associating the end-user with the customer database

Each BankID end-user has a unique identifier in the certificates. This identifier is unique within BankID and uniquely identifies a physical person. Each person may however have more than one unique identifier, depending on whether it is a Personal BankID or Employee BankID.

The unique identifier can not be transferred once associated to a person. The unique identifier (UniqueID) can be extracted from the end-user certificate using available BankID server functionality.

Merchants that are authorized to retrieve SSN as additional information from the VA, may do so.

Only the SSN or the UniqueID shall be used to identify the end-user.

For further details please refer to:

[ICSRV], 6.1.15 BID_GetInfoItem (for retrieving the uniqueID from certificate)5.9 Retrieving additional information from VA (for retrieving SSN from VA)
[IJSRV], 5.2.12 getCertificateInfo (for retrieving the uniqueID from certificate)4.2.5Retrieve additional information from VA

BankID Client parameters and values

Key	Description	Values	Value set by	Mobile
action		"auth" (Default) for Authentication "sign" for Signing "netPay" for BankAxess	Merchant	🗸
locale		"Norwegian" (Default) "English"	Merchant	🗸
URL	This is the URL which the applet uses to communicate with the merchant application during authentication and signing. The URL must use SSL.	Any URL. Note that the BankID client will verify that the hostname of the URL matches the webaddress in the configuration file.	Merchant	🗸
Timeout	The time, in milliseconds, the applet will wait for a response from the merchant application.	40000 (Default)	Merchant	🗸
sid	SessionID. This is a parameter that can be used by merchant in order to keep track of sessions. If this tag parameter is specified, the applet will send this information back to the server	Any string.	Merchant	🗸
certType	Lists the BankID certificate types that the application accepts	"ALL" or a comma separated list of PolicyOIDs	Merchant through BankID server configuration	🗸
mitm	Man in the middle information	Set by BankID server	Merchant through BankID server configuration	🗸
mifv	Merchant interface version	Set by BankID server	BankID server	🗸
popInfo	A reference to the merchants public key.	Set by BankID server	BankID server	🗸
popParameters	Proof of possession information. This value contains all applet parameters that are integrity protected.	Set by BankID server	BankID server	🗸
popSignature	The merchants signature over the pop parameters (cf. popParameters) and their respective values.	Set by BankID server	BankID server	🗸
tid	A trace id	Set by BankID server	BankID server	🗸
carrier	The type of BankID. For the applet tag, this is currently always Banklagret BankID.	'NC'	Merchant	🗸
cmsFormat	The CMS (PKCS7) format to be used for the transaction. Only relevant for signing.	"PKCS7" – Default BankID format "PKCS7_ISO320001" – PadES compatible format	Merchant in initTransaction	×
ocspFormat	The OCSP response format to be used for the transaction. Only relevant for signing	"OCSP_BANKID_DEFAULT" – Default BankID format "OCSP_RFC6960_COMPATIBLE" – PadES compatible format	Merchant in initTransaction	×

Merchant application

The communication with the client is through java servlets, ASP pages or similar.

Encoding

The information passed to and from the client are URL encoded A method for converting a string into a MIME type called "x-www-form-urlencoded". key/value pairs separated with the character "&". The URL- encoding and decoding must be performed by the merchant web application, and is not part of the BankID API. The character encoding used is "ISO-8859-1".

The bulk of the data transmitted between the client and the server is encrypted. The parameters appears as encKey, encData and encAuth in packets originating from the client, and encData and encAuth in responses to the client.

The following example shows the information that is sent to and from the client during the initial phase of authentication:

Client sends:

operation=initAuth&encKey=<base64encoded string>&encData=<base64encoded string>&
encAuth=<base64encoded string>(&sid=<sid>)

The response will be:

encData=<base64encoded string>&encAuth=<base64encoded string>

or

errCode=<the error code>

Communication Parameters

The following tables describes the keys that are defined.
Note that all values must be URLencoded.

Set by merchant per transaction

Key	Format	Description	Comment
operation	String	The parameter describes the operation to perform on the merchants application. Operation values are: initAuth initSign verifyAuth verifySign handleError getAppParameters
data	Base64-encoded	Data to be signed.	Used during signing by both the client and merchant.
nextURL	String	The URL the applet redirects to after completion.	Used together with 'status=OK' or together with 'errCode=theErrCode'. Note: The URL must be HTTPS.
mimeType	String	MIME type of the data to be signed.	Used during signing.
sid	String	Session identifier	The server may change the sid at any time. The client always returns the last received sid. Note that the sid is used to identify the session for the getAppParameters callback (BankID App).
sdo	Base64-encoded	SDO XML object	Enables the end-user to save signed data.
dataDescription	String	Short description of the content of the SDO data	This info is shown in the SDO viewer, and during PDF-signing. Also used by the client when storing an SDO
userID The merchant may set the user profile by either including just the userID, or the userID and the OTP Service name. See [ICSRV] or [IJSRV] for details.	String	End-users user ID.	Used when the merchant is using user profile.
OTPService	String	OTP service name.	"_self", "_new", "_parent", "_blank", "_top"
target	String	The nextURL will be presented in the target frame if this parameter is applied.	A method in BankID server helps merchant generate the signers list.
signers	String	A comma separated list containing information, common name, signing time, and BankID type, about previous signers.

Generated by BankID server or client

Key	Format	Description	Comment
tokenType	String	"roaming"	Used by the Banklagret client in the first communication with the server component.
clientChallenge	Base64-encoded	Client generated challenge.	Used by the client to authenticate the merchant.
serverChallenge	Base64-encoded	Server generated challenge.	Used by the merchant to authenticate the client.
pkcs7	Base64-encoded	End-user or merchant signature	Used during both authentication and signing.
ocsp	Base64-encoded	OCSP response	May be used by merchant when creating an SDO. The merchant then does not have to do a VA lookup on its own certificate.
status	String	OK indicates SUCCESS; all other values will indicate FAILURE.	Result of the last operation performed on the server during an authentication or signing process.
errCode	String	Defines the error that has occurred.	Can be generated on both the server and the client.
bssChannel	String	hash of the merchant signature.	Security mechanism.
bssChannelSignature	String	Merchant signature over bssChannel	To verify that the content of bssChannel is not compromised.
signers	String	A comma separated list containing information, common name, signing time, and BankID type, about previous signers.	A method in BankID server helps merchant generate the signers list.
mifv	String	The Merchant InterFace Version	The interface version number is used to tell the Banklagret Client which interface version the (merchant) server uses.
mitm	String	The mitm parameter holds information used to verify that both the COI and the Merchant server communicates with the same client.

Communication between Mobile GW and merchant

The Mobile GW communicates with the merchant application using the HTTPS communication protocol. The Mobile GW functions very similarly to the Banklagret client, and will post information to a defined URL retrieved from the supplied URL parameter.

Mobile parameters and values

The following items are mandatory when using BID_RequestMobileAction/requestMobileAction (from this point onward jointly referred to as RequestMobileAction). The values are configured using Infoitems (C server) or MobileInfo (Java server)

Key	Description
action	The action to perform. Values are "auth", "sign" or "netPay".
URL	The merchant URL used for BankID communication
phoneNumber	The phone number
phoneAlias	The date of birth on the form ddmmyy
merchantReference	The reference to show to the user during mobile authentication process. This key is mandatory if action is "auth".

The following are optional, using the default value if not set:

Key	Description	Default value
locale	The locale, i.e.the language to be used.	no_NO
countryCode	The international dialing prefix.	47
checkAlias	Controlls if the phoneAlias should be checked in BankID COI.	True
timeout	The timeout for BankID MobileGateway when communicating with merchant URL.	40000
sid	The session ID that will be sent back during BankID communication.	Not used if not set
synchronousCommunication	Defines if the communication is performed synchronously or not.	True

Remaining configuration parameters controlling use of BankID on Mobile are derived from the BankID server configuration (e.g. certificate types allowed).

PushSMS

This BankID server operation can be used for for sending an SMS to the end user after a successful transaction.

HandleError

BankID on Mobile specific callback operation for use when an error is detected at the Merchant GW during asynchronous processing.

Asynchronous communication

The default behaviour when calling RequestMobileAction() is to be synchronous, i.e. it returns after the whole mobile and BankID communication has finished, indicating whether the operation was successful or not. By setting the parameter for synchronous communication to false before calling RequestMobileAction(), the function will be asynchronous.

When operating in asynchronous mode, RequestMobileAction() will return after an initial check in BankID COI, returning a transaction reference and a status code indicating whether the check was successful. If the status code indicates success the mobile gateway will initiate normal BankID communication.

Determining the success of the BankID and mobile communication, which is performed in another thread on the web server, must be done by some form of polling. The RequestMobileStatus() call is not currently implemented on the mobile gateway, so the web application must poll its own system to determine if the mobile BankID process was successful and complete and then proceed with the business logic of the application.

If using asynchronous communication, take care to block users whose RequestMobileAction invocation is already being processed from initiating further simultaneous invocations until the one being processed has finished.

Browser not supported