Understand Secure Connections

Recommended Practices for Secure TCP/IP Connections

It is advised to always use a secure connection for transmitting payment data. This ensures data protection and integrity during transmission.

Mutual Authentication and Secure Connection

Our terminals are equipped with a hardware security module that enhances secure connections through the following features:

• Mutual authentication using SSL.

• Mandatory use of TLSv1.2 protocol.

• Storage of the terminal's private key within the hardware security module.

• Trusted server certificates are also stored in the hardware security module.

• Elimination of insecure algorithms in SSL connections, including MD5, SHA1, RC4, etc.

• Limited session timeout duration for added security.

Trusted Store Management

Certificates in the trusted store must be authenticated either by the acquirer's root public key or the vendor's terminal root public key, which is embedded in the firmware of the security module. All trusted server certificates must be signed by the acquirer or vendor before being managed through the HSM management API.

Hardware SSL Configuration

• Issuing Client Certificates: The application initializes by obtaining the terminal's CSR, generated by the internal RSA private key of the hardware security module. This CSR must be submitted to a CA to obtain the relevant certificate, which is then injected into the hardware security module with an appropriate alias.

• Importing Server Certificates: Server certificates, signed by the terminal acquirer's private key, should be injected into the hardware security module as trusted certificates.

Quick SSL and HTTPS Demonstration Using Provider Method

This approach is recommended for new projects and affects only the current application's connections.

• KeyManager and TrustManager Preparation: Customize these managers to select the appropriate terminal public key and to manage server certificate information.

    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());
            }
        }
    }

• Using SSL Socket and HTTPS: Ensure the use of the "HSMTLS" security provider and the correct public key alias, allowing the use of keys and certificates stored in the HSM.

Using SSL Socket

            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);

Using HTTPS

            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 public key alias, like "terminal_pub," should be authenticated by the server and may vary depending on the server.

Quick SSLSocket and HTTPS Demonstration Using Property Method

This older method impacts the global environment and is not recommended for new projects. It involves setting up system properties for SSL Socket and HTTPS connections.

Using SSL Socket

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

Using HTTPS

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

Secure Configuration Details

• Key Management: Secure connections utilize mutual authentication. The host verifies the terminal's certificate (related to certAlias) issued by the CA in the host's truststore. The terminal authenticates the host's certificate using the communication root certificate in the hardware security module. Both certificates are stored in X509 format.

• Session Managemen