How to Understand Secure Connections

It’s recommended to use secure connection via TCP/IP environment. It’s recommended to transfer payment data only on secure connection.

Mutual Authentication Secure Connection

There is a hardware secure module in the terminal. The hardware secure module support several important security features for secure connections:

• Mutual authentication SSL
• Force using TLSv1.2 protocol.
• The private key of the terminal is stored in hardware security module of the terminal.
• The trusted certificates of the server are also stored in the hardware security module.
• Remove un-secure algorithm in SSL connection, include MD5, SHA1, RC4…
• Limit the session timeout.

Trusted Store Management

The certificates in the trusted store should be authenticated by the acquirer’s root public key in the certificate or vendor’s terminal root public key which is embedded in the firmware of the security module. So all the trusted server certificate must be signed by acquire or vendor before injecting by the HSM management API.

Hardware SSL Configuration

Issue Client Certificate. The initializing application should get the CSR of the terminal, which is generated by the internal RSA private key of the hardware secure module. Then the CSR should be submitted to CA and get the relevant certificate. This client certificate should be injected to the hardware secure module with proper alias. Import Server Certificate. The server certificate should be injected to the hardware secure module as the trusted certificate. This certificate should be signed by terminal acquirer’s private key.

Quick SSL and HTTPS Demo via Provider

This method will only affect the connection in current application. It is recommend to be used in new projects. Prepare KeyManager and TrustManager : Prepare the customized KeyManager to configure which terminal public key to use. Prepare the customized TrustManager if you want to get the information of the server certificates:

    private class AliasKeyManager implements X509KeyManager {
        private String mAlias;
        private AliasKeyManager(KeyStore ks, String alias, String password) {
            this.mAlias = alias;
        }
        public String chooseClientAlias(String[] str, Principal[] principal,Socket socket) {
            return this.mAlias;
        }
        @Override
        public String chooseServerAlias(String keyType, Principal[] issuers,Socket socket) {
            return null;
        }
        @Override
        public X509Certificate[] getCertificateChain(String alias) {
            return null;
        }
        @Override
        public String[] getClientAliases(String keyType, Principal[] issuers) {
            return null;
        }
        @Override
        public String[] getServerAliases(String keyType, Principal[] issuers) {
            return null;
        }
        @Override
        public PrivateKey getPrivateKey(String alias) {
            return null;
        }
    }

    private class TestTrustManager implements X509TrustManager {
        public java.security.cert.X509Certificate[] getAcceptedIssuers() {
            return null;
        }
        @Override
        public void checkClientTrusted(
                java.security.cert.X509Certificate[] chain, String authType) throws CertificateException {
        }
        @Override
        public void checkServerTrusted(java.security.cert.X509Certificate[] chain, String authType) throws CertificateException {
            // The server certificates are already authenticated by HSM.
            // You can do more business logic to the server certificates here.
            for (X509Certificate x509c : chain) {
                Logger.debug("checkServerTrusted chain,length=" + chain.length + ",content=\n" + x509c.toString());
            }
        }
    }

Use SSL Socket: Use the proper security provider “HSMTLS” and proper public key alias to use the keys and certificates stored in HSM:

            KeyManager[] keyManagers = 
new KeyManager[]{new AliasKeyManager(null,"terminal_pub", null)};
            TrustManager[] trustManager = new TrustManager[]{new TestTrustManager()};
            SSLContext context = SSLContext.getInstance("TLSv1.2", "HSMTLS");
            context.init(keyManagers, trustManager, null);

            SSLSocketFactory factory = context.getSocketFactory();
            SSLSocket socket = (SSLSocket) factory.createSocket(serverIP, port);

Use HTTPS: Use the proper security provider “HSMTLS” and proper public key alias to use the keys and certificates stored in HSM:

            KeyManager[] keyManagers = new KeyManager[]{new AliasKeyManager(null, "terminal_pub", null)};
            TrustManager[] trustManager = new TrustManager[]{new TestTrustManager()};
            SSLContext context = SSLContext.getInstance("TLSv1.2", "HSMTLS");
            context.init(keyManagers, trustManager, null);
            
            URL sslURL = new URL(url);
            HttpsURLConnection con = (HttpsURLConnection) sslURL.openConnection();

The terminal public key alias “terminal_pub” is depends on the certificate of terminal’s public key, which should be authenticated by Server. It may be different for each different server.

Quick SSLSocket and HTTPS Demo via Property

This method is old version, but it will affect the global environment. It is recommended not to be used in new projects. Use SSL Socket: Setup the two system properties, the connection socket as the normal SSL connection. For example:

        System.setProperty("javax.net.ssl.keyStoreProvider", "SunPKCS11-wizarpos");
        String terminalPublicCertAlias = "terminal";
        System.setProperty("javax.net.ssl.certAlias", terminalPublicCertAlias);
        try {
            SSLContext sslContext = SSLContext.getInstance("TLS");

Use HTTPS: Similar as SSL Socket usage, setup the two system property, the connection socket as the normal HTTPS connection. For example:

        System.setProperty("javax.net.ssl.keyStoreProvider", "SunPKCS11-wizarpos");
        String terminalPublicCertAlias = "terminal";
        System.setProperty("javax.net.ssl.certAlias", terminalPublicCertAlias);
        HttpPost httpPost = new HttpPost(strURL);

The terminalPublicCertAlias is depends on the certificate of terminal’s public key, which should be authenticated by Server. It may be different for each different server.

Secure Configurations

Key Management. When the developer using the secure connections, the secure connection use mutual authentication. The host authenticate the terminal’s certificate relevant to the certAlias, which is issued by the CA in the truststore of the host. The terminal authenticates the host’s certificate by the communication root certificate stored in the hardware secure module. Both host’s certificate and the terminal certificate is stored as X509 certificate format. Session Management. The session timeout is limited by SSL module in terminal. The default value of the session timeout is 5 minutes and it’s un-changeable manually or by API.