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.

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.

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.

BID_CloseSession

Syntax

int BID_CloseSession( const SESSION_HANDLE sessioncontext );

Purpose 
Closes a merchant session.

Internal state

BID_GetInfoItem

Syntax

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

Purpose

Retrieve an infoitem from the session

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.

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.

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.

BID_Free

Syntax

int BID_Free( char* allocated )

Purpose
Release the memory associated with the pointer.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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.

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.

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

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.

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

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.

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

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

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

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.

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.