API

This section documents the available API for BankID C Server.

The method names reflects the convention used on Windows systems, imported from BIDCSERVER.h. Linux and Unix implementations should use method names in lowercase, like bid_initialize and bid_getinfoitem, imported from serverkernel.h.

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

Initialization and 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

Shut down 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 section 4
ignored	const char*	in	Reserved.
trustedstore	const char*	in	See section 4
grantedpolicies	const char*	in	See section 4
proxyserver	const char*	in	See section 4 (optional)
proxyport	const char*	in	See section 4 (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 section 4
ignored	const char*	in	Reserved
trustedstore	const char*	in	See section 4
grantedpolicies	const char*	in	See section 4
proxyserver	const char*	in	See section 4 (optional)
proxyport	const char*	in	See section 4 (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 docnum.

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 docnum. 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 merchant BankID 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.

BID_AddDocumentPDFSerialSign (PAdES)

Syntax

int BID_AddDocumentPDFSerialSign(	const int sessioncontext,
									const char *data,
									const char *dataDescription,
									BID_SerialSigningKind kind,
									BID_VisualSealPosition * merchant_seal_position,
									BID_VisualSealPosition * end_user_seal_position)

Purpose
Adds a document which will be signed serially, resulting in a document with at least PAdES B-B profile when signing finished.

Parameter	Type	In/Out	Description
sessioncontext	SESSION_HANDLE	in	Session context
data	char *	in	The data to be signed represented as a BASE64 encode string
kind	BID_SerialSigningKind	in	Type of serial signing, BID_SERIAL or BID_SERIAL_END_USER_ONLY
merchant_seal_position	BID_VisualSealPosition*	in	The optional (or NULL) placement of the merchant seal
end_user_seal_position	BID_VisualSealPosition*	in	The optional (or NULL) placement of the end user seal

BID_GetSerialSignedPdf (PAdES)

Gets a base64 encoded byte stream representing a serial signed document as far as the process has come.

It should be called after verifyTransactionRequestSerial when the merchant is doing the assembling of validation data into the PAdES itself.

It should be called after verifySignAddDSS when merchant lets BankID do this assembling.

Syntax

int BID_GetSerialSignedPdf( const int sessioncontext,
							const int docnum,
							char **pdfDataB64)

Purpose

Get the complete serial signed PDF. This call is only valid after the PDF is signed.

Parameter	Type	In/Out	Description
sessioncontext	SESSION_HANDLE	in	Session context
docnum	int	in	should refer to a serial signed document
pdfDataB64	char **	out	complete signed PAdES, should be freed by BID_Free

BID_GetSerialSignedData (PAdES)

Syntax

int BID_GetSerialSignedData(const int sessioncontext,
							const int docnum,
							BID_SerialSignedData ** serial_signing_data)

Purpose

Get the signed data in a serial signing flow, turnkey or selfassembler, BankID 2.1 only. The data contains the documents and their current different incremental updates.
The method acts the same as BID_GetSignedData but gets the serial_signing_data instead. Must be used to hold data between the different callbacks from client.

Use this method to get the data to hold between requests from BankID client/ClientProxy. Use BID_SetSerialSignedData to set them back into the session, in sequence.

Note: You need to loop through ALL documents, in sequence, same as for BID_GetSignedData.

Note: The data is copied from the values in bankid session, so freeing the serial_signing_data is your responsibility.

Note: use BID_FreeSerialSigningData for serial_signing_data.

Parameter	Type	In/Out	Description
sessioncontext	SESSION_HANDLE	in	Session context
docnum	int	in
serial_signing_data	BID_SerialSignedData **	out	serial signing data, null if document is parallel kind, use BID_Free_SerialSignedData to clean up this.

BID_SetSerialSignedData (PAdES)

Syntax

int BID_SetSerialSignedData(const int sessioncontext,
							char* signed_data,
							BID_SerialSignedData * serial_signing_data)

Purpose

Sets the data that was signed before handling it in either BID_InitSignSignMerchantSeal, BID_InitSignBuildEndUserSeal, BID_verifyTransactionRequestSerial or BID_VerifySignAddDSS
The method acts the same as BID_SetSignedData but is used for the serial_signing_data.

Note: You need to loop through ALL documents, in sequence, same as for BID_SetSignedData.

Note: The data is copied from the in parameters, so freeing the serial_signing_data is your responsibility.
Note: use BID_FreeSerialSigningData for serial_signing_data.

Parameter	Type	In/Out	Description
sessioncontext	SESSION_HANDLE	in	Session context
signed_data	char *	in
serial_signing_data	BID_SerialSignedData *	in

BID_Free_SerialSigningData (PAdES)

Syntax

int BID_Free_SerialSigningData(BID_SerialSignedData * serial_signing_data);

Purpose

Frees all elements reffered from the serial_signing_data and then the serial_signing_data object itself.

Parameter	Type	In/Out	Description
sessioncontext	SESSION_HANDLE	in	Session context
serial_signing_data	BID_SerialSignedData *	in	pointer to data to clean up, null allowed

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	Mandatory	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 (All flows except PAdES with self-assembled seals)

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 and initSign operations 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.

To perform parallel (SEID-SDO) signing of text, XML or PDF documents, all documents must have been added with the functions BID_AddDocumentText, BID_AddDocumentXML or BID_AddDocumentPDF, and the infoitem doSerialSigning must not have been set to Y before this function is called.

To perform PAdES serial signing, all documents must have been added with the function BID_AddDocumentPDFSerialSign, and the infoitem doSerialSigning must have been set to Y before this function is called. If doSerialSigning != "Y" and documents have been added with BID_AddDocumentText, BID_AddDocumentXML or BID_AddDocumentPDF (no SerialSign on the end), the call will fail. If doSerialSigning == "Y" and documents have been added with BID_AddDocumentPDFSerialSign, the call will fail.

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_InitTransactionSelfAssembler (PAdES with self-assembled seals)

Syntax

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

Purpose
Handles the initSign operation received from the BankID client when merchant wants to do serial signing and self-assemble the visual seals.

It takes the encrypted request and creates the encrypted response that is sent back to the client.

The merchant_visual_seal_builder will be called by BankID server during the call to BID_InitTransactionSelfAssembler, for each document with serialsigning kind "serial". The merchant must in this callback function add an incremental update to the PDF document in question. The merchant_visual_seal_builder must be non-NULL.

Note: in the corner case, all documents are BID_SERIAL_END_USER_ONLY, the merchant_visual_seal_builder will not be called, but to active selfassembling mode, it must be set.

The function BID_GetSerialSignedData must be called for each document and the serial_signing_data must be 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 'traceID', 'cmsFormat' and 'ocspFormat' must be set before a call to initTransaction.

It should be noted that it will not be possible to create SEID SDOs for serial signed document.

It should also be noted that in a multidocument flow, either all or none of the documents are serial signed, a mix is not supported.

This function only makes sense for PAdES serial signing, so all documents must have been added with the function BID_AddDocumentPDFSerialSign, and the infoitem doSerialSigning must have been set to Y before this function is called, otherwise it will fail.

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.
merchant_visual_seal_builder	BID_VisualSealBuilder	In	Pointer to function for adding a visual seal to a given document. Can not be NULL.
response	char **	out	The encrypted response

Infoitem	Description	Mand.	2.1
cmsFormat	Values: "PKCS7_ISO320001" (PAdES compatible)	Yes	X
ocspFormat	Values: "OCSP_RFC6960_COMPATIBLE" (PAdES compatible)	Yes	X

BID_InitSignBuildEndUserSeal (PAdES with self-assembled seals)

Syntax

int BID_InitSignBuildEndUserSeal(	const int sessioncontext,
									const char* enckey,
									const char* encdata,
									const char* encauth,
									const char* operation,
									const char* sid,
									BID_VisualSealBuilder end_user_visual_seal_builder, 
									char** response)

Purpose
Creates the encrypted response to the initSignBuildEndUserSeal operation, the method is used for serial signed documents.

Used in self assembling flow to create the merchant part incremental update of the document . The method is used for serial signed documents, it will be called once pr. document.

Before calling this, BID_SetSerialSessionData should be called to associate document data with the sessioncontext

After calling this, BID_GetSerialSessionData should be called to save the document data for later callbacks.

Parameter	Type	In/Out	Description
sessioncontext	SESSION_HANDLE	in	Session context
enckey	char *	in
encdata	char *	in
encauth	char *	in
operation	char *	in
sid	char *	in
end_user_visual_seal_builder	BID_VisualSealBuilder	in	pointer to function to call when BIDServer needs to build visual seal for the end_user. NULL is illegal here.
response	char **	out	result

BID_InitSignSignMerchantSeal (PAdES)

Syntax

int BID_InitSignSignMerchantSeal(	const int sessioncontext,
									const char* enckey,
									const char* encdata,
									const char* encauth,
									const char* operation,
									const char* sid,
									char** response)

Purpose
Creates the encrypted response to the initSignSignMerchantSeal operation, the method is used for serial signed documents, turnkey flow.

Performs the merchant signing of the original documents pluss the WebClient/ClientProxy added merchantseal.

Used in turnkey flow to sign the merchant seal created by BankID clientProxy.

The method is used for document with serialsigning kind serial, may in theory be called more than once pr. session.

Before calling this, BID_SetSerialSessionData should be called to associate document data with the sessioncontext

After calling this, BID_GetSerialSessionData should be called to save the document data for later callbacks.

CMS and OCSP format should be set to the PAdES compatible values in the infoitems.

Parameter	Type	In/Out	Description
sessioncontext	SESSION_HANDLE	in	Session context
enckey	char *	in
encdata	char *	in
encauth	char *	in
operation	char *	in
sid	char *	in
response	char **	out	result

Infoitem	Description	Mand.	2.1
ocspFormat	Values: "OCSP_RFC6960_COMPATIBLE" (PAdES compatible)	Yes	X
cmsFormat	Values: "PKCS7_ISO320001" (PAdES compatible)	Yes	X

BID_VerifyTransactionRequest (All flows except PAdES with self-assembled validation)

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 are 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_VerifyTransactionRequestSelfAssembler (PAdES with self-assembled validation data)

Syntax

int BID_VerifyTransactionRequestSerial( const SESSION_HANDLE sessioncontext, 
										const char* encKey, 
										const char* encData, 
										const char* encAuth, 
										const char* operation, 
										const char* sid,
										BID_ValidationBuilder validation_increment_builder);

Purpose
Handles the decryption of the data received from the client when the operation is 'verifySign' when the signing is serial. 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.

BID_SetSerialSignedData should be used before this function to associate the signed data with the sessioncontext.

Ocsp and cms format should be set to the serial signing variants.

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.

Note: if validation_increment_builder is nonnull, this callback will be the last that the Webclient/ClientProxy calls the merchant for this session.

Note: if validation_increment_builder is null, WebClient/Clientproxy will send another callback with operation= "verifySignAddDSS" to complete the building of the PAdES. Then BID_GetSerialSignedData should be called to save session data for the next callback.

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.
validation_increment_builder	BID_ValidationBuilder	In	A pointer to a function used if merchant itself wants to add a Digital Signing Storage (DSS) incremental update to the PAdES. Can not be NULL.

Infoitem	Description	Mand.	2.1
ocspFormat	Values: "OCSP_RFC6960_COMPATIBLE" (PAdES compatible)	Yes	X
cmsFormat	Values: "PKCS7_ISO320001" (PAdES compatible)	Yes	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.

Note: to get the complete PAdESes in selfassembler mode, use the BID_GetSerialSignedPdf function after calling BID_VerifyTransactionRequestSerial.

BID_VerifyTransactionResponse (PAdES and non-PAdES)

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.

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

BID_VerifySignAddDSS (PAdES)

Syntax

int BID_VerifySignAddDss(	const int sessioncontext,
							const char* enckey,
							const char* encdata,
							const char* encauth,
							const char* operation,
							const char* sid,
							char** response)

Purpose
Creates the encrypted response to the veridySignAddDSS operation, the method is used for serial signed documents. Merchant receives incremental updates containing a DSS for each PAdES. These incremental updates contain certificates and OCSPs for the signing done in this session.

Used in turnkey validation flow.

Before calling this, BID_SetSerialSessionData should be called to associate document data with the sessioncontext

CMS and OCSP format should be set to the PAdES compatible values in the infoitems.

Note: to get the complete PAdESes in turnkey validation mode, use the BID_GetSerialSignedPdf function after calling BID_VerifySignAddDSS

Parameter	Type	In/Out	Description
sessioncontext	SESSION_HANDLE	in	Session context
enckey	char *	in
encdata	char *	in
encauth	char *	in
operation	char *	in
sid	char *	in
response	char **	out	result

Infoitem	Description	Mand.	2.1
ocspFormat	Values: "OCSP_RFC6960_COMPATIBLE" (PAdES compatible)	Yes	X
cmsFormat	Values: "PKCS7_ISO320001" (PAdES compatible)	Yes	X

Serial signing (PAdES) self-assembly functions and utilities

These functions are only relevant in self-assembling merchant applications, i.e. applications that want to generate seals or validation data themselves instead of letting the COI handle it.

BID_ByteRange and BID_ByteRangeWithData structs

The BID_ByteRange and BID_ByteRangeWithData data structures are used during signing. They are related to the ByteRange in the PDF standard.

A PDF signature contains a digest over two potentially disjoint byte sequences. A BID_ByteRange specifies the starting indices of these two sequences (low0 and low1) and their lengths (len0 and len1). A BID_ByteRangeWithData contains a BID_ByteRange and a pointer to the data being described by the same BID_ByteRange.

When talking about byteranges below, "(a, b, c, d)" means "a byterange with {low0 = a, len0 = b, low1 = c, len1 =d}".

Index: 0           low0             low0 + len0                low1           low1 + len1      n_file_length
       |___________|________________|__________________________|______________|________________|

Size:              |----- len0 -----|-- low1 - (low0 + len0) --|---- len1 ----|

                   |-- sequence0 ---|----------- gap ----------|- sequence1 --|

                   |----------- BID_ByteRangeWithData.data -------------------|

BID_Byterange_gap_start_index

Syntax

int BID_Byterange_gap_start_index(BID_ByteRange const *b, int *out);

Purpose

Get the index of the start of the gap (i.e. low0 + len0).

Parameter	Type	In/Out	Description
b	BID_ByteRange const *	in	A byterange to inspect
out	int *	out	Pointer to an int to put the result in
	int	return	Returns zero on success, an errorcode if something went wrong

BID_Byterange_gap_offset

Syntax

int BID_Byterange_gap_offset(BID_ByteRange const *b, int *out);

Purpose

Get the index of the start of the gap relative to the start of the data covered by the byterange (i.e. len0).

Parameter	Type	In/Out	Description
b	BID_ByteRange const *	in	A byterange to inspect
out	int *	out	Pointer to an int to put the result in
	int	return	Returns zero on success, an errorcode if something went wrong

BID_Byterange_gap_len

Syntax

int BID_Byterange_gap_len(BID_ByteRange const *b, int *out);

Purpose

Get the length in bytes of the gap in a byterange.

Parameter	Type	In/Out	Description
b	BID_ByteRange const *	in	A byterange to inspect
out	int *	out	Pointer to an int to put the result in
	int	return	Returns zero on success, an errorcode if something went wrong

BID_Byterange_len_excl_gap

Syntax

int BID_Byterange_len_excl_gap(BID_ByteRange const *b, int *out);

Purpose

Get the length in bytes of the data segment described by a byterange, excluding the gap.

Parameter	Type	In/Out	Description
b	BID_ByteRange const *	in	A byterange to inspect
out	int *	out	Pointer to an int to put the result in
	int	return	Returns zero on success, an errorcode if something went wrong

BID_Byterange_len_incl_gap

Syntax

int BID_Byterange_len_incl_gap(BID_ByteRange const *b, int *out);

Purpose

Get the length in bytes of the data segment described by a byterange, including the gap.

Parameter	Type	In/Out	Description
b	BID_ByteRange const *	in	A byterange to inspect
out	int *	out	Pointer to an int to put the result in
	int	return	Returns zero on success, an errorcode if something went wrong

BID_Byterange_set

Syntax

int BID_Byterange_set(BID_ByteRange *br, int low0, int len0, int low1, int len1);

Purpose

Set values into a provided byterange structure. The range will be normalized. Normalizing a byterange sets the byterange to all zeroes if both length are zero. Normalizing a byterange moves the second part to the first part if length of first is zero and gap is zero. len1 will be set to zero.

Parameter	Type	In/Out	Description
br	BID_ByteRange *	out	A byterange to modify
low0	int	in	Index of first byte of first byte sequence of a byterange
len0	int	in	Length of first byte sequence in a byterange
low1	int	in	Index of first byte of second byte sequence of a byterange
len1	int	in	Length of second byte sequence in byterange
	int	return	Returns zero on success, an errorcode if something went wrong

BID_Byterange_set_simple

Syntax

int BID_Byterange_set_simple(BID_ByteRange *br, int len);

Purpose

Set a byterange to a given length. Equivalent to `bid_byterange_set(br, 0, len, len, 0)`.

Parameter	Type	In/Out	Description
br	BID_ByteRange *	out	A byterange to modify
len	int	in	Number of bytes the byterange should fit
	int	return	Returns zero on success, an errorcode if something went wrong

BID_Byterange_set_offset

Syntax

int BID_Byterange_set_offset(BID_ByteRange *br, BID_ByteRange const *src, int len);

Purpose

Turn br into a copy of src, but shift low0 and low1 by len.

Parameter	Type	In/Out	Description
br	BID_ByteRange *	out	A byterange to modify
src	BID_ByteRange *	in	A byterange to copy
len	int	in	How many bytes br should be offset relative to src
	int	return	Returns zero on success, an errorcode if something went wrong

BID_Byterange_set_empty

Syntax

int BID_Byterange_set_empty(BID_ByteRange *br);

Purpose

Set a byterange to (0, 0, 0, 0).

Parameter	Type	In/Out	Description
br	BID_ByteRange *	out	A byterange to modify
	int	return	Returns zero on success, an errorcode if something went wrong

BID_Brwd_free

Syntax

void BID_Brwd_free(BID_ByteRangeWithData * br);

Purpose

Free memory allocated by a byterange with data. Frees memory for data element, then frees memory for the byterange itself.

Parameter	Type	In/Out	Description
br	BID_ByteRangeWithData *	in	Instance to free

BID_Brwd_create

Syntax

BID_ByteRangeWithData * BID_Brwd_create(unsigned char * data, BID_ByteRange const *br);

Purpose

Create a byterange with data. It copies both `data` and `br`.

Parameter	Type	In/Out	Description
data	unsigned char *	in	Pointer to data to hold
br	BID_ByteRange *	in	Byterange describing data
	BID_ByteRangeWithData *	return	Pointer to a BID_ByteRangeWithData or NULL if out of memory

BID_Brwd_create_copy

Syntax

BID_ByteRangeWithData * BID_Brwd_create_copy(BID_ByteRangeWithData * brwd);

Purpose

Make a copy of a BID_ByteRangeWithData, i.e. allocate memory and copy content.

Parameter	Type	In/Out	Description
brwd	BID_ByteRangeWithData *	in	Pointer to a BID_ByteRangeWithData to copy
	BID_ByteRangeWithData *	return	Pointer to a BID_ByteRangeWithData or NULL if out of memory

BID_Brwd_create_simple

Syntax

BID_ByteRangeWithData * BID_Brwd_create_simple(unsigned char * data, int len);

Purpose

Create a BID_ByteRangeWithData containing provided data and a byterange of (0, len, len, 0).

Parameter	Type	In/Out	Description
data	unsigned char *	in	Pointer to data to hold
len	int	in	Length of data
	BID_ByteRangeWithData *	return	Pointer to a BID_ByteRangeWithData or NULL if out of memory

BID_Brwd_create_empty

Syntax

BID_ByteRangeWithData * BID_Brwd_create_empty();

Purpose

Create a BID_ByteRangeWithData with no data.

Parameter	Type	In/Out	Description
	BID_ByteRangeWithData *	return	Pointer to a BID_ByteRangeWithData or NULL if out of memory

BID_Brwd_concat

Syntax

BID_ByteRangeWithData * BID_Brwd_concat(BID_ByteRangeWithData * first, BID_ByteRangeWithData * second);

Purpose

BID_Brwd_concat is used to join to byteranges into a new freshly allocated one.

Byteranges must be concatenable, i.e. second must start at end of first byterange, or one or both shall be empty. Will allocate a new byterange with data, allocates its data element big enough to hold the sum of first and second. The resulting byterange will start at first's low0 and end at second's low1 + len1, gap preserved will be second's gap.

If either first or second is empty, the result with be the other.

Parameter	Type	In/Out	Description
first	BID_ByteRangeWithData *	in	Pointer to a BID_ByteRangeWithData
second	BID_ByteRangeWithData *	in	Pointer to a BID_ByteRangeWithData
	BID_ByteRangeWithData *	return	Pointer to a BID_ByteRangeWithData or NULL if out of memory

BID_Brwd_get_data_without_gap

Syntax

BID_ByteRangeWithData * BID_Brwd_get_data_without_gap(BID_ByteRangeWithData * brwd);

Purpose

Join the first and second array of bytes described by a byterange into one.

This function is used to extract the data to be signed out of a byterange with data structure. The result is again a byterange with data structure where the right part has zero length and the left part has the length from byterange_len_excl_gap(&brwd→byte_range, &length).

Result should be freed using bid_brwd_free. It always copies the data, even if there is no gap in brwd.

Parameter	Type	In/Out	Description
brwd	BID_ByteRangeWithData *	in
	BID_ByteRangeWithData *	return	Pointer to a BID_ByteRangeWithData or NULL if out of memory

BID_Brwd_strip_off_prefix

Syntax

BID_ByteRangeWithData * BID_Brwd_strip_off_prefix(BID_ByteRangeWithData * brwd, int prefixlen);

Purpose

BID_Brwd_strip_off_prefix is used to remove an initial part from a byte range with data.

Result should be freed using bid_brwd_free.

Parameter	Type	In/Out	Description
brwd	BID_ByteRangeWithData *	in
prefixlen	int	in	How many bytes to strip from the start
	BID_ByteRangeWithData *	return	Pointer to a BID_ByteRangeWithData or NULL if out of memory or illegal prefixlen

BID_Brwd_insert_signature_in_gap

Syntax

int BID_Brwd_insert_signature_in_gap(BID_ByteRangeWithData * dest, unsigned char * data, int data_len);

Purpose

BID_Brwd_insert_signature_in_gap is used to insert a signature (pkcs7 DER encoding) into a byterange with data's gap area.

This method is mostly for internal usage. The length of the byterange with data's gap should be at least twice data_len since signature will be written hexEncoded, see details at http://www.adobe.com/content/dam/Adobe/en/devnet/acrobat/pdfs/PDF32000_2008.pdf page 476.

Parameter	Type	In/Out	Description
dest	BID_ByteRangeWithData *	out
data	unsigned char *	in	Data to insert into signature gap
len	int	in	Number of bytes in PKCS7
	int	return	0 if OK, else error code, especially SERIALSIGN_GAP_TOO_SMALL

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

Browser not supported