Managing certificates manually
Internal certificates
For the internal certification between the HCL Commerce Docker containers, you must ensure that the Common Name (CN) in your certificate and "SubjectAlternativeName" can match the host name that the Docker containers will use. Also, when other source containers connect to a target container, the source container must use the target container's host name. There is strict verification logic in place to check whether the host name that is used in a request is the same as the SubjectAlternativeName in the certificate on the target container. If the host names do not match, then the connection fails.
SubjectAlternativeName [
[DNSName: app, DNSName: db, DNSName: search, DNSName: store, DNSName: xc]
]
- Create new certificates and specify the appropriate Common Name (CN) and SubjectAlternativeName in the certificates.
- If you are using docker run to deploy containers, use the --add-host variable to map the IP address to the default host name. For more information, see Docker run documentation.
- If you are using docker-compose to deploy containers, leverage the
extra_hosts variable to map the IP address to the default host name. For more
information, see Docker extra_hosts documentation. For example, the default host name for
the database is db. If you are not using a database Docker container, then you
need to use the extra_hosts variable to map the database IP address to the host name
db. For
example,
Here are two sample YAML files that you can use as a reference for how to use the extra_hosts variable.extra_hosts: - "db:DatabaseServerIP"
Note: If the link does not prompt you to save, right-click and save the file. Open the file in a source code editor to view and edit in the proper YAML format. - Add a proxy container to map the default host name and target server.
External certificates
- For secure external communication between HCL Commerce and third party software, ensure that you are importing the proper one-way or two-way certification information. This includes exporting your certificate public keys, and importing them into your third-party application Trust Store.
- Ensure that your customization code, that you create to connect to third party software, use the correct certification name.
Defining certificate information in a JSON file
- For one-way SSL certificate validation, where one application needs a certificate to a
communicate with another application that has SSL enabled, you only need to define the
issuing_ca in the JSON file. For
example,
{ "issuing_ca": "-----BEGIN CERTIFICATE-----\nMIIFJjCCAw6gAwIBAgIUDUnfHPvwqpztM2lJh40lVUmTjV8wDQYJKoZIhvcNAQEL\nBQAwKzEpMCcGA1UEAwwgc2VsZnNlcnZlX3Byb2R1Y3Rpb25fcGtpIFJvb3QgQ0Ew\nHhcNMTcwODI1MDUwNTEzWhcNMjcwODIzMDUwNTQzWjArMSkwJwYDVQQDDCBzZWxm\nc2VydmVfcHJvZHVjdGlvbl9wa2kgUm9vdCBDQTCCAiIwDQYJKoZIhvcNAQEBBQAD\nggIPADCCAgoCggIBAM5LpBH9Qyg5VjTkdMj61gt72CVIrqE5s9iD+Bpb2hlLnWdb\n52FtcgCxIRca8kJhCYK53dNVmCP8d7LSzogxdIHyzEe5f405ukJVZIbYEYcA4BLK\n3UU322bYJkTTToABwV+XhlHjLhaze9GLo4snCklxAzafWvqR1C0faB2dPtq5WyQi\n/2uCvGHcpqe/ozNvZON6eYkjQpCwHftR0TwVVb435hvJb6FeeV95MgVq/C0pZFG4\nGLgJNj4GK4BtG2wsIDVMMcaoFrSKfKDqyE+4ekvzYP4nDzbYK5XsgH7/7XB9tL7w\nwMVj0J1mR3TbxVTBZyk509F0oXqBcNb6vvybJevhDlkXMQPgxyOmogm6GUQ3beMX\nsRpN5uotnbWaF0MQbgo8YrgQX3BGrLmKRfk9rIMoBKabptDMRw5Df1ouu5D9Jb3b\n3nlelkRXR5qb0R68CM0S78KqVB32NQsLixQ58YUKmcvlQcaIF9cwC28+LYm4sRq/\nV0tCl68K19PmgZT+Qr0Apakw+vlQ8ojvT+/wTVtg+gphuG7Ovv00xRXa/dpoC3Ff\nOktxUmu3bh4YU/IVCT3+YbwB7vyOfKGTwSmVK+s5gt4MDM65zX58xa85psJI8mqP\nCwKGDleglrAIrHxxg2wKrIibiIriSnjJsKqCzpcm9+6V4zewwQFqdfr1R92rAgMB\nAAGjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMBAf8EBTADAQH/MB0GA1UdDgQW\nBBQNl+8T/jYl1zV4Sct1EKqHBDcUUzANBgkqhkiG9w0BAQsFAAOCAgEAYo+vaKzi\nW2YTogGvuDvWnFzDtRa6zfB1UNqUTiacmr9ISqTDGJPOE7o7+5//31yS63/VuPAb\nsskfjtbywGUcjLEoa//vqDUA5VPQSr2MGpqZItt+QQ7eIQPQEt6IaqohmIxvgyDI\nvV35Ld06slZju9IZJdOx5GyRU49ZrhTciNeHBFJbPTzTWw7swjP1Kj13BJ9++YlU\ndHHnJecMgRPXbbFn8cThcIUwhaTEWFhlC7zc4YUpTm8nmHaCLmG8TM7tYLaymHqd\nypMBa3TrGr4+XIgwkWWb9h9+JnlBXc+aq2pJulErzN3raytzv+iTOwcI+YCufgee\nAf25Zzk9t75KIHjSdqu1U/QXiPSgJgr7o2yrtZbeLT+eMHuhCfbuWduipuRgTlUk\na8hvoiFDabCrlJABDYHNO8WMCIqX9qja0crqA1JbPXAEMiYwdtoU+p27CtNupGVE\nQENamacyYD5VhApTnxACwwakMep0jDYQUXUYTeLz6Aj3vVUJl54/3Uqbh6fxKamh\n8xDeb+HjhO5UKDkfAH0qe17qSGGVftMI3YMPCEqrvnnoVl8VHxpvdVjjJoHEEKoE\ne8mrX4Jp9O3xVcGFItMQQzvWc1A47ewqIy6x+bk+0W8fL6+rKd+8U7aRIvC7LFiw\nluvq3QIacuHULtox36A7HFmlYDQ1ozh+tLI=\n-----END CERTIFICATE-----" }
- For two-way SSL certificate validation, where SSL is enabled on both applications, you need to
define more information. For example,
{ "certificate": "-----BEGIN CERTIFICATE-----\nMIIETDCCAjSgAwIBAgIUTrvpjzgpyt6L9AWj2E0W4ps2woswDQYJKoZIhvcNAQEL\nBQAwKzEpMCcGA1UEAwwgc2VsZnNlcnZlX3Byb2R1Y3Rpb25fcGtpIFJvb3QgQ0Ew\nHhcNMTcwOTI2MDQ1NzM3WhcNMTcxMTIxMDQ1ODA3WjAPMQ0wCwYDVQQDEwR0ZXN0\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAtuWgQ5P9KjpgplOyejAE\nj5pDgSmQ6mZkbqY6gnIIKlw1I4Vulaigmeiir37NcAHtLA9HrpqafKoQqt3RPIFq\nMq2qb728JUNqdkmgp1QRnXdRVqrvGxT3o6XLMmxpkniwL+f3A/qFzuBgDJVltKLn\n1e0O3conPiiGtqaZ70+1lccKkKviLoin13T+27gFFws6dT74znCxT8c/ikXGMja1\nTDEddd+qkXlo4At104Fo7Uhx95JWorSljSTaCQkEeOjX+8SJHkARSrKeGEvkBESp\nXD23oUY9MlxGQnldioLAI5Eu8fRo3PKQUhuFnuoxTr0pO7R60AEe8E0sVU/cE3Ut\nswIDAQABo4GDMIGAMA4GA1UdDwEB/wQEAwIDqDAdBgNVHSUEFjAUBggrBgEFBQcD\nAQYIKwYBBQUHAwIwHQYDVR0OBBYEFLfcxphP+aSe61Mdi8IDP7bBvGXdMB8GA1Ud\nIwQYMBaAFA2X7xP+NiXXNXhJy3UQqocENxRTMA8GA1UdEQQIMAaCBHRlc3QwDQYJ\nKoZIhvcNAQELBQADggIBAH3oLFPSSgubbwhXycm+oTMnEZyUwKfwAjkc2mykDZ/p\nPPrHZKCfMuWNf8mp7mK0K8O2JjBKbUlUUJZgd/8/9d0vLqU7Hf97Xk/8d0Rxwqgd\n2OmdujQpj49NFoAC+jAcGFXASwvGAzWg4ylTi+zvpUbVpLk0hOpYnJFvxEcXj0ab\nul9Mq0hrjarmkPAoDhmWjUQG8EKiJEelIv5r4OuNIDl+N5B3BNU+g8nz4GWJKIbP\n6dEb98GJh0tFqOHoxewVmrCmMnsGfJYJDqLg+CwXHSNS8xYQnuFzcJXQ4j7Kge5P\nCeMB6fizgTiUXFexjbTv6RUk1DfOywtRu7Wus9joTpDILb/WlIUlGvRj2j395BvK\naq5nLcgSpmO46776uobh6MN6se1kmpJ20sjUZWEtJsKODSAv7LA9jsMWhh1SGEWf\nUuQ1hUKHZ2073hgc0InmYGGyTJAnI3mYIbL+ddprK1CpORAH2cruqn9I192sCWNw\npZIxuMCiRUrFWitKEkFwPfmDbVhPQ/ZvxMcdAHXJ+ZQ9RxcanmcBGnlvCjidOBZa\naLN2/Y99M26z+XcYG9rN0fx5Htf4UDENQ8kp8TITmyHdwvqVox/UXcPWzV3MD7+I\nn0UdA2lqnM2Rv+kg2MGm0u9Y/noZz4IS4YTlfxMbGF212ROcCC9/oQYy321NqBns\n-----END CERTIFICATE-----", "private_key": "-----BEGIN RSA PRIVATE KEY-----\nMIIEpQIBAAKCAQEAtuWgQ5P9KjpgplOyejAEj5pDgSmQ6mZkbqY6gnIIKlw1I4Vu\nlaigmeiir37NcAHtLA9HrpqafKoQqt3RPIFqMq2qb728JUNqdkmgp1QRnXdRVqrv\nGxT3o6XLMmxpkniwL+f3A/qFzuBgDJVltKLn1e0O3conPiiGtqaZ70+1lccKkKvi\nLoin13T+27gFFws6dT74znCxT8c/ikXGMja1TDEddd+qkXlo4At104Fo7Uhx95JW\norSljSTaCQkEeOjX+8SJHkARSrKeGEvkBESpXD23oUY9MlxGQnldioLAI5Eu8fRo\n3PKQUhuFnuoxTr0pO7R60AEe8E0sVU/cE3UtswIDAQABAoIBAB3kQ6An1K2NIvSs\nIzRTGru5k6TNfVDB8VIgOtnM90atEUY/7YXqLG1bFxOlnr/aoL+ds7J2tB8B0H2M\niUDhSdEEjyF6GgDhFspEWExgsgxRTuriPvfnIl4Nn7sa+tokfW8m8zkkPbBE/Y2w\n8RFnuoo9FzvqaSWAjBvX+LqjBWN4AGHxPcBcZs/H4U7RvdO0etX2Zbpjs62K/KO3\ni3e4MXgGZtj0Vx2LYD/AYSbqEoo1v8/U1AbGmsCTTNc2EwARhyb1zUgO7yc9yft6\nUoAC6pZjxOFsJtwz26jpNdqXz9t1xml3XnNusqHe+hgStQlIL2mgU8qj18q5pqpu\nkehM9LECgYEAxiU9WA7kQTp8hGKTRqrRbcGBsLTGxsYeILFQggtJBOZ5ngOH35Nd\nUIzQ1EjKODFEzGH9qPBBfE6BNdl3naHuYgIS3Uz8FCAwsOZAW6X8tC7VU/ZrwKUA\nF3Rc2iek+J1bdaz5o3hnR2eY/6kVuNHznxqIzK+JuZ7Dq/wEMlAL4gkCgYEA7Eyb\n4uyQFMXfPLiZPn7opNlgmi4i5lNLbPAjJq0dagdP8HbhLBqQThMcyAnu9rJmNm6t\n2Wu8kkKIpcZiGOVzFQvoTWOm6KGU/nIFFH1p6AAz/hvhATFA8HpLe9B7la9T6c5R\nabbtFbUNrHyoieMsIxkrjPo1zVIThLJeIVdoUNsCgYEAwuhKyV4MpSU06rxUhsTs\nsXwRaJLKnSiw5hPFT8ZuE0XrB8YNV52LwvphSRA46sF8HVeevxlmMTK/4wqBoSty\nZDIKAGoD5IAtpTU4xW4nf845xhe1spAb4PZzh5xLqMqQ9tYp0eVUImcDlyjp1x2e\n+TiOrFlXrqE/dOO39Q3MQpECgYEA5plMd4OMh/kiBcvQIOEQf+9zCoODo2od7U3b\nv96pGdPQ+0XIMJYrxUV5jO3EuhMXFH+mQMuW1tT/LWgQS2N/j0ZziTJ6rAMjt7vl\noT1SoQmxs4XZaqR6TzPJfibStBzJsx2Y7aWKcOijU3TDtOxxIj9p9MYowxoZ2iGH\nItp9/okCgYEAh6lbVbf77NArp1FsocQoeZ2ZL1hsOXpmRwpNmePPA6DfjqJyttpH\ngSh8Z0daqMvojStilhwIkEURy9ITuPYoKt2blWQY8RY//H1zFnwKg2AJR5PvlWcT\n0JBxt4cHMYy6jW2Q8/ZTVuttPd+UVIDehTFN6oyWF6FBgKxLO5bSjzc=\n-----END RSA PRIVATE KEY-----", "issuing_ca": "-----BEGIN CERTIFICATE-----\nMIIFJjCCAw6gAwIBAgIUDUnfHPvwqpztM2lJh40lVUmTjV8wDQYJKoZIhvcNAQEL\nBQAwKzEpMCcGA1UEAwwgc2VsZnNlcnZlX3Byb2R1Y3Rpb25fcGtpIFJvb3QgQ0Ew\nHhcNMTcwODI1MDUwNTEzWhcNMjcwODIzMDUwNTQzWjArMSkwJwYDVQQDDCBzZWxm\nc2VydmVfcHJvZHVjdGlvbl9wa2kgUm9vdCBDQTCCAiIwDQYJKoZIhvcNAQEBBQAD\nggIPADCCAgoCggIBAM5LpBH9Qyg5VjTkdMj61gt72CVIrqE5s9iD+Bpb2hlLnWdb\n52FtcgCxIRca8kJhCYK53dNVmCP8d7LSzogxdIHyzEe5f405ukJVZIbYEYcA4BLK\n3UU322bYJkTTToABwV+XhlHjLhaze9GLo4snCklxAzafWvqR1C0faB2dPtq5WyQi\n/2uCvGHcpqe/ozNvZON6eYkjQpCwHftR0TwVVb435hvJb6FeeV95MgVq/C0pZFG4\nGLgJNj4GK4BtG2wsIDVMMcaoFrSKfKDqyE+4ekvzYP4nDzbYK5XsgH7/7XB9tL7w\nwMVj0J1mR3TbxVTBZyk509F0oXqBcNb6vvybJevhDlkXMQPgxyOmogm6GUQ3beMX\nsRpN5uotnbWaF0MQbgo8YrgQX3BGrLmKRfk9rIMoBKabptDMRw5Df1ouu5D9Jb3b\n3nlelkRXR5qb0R68CM0S78KqVB32NQsLixQ58YUKmcvlQcaIF9cwC28+LYm4sRq/\nV0tCl68K19PmgZT+Qr0Apakw+vlQ8ojvT+/wTVtg+gphuG7Ovv00xRXa/dpoC3Ff\nOktxUmu3bh4YU/IVCT3+YbwB7vyOfKGTwSmVK+s5gt4MDM65zX58xa85psJI8mqP\nCwKGDleglrAIrHxxg2wKrIibiIriSnjJsKqCzpcm9+6V4zewwQFqdfr1R92rAgMB\nAAGjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMBAf8EBTADAQH/MB0GA1UdDgQW\nBBQNl+8T/jYl1zV4Sct1EKqHBDcUUzANBgkqhkiG9w0BAQsFAAOCAgEAYo+vaKzi\nW2YTogGvuDvWnFzDtRa6zfB1UNqUTiacmr9ISqTDGJPOE7o7+5//31yS63/VuPAb\nsskfjtbywGUcjLEoa//vqDUA5VPQSr2MGpqZItt+QQ7eIQPQEt6IaqohmIxvgyDI\nvV35Ld06slZju9IZJdOx5GyRU49ZrhTciNeHBFJbPTzTWw7swjP1Kj13BJ9++YlU\ndHHnJecMgRPXbbFn8cThcIUwhaTEWFhlC7zc4YUpTm8nmHaCLmG8TM7tYLaymHqd\nypMBa3TrGr4+XIgwkWWb9h9+JnlBXc+aq2pJulErzN3raytzv+iTOwcI+YCufgee\nAf25Zzk9t75KIHjSdqu1U/QXiPSgJgr7o2yrtZbeLT+eMHuhCfbuWduipuRgTlUk\na8hvoiFDabCrlJABDYHNO8WMCIqX9qja0crqA1JbPXAEMiYwdtoU+p27CtNupGVE\nQENamacyYD5VhApTnxACwwakMep0jDYQUXUYTeLz6Aj3vVUJl54/3Uqbh6fxKamh\n8xDeb+HjhO5UKDkfAH0qe17qSGGVftMI3YMPCEqrvnnoVl8VHxpvdVjjJoHEEKoE\ne8mrX4Jp9O3xVcGFItMQQzvWc1A47ewqIy6x+bk+0W8fL6+rKd+8U7aRIvC7LFiw\nluvq3QIacuHULtox36A7HFmlYDQ1ozh+tLI=\n-----END CERTIFICATE-----", "destination_host": "desthost" //only required for the Transaction server. }
- issuing_ca
- This key contains the entire certificate authority (CA) certificate chain.
- destination_host
- This parameter is only required in the JSON file for the Transaction server Docker container. The Transaction server uses the destination_host name to generate dynamic SSL in the WebSphere Application Server that is running in the container.
Generating self-signed certificates
The following is a generalized example of how to generate a self-signed certificate. You can also use your own method of generating certificates.
- Create a configuration file to include the certificate information. The following is a
template for a myconfiguration.conf
file.
[req] default_bits = 2048 prompt = no default_md = sha256 req_extensions = req_ext distinguished_name = dn [ dn ] C=CA ST=Ontario L=Toronto O=HCL OU=Commerce emailAddress=emailAddress CN = current_domain_name [ req_ext ] basicConstraints = CA:TRUE keyUsage = nonRepudiation, digitalSignature, keyEncipherment subjectAltName = @alt_names [ alt_names ] DNS.0 = current_domain_name DNS.1 = ...
- Create a private key. Use the key in the server.key.secure file as
the private_key name/value pair of the JSON
file.
openssl genrsa -out server.key.secure 2048
- Create a request certificate with parameters from the configuration file.
openssl req -new -key server.key.secure -out server.csr -config myconfiguration.conf
- Create a certificate with parameters from the configuration file. Use the certificate in
server.crt file as the value of the
certificate name/value pair in the JSON file. For self-signed
certificates, this value is also the
issuing_ca.
If you are using a certificate authority (CA), the issuing_ca is provided by the CA.openssl x509 -req -days 365 -in server.csr -signkey server.key.secure -out server.crt -extensions req_ext -extfile myconfiguration.conf
- Check the request file and certificate to ensure that
SubjectAltName
exists.
openssl req -text -noout -in server.csr openssl x509 -in server.crt -text -noout
Loading the JSON files to the /SETUP/certs/custom directory of a Docker container
The following are three methods of copying the JSON files to your Docker image.
- You can use the following two docker commands to copy the JSON files into the containers
manually, and create the custom directory if it does not already
exist.
docker exec -u 0 container mkdir -p /SETUP/certs/custom/ docker cp default.json container:/SETUP/certs/custom/
- You can use the COPY instruction in a Dockerfile to copy the JSON files to the
/SETUP/certs/custom directory and create a new Docker image. For
example, the following Dockerfile copies a default.json file to the
/SETUP/certs/custom
directory.
FROM Docker_registry/commerce/crs-app:source_image_tag COPY default.json /SETUP/certs/custom/
- You can customize the WCB utility to package your JSON files into the output customization package. Then, when you build a new Docker image with your customization package, the /SETUP/bin/applyCustomization.sh script automatically puts your JSON files into the /SETUP/certs/custom directory. For more information, see Customizing the HCL Commerce Build tool.
Importing the local certificates from the JSON file into your running Docker container are handled by the /SETUP/bin/updateLocaCerts.sh script that is included in all the HCL provided Docker containers. The updateLocalCerts.sh script looks in the /SETUP/certs/custom directory and loads all JSON files.