New functionality

The new version, 5.5.5 is backward compatible. 

There is a minor change in the PKCS#7 for the PKCS7_ISO32001 introduced in 5.2: the algorithmidentifier is removed from the signerinfo.

PAdES support

The 5.2 version of BankID C Server introduced support for new CMS (PKCS#7) and OCSP response formats to be produced during a Sign operation. The formats are introduced to enable creation of PAdES compatible PDF Signatures based on output from BankID. They should generally not be used in other signing scenarios. Authentication transactions will allways use the default original BankID formats.

The 5.5.5 version adds functionality that make it possible to create complete PAdES with a minimum of work in the merchant code.

The CMS and OCSP response formats are controlled by setting their respective info items prior to invoking BID_InitTransaction and BID_VerifyTransactionRequest. The info items must allways have the same values for BID_InitTransaction and BID_VerifyTransactionRequest when they are used.

New methods for PAdES handling

API is updated with the following methods which allows the creation of PAdESes both in turnkey and in self assembling mode.

1. BID_AddDocumentPDFSerialSign - adds a document to be signed serially
2. BID_GetSerialSignedData - gets data from session to save between requests
3. BID_GetSerialSignedPdf - gets complete PAdES after signing finished
4. BID_SetSerialSignedData - resets data between requests
5. BID_Free_SerialSigningData - cleanup function
6. BID_InitSignTransactionSelfAssembler - same as BID_InitSignTransaction, but allows the merchant application to do self-assembly of visual seals
7. BID_InitSignBuildEndUserSeal - used in self assembling mode to route the data to the endUserSeal builder function
8. BID_InitSignSignMerchantSeal - used in turnkey mode to sign the BankID built merchant seal
9. BID_VerifyTransactionRequestSelfAssembler - same as BID_VerifyTransactionRequest, but allows merchant application to do self-assembly of validation data
10. BID_VerifySignAddDSS - function to join the BankID created DSS/validation increment to the PAdES
11. Various BID_ByteRange and BID_ByteRangeWithData convenience methods.

How to use the new functions are described in the quick start guide and in Using BankID C Server

New structures for PAdES handling

See structures.h for more info.

BID_ByteRange

// A byterange, same semantic as in PDF standard
typedef struct stBID_ByteRange {
    int low0;
    int len0;
    int low1;
    int len1;
} BID_ByteRange;

// an array of bytes with a ByteRange specifying these data. 
// data[0] is the element logically at byte_range.low0
// data[byte_range.low1 + byte_range.len1 - byte_range.low0] is the last element in the array
typedef struct stBID_ByteRangeWithData {
    BID_ByteRange byte_range;
    unsigned char * data;
} BID_ByteRangeWithData;

// Holder for data sent to self assembling merchant in seal builder callbacks
typedef struct stBID_VisualSealCertData {
    char * commonName;
    char * serialNumber;
    char * organization;
    char * country;
    char * dateOfBirth;
} BID_VisualSealCertData;

BID_SerialSigningKind

typedef enum enBID_SerialSigningKind {
    BID_PARALLEL = 0,
    BID_SERIAL,
    BID_SERIAL_END_USER_ONLY
} BID_SerialSigningKind;

// where a seal should be built in the PAdES
typedef struct stBID_VisualSealPosition {
    double x;
    double y;
    int page;
} BID_VisualSealPosition;

// Holder for the various incremental updates during serial signing
typedef struct stBID_SerialSigningData {
	BID_ByteRangeWithData * original_data;
    BID_SerialSigningKind signing_kind;
    BID_ByteRangeWithData *merchant_delta;
    BID_ByteRangeWithData *end_user_delta;
    BID_ByteRangeWithData *validation_delta; 
    BID_VisualSealPosition *merchant_seal_position;
    BID_VisualSealPosition *end_user_seal_position;
} BID_SerialSigningData;

BID_ValidationBuilder

// Function handling building of DSS incremental updates in PDF, defined by merchant, called by BankID server in self assembler validation mode
typedef int(CALLBACKTYPE * BID_ValidationBuilder)(int sessioncontext, int docnum,
   BID_ByteRangeWithData * pdfdata,
   char * endUserFullOcspResponse,
   char ** endUserX509Certs,
   char * serverFullOcspResponse,
   char ** merchantX509Certs,
   BID_ByteRangeWithData ** validation_result);

// Function handling building of visual seals, defined by merchant, called by BankID server in self assembler mode
typedef int(CALLBACKTYPE * BID_VisualSealBuilder)(int sessioncontext, int docnum,
   BID_ByteRangeWithData * pdfdata,
   BID_VisualSealCertData * visual_seal_cert_data,
   BID_ByteRangeWithData ** visual_seal_result);

Syntax

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

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.

Important changes from previous versions

New version of Visual Studio

From version 5.2 the Windows version of BankID C Server may require the Microsoft Visual C++ Redistributable for Visual Studio 2015  for the targeted platform (vc_redist_x64.exe or vc_redist_x86.exe) at runtime. 

Updated trust store certificate file names

The 5.2 release of the BankID C Server contain new versions of the pre-production and production trust-store certificates for BankID. These can be found in the release package under Certs/Va_ssl. It is important that these certificates are used when upgrading from a version prior to 5.2. The certificates can be placed in the chosen trust store folder for BankID C Server.

It is only the file names of the certificates that has been changed. These have been rehashed because BankID C Server version 5.2 is linked with OpenSSL 1.0.2k. Previous versions were linked with OpenSSL 0.98. The hash algorithm used for subject name hashing changed in OpenSSL version >= 1.0.0, and all certificate stores have to be rehashed when moving from OpenSSL 0.9.8 to 1.0.2k.

The rehasing can also be done manually on exising certificate files in the BankID C Server trust-store folder. OpenSSL must be available to be able to do this:

1. Execute the following OpenSSL command: openssl x509 –in “path to file” –hash –noout
2. Change the file name according to the output from the command. The output will be the new filename minus the ending “.0”, which must to be added manually. If more than one certificate get the same hash value “.0” must be replaced with “.1”, “.2” etc.

Example file names where the hash value output from the openssl command is 08b37ef3 for two certificates:

• Certificate 1: 08b37ef3.0
• Certificate 2: 08b37ef3.1