This document describes upgrade from 5.1.x to 5.3.2.

New functionality

The new version, 5.3.2 is not neccesarily backward compatible, this is due to

1. upgrade from Java 1.6 to Java 1.8
2. upgrade bouncycastle version to 1.60

Except for these changes, the changes are of internal character or just extensions. Existing applications should be compilable and runnable as is.

Changes in this upgrade are mainly concering PAdES support in BankID server and of course the BankID infrastructure.

In the 5.2.0 version, the CMS generated for merchant for format PKCS7_ISO320001 contained a nonce, this is removed. 

Are errors concerning nextUrl setting when client uses callback and need for generating merchantref in mobile signing fixed, or other known errors in 5.2.0 maybe ?

EnvOverride

The envOverride class has changed. This is a class which is normally never used by merchants, since they use either the PreProduction or the Production environment.

For internal BankID developers, changes in this class may be of interest.

PAdES support

BankID Server 

The 5.2 version of BankID J Server introduces new varaiables to the BIDSessionData class. The new variables provide the possibility to specify CMS (PKCS#7) and OCSP response formats to be used during a Sign operation. The new formats are introduced to enable creation of PAdES compatible PDF Signatures, and should generally not be used in other signing scenarios. 

Authentication transactions will allways use the original default BankID formats. Any formats set in BIDSessionData will be ignored for such transactions.

The formats must be set in the session data before calling initTransaction. They will be passed along to the COI through the web client, and will also be used in BankID J Server during verifyTransactionRequest.

Details about the new enum classes and their values, and the changes to BIDSessionData, can be found in the subsequent sections.

The BankID server 5.3.2 version adds functionality that make it possible to create complete PAdES with a minimum of work in the merchant code. Extentions to the known "initSign","verifySign" signing flow are introduced to create PAdES'es.

The merchant may let BankID create Visual seals for the merchant and the endUser, or the merchant may be a so called selfAssembler, which generates the graphics himself and let BankID do the signing only.

The  merchant may let BankID create signature validation data in the PAdES or the merchant may do this himself, in which case BankID server supports the merchant with certificates and validation information about each.

BankID does not add timestamps to the PAdES, so if a timestamp incremental update shall be added to the PAdES, the merchant must do this himself, this may be done as a part of the merchants validation handling.

How to use the new functionality are detailed in the quick start guide and the Using BankID Java Server

ClientProxy

To support the new BankID server the ClientProxy has been updated. If the merchant is running an instance of the ClientProxy component, this must be updated.

New structures and methods for PAdES handling

CMSFormat (Enum)

OCSPFormat (Enum)

BIDSessionData

SerialSigningProperties

Property describing what role the merchant plays during serial signing, turnkey or selfassembler. This count for all documents to sign.

bidSessionData.setSerialSigningProperties(SerialSigningProperties.turnKey().withSelfAssembledValidation());

SigningKind

An element of  DocumentToSign, used to set signingmode on document, i.e. serial,serialEndUserOnly for PAdES and parallel for non PAdES

Must be set on each document, therefore the BIDSessionData::addPDFDocument returns the document added to make it easy to set the serial signing kind.

bidSessionData.addPDFDocument(pdfBytes,description).setSigningKind(SigningKind.serialEndUserOnly);

ByteRange and ByteRangeWithData

These are supportclasses for selfassemblers for holding incremental updates, see JavaDoc or examples 

New PAdES support methods in BIDFacade:

The selfAssembler methods all defines a callback function which the merchant must implement.

BIDFacade::initTransactionSelfAssembler // same as initTransaction but for merchants creating their own visual seals
BIDFacade::verifyTransactionRequestSelfAssembler // same as verifyTransactionRequest but for merchants creating their own validation incremental update
BIDFacade::initSignSignMerchantSeal // support method needed for turnkey PAdES visual seal building
BIDFacade::initSignBuildEndUserSeal // support method needed for selfAssembler PAdES visual seal building
BIDFacade::verifySignAddDSS // support method needed for turnkey PAdES validation building

New PAdES operations that must be handled

New operations had to be introduced to support an extended interplay with BankId server and ClientProxy. 

"initSignSignMerchantSeal" – turnkey seal only

"initSignBuildEndUserSeal" – selfassembler seal only

"verifySignAddDSS" – turnkey validation only

Extracting the complete PAdES in the merchant

A new operation on DocumentToSign has been added to support this. The method assembles the pdf as far as it has been produced and returns the PAdES.

DocumentToSign::getSignedDocumentBytesIncludingIncrementalUpdates()

Removed functionality

Functionality related to BankID 1.0 has been discontinued. In relation to this discontinuation, the following functions have been removed in version 5.2:

• getTag
• getLauncherURI

Support for validating the legacy BankID SDO format has also been removed in version 5.2. This affects the method validateSDO, which from now on only supports validation of SEID SDO’s.