Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Table of Contents
outlinetrue
stylenone

Concepts and abbreviations

Concept/abbreviation 
BankID CABankID Certification Authority: The originator's system for issuing BankIDs.
BankID RABankID Registration Authority: The originator's system for handling the lifecycle of BankIDs.
BankID VABankID Validation Authority: The originator's system for online checking the revocation status of a BankID.
CN

Common Name: A field in the X.509 certificates of an BankID identifying the merchant.

CSRCertificate signing request: A request for a BankID CA to sign a certificate stating that the Common Name of an merchant is coupled to a BankID (i.e. coupled to a specific public/private key pair).
OCSPOnline Certificate Status Protocol.
OriginatorIssuer of an BankID.
Sky-MATMAT = Merchant Activation Tool: Online service for activating an Open B2B BankID.

Anchor
usage_scenarios
usage_scenarios
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:

...

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

Gliffy Diagram
size600
nameBankID Open B2B sender verifies status scenario

Scenario: Receiver verifies BankID status

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

Gliffy Diagram
size600
nameBankID Open B2B receiver verifies status scenario

Comparison of scenarios

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

...

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.

Gliffy Diagram
size600
nameBankID Open B2B lifecycle overview

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

A self-service BankID RA in preprod is available to issue BankID merchant certificates for testing. Note that this tool optionally support immediate activation of the certificate. Activation may also happen as a separate step via the Sky-MAT tool

PROD

Production BankIDs must be ordered from a reseller or from BankID Norge.

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:

...

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

PREPROD

A web-based activation tool Sky-MAT for pre-preprod certificates is available at BankID Open B2B Sky-MAT PREPROD.

PROD

A web-based activation tool Sky-MAT for production certificates 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

Renewal of preprod certificates is currently not supported via the Sky-MAT tool. Please use the legacy Java-based HAT tool for this.

PROD

Renewal of production certificates is currently not supported via the Sky-MAT tool. Please use the legacy Java-based HAT tool for this.

...

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

PREPROD

Please use the self-service BankID RA in preprod to revoke BankID merchant certificates for testing. 

PROD

Please contact the your reseller or BankID Norge to revoke a BankID merchant certificate in production. 

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.

...