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: 2.16.578.1.16.1.9.1 Bank-stored end-user PERSONAL certificate 2.16.578.1.16.1.11.2.1 Bank-stored end-user EMPLOYEE certificate 2.16.578.1.16.1.12.1.1 Bank-stored end-user PERSONAL QUALIFIED certificate 2.16.578.1.16.1.13.1.1 Bank-stored end-user EMPLOYEE QUALIFIED certificate 2.16.578.1.16.1.12.2.1 Mobile end-user PERSONAL certificate example configuration value: 2.16.578.1.16.1.9.1, 2.16.578.1.16.1.11.2.1, 2.16.578.1.16.1.12.1.1, 2.16.578.1.16.1.12.2.1 OR ALL	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. The value ALL also means support for all future OIDs.
commtimeout OR vacommtimeout This will override the communication timeout value for that specific server sdmcommtimeout¹ mobilecommtimeout¹ servicehostcommtimeout¹	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 OR vaproxysettings This will override the httpproxysettings for that specific server mobileproxysettings² serviceHostproxysettings² sdmproxysettings²	<proxyhost>:<proxyport> e.g. 192.168.0.0:8080	Proxy host and proxy port separated by a ":". This parameter is NOT mandatory. If this parameter is provided then all HTTP and HTTPS traffic between BankID Server and the remote TAGSERVER, VA, ServiceHost and mobile infrastructure will be tunneled through this proxy.
httpproxyauth OR vaproxyauth² mobileproxyauth² servicehostproxyauth² sdmproxyauth²	<proxyuser>:<proxyuserpwd> e.g. isa:pwd	Proxy user and password separated by a ":".
logpropfilelocation	Example: C:\\log log4j.props (WIN) OR /opt/log/log4j.props (UNIX)	This property tells BankID Server to turn on logging, and which log property file to use for a dedicated merchant context.
loggername	Example: Merchant1Logger	This property is mandatory if the property logpropfilelocation differ from null. The value of this property tells BankID server what logger to use during logging for a dedicated merchant context.

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:

Java 1.8

http://docs.oracle.com/javase/8/docs/technotes/guides/security/crypto/CryptoSpec.html

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:

Java 1.6	http://docs.oracle.com/javase/6/docs/technotes/guides/net/properties.html https://docs.oracle.com/javase/6/docs/technotes/guides/net/http-keepalive.html
Java 1.7	http://docs.oracle.com/javase/7/docs/api/java/net/doc-files/net-properties.html http://docs.oracle.com/javase/7/docs/technotes/guides/net/http-keepalive.html
Java 1.8	https://docs.oracle.com/javase/8/docs/api/java/net/doc-files/net-properties.html https://docs.oracle.com/javase/8/docs/technotes/guides/net/http-keepalive.html

Browser not supported