Integration of BankID Java Server with merchant applications
- Christoffer Normannsen
BankID Java Server is a java library. Include the bidjserver-X.X.X-dist.jar plus the files mentioned in chapter 2.1.1 in your application's classpath. The X.X.X here symbols the current version number. BankID server since 5.2.x demands Java 1.8.
Configuration of BankID Java Server
BankID-enabled application is an application that performs BankID operations on behalf of one or several merchants. This means that this application may load/register more than one merchant context in BIDJSERVER. Each merchant context is uniquely identified by a merchant name.
NB!
Trying to load two merchant contexts with the same name will not work. The last context loaded will override all the other configurations with the same merchant name. The name should be a unique identifier (label) .
A merchant context in BIDJSERVER may be configured by doing one of the following:
- Creating a BankID properties-file for each merchant
- Register each merchant context via the BankID Server API
Using property files
To configure a merchant context in BIDJSERVER using a property-file you have to follow these simple steps:
- Create a property-file named <merchantname>.props. The .props extention is mandatory. The name of the .props-file is the same name passed to BIDJSERVER. If the BankID-enabled application is configuring several merchants then it is of outmost importance that the name of the file uniquely identifies the merchant (e.g. UniqueMerchantName.props).
- The newly created <merchantname>.props file may contain the following entries:
Name of property | Example value of property | Description |
|---|---|---|
keystorefile | /opt/merchant/merchant.bid | This property tells BankID Server which keystore to use for a dedicated merchant context. It is recommended that the fully qualified path to the file is set. If you only provide the name of the file (e.g. merchant.bid) then this file MUST be present in your application's classpath. |
webaddress | www.merchant.com,192.123.12.2 | The DNS name of the Merchant web server comma separated with all IP addresses that resolve to this DNS name. |
tokenuserpin | some password | If the merchant has its private keys stored in a HSM then the merchant must provide the tokenuserpin. This value is the PKCS#11 password used to log into the HSM. |
grantedpolicies | Supported BankID Certificate Policy OIDS: | This parameter is mandatory for each merchant context configured in BankID Server. The value tells BankID Server which BankID Certificate types to grant access to for a given merchant. This value MUST be a comma-separated list of policy OIDs or the value ALL. |
commtimeout This will override the communication timeout value for that specific server sdmcommtimeout1 | 20000 (20 seconds) | Communication timeout value in MILLISECONDS. This parameter is optional. If this parameter is not set then BankID Server defauls to 10000 milliseconds (10 seconds). This value is the timeout value for the BankIDServer communication with internal COI components. |
httpproxysettings This will override the httpproxysettings for that specific server mobileproxysettings2 | <proxyhost>:<proxyport> | Proxy host and proxy port separated by a ":". |
httpproxyauth | <proxyuser>:<proxyuserpwd> | Proxy user and password separated by a ":". |
logpropfilelocation | Example: | This property tells BankID Server to turn on logging, and which log property file to use for a dedicated merchant context. |
loggername | Example: | This property is mandatory if the property logpropfilelocation differ from null. |
Example BankID Server configuration file
######################################################################## # # THE NAME OF THIS FILE IS petshop.props. THIS MEANS THAT THE MERCHANTNAME # IN BANKID JAVA SERVER WILL BE “petshop”. # ########################################################################## # BE SURE THAT THE PROCESS IN WHICH BIDJSERVER RUNS HAS WRITE ACCESS TO # THE GIVEN LOCATION AND FILE keystorefile=/opt/petshop/petshop.bid # THE DNS SERVER OF PETSHOP’S WEBSERVER COMMA-SEPARATED WITH ALL IP- # ADRESSES THAT RESOLVE TO THIS DNS NAME webaddress=www.petshop.com,192.178.22.1,192.178.22.2 # THE GRANTEDPOLICIES CONFIGURED TELLS THAT THE PETSHOP WEB-APPLICATION # ONLY SUPPORTS BANK-STORED BANKID CERTIFICATE (PERSONAL AND EMPLOYEE) grantedpolicies=2.16.578.1.16.1.9.1, 2.16.578.1.16.1.11.2.1 # CURRENT OIDS #POLICY_OID_SOFT_MERCHANT = "2.16.578.1.16.1.6.1.1"; #POLICY_OID_HSM_MERCHANT = "2.16.578.1.16.1.6.2.1"; #POLICY_OID_NETCENTRIC_PERSONAL = "2.16.578.1.16.1.9.1"; #POLICY_OID_NETCENTRIC_EMPLOYEE = "2.16.578.1.16.1.11.2.1"; #POLICY_OID_NETCENTRIC_QUALIFIED_PERSONAL = "2.16.578.1.16.1.12.1.1"; #POLICY_OID_NETCENTRIC_QUALIFIED_EMPLOYEE = "2.16.578.1.16.1.13.1.1"; #POLICY_OID_MOBILE_PERSONAL = "2.16.578.1.16.1.12.2.1"; #ALL THE ABOVE = ALL # THE PROPERTIES BELOW ARE COMMENTED OUT BECAUSE THE SERVER RUNNING # BIDJSERVER HAS DIRECT ACCESS TO THE INTERNET. #httpproxysettings=proxy1:8080 #httpproxyauth=username:passwd #mobileproxysettings=proxy2:8080 #mobileproxyauth=username:passwd # IF THE MERCHANT HAS ITS PRIVATE KEYS STORED IN A HARDWARE SECURE MODULE # (HSM)THEN BANKID SERVER NEEDS A PASSWORD TO LOGIN TO THE DEVICE (ALSO # CALLED A TOKEN). tokenuserpin=123456 # COMMUNICATION TIMEOUT VALUE IN MILLISECONDS. THIS CONFIG PARAM IS # OPTIONAL. IF THIS PARAMETER # IS NOT SET THEN BANKID SERVER DEFAULTS TO 10000 MILLIS (10 SECONDS). # THIS VALUE IS USED IN BOTH # THE BANKIDSERVER-MOBILEGATEWAYAND # THE BANKIDSERVER-VA COMMUNICATION. # commtimeout=10000 # IF YOU WOULD LIKE TO TURN ON LOGGING FOR THIS MERCHANT, UNCOMMENT # THESE PROPERTIES AND CREATE A LOG PROPERTY FILE AS DESCRIBED BELOW # logpropfilelocation=/opt/log/log4j.props # loggername=Merchant1Logger
Example of log4j properties file for BankID Server
log4j.category.Merchant1Logger=DEBUG, merchant1file
log4j.additivity.Merchant1Logger=false
log4j.configuration.delay=100
log4j.appender.merchant1file =org.apache.log4j.DailyRollingFileAppender
log4j.appender.merchant1file.File=/opt/log/Merchant1.log
log4j.appender.merchant1file.layout=org.apache.log4j.PatternLayout
log4j.appender.merchant1file.layout.ConversionPattern=%d{yyyy-MM-dd HH:mm:ss,SSS} %x [%p] [%C{1}.%M] %m%n
Using the BankID Server API
How to register a merchant context in BIDJSERVER using the API methods is detailed in the code excerpt in section Using BankID Java Server. In short you have to provide the information present in the above properties files to API methods.
Additional Configuration
In BankID authentication and signing processes merchant applications need initialize the BankID on mobile auth or signing process, and get the end-user's certificate status. In all these cases BankID Server needs to contact the remote BankID applications.
To be able to use the BankID Server, a .bid file must be generated. The generation of bid-files are beyond the scope of this document, but a detailed description is provided in the HAT User Guide [HAT].
SSL Configuration
When communicating with the remote BankID applications BankID Server contacts them via the Secure Socket Layer (SSL). The SSL-certificates are issued by the BankID root Certificate Authority (CA).
The BankID Java Server has the BankID root CA certificate hardcoded, and will during startup create an SSL truststore using this certificate. If this for some reason should fail, the merchant applications need to trust the BankID root certificate(s).
If logging is configured and the following lines are written to the log during startup of the BankID Java Server the merchant application have to create the SSL truststore as described below:
------------------------------------------------------------------ Exception caught creating SSL trustore. Exception: java.security.NoSuchProviderException Exception message : No such provider: IBMJSSE2 Tried to initialize TrustManagerFactory using algorithm [IbmX509] Tried to get KeyStore instance using [jks] Merchant application then need to update jssecacerts!!!!! ------------------------------------------------------------------
The BankID root certificate for the pre-production and production environments are located in the "Cert" directory on the release CD:
If the merchant application is configured to run in the pre-production environment then the "PreProd_RootCA.crt" certificate must be imported into the "jssecacerts" truststore located under the applications JRE directory:
- <JAVA_HOME>/jre/lib/security/jssecacerts
To create the "jssecacerts" truststore use the keytool program located under <JAVA_HOME>/bin directory and type the following command:
- keytool –import –trustcacerts –alias <some alias> -file <path>/PreProd_RootCA.crt –keystore jssecacerts
Do the same for the production BankID root certificate if running in the production environment.
Unlimited Strength Java(TM) Cryptography Extension
Due to export control restrictions in the US, the version of JCE policy files that are bundled in the J2SDK environment allow "strong" but limited cryptography to be used.
The communication between the BankID client and the BankIDServer uses AES encryption with 256bits keysize. Therefore the Unlimited Strength Java(TM) Cryptography Extension Policy Files need to be downloaded and installed.
More information on the following URLs:
Configuration for the use of HSM stored keys
It is important that programmers implementing the merchant application are aware of the following:
- BankID Server supports the PKCS#11 interface and therefore requires that the merchant HSM supplies a PKCS#11 driver/adapter. Even if an HSM has a PKCS#11 driver it is not given that BankID Server works with this HSM. HSM vendors are free to implement subsets of the PKCS#11 interface, if the PKCS#11 driver does not expose the required PKCS#11 methods that BankID Server uses, then the use of the HSM will fail.
BankID Java Server is tested with the following HSMs:
- SafeNet Luna SA v3.1 (PKCS#11 driver: cryptoki.dll)
- SafeNet Luna PCI-7000 (PKCS#11 driver: cryptoki.dll)
- SafeNet Luna SA v3.1 (PKCS#11 driver: libCryptoki2_64.so)
HTTP Client Configuration
BankID Java Server uses Google HTTP Client for HTTP communication, with the standard Java HTTP low-level transport based on the java.net package as implementation. This implementation supports persistent connections (also called keep-alive). Persistent connections properties, and other networking properties, can be configured through system properties.
More information can be found on the following URL's: