Encrypted web service requests

For Nexus Card SDK 5.5 and later, see Set up SSL connection to Card SDK by uploading PKCS#12 file instead.

If your application and the Card SDK runs on the same machine there is no need for a secure channel between them. However, the requirement for a secure channel may change when your application and the Card SDK runs on separate machines. The typical use case is a separate PC for production. For
this purpose, the Card SDK uses HTTP Secure (HTTPS) which combines HTTP on top of the SSL/TLS layer. It is the straightforward approach for a secure channel of the used SOAP and REST web service.

In this article we distinguish between:

An only encrypted communication, here named SSL with unidirectional authentication. This also implies server authentication to prevent the problem of man-in-the-middle attacks which would impede the intention of an encrypted communication.
An encrypted communication that uses client authentication in addition, here named SSL with mutual authentication.

The Card SDK offers both features. However, the typically used way is only encrypted communication (SSL with unidirectional authentication). It depends on your requirements which feature to use.

Prerequisites

Be familiar with the technology of SSL and used X.509 certificates.

Certificates

The SDK's SSL implementation to offer unidirectional and mutual authentication uses four X.509 certificates. The SDK provides them as templates:

For SSL with unidirectional authentication:
- The Web service's root certificate IDProductionServiceRootCert.pem.
- The derived server certificate IDProductionServiceCert.pem.¹

Only the latter is actually accessed by the SDK. Its root certificate is provided to be used from your application or within Windows to guarantee a valid certificate chain.

For SSL with mutual authentication:
- A client's root certificate IDProductionServiceClientsRootCert.pem.
- A derived client certificate IDProductionServiceClientCert.pem.²

Only the root certificate is actually accessed by the SDK to validate the certificate of a request. The latter is provided to be used by your application.

The certificates are located in the system directory of the SDK. When they are found with the names mentioned above, SSL is immediately available.

¹ Unlike usual BASE64 encoded certificates, IDProductionServiceCert.pem also contains the private key, just appended to the certificate definition. The IDProductionService requires the file in this way.
² The certificate is in addition provided as PKCS#12 package (IDProductionServiceClientCert.p12) containing its private key as well. The package's password is 123456.

How to use an encrypted request

An encrypted request is done by specifying an endpoint that uses

https instead of http.
the standard IDProductionService port number incremented by one.
the corresponding host name as the endpoint typically does not refer to localhost.

That means an URL to access the service may change from http://localhost:54880 to https://IDBox1002:54881.

When developing an application that uses the SDK with SSL requests, we recommend to start developing an application in the usual way using unencrypted requests.

Configuration

The following configuration of the SDK's IDProductionService is required:

SSL with unidirectional authentication is immediately available after SDK installation. If you replace the delivered service certificate by an own one, the SDK will recognize this as it cannot be opened using the standard password. You can configure the password starting the Configuration Manager. The user is automatically asked to enter the password.¹
SSL with mutual authentication needs to be activated. The reason is, that after activating this mode, the unencrypted mode is no longer available. When requiring client authentication, an unencrypted and unauthorized access would impede this goal. After activation, only the wsdl may be requested by an unencrypted request. This allows IDEs and tools a wsdl access without enforcing them to authenticate (which is not necessary and often only possible with difficulty). The activation is done by providing the certificates with the above mentioned file names in the SDK's system directory. For this reasons, the service's clients root certificate is initially provided with the name IDProductionServiceClientsRootCert(disabled).pem, just to make it "invsible" with its real name.¹

¹The SDK does not offer an own user management. However, it is typically (and recommended to be) installed below the Windows ProgramFiles directory. That means, its binaries and certificates are write-protected and the provisioning of new certificates is reserved for users owning administrator rights. Please consider these facts when administrating the system's users.

How to use Windows Certificate Store

You must do some preparation when developing applications which use Windows's Certificate Store. Examples of such applications are those which use .NET, JavaScript with Internet Explorer or C/C++ using the WinINet API. The configuration is necessary at each client.

SSL with unidirectional authentication
Add IDProductionService's root certificate to Windows's store of Trusted Root Certification Authorities.² Note that there are security consequences adding a certificate to this store.

SSL with mutual authentication
Add the client certificate to Windows's store of Personal certificates. As the private key is required in these certificates, add the provided PKCS#12 package which contains certificate and private key (IDProductionServiceClientCert.p12 ).

²To reach the certificate configuration, go to Internet Explorer > Internet Options > Content and click Certificates.