API

This section documents the available API for BankID C Server.

The method names reflects the convention used on Windows systems. Linux and Unix implementations should use methodnames in lowercase, like bid_initialize and bid_getinfoitem.

The API methods are described in the following sub-sections:

Init & Shutdown

BID_Initialize

Syntax

int BID_Initialize();

Purpose

Initialize BankID C Server.

BID_HSMInitialize

Syntax

int BID_HSMInitialize(const char* pkcs11driver);

Purpose

Initialize BankID C Server to use HSM.

Parameter	Type	In/Out	Description
pkcs11driver	const char*	In	Full path to pkcs11 driver implementation file. This is a dll for windows, and so files for UNIX flavours.

BID_Finalize

Syntax

int BID_Finalize();

Purpose

Uninitialize BankID C Server.

Session handling

BID_OpenSession

Syntax

int BID_OpenSession(	SESSION_HANDLE* 	sessioncontext,
						const char*		   	keylocation,
						const char* 		password,
						const char*	   		configlocation,
						const char*	   		webaddress,
						const char*     	ignored,
						const char*	   		trustedstore,
						const char*	   		grantedpolicies,
						const char*	   		proxyserver,
						const char*			proxyport);

Purpose

Open a BankID C Server session.

Parameter	Type	In/Out	Description
sessioncontext	SESSION_HANDLE*	out	Session context
keylocation	const char*	in	Full path to merchant bid file.
password	const char*	in	Password for the merchant bid file
configlocation	const char*	in	Path to configuration file that holds the properties for the merchant session. If this parameter is NULL, then webaddress, trustedstore and grantedpolicies must be set (not NULL).
webaddress	const char*	in	See Configuration of BankID C Server
ignored	const char*	in	Reserved.
trustedstore	const char*	in	See Configuration of BankID C Server
grantedpolicies	const char*	in	See Configuration of BankID C Server
proxyserver	const char*	in	See Configuration of BankID C Server (optional)
proxyport	const char*	in	See Configuration of BankID C Server (optional)

BID_HSMOpenSession

Syntax

int BID_HSMOpenSession( SESSION_HANDLE*	sessioncontext,
						const char*		keylocation,
						const char*		password,
						const char*		configlocation,
						const char*		webaddress,
						const char*     ignored,
						const char*		trustedstore,
						const char*		grantedpolicies,
						const char*		proxyserver,
						const char*		proxyport,
						const char*		pkcs11password,
                        const int     	slot);

Purpose
Open a BankID C Server HSM session.

Parameter	Type	In/Out	Description
sessioncontext	SESSION_HANDLE*	out	Session context
keylocation	const char*	in	Full path to merchant bid file.
password	const char*	in	Password for the merchant bid file
configlocation	const char*	in	Path to configuration file that holds the properties for the merchant session. If this parameter is NULL, then webaddress, trustedstore, grantedpolicies and pkcs11password must be set (not NULL).
webaddress	const char*	in	See Configuration of BankID C Server
ignored	const char*	in	Reserved
trustedstore	const char*	in	See Configuration of BankID C Server
grantedpolicies	const char*	in	See Configuration of BankID C Server
proxyserver	const char*	in	See Configuration of BankID C Server (optional)
proxyport	const char*	in	See Configuration of BankID C Server (optional)
pkcs11password	const char*	In	Password for the HSM.
slot	const int	in	The HSM slot to use.

BID_CloseSession

Syntax

int BID_CloseSession( const SESSION_HANDLE sessioncontext );

Purpose
Closes a merchant session.

Parameter	Type	In/Out	Description
sessioncontext	SESSION_HANDLE	in	Session context

Internal state

BID_GetInfoItem

Syntax

int BID_GetInfoItem(const SESSION_HANDLE 	sessioncontext,
					const char*				key,
					char**					value);

Purpose

Retrieve an infoitem from the session

Parameter	Type	In/Out	Description
sessioncontext	SESSION_HANDLE	in	Session context
key	const char*	in	The key where the value is stored
value	char**	out	The value for the key in request

BID_SetInfoItem

Syntax

int BID_SetInfoItem(const SESSION_HANDLE sessioncontext,
					const char*	     	 key,
					const char*          value );

Purpose

Add an infoitem in sessionstore. This function is basically used to store key/value pairs for a certain merchant session and thread.

Parameter	Type	In/Out	Description
sessioncontext	SESSION_HANDLE	in	Session context
key	const char*	in	The key for the value
value	const char*	in	The value for the key

BID_RemoveInfoItems

Syntax

int BID_RemoveInfoItems(const SESSION_HANDLE sessioncontext);

Purpose
Removes all infoitems for the current thread.
NOTE!
Remember to remove all infoitems right after use for the calling thread. After a call to BID_GetCertstatus (asking for additional information from VA) this method must be called.

Parameter	Type	In/Out	Description
sessioncontext	SESSION_HANDLE	in	Session context

BID_GetRecentError

Syntax

int BID_GetRecentError( const SESSION_HANDLE sessioncontext, 
						char** error);

Purpose
Gives the application detailed information and stack trace about the most recent error on the calling thread.

Parameter	Type	In/Out	Description
sessioncontext	SESSION_HANDLE	in	Session context
error	char**	out	The error text for the last error occurring on this thread.

BID_Free

Syntax

int BID_Free( char* allocated )

Purpose
Release the memory associated with the pointer.

Parameter	Type	In/Out	Description
allocated	char*	in	All "out" parameters in the API must be deallocated using this method. For BID_SEIDSDO structure pointers use BID_SDOFree() instead.

BID_AddDocumentText

Syntax

int BID_AddDocumentText(const SESSION_HANDLE sessioncontext, 
						const char *data, 
						const char *dataDescription)

Purpose
Add a text document to the list of documents to be signed.

Parameter	Type	In/Out	Description
sessioncontext	SESSION_HANDLE	in	Session context.
data	const char *	in	The data to be signed.
dataDescription	const char *	in	The description of the data to be signed.

BID_AddDocumentPDF

Syntax

int BID_AddDocumentPDF( const SESSION_HANDLE sessioncontext, 
						const char *data, 
						const char *dataDescription)

Purpose
Add a PDF document to the list of documents to be signed.

Parameter	Type	In/Out	Description
sessioncontext	SESSION_HANDLE	in	Session context.
data	const char *	in	The data to be signed.
dataDescription	const char *	in	The description of the data to be signed.

BID_AddDocumentXML

Syntax

int BID_AddDocumentXML( const SESSION_HANDLE sessioncontext, 
						const char *xml, 
						const char *xsl, 
						const char *dataDescription)

Purpose
Add an XML document to the list of documents to be signed.

Parameter	Type	In/Out	Description
sessioncontext	SESSION_HANDLE	in	Session context.
xml	const char *	in	The XML to be signed.
xsl	const char *	in	The XSL transformation for the XML
dataDescription	const char *	in	The description of the data to be signed.

BID_GetSignedData

Syntax

int BID_GetSignedData(	const SESSION_HANDLE sessioncontext, 
						int docnum, 
						char **signed_data, 
						char **signature)

Purpose
Retrieve the details and signatures of the documents that was sent to the client to be signed. The signature is the merchant's signature over the data.

Parameter	Type	In/Out	Description
sessioncontext	SESSION_HANDLE	in	Session context.
docnum	int	in	The index of the document. 0 is the first document.
signed_data	char **	out	The data that was signed.
signature	char **	out	The merchant signature over the data.

BID_SetSignedData

Syntax

int BID_SetSignedData( 	const SESSION_HANDLE sessioncontext, 
						const char *signed_data)

Purpose
Set the signed data before calling the BID_VerifyTransactionRequest method.

Parameter	Type	In/Out	Description
sessioncontext	SESSION_HANDLE	in	Session context
signed_data	const char *	in	The data that was signed.

BID_GetSignatureAndOCSP

Syntax

int BID_GetSignatureAndOCSP(	const SESSION_HANDLE sessioncontext, 
							 	int docnum, 
							 	char **clientsignature, 
							 	char **clientocsp)

Purpose
Retrieve the client signature and client basic ocsp response for document x.

Parameter	Type	In/Out	Description
sessioncontext	SESSION_HANDLE	in	Session context
docnum	int	in	The index of the document. 0 is the first document.
clientsignature	char **	out	The end user signature (PKCS7)
clientocsp	char **	out	The basic OCSP for the end user certificate

BID_GetSignatureAndFullOCSP

Syntax

int BID_GetSignatureAndFullOCSP(const SESSION_HANDLE sessioncontext, 
								int docnum, 
								char **clientsignature, 
								char **clientfullocsp)

Purpose
Retrieve the client signature and full client ocsp response for document x. Generally used when signing PDFs and adding PDF signatures (PAdES) to the document with the signature and full OCSP response.

Parameter	Type	In/Out	Description
sessioncontext	SESSION_HANDLE	in	Session context
docnum	int	in	The index of the document. 0 is the first document.
clientsignature	char **	out	The end user signature (PKCS7)
clientfullocsp	char **	out	The full OCSP for the end user certificate

BID_GetReportData

Syntax

int BID_GetReportData( 	const SESSION_HANDLE sessioncontext, 
 						const char *key, 
						char **report)

Purpose
Retrieve the report for the selected key. The report is returned as a UTF-8 string.

Parameter	Type	In/Out	Description
sessioncontext	SESSION_HANDLE	in	Session context
key	const char *	in	The key to request data for.
report	char **	out	The data for the key.

BID_GetPKCS7Info

Syntax

int BID_GetPKCS7Info ( 	const SESSION_HANDLE sessioncontext, 
						const char *pkcs7, 
						const int infoitem, 
						char **out );

Purpose
The BID_GetPKCS7Info method is used to fetch various information from a PKCS7. The information to be fetched is conveyed in the infoitem parameter.

Parameter	Type	In/Out	Description
sessioncontext	SESSION_HANDLE	in	Session context
pkcs7	const char*	in	The PKCS7
infoitem	const int	in	A int specifying the information to fetch
out	char**	out	The output

The possible values for the infoitem value is specified in this list:

Value	Description
0	Issuer name
1	Subject name
2	Valid from date
3	Valid to date
4	Versionnumber
5	Serialnumber
6	Key algorithm
7	Key size
8	Unique ID
9	Originator
10	Bank name
11	Date of birth
12	Policyoid
13	Common name
14	Signing certificate
15	Key usage
16	Email address
17	Signing time
18	Phone number
19	Signing time long

BID_GetTransactionInfo

Syntax

int BID_GetTransactionInfo (const SESSION_HANDLE sessioncontext, 
							const char *tid, 
							const char *oids, 
							const char *timeout );

Purpose
The BID_GetTransactionInfo is used to request information about a transaction identified by tid. The "oids" parameter specifies the type of information.

Parameter	Type	In/Out	Description
sessioncontext	SESSION_HANDLE	in	Session context
tid	const char*	in	The tid that identifies this transaction
oids	const char*	in	One or more OIDs that specifiy the kind of information to request.
timeout	const char*	In	Not used

To get access to the information, the brukerstedsbankid making the request must be authorized to request the information. This is done by the Banks in the RA interface, in the same way as when granting access to request additional information from the VA, see [IMPLW]and [RAIF] for more information.

After a successful call to BID_GetTransactionInfo, the information must be fetched from the BankID C Server by successive calls to BID_GetInfoItem where the key is one of the oids from the call.

BankID implementation

BID_InitSession

Syntax

int BID_InitSession (	const SESSION_HANDLE sessioncontext, 
						char** helperUri, 
						char** traceId, 
					 	char** clientId );

Purpose
The BID_InitSession method is used to initialize a session for the BankID Web-client (javascript). The call sets variables to be used in the javascript client such as "showConfirmation", "showUnderstanding" and "userAgent". See [IMPLW] for more details about each infoitem.

Infoitem	Description	Mand.	2.0	2.1
action	"auth", "sign", "changepassword" or "netpay"	Yes	X	X
localeId	"nb", "en"	Yes	X	X
merchantUrl	Url to connect to the merchant	Yes	X	X
sid	SessionID. Id used to track the session	Yes	X	X
userAgent	The useragent string for the browser	Yes	X	X
Timeout	The timeout time for the merchant	No	X	X
nextUrl	The url the client should navigate to afterwards	Yes	X	X
merchantFEDomain	The merchant domain (for CSP)	Yes	X	X
showConfirmation	Show confirmation dialog (sign only)	No	X	X
showUnderstanding	Show understanding check box (sign only)	No	X	X
suppressBroadcast	Ignore broadcast messages	No	X	X
withCredentials	Send cookies to merchant	No	X	X
certType	The certTypes to allow	No	X	X
docDisplayMode	How to display to be signed (sign only)	Yes	X	X
extPDFDomain	The domain to load the pdf from (sign only)	No	X
merchantFEAncestors	The domains the client may connect to	No		X
clientproxyUrl	The url to the clientproxy	No		X
clientProxyPublicKey	The public key for the clientproxy	No		X
clientVersion	The desired client version	No		X

The following infoitems must be set before calling BID_InitSession:

action
localeId
merchantURL
sid
userAgent
timeout
nextURL
merchantFEDomain

The following infoitems are optional and may be set before calling BID_InitSession:

showConfirmation - Sign only
showUnderstanding - Sign only
suppressBroadcast
withCredentials
certType
docDisplayMode - Sign only
extPDFDomain - Sign only, only if PDF

Parameter	Type	In/Out	Description
Sessioncontext	SESSION_HANDLE	in	Session context
helperUri	char**	out	The helper URI
traceId	char **	out	The traceId
clientId	char **	out	The clientId

The info item "info" should be checked after this call has been invoked.

BID_InitTransaction

Syntax

int BID_InitTransaction ( 	const SESSION_HANDLE sessioncontext, 
							const char* encKey, 
							const char* encData, 
							const char* encAuth, 
							const char* operation, 
							const char* sid, 
							char** response );

Purpose
Handles the initAuth/initSign operation received from the BankID client. It takes the encrypted request and creates the encrypted response that is sent back to the client.

If operation is 'initAuth', the info item 'serverchallenge' must be retrieved and stored for later use after a call to this function.

If operation is 'initSign', the info item 'signedData' must be retrieved and stored for later use.

The info item 'clientip' may be available and used after a call to this function. The 'clientip' info item is not supported by BankID 2.0 / WebClient. See 5.4.

The info items ‘cmsFormat’ and ‘ocspFormat’ can be set before a call to initTransaction. Setting these info items enables a sign operation to produce other CMS and OCSP response formats than the original default BankID formats. The non-default BankID formats are PAdES compatible and enables the merchant to create PDF Signatures that are PAdES compliant. Please note that the PDF bytes to be signed must contain an empty Signature Dictionary, as this dictionary must be a part of the content that is signed. It should also be noted that it will not be possible to create SEID SDOs when other formats are used than the original default BankID formats.

Parameter	Type	In/Out	Description
sessioncontext	SESSION_HANDLE	in	Session context
encKey	const char *	in	The encryption key
encData	const char *	in	The encrypted request
encAuth	const char *	In	The integrity protection
operation	const char *	in	The operation parameter as it is received from the client.
sid	const char *	In	The sid as it is received from the client.
response	char **	out	The encrypted response

Infoitem

Description

Mand.

2.0

2.1

cmsFormat

Values:

“PKCS7” (default original BankID format) “PKCS7_ISO320001” (PAdES compatible)

Default value: “PKCS7”

No

X

X

ocspFormat

Values:

“OCSP_BANKID_DEFAULT” (default original BankID format)

“OCSP_RFC6960_COMPATIBLE” (PAdES compatible)

Default value: “OCSP_BANKID_DEFAULT”

No

X

X

BID_VerifyTransactionRequest

Syntax

int BID_VerifyTransactionRequest( 	const SESSION_HANDLE sessioncontext, 
									const char* encKey, 
									const char* encData, 
									const char* encAuth, 
									const char* operation, 
									const char* sid );

Purpose
Handles the decryption of the data received from the client when the operation is 'verifyAuth', 'verifySign' or 'handleError'. It takes the encrypted request and verifies the information from the end user received from the client. The verification includes checking the validity of the end user's signature and certificate.

If the operation is 'verifyAuth', the 'serverchallenge' info item must be set before calling this function. If the operation is 'verifySign', the info item 'signedData' must be set before calling this function.

To obtain additional information from the va, the info items 'addsocialno', 'addaccountno' and 'addorganisationno' may be set. If any of the latter three is set, the information may be retrieved by calls to BID_GetInfoItem specifying the info item name minus the 'add'. See 5.4.

If an OCSP response format other than the default original BankID format was specified before initTransaction, the same format should be used for verifyTransactionRequest. This is achieved by setting the info item ‘ocspFormat’ prior to calling the function

Parameter	Type	In/Out	Description
sessioncontext	SESSION_HANDLE	in	Session context
encKey	const char *	in	The encryption key
encData	const char *	in	The encrypted request
encAuth	const char *	In	The integrity protection
operation	const char *	in	The operation parameter as it is received from the client.
sid	const char *	In	The sid as it is received from the client.

Infoitem

Description

Mand.

2.0

2.1

ocspFormat

Values:

“OCSP_BANKID_DEFAULT” (original BankID format)

“OCSP_RFC6960_COMPATIBLE” (PAdES compatible)

Default value: “OCSP_BANKID_DEFAULT”

No

X

X

Note to windows users:
The vatimeout parameter can be used to limit the time the BankID C Server hangs in case it is unable to connect to the VA. This is due to a implementation detail in OpenSSL / Windows socket API that causes the select-call to hang (blocking) until timeout in cases when it is unable to connect to the server. This is a rare error as the availability of the VA is high.

BID_VerifyTransactionResponse

Syntax

int BID_VerifyTransactionResponse ( const SESSION_HANDLE sessioncontext, char** response );

Purpose
Handles the creation of the encrypted response to the BankID client for the initAuth/initSign/handleError operation.
The info item 'nexturl' must be set prior to a call to this function. BID_RemoveInfoItems() must not be called between calls to BID_VerifyTransactionRequest and BID_VerifyTransactionResponse. See 5.4.

Parameter	Type	In/Out	Description
sessioncontext	SESSION_HANDLE	in	Session context
response	char **	in	The encrypted response

BankID on Mobile

BID_RequestMobileAction

Syntax

int BID_RequestMobileAction(const SESSION_HANDLE sessioncontext, 
							char** transactionreference);

Purpose
Used by the merchant to perform a BankID operation using the mobile phone of the user.
The parameters must be set in the merchant's session prior to calling this method by using BID_SetInfoItem(). The infoitems are described in section 4.6.1 in [IMPL].

Parameter	Type	In/Out	Description
sessioncontext	SESSION_HANDLE	in	Session context
transactionreference	char**	out	The transaction reference for the performed operation. This can later be used for sending the user an SMS using BID_PushSms or check the status of an asynchronous action using BID_RequestMobileStatus.

BID_GenerateMerchantReference

Syntax

int BID_GenerateMerchantReference( 	const SESSION_HANDLE sessioncontext, 
									const char* locale, 
									char** merchantreference );

Purpose
Generates the reference to show to the user during mobile authentication. This reference will also be visible on the mobile phone of the user when used as infoitem for BID_RequestMobileAction(). Supported locale(s): "no_NO".

Parameter	Type	In/Out	Description
sessioncontext	SESSION_HANDLE	in	Session context
Locale	const char *	in	The locale / language the reference will be generated in.
merchantreference	char**	out	Text to be displayed to the user on the merchant site

BID_PushSMS

Syntax

int BID_PushSms(const SESSION_HANDLE sessioncontext, 
				const char* transactionreference, 
				const char* text );

Purpose
BID_PushSms can be used to send the user an SMS upon receiving a transaction reference from BID_RequestMobileAction

Parameter	Type	In/Out	Description
sessioncontext	SESSION_HANDLE	in	Session context
transactionreference	const char*	in	The transaction reference returned from previous call to BID_RequestMobileAction
Text	const char*	in	The text for the SMS. Maximum 118 characters

Additional functionality

BID_SignData

Syntax

int BID_SignData(const SESSION_HANDLE sessioncontext, 
				const unsigned char* data, 
				const size_t datalen
				char** pkcs7 );

Purpose
BID_SignData can be used to sign and create a PKCS#7 signature outside of a BankID transaction.

The infoitem 'cmsFormat' can be set in advance to change the format of the resulting PKCS7 as explained in BID_InitTransaction.

Parameter	Type	In/Out	Description
sessioncontext	SESSION_HANDLE	in	Session context
data	const char*	in	The data to be signed
datalen	const char*	in	Length of the data to be signed
pkcs7	char **	out	The signature (PKCS7)

BID_GetOwnCertStatus

Syntax

int BID_GetOwnCertStatus(const SESSION_HANDLE sessioncontext, 
						char** ocspresponse );

Purpose
BID_GetOwnCertStatus can be used to do a Validation Authority (VA) lookup on the merchants own signing certificate.

The infoitem 'ocspFormat' can be set in advance to change the format of the resulting OCSP Response as explained in BID_InitTransaction.

Parameter	Type	In/Out	Description
sessioncontext	SESSION_HANDLE	in	Session context
ocspresponse	char **	out	The OCSP response for the merchant signing certificate

Browser not supported