This page describes the BankID Open B2B packaging, ie. a set of documentation, tools and example code on how to use BankID merchant certificates in business-to-business scenarios. An Open B2B BankID consists of industry compliant X.509 certificates, and can be used without the need for installed BankID software. The target audience of this document is merchant project teams: Technical personnel designing and coding the use of BankID Open B2B. The rest of this document is organized as follows:

Concepts and abbreviations

BankID Open B2B scenarios

An Open B2B BankID is a standard X.509 certificate and can be used in many ways. However, there are a couple of use cases that are especially relevant. Both use cases relates to signing data sent from merchant A to merchant B. Sending data signed with an Open B2B BankID ensures that the receiver can verify that:

• The data are not changed under transport.
• The identity of the sender is genuine and non-reputable. 

There are two scenarios for verifying data integrity and sender identity. Both implies that the signature itself is validated, this is done offline by the receiver. Further, to be sure the signature is made with a valid BankID, the status of the signing BankID must be verified online with BankID VA.

For both scenarios it is the merchant verifying BankID status that are charged for the status check.

Scenario: Sender verifies BankID status

When merchant A checks its own BankID status with BankID VA (2), merchant A will get a signed OCSP response in return. The OCSP response is sent to merchant B together with the data and the signature itself. Merchant B must validate, offline, both the signature (4) and the OCSP response's signature (5).

Scenario: Receiver verifies BankID status

Merchant B checks merchant A's BankID status with BankID VA (4).

Comparison of scenarios

The two most important factors to be considered when choosing between these two scenarios are therefore:

• Which merchant should be charged for the status checks?
• Which merchant shall integrate with BankID VA?

Another aspect to consider is the long term validity of the BankID status check, which is better with the "sender verifies" approach. This is because the status check is performed at the time of signing. If the signing BankID is revoked later, the OCSP response still shows the BankID was valid at time of signing. This difference is subtle, but may be a concern if the receiver, Merchant B, performs the status check long time (relatively) after Merchant A has sent the data. This can be relevant in batch oriented systems.

Example code

Example code supporting both the usage scenarios and the Open B2B BankID lifecycle are located in BankID Norge's GitHub repository, on the master branch. There are lifecycle examples both with Java's keytool and OpenSSL. The usage examples are in Java.

BankID lifecycle overview

This chapter describes the lifecycle of an Open B2B BankID. Online tools and/or example code required in each phase of the lifecycle are also referenced here.

Create

Order

The first step to create a fully functional (active) BankID is to submit an order to the originator's BankID RA. Inputs to the order are the merchants organization name and Common Name for the BankID. The order results in an activation URL and a shared secret, both to be used for activation of the BankID, see next chapter.

PREPROD

Self-service BankID RA is available at BankID RA PREPROD. Kontaktinfo for å få user/pass?

PROD

Production BankIDs must be ordered from a reseller or from BankID Norge. Link/referanse til hvor det er beskrevet.

Activate

Before the BankID can be used it must be activated. This means acquiring a X.509 certificate with the merchant's CommonName coupled to the merchant's public key, where the corresponding private key is known to the merchant only. This is done by:

1. Create a private/public key pair. See example code in BankID Norge's GitHub repository.
2. Use the private/public key pair to create a CSR for each of the two certificates a BankID consists of. Se example code in BankID Norge's GitHub repository. 
3. Submit the CSRs to Sky-MAT, together with the activation URL and shared secret from the BankID order.

There are some requirements to the CSRs. If the CSRs do not conform to these, the activation will be rejected by Sky-MAT. The requirements are:

• Use two different private/public key pairs for the two CSRs (authentication/signing).
• Never use the same set of private/public key pairs for CSRs for two different BankIDs. Dette er ikke på plass pr i dag, løses i NFOI-732 - Getting issue details... STATUS
• The Common Name in the CSRs MUST be the same as in the BankID order. 

The result of a successful activation is a standard X.509 certificate chain, one for authentication and one for signing purposes. The format of the chain is PKCS#7. The merchant's certificate is the end entity of this chain. The merchant's certificates has key usage:

• Authentication: Digital Signature, Key Agreement
• Signing: Non Repudiation

PREPROD

Self-service activation tool is available at BankID Open B2B Sky-MAT PREPROD.

PROD

Self-service activation tool is available at BankID Open B2B Sky-MAT PROD.

Create keystore

The last step before the BankID can be used for authentication/signing purposes is coupling the X.509 certificate with the merchant's private key and save it in a keystore. See example code in BankID Norge's GitHub repository how to do this. Also see appendix A for details about keystore usage.

Test

The Open B2B BankID can be tested with the integration tests found in BankID Norge's GitHub repository.

Use

Typical tasks in the usage scenarios are:

• Sign data to be sent to another merchant
• Get signed status check of BankID
• Create detached signature: Package merchant signature and status check into a Cryptographic Message Syntax (PKCS#7) format
• Send data and detached signature to another merchant
• Check validity of senders BankID

Example code for all these tasks are found in BankID Norge's GitHub repository.

Renew

The BankID expires after 4 years. Before this happens the BankID must be renewed.

PREPROD

Self-service renewal is not supported yet.

PROD

Production BankIDs must be renewed through a reseller or BankID Norge. Link/referanse til hvor det er beskrevet.

Revoke

If a BankID is not to be trusted anymore because it's integrity is broken, it must be revoked.

PREPROD

Self-service BankID RA is available at BankID RA PREPROD. Kontaktinfo for å få user/pass?

PROD

Production BankIDs must be revoked through a reseller or BankID Norge. Link/referanse til hvor det er beskrevet.

Appendix A: Keystores and trust

For general guidance how to use Java trust stores, see the X509TrustManager chapter in Java Secure Socket Extension (JSSE) Reference Guide.

Trust stores

BankID CA trust

Data sent from one merchant to another is signed with a merchant BankID. Verifying such signatures requires that the BankID root Certificate Authority (CA) is registered as a "trust anchor", see TrustAnchor chapter in Java PKI Programmer's Guide.

The example code loads the trust anchor from a hardcoded BankID root CA certificate.

BankID VA (OCSP responder) trust

BankID status online check is done with an OCSP request to the VA. Verifying the OCSP response requires the VA's certificate to be registered as "OCSP responder certificate".

The example code loads the OCSP responder from a hardcoded VA certificate. Denne mangler for PROD i eksempelkoden.

BankID VA SSL trust

BankID status online check is done with an OCSP request to the VA over Secure Socket Layer (SSL). The SSL-certificate for VA is issued by the BankID root Certificate Authority (CA). 

The example code loads the BankID root CA certificate into the JSSE-stack from a Java keystore.

Merchant Open B2B keystore

When signing data (which can be arbitrary data for sending to another merchant or a VA OCSP request) a merchant must use it's private key.

The example code loads the merchant certificate and private key from a Java keystore.

Change log