3. Generic integration guidelines
When integrating the iDIN Software Libraries into your solution, the guidelines in the upcoming sections should be followed.
To be able to function, the library needs to have access to three certificates:
- Merchant’s certificate: This is the certificate owned by the Merchant. It’s the private certificate used to sign messages sent by the Merchant to the Acquirer's Routing Service platform. Its public key is also used by the Acquirer to authenticate incoming messages from the Merchant. The Merchant certificate must be in PKCS#12 format which has the extension .p12 or .pfx;
- The SAML certificate: This is the certificate owned by the Merchant. Its public key is used by the Issuer to encrypt information. The Merchant can then use the private key to decrypt that information. The SAML certificate must be in PKCS#12 format which has the extension .p12 or .pfx;
- The Acquirer’s (a.k.a. Routing Service’s) public certificate: This is the public certificate used to authenticate incoming messages from the Acquirer. The library only needs its public key. The public certificate must be in PEM format (base64 ASCII) and typically has the file extension .cer, .crt or .pem.
The certificate that is used to sign the messages (1), and the certificate that is used by the Issuer to encrypt information (2) may be the same certificate. Hence, depending on your preferences you can use two or the same certificate for both (1) and (2).
Certificates can be bought from a Certificate Authority, or they can be created yourself with for example OpenSSL. How to safely store and maintain certificates is beyond the scope of this manual. Examples to create a private key, public certificate and PKCS#12 file are provided below.
Note: The requirements on the certificates and more information about how these are used within iDIN can be found in the Merchant Implementation Guidelines in §10.3 - §10.6.
- The private key should never be shared with other parties
- This private key does not have to be loaded in the library directly
- The private key has a length of 2048 bit and in encrypted with a password
The following OpenSSL command can be used to create a private key:
openssl genrsa -aes128 -out YourPrivateKey.pem -passout pass:[password] 2048
Note: Please be wary when copying directly from this PDF document, some characters may not be properly copied causing the command to not work (e.g. wrong type of ‘-‘).
- The public certificate is created from the private key created earlier;
- The expiration period of the public certificate must be a minimum of 1 year, and a maximum of 5 years;
- When creating a public certificate, the user is asked to fill in information about the country name, state/province, city, organisation name, unit name, common name and email address. These parameters can be chosen at will;
- The public certificate(s) needs to be uploaded in the portal of the Routing Service;
- For the output the extension .cer has been chosen, however this may also be .crt or .pem.
The following OpenSSL can be used to create the public certificate
openssl req -x509 -sha256 -new -key YourPrivateKey.pem -passin pass:[password] -days 1825 -out YourPublicCertifiate.cer
Note: Please be wary when copying directly from this PDF document, some characters may not be properly copied causing the command to not work (e.g. wrong type of ‘-‘).
- The PKCS#12 contains both the private key and the public certificate, therefore it should also never be shared with other parties;
- The PKCS#12 files (Merchant/SAML certificates) should be imported in the Software Library;
- For the output the extension .p12 has been chosen, however this may also be .pfx.
The following OpenSSL can be used to create the PKCS#12 file:
openssl pkcs12 -export -out YourPKCS12File.p12 -inkey YourPrivateKey.pem -password pass:[password] -in YourPublicCertificate.cer
Note 1: Please be wary when copying directly from this PDF document, some characters may not be properly copied causing the command to not work (e.g. wrong type of ‘-‘).
By default, the library will try to load the certificates from the Certificate Store, using the fingerprints specified in the configuration. The library will first search the Local Machine store, followed by the Current User certificate store. To succeed, the host application's identity must have at least read permissions for the certificates.
Loading the certificates from locations other than the Certificate Store is possible as the Configuration class has several constructors taking in different versions of parameters, 3 of these constructors containing an optional parameter (implimenting the ICertificateLoader interface) that offers the option to inject a certificate loader, in order to adapt to differences in certificate management among OS types.
namespace BankId.Merchant.Library.AdvancedConfiguration
{
public interface ICertificateLoader
{
X509Certificate2 Load(string thumbprint);
}
}The package has the following noteworthy files:
- BankId.Merchant.Library.dll: This file is the actual library, which can be used to integrate into the code. More details in the next paragraph;
- BankId.Merchant.Library.deps.json: The deps.json file is a dependencies manifest. It can be used to configure dynamic linking to assemblies that come from packages.
First, an existing project is required (for example, an ASP.NET web site, or a simple C# Console Application) into which the library can be added. Then, unpack the library files into a designated folder. A subfolder of your project would be a good choice.
Acquirer’s second certificate (advanced use)
When Acquirers changes its certificate (this happens once every few years), the Merchant must configure the new certificate in the software library. If absolutely no downtime is allowed for changing the certificate in the software library a second certificate can be configured. The .NET Core library has added support to authenticate the incoming messages with two certificates. The second certificate can be registered in the same way as the first one (i.e. in the configuration file or from code). The library can check if a message was authenticated with one of these two certificates. This ensures continuous usage of the application when the Acquirer changes its certificate.
iDIN requires TLS 1.2 for communication or higher. Older versions of TLS/SSL are not supported due to security requirements. Therefore, the TLS 1.2 security protocol must be configured on the application. This can be done by adding the following code snippet into the application’s startup file (Program.cs or Startup.cs):
ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls12;After that, you need to provide the configuration settings in either the App.config or Web.config of your project. Below is an example that shows how to do that in Visual Studio:
Create a configuration section and change settings as needed (this screenshot shows only an example):
The library is now ready to perform requests. Chapter 5 in this manual provides more information on how to perform these operations.
The following code snippet can be copied/pasted into a new console application project to start using the library right away. Make sure the namespace and class names are equal to the names chosen when the project was set-up, and change the configuration settings as necessary (check Section 4.2 in this manual for more information about specific settings):
using System;
using System.IO;
using BankId.Merchant.Library;
using BankId.Merchant.Library.AppConfig;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Configuration.FileExtensions;
using Microsoft.Extensions.Configuration.Json;
using Microsoft.Extensions.Configuration.Binder;
namespace MyBankIDConsoleApplication
{
class Program
{
static void Main(string[] args)
{
var builder = new ConfigurationBuilder()
.SetBasePath(Directory.GetCurrentDirectory())
.AddJsonFile("appsettings.json");
var config = builder.Build();
var applicationConfig = config.GetSection("iDIN.Merchant.Library.Settings").Get<ApplicationSettings>();
var bankIdConfig = new Configuration(
applicationSettings:applicationConfig,
certificateLoader:null);
var communicator = new Communicator(bankIdConfig);
var directoryResponse = communicator.GetDirectory();
if (directoryResponse == null)
Console.WriteLine("Directory Response is null");
if (directoryResponse.IsError)
{
Console.WriteLine(String.Format("Received ErrorCode: {0}", directoryResponse.Error.ErrorCode));
Console.WriteLine(String.Format("Received ErrorDetails: {0}", directoryResponse.Error.ErrorDetails));
Console.WriteLine(String.Format("Received ErrorMessage: {0}", directoryResponse.Error.ErrorMessage));
return;
}
foreach (var issuer in directoryResponse.Issuers)
{
Console.WriteLine(issuer.Country + " " +
issuer.Id + " " +
issuer.Name);
}
Console.ReadLine();
}
}
}