Versions Compared

Version Old Version 1 New Version Current
Changes made by

Erik Larsen

S (Deactivated)

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Published by Scroll Versions from space DOC and version Kobenhavn

 

Table of Contents
absoluteUrltrue

...

Gliffy
nameBankID Web-client implementation documents overview

Figure 3 – BankID Web-client implementation documents overview 

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

...

The BankID Web-client is a single-page AJAX web application. It consists of both HTML/CSS and JavaScript. In order to execute correctly the Web-client is dependent on a set of web features, including CORS and XDM. For a detailed overview the reader is referenced to [BIOA]. 
The Web-client is designed to support initialization by three different modes:

...

  • PDF Documents To Be Signed are displayed properly
  • control is returned to the native application upon termination, if necessary.


For more details, see [IMMC]. 
Also note that the Web-client includes an option to activate the HTML5 geolocation-API for fraud detection purposes. In order for this to work properly any native apps should specifically enable support in the WebView. For more details regarding the use of WebViews see [IMMC].

Configuration and initialization of BankID Server

...

Gliffy
nameOverview of main activities for configuration an initialisation

Figure 4 – Overview of main activities for configuration and initialization 
 Step 1: Configure the BankID Server
Please refer to:

  • this document, BankID Server Features.
  • [ICSRV], 4. Configuration of BankID C server
  • [IJSRV], 3.1 Configuration of BankID J Server


 Step 2: Initialize the BankID Server
Please refer to:

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

...

CORS1 allows XMLHttpRequest requests across domains, which traditionally wouldn't be allowed under the browser's Same origin policy (SOP)2. CORS works by adding a special header to responses from a server to the client. If a response contains the Access-Control-Allow-Origin header, and if the browser supports CORS3,4, it is possible to access resources from a different domain. In order to achieve this the merchant site must allow CORS access from scripts provided from *https://csfe.bankid.no* by setting the Access-Control-Allow-Origin directive. This is true also for signing with BankID 2.1 due to the fact that the Web-client will send handleError() directly to the merchantURL in case of communication errors towards the Client proxy. See also section 
Client proxy.

...

Code Block
Access-Control-Allow-Origin: https://csfe.bankid.no
Access-Control-Allow-Credentials: true

Code example 1 – Configuration of CORS 

The merchant can make sure that the Web-client sends requests with credentials by specifying this in the initSession() request, see Table 11 for more details.

...

Anchor
_Ref380564719
_Ref380564719
Anchor
_Toc431376743
_Toc431376743
Code example 2 – CSP header 
The configuration of script-src has two possible outcomes:

...

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

Gliffy
nameOverview of main activities for authentication and signing

Figure 5 – Overview of main activities for authentication and signing 
Steps  and  in Figure 5 are shown in more detail in Figure 6. Below Figure 6 follows a textual explanation of some of the aspects that show the initialization and load process. Look for the numbered items in the diagram.

Steps  ,  and  are shown in more detail in Figure 7.

 Denotes the setting of client features, which is done at three different points in the process: initSession(), bankidhelper.init() and initTransaction(). 

Gliffy
nameOverview - Merchant BankID integration application - Flow chart

Figure 6 – Overview – Merchant BankID integration application – Flow chart
Continues in Figure 7 .  See 3.2.8 Error handling. 

 If the merchant application collects the userID it is advised that the keystroke data for the userID form are collected by using a BehavioWeb JavaScript. A tailored script to collect keyboard biometrics for the SSN1,2 is provided in the release package . See [BIDG] for a code sample. These keystroke data are subsequently sent to the client in the initTransaction() response, see Table 4.

...

Key

Description

Values

merchantURL

This is the URL which the client uses to communicate with the merchant application during authentication and signing. The URL must use SSL.

Any URL that uses SSL.

useragent

The client application connecting the web server, typically a web browser, but it can also be other programs that access web pages.

In this case a text string in a common pattern identifying the browser's make and model, among other things.

action

The action you would like to perform.

Use "auth" for Authentication, "sign" for Signing, "netPay" for BankAxess and "changepassword" for user initiated change of password via merchant.

localeId

The language to use in the client.

"nb" = Norwegian, "en" = English.

sid

The session id the merchant generates and uses to identify the session. Optional.

A unique sid as a string.

merchantFEDomain

Set to be able to verify origin on later messages across via XDM.

Any domain as a valid URL, must use SSL: "https://www.merchant.com". Must be the same domain that hosts the Helper.

Table 2 – BankID Web-client initSession() parameters
The table above only lists the required parameters. Chapter 3.4 gives a broader description of all the parameters from Table 2, and also lists and describes the parameters that are optional for the initSession() from the Merchant's point of view.

...

 

initAuth request

initSign request

Parameter

Value

Value

Main

Decrypted

Inner

operation

 

 

initAuth

initSign

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

clientChallenge

 

Client generated challenge.
Used by the client to authenticate the merchant.

 

carrier

 

"NC_BID20"

traceId

 

The traceId from this transaction in COI

encAuth

 

 

A base64 encoded message authentication code over the rest of the main parameters

sid

 

 

Merchant specific session id

For further details see 3.6.

Table 3 – InitTransaction() request – BankID Web-client
The contents of the three parameter columns are as follows:

...

initAuth response

initSign response

Parameter

Value

Value

Main

Decrypted

Inner

encData

 

 

The base 64 encoded encrypted data returned to the client

serverChallenge

 

BankID Server generated challenge. Used by the merchant to authenticate the client.

 

data

 

 

Data to be signed. Used during signing by both the client and merchant.

pkcs7

 

Merchant signature over the clientChallenge

Merchant signature over the data to be signed

bssChannel

 

Data to be forwared to COI.

 

bssChannelSignature

 

Merchant signature over the bssChannel

dataDescription

 

 

Used to identify the document in the client.

mimeType

 

 

The mimeType of the data to be signed.

extPDFURL

 

 

URL to the document to be signed. Note: Must be within the same domain as extPDFDomain, see Table 11 for more details.

nextURL

 

Optional. The URL the client may redirect to after completion. Use of callback function will have precedence over this URL. This parameter will overwrite any previous nextURL. Note: The URL must be HTTPS.

userId

 

Returned if Merchant has collected userId

userIDKeyStrokeData

 

If userId is set in response, behaviour metrics should be returned.

encAuth

 

 

A base64 encoded message authentication code over the encData parameter.

For further details see 3.6.

Table 4 – InitTransaction() response – BankID Web-client 2.0 

initAuth response

initSign response

Parameter

Value

Value

Main

Decrypted

encData

 

The base 64 encoded encrypted data returned to the client

serverChallenge

BankID Server generated challenge. Used by the merchant to authenticate the client.

 

documents

 

Used during signing by both the client and merchant. A JSON array of JSON objects.

 

 

 

 

 

 

 

Per document5

data

 

Data to be signed. May include merchant visual seal.

mimeType

 

The mimeType of the data to be signed

dataDescription

 

Used to identify the document in the client.

encoding

 

 

  
signingKind String: parallel/serial/serialEndUserOnly
byteRange 

JSON array of 4 integers:

Describes layout of data, i.e. where is the merchant seal if some

(opt) merchantSeal 

JSON object:

x,y and page for merchantSeal placement

(opt) endUserSeal 

JSON object:

x,y and page for endUserSeal placement

serialSessionInfo

  

JSON object:

Only when signing serial

noGraphic 

true or false:

Turnkey: no graphic in visual seals

timeStampServiceUrl 

url or empty:

For overriding default

serialPkcs7s

 list of merchant signatures over the data to be signed (as in coidata), for serial documents only, NODATA else.

nextMerchantOperation

 

initSignBuildEndUserSeal or initSignSignMerchantSeal:

tells next action on merchant side, dependent on turnkey or self assembling mode

merchantCert

 

JSON object:

Description of the merchant, used for building merchant sear, turnkey.

coiData

 

Data to be forwarded to COI.

Only sent when all documents to be signed are signed by merchant

coiData Content

pkcs7s

 

List of merchant signatures over the data to be signed

bssChannel

 

The BankID Server secure Channel. This will contain the list of hashes of PKCS#7. This information will be used in the OTP token.

bssChannelSignature

 

Merchant signature over the bssChannel

pkcs7

Merchant signature over the clientChallenge

 

nextURL

Optional. The URL the client may redirect to after completion. Use of callback function will have precedence over this URL. This parameter will overwrite any previous nextURL. Note: The URL must be HTTPS.

userId

Returned if Merchant has collected userID

userIDKeyStrokeData

If userID is set in response, behavior metrics should be returned.

otpService

If userID is set in response

encAuth

 

A base64 encoded message authentication code over the encData parameter.

For further details see 3.6.

Table 5 – InitTransaction() response – BankID Web-client 2.1 
The client passes the server's signature to the BankID COI for validation, and then the appropriate dialogues are shown to the end-user.

...


Continued from Figure 6.  See 3.2.8 Error handling.

Gliffy
nameOverview - Merchant BankID integration application - Flow chart pt.2

Figure 7 – Overview – Merchant BankID integration application – Flow chart
 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).

verifyAuth request

verifySign request

Parameter

Value

Value

Main

Unencrypted

Inner

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

ocsp

 

 

A merchant certificate status instance (OCSP response)

carrier

 

"NC_BID20"

traceId

 

The traceId from this transaction in COI

encAuth

 

 

A base64 encoded message authentication code over the rest of the main parameters

sid

 

 

Merchant specific session id

For further details see 3.6.

Table 6 – VerifyTransactionRequest() – BankID Web-client 2.0

verifyAuth request

verifySign request

Parameter

Value

Value

Main

Unencrypted

Inner

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

 

ocsp

 

 

Last ocsp after CS check of Merchant sign certificate for each merchant pkcs7

clientpkcs7s

 

 

Comma separated list of PKCS7s (client signatures).

rtReport

 

Blob lob of comma separated name=value pairs. Used to send information from client to merchant. See Appendix G

carrier

 

"NC_BID20"

traceId

 

The traceId from this transaction in COI

endUserSeals  

Used in turnkey mode only, holds the end user visual seals built by clientProxy.

Will be added to session data to complete PAdES up to B-B profile.

encAuth

 

 

A base64 encoded message authentication code over the rest of the main parameters

sid

 

 

Merchant specific session id

For further details see 3.6.

Table 7 – VerifyTransactionRequest() – BankID Web-client 2.1
Please note that in BankID 2.1 the verifySign() request will contain the signatures of all documents that were signed. 
The merchant application then needs to:

...

verifyAuth response

verifySign response

Parameter

Value

Value

Main

Unencrypted

Inner

encData

 

 

The base 64 encoded encrypted data returned to the client

nextURL

 

Optional. The URL the client may redirect to after completion. Use of callback function will have precedence over this URL. This parameter will overwrite any previous nextURL. Note: The URL must be HTTPS.

SDO

 

 

SDO XML object. Enables the end-user to save signed data. See text below the table. NB: Not supported in BankID 2.0/2.1.

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.6.

Table 8 – VerifyTransactionResponse() – BankID Web-client 2.0 and 2.1
An option for the end-user to save the SDO, if received, to disk or to a centrally located archive is currently not supported by the Web-client but may be available in future versions. 
For further details regarding authentication, please refer to:

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


For further details regarding signing, please refer to:

  • [ICSRV], 5.5 Signing process without SEID SDO & 5.6 Signing process with SEID SDO

  • [IJSRV], 4.2.2 Signing process without creating of SEID SDO& 4.2.3 Signing process and creation of SEID SDO

...

helperParams

Comment

Caption

Used in scenario

Mandatory

frameMode

"iframe" (default), "window"1, "redirect". Governs the browsing context of the client.

Governs the browsing context of the client.

All.

Yes

cid

Received previously in initSession() response, pka kid.

A unique clientID received previously in initSession() response.

All

Yes

callback

Function that Helper will call upon client termination. This is the preferred way of returning control to the Merchant application. See Table 10 for details.

A function that Helper will call upon client termination. If not provided the last received nextURL over a secure channel will be used to return control instead.

All

Optional

containerID

A reference to an element id in DOM where the client will be injected, see [BIDG].

A reference to an element id in DOM where the client will be injected.

If frameMode == "iframe"

Yes

height

Default set to 100%, which is the recommended height.

The height of the iframe provided to the client.

If frameMode == "iframe"

Optional

windowHeight

The desired window height in pixels. Default set to 500.

The height of the window provided to the client.

If frameMode == "window"

Optional

width

Default set to 100%, which is the recommended width.

The width of the iframe provided to the client.

If frameMode == "iframe"

Optional

windowWidth

The desired window width in pixels. Default set to 350.

The width of the window provided to the client.

If frameMode == "window"

Optional

positionX

Integer representing the left position of the window on the screen.

Integer representing the left position of the window on the screen.

If frameMode == "window"

Optional

positionY

Integer representing the top position of the window on the screen.

Integer representing the top position of the window on the screen.

If frameMode == "window"

Optional

errorRedirectUrl

Location to redirect to in case of an initialization error.

Location to redirect to in case of an initialization error if frame mode is "redirect".

If frameMode == "redirect". Note that return using callback function is not supported in this instance.

Yes

sessionCookie

New 2.1 parameter. Specifies whether a session cookie is used. Object must have a name attribute, and optionally a value attribute. Is not used during frameMode redirect, see [BIDG], and text about withCredentials below Table 11. The cookie is sent inside encData from the Web-client to the Client proxy.

Specifies whether a session cookie is used. Object must have a name attribute, and optionally a value attribute.

Signing transactions in 2.1, not applicable for auth or 2.0.

Optional

Table 9 – Helper parameters set by Merchant
For captions in supported languages besides English, see Appendix D.

...

Code Block
languagexml
<script type="text/javascript" src="<helperURI from initSession()>"></script> 
<--
// Merchant javascript to call init() and define callback() goes here
-->

Code example 3 – Helper initialization

Info

1 Note that frameMode="window" must be initiated by a user click/tap in order to avoid conflicts with any pop-up blockers.

...

Object name

statusParams

Comment

Example value

error

errorId

An error code, see [BEMEC].

2904

error

A textual description of the result.

"Some error text"

detail

Added if available.

[ "Cross Origin Resource Sharing (CORS) is not supported!" ]

status

statusText

A textual description of the result.

"Success"

status

Status code. See below for more details.

1

Table 10 – The result objects of the callback function in BankID 2.1
The Initialiser´s callback function expects an error and a status parameter, and if this return alternative is used, the callback-function will be called with these two objects. The value of the error object contains an error code and an error description of any errors occurring during the startup phase (before the client has been in touch with either merchant or COI), see Code example 4. Otherwise it will be null.

Code Block
{ 
        errorId: 2904, 
        error: "Your browser does not support BankID",
        detail: [ "Cross Origin Resource Sharing (CORS) is not supported!" ]
}

Code example 4 – Error object in Helper callback function 
The value of the result object will contain a status code and a description (if the error object is null). The status code can be one of the following:

...

Gliffy
nameError handling in client

Figure 8 – Error handling in client
Note that with BankID 2.1 encData in handleError() is extended with rtReport as described for verifyTransaction() request in Table 7. The request will not contain any signatures even if one or more documents were successfully signed during the process. If an handleError() is returned in the midst of a multi-document signing process, the end-user will have to start the entire process all over again.

...

If an error occurs that prevents the merchant from calling verifyTransactionRequest() / verifyTransactionResponse(), an unencrypted response may be sent to the client (through the Client proxy in case of signing with BankID 2.1). This response should be on the form "errCode=<errorCode>". 

Gliffy
nameError handling in the server component

Figure 9 – Error handling in the server component 
It is possible to specify nextUrl in the unencrypted handle error message, but it will be ignored by the BankID Web-client.

...

The BankID Web-client is based on responsive design and adapts to the space made available for the iframe. For further details see [IMMC].

Size restrictions and recommendations

As mentioned in 3.2.1 the BankID Web-client is designed to work well across a broad range of devices. There are still some recommendations regarding the minimum size of client. For further details, see [IMMC].

In case of document signing, it may be appropriate to consider the docDisplayMode=overlay, depending on the size and nature of the document to be signed. See 3.2.1 for more information.

...

For further details please refer to:

...

  • Section B.5 in this document.
  • [ICSRV], 6.1.7 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.5 Retrieve additional information from VA

...

Key

Description

Caption

Values

Value set by

BankID 2.1

action

Tells BankID COI what kind of operation which will be initiated.

The type of BankID operation to be initiated.

"auth" (Default) for Authentication
"sign" for Signing
"netPay" for BankAxess
"changePassword" for changing end-user password (supports camel casing also).

Merchant

Cont'

localeId

Sets the language of the client that will be assembled by BankID COI.

The wanted language of the client.

"nb" = Norwegian (default)
"en" = English

Merchant

Cont'

nextURL

Optional. This is an error fallback URL used by the client if an error occurs and the client cannot obtain the proper nextURL from the merchant, or if the merchant did not provide a callback function. Note: The URL must use SSL.

An error fallback URL used by the client if any error occurs, must use SSL.

Example: "https://www.merchant.no/genericErrorPage"

Merchant

Cont'

merchantURL

This is the URL which the web-client uses to communicate with the merchant application during authentication and signing. The URL must use SSL.

The merchant endpoint of the merchant protocol, must use SSL.

Any https-URL. Note that the BankID client will verify that the hostname of the URL matches the webaddress in the configuration file.

Merchant

Cont'

timeout

Optional. The time, in milliseconds, the web-client will wait for a response from the merchant application. The minimum value is 1 ms.

The time, in milliseconds, the client will wait for a response from the merchant application, optional.

40000 (Default)

Merchant

Cont'

sid

SessionID. This is a parameter that can be set and used by merchant in order to keep track of sessions.

A sessionID set by merchant. Optional.

Any string.

Merchant

Cont'

certType

Optional, the default value comes from merchant config. Lists the BankID certificate types that the application accepts

Lists the BankID certificate types that the application accepts, Optional.

"ALL" or a comma separated list of PolicyOIDs

Merchant through BankID Server configuration

Cont'

showUnderstanding

Optional. During a signing process, the merchant can with this flag control whether the text "Jeg har lest og forstått innholdet" (including the checkbox) will be visible or not.

Determines if the text "Jeg har lest og forstått innholdet" (including the checkbox) will be visible or not. Optional.

"Y" (Default)
"N"

Merchant

Cont'

showConfirmation

Optional. During a signing process where an SDO receipt is received at the client, this flag controls whether a "confirmation of signing complete" message is to be presented.

During a signing process where an SDO receipt is received at the client, this flag controls whether a "confirmation of signing complete" message is to be presented. Optional.

"Y" (Default)
"N"

Merchant

Cont'

suppressBroadcast

Optional. Set if any message from COI to all users will be suppressed. If "N" and there is a broadcast msg from COI, the msg will be incorporated into the client, which will format and display it to the end-user.

Suppress any broadcast message from COI. Optional.

"N" (Default)
"Y"

Merchant

Cont'

extPDFDomain

Optional. Display of PDF by external application. Only mandatory if action = "sign". Is set in the CSP for the client to permit sourcing from extPDFURL.

Display of PDF by external application. Only mandatory if action = "sign".

"https://www.merchant.no/pdfs"

Merchant

2.0 only

docDisplayMode

Optional. Determines how external documents to be signed will be displayed. Only mandatory if action = "sign".

Determines how external documents to be signed will be displayed. Only mandatory if action = "sign".

"interior" (default)
"window"
"overlay"

Merchant

Cont'

merchantFEDomain

The expected domain of the Helper, as seen from the client. Must use HTTPS. Also used in X-Frame-Option1.

The expected domain of the Helper, as seen from the client.

"https://www.merchant.com"

Merchant

Cont'

merchantFEAncestors

Optional. A space separated list of domains. Merchants that use an iframe inside another iframe should set it in order to define the browsing contexts in which the Web-client is allowed to execute. Used to set the correct CSP-directive2.

The chain of domains used in an iframe in iframe-scenario. Optional.

"https://www.domain-1.com

https://www.domain-2.com
https://www.domain-N.com"

Merchant

New

userAgent

Used to check against userAgent blacklist in COI.

The end user's UA-string.

 

Merchant

Cont'

withCredentials

Optional. Used to activate CORS-requests with credentials. Tells the Web-client to set Access-Control-Allow-Credentials = true, resulting in any cookies set in the context of the merchant application are forwarded by the client over the merchant protocol.

Sets CORS credentials to true in order to include any Merchant cookies. Optional.

"N" (Default)
"Y"

Merchant

Cont'

clientProxyURL

Optional. If not provided by Merchant, the centrally located Client proxy will be used as default.

The URL of the Client proxy used by the Merchant

URL of any BankID approved Client proxy, set by Merchant. Default:3

https://cp.bankid.no/clientproxy

Merchant/COI

New

clientProxyPublicKey

Optional. The hex encoded modulus of the Client proxy's public RSA key the client will use to encrypt requests to the Client proxy. Exponent is 65537. If not provided by Merchant, a centrally stored key will be used.

The public RSA key the client will use to encrypt requests to the Client proxy. Optional.

Hex encoded modulus, set by Merchant

Merchant/COI

New

clientSessionTimeout

Optional. Merchant may use this to align the valid session intervals on the merchant and COI sides. Merchants should consider if auth and sign should have different values. It has no performance impact on COI.
This parameter also sets the valid Client proxy session interval.

The time, in milliseconds, the client session will live according to the merchant application. Optional.

1800000 ms (Default)

Merchant

New

clientVersion

Optional. Lets the merchant decide to perform signing with BankID 2.0 or 2.1. Note that for authentication only the 2.1 client exists, i.e. the same client will be returned regardless of this parameter value.

The desired BankID version to be used for document signing. Optional. Default value: "2.0".

"2.0" (default) / "2.1"

Merchant

New

Table 11 – BankID Web-client parameters and values
For captions in supported languages besides English, see Appendix D.

...

Further note that to ensure full backwards compatibility with BankID 2.0, the new parameter clientVersion is introduced with BankID 2.1, as described in Table 11.

Info

1 http://www.rfc-editor.org/rfc/rfc7034.txt

2 http://www.w3.org/TR/CSP2/#directive-frame-ancestors

3 For pre-production: https://cp-preprod.bankid.no/clientproxy

...

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

    • initSignSignMerchantSeal
    • initSignBuildEndUserSeal

 

documents

JSON

Array of data elements used in multi-document signing. Only used in BankID 2.1.

Per document:

  • data
  • mimeType
  • dataDescription
  • encoding (latin1)
  • signingKind
    • byteRange
    • merchantSeal -position of seal
    • endUserSeal - position of seal

data

Base64-encoded

Data to be signed.

Used during signing by both the client and merchant. Several methods to set these raw data exists, some needs raw data b64 encoded, other needs the data as is in Java Strings.

nextURL

String

Optional. The URL the client redirects to after completion.

Used together with 'status=OK' or together with 'errCode=theErrCode'. Note: The URL must be HTTPS. The callback function in Helper is preferred over this parameter.

mimeType

String

MIME type of the data to be signed.

Used during signing (text/plain, text/BIDXML application/pdf).

sid

String

Session identifier

If sid is present in the initSession() request, the Web-client will include the sid during the initial server communication. The server may change the sid at any time. The client always returns the last received sid.

sdo

Base64-encoded

SDO XML object

Enables the end-user to save signed data. Not supported in 2.1.

dataDescription

String

Short description of the content of the SDO data.

This info is shown during PDF-signing.

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-user's user ID.

Used when the merchant is using user profile.

OTPService

String

OTP service name.

Used when the merchant is using user profile.

extPDFURL

String

URL to pdf to be signed.

Any URL using https. Only BankID 2.0.

userIDKeystrokeData

String

Key biometrics for user name input field from Merchant application

See BehavioWeb.

serialSessionPropertiesJSONcontaining pr. signing session serial signing informationSets pr. session serial signing parameters for example kind of merchant mode, only PAdES
serialPkcs7sStringcommasep list of enduser signatures (b64) for serial documents.only together with coiData, only PAdES
merchantCertJSONdescription of merchant cetificateused for building merchant visual seal, only PAdES turnkey mode
endUserCertJSONdescription of enduser certificateused for building end user visual seal, only PAdES self assembling mode
nextMerchantOperationStringsignal to client what to do next in some serial signing flowsonly PAdES
merchantSealsJSONclientProxy generated merchant sealsonly PAdES turnkey mode
endUserSealsJSONclientProxy generated end user sealsonly PAdES turnkey mode
cmsFormatStringkind of format in pkcs7ordinary bankID or PAdES compatible
ocspFormatStringkind of format in ocsp responsesordinary bankID or PAdES compatible

Table 12 – Values set by merchant per transaction

Generated by BankID Server or client in either initTransaction() or verifyTransaction().

...

Key

Format

Description

Comment

operation

String

 

Request type / identifactor

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 BankID Server to authenticate the client.

pkcs7

Base64-encoded

End-user or merchant signature

Used during both authentication and signing in BankID 2.0. For authentication only in 2.1. See also clientpkcs7s below.

clientpkcs7s

Base64-encoded

Comma separated list of PKCS7s (client signatures).

Used in signing transactions in BankID 2.1.

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. BankID 2.1: Last ocsp after CS check of Merchant sign certificate for each merchant pkcs7.

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.

rtReport

 

Blob of comma separated name=value pairs. Used to send information from client to merchant.

See Appendix G

Table 13 – Values generated by BankID Server or client

Background Color
coloryellow

TODO: must be updated to reflect a) BankID 2.1 multidocument changes and SIGN2's PAdES support