How to Understand Secure Connections - Revision history

Mahong: Replaced content with "{{Migrating|https://smartpossdk.gitbook.io/cloudpossdk/faq/other-development/understand-secure-connections}}"

2024-04-08T03:30:01Z

Replaced content with "{{Migrating|https://smartpossdk.gitbook.io/cloudpossdk/faq/other-development/understand-secure-connections}}"

← Older revision		Revision as of 03:30, 8 April 2024
Line 1:		Line 1:
	~~== Recommended Practices for Secure TCP/IP Connections ==~~		{{Migrating\|https://smartpossdk.gitbook.io/cloudpossdk/faq/other-development/understand-secure-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.
	~~<syntaxhighlight lang="java">~~
	~~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());~~
	}
	}
	}
	</~~syntaxhighlight>~~
	* '''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'''~~
	~~<syntaxhighlight lang="java">~~
	~~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);~~
	</~~syntaxhighlight>~~
	~~: '''Using HTTPS'''~~
	~~<syntaxhighlight lang="java">~~
	~~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();~~
	</~~syntaxhighlight>~~
	~~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'''~~
	~~<syntaxhighlight lang="java">~~
	~~System.setProperty("javax.net.ssl.keyStoreProvider", "SunPKCS11~~-~~wizarpos");~~
	~~String terminalPublicCertAlias = "terminal";~~
	~~System.setProperty("javax.net.ssl.certAlias", terminalPublicCertAlias);~~
	~~try {~~
	~~SSLContext sslContext = SSLContext.getInstance("TLS");~~
	</~~syntaxhighlight>~~
	~~: '''Using HTTPS'''~~
	~~<syntaxhighlight lang="java">~~
	~~System.setProperty("javax.net.ssl.keyStoreProvider", "SunPKCS11~~-~~wizarpos");~~
	~~String terminalPublicCertAlias = "terminal";~~
	~~System.setProperty("javax.net.ssl.certAlias", terminalPublicCertAlias);~~
	~~HttpPost httpPost = new HttpPost(strURL);~~
	~~</syntaxhighlight>~~
	~~== 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 Management:''' Session timeouts are controlled by the SSL module in the terminal, with a default unmodifiable timeout of 5 minutes.

Simon no use: Simon moved page Secure Connections to How to Understand Secure Connections: Normalize the title

2024-01-10T22:33:13Z

Simon moved page Secure Connections to How to Understand Secure Connections: Normalize the title

← Older revision

Revision as of 22:33, 10 January 2024

Simon no use at 22:31, 10 January 2024

2024-01-10T22:31:32Z

Show changes

Mahong at 03:21, 4 August 2022

2022-08-04T03:21:48Z

← Older revision		Revision as of 03:21, 4 August 2022
Line 13:		Line 13:

	== Hardware SSL Configuration ==		== 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.		'''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.		'''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 ==		== 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.		This method will only affect the connection in current application. It is recommend to be used in new projects.
	Prepare KeyManager and TrustManager :		'''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:		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:
	<syntaxhighlight lang="java">		<syntaxhighlight lang="java">
Line 68:		Line 68:
	}		}
	</syntaxhighlight>		</syntaxhighlight>
	Use SSL Socket:		'''Use SSL Socket:'''
	Use the proper security provider “HSMTLS” and proper public key alias to use the keys and certificates stored in HSM:		Use the proper security provider “HSMTLS” and proper public key alias to use the keys and certificates stored in HSM:
	<syntaxhighlight lang="java">		<syntaxhighlight lang="java">
Line 81:		Line 81:
	</syntaxhighlight>		</syntaxhighlight>

	Use HTTPS:		'''Use HTTPS:'''
	Use the proper security provider “HSMTLS” and proper public key alias to use the keys and certificates stored in HSM:		Use the proper security provider “HSMTLS” and proper public key alias to use the keys and certificates stored in HSM:
	<syntaxhighlight lang="java">		<syntaxhighlight lang="java">
Line 95:		Line 95:
	== Quick SSLSocket and HTTPS Demo via Property ==		== 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.		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:		'''Use SSL Socket:'''
	Setup the two system properties, the connection socket as the normal SSL connection. For example:		Setup the two system properties, the connection socket as the normal SSL connection. For example:
	<syntaxhighlight lang="java">		<syntaxhighlight lang="java">
Line 104:		Line 104:
	SSLContext sslContext = SSLContext.getInstance("TLS");		SSLContext sslContext = SSLContext.getInstance("TLS");
	</syntaxhighlight>		</syntaxhighlight>
	Use HTTPS:		'''Use HTTPS:'''
	Similar as SSL Socket usage, setup the two system property, the connection socket as the normal HTTPS connection. For example:		Similar as SSL Socket usage, setup the two system property, the connection socket as the normal HTTPS connection. For example:
	<syntaxhighlight lang="java">		<syntaxhighlight lang="java">
Line 113:		Line 113:
	</syntaxhighlight>		</syntaxhighlight>
	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.		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.

Mahong: Created page with "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 Conn..."

2022-08-04T03:15:22Z

Created page with "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 Conn..."

New page

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:
<syntaxhighlight lang="java">
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());
}
}
}
</syntaxhighlight>
Use SSL Socket:
Use the proper security provider “HSMTLS” and proper public key alias to use the keys and certificates stored in HSM:
<syntaxhighlight lang="java">
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);
</syntaxhighlight>

Use HTTPS:
Use the proper security provider “HSMTLS” and proper public key alias to use the keys and certificates stored in HSM:
<syntaxhighlight lang="java">
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();
</syntaxhighlight>
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:
<syntaxhighlight lang="java">
System.setProperty("javax.net.ssl.keyStoreProvider", "SunPKCS11-wizarpos");
String terminalPublicCertAlias = "terminal";
System.setProperty("javax.net.ssl.certAlias", terminalPublicCertAlias);
try {
SSLContext sslContext = SSLContext.getInstance("TLS");
</syntaxhighlight>
Use HTTPS:
Similar as SSL Socket usage, setup the two system property, the connection socket as the normal HTTPS connection. For example:
<syntaxhighlight lang="java">
System.setProperty("javax.net.ssl.keyStoreProvider", "SunPKCS11-wizarpos");
String terminalPublicCertAlias = "terminal";
System.setProperty("javax.net.ssl.certAlias", terminalPublicCertAlias);
HttpPost httpPost = new HttpPost(strURL);
</syntaxhighlight>
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.