Create a Keystore File for a Two-Way, SSL-Based Integration

If you need to create an integration that communicates with a two-way, SSL-enabled server, you must create the keystore file required for establishing an Oracle Integration identity to facilitate a two-way, SSL-based integration.

To create an integration that consumes external REST APIs hosted on the two-way, SSL-enabled server, ensure that the server on which the external REST APIs are hosted is enabled for two-way SSL support. Use Java version 1.8 or higher.

You can obtain the client certificate in a variety of ways. Select the method that is best for your environment. For example, you can obtain the certificate directly from many certificate authorities. The steps in this section describe how to generate a certificate signing request (CSR) and have it signed by a well known certificate authority.

Note:

  • This section describes how to configure Oracle Integration for use in outbound, two-way SSL integrations. To use Oracle Integration in inbound, two-way SSL integrations, you can use the Oracle Cloud Infrastructure API Gateway. The Oracle Cloud Infrastructure API Gateway is integrated with the Oracle Cloud Infrastructure certificates service. This approach enables you to deliver APIs implemented with Oracle Integration that enforce client mTLS.
  • The alias name to provide must match the name provided for the private key entry in the JKS file.

See this blog and Adding mTLS support to API Deployments.

Commonly Used Terms and Tools

Term Description
Secure socket layer (SSL) and Transport Layer Security (TLS) SSL and TLS, its successor, are protocols for establishing authenticated and encrypted links between networked computers.
Digital certificate A data file that holds the cryptographic key provided to an organization or entity by a trusted authority. A simple analogy is a driver’s license. The license uniquely identifies the person to whom it is issued. The license is issued by the DMV, a trusted authority.
Certificate A public key and private key form a pair used to encrypt and decrypt data. Public keys can be freely given to anyone who needs to securely exchange data. Private keys must never be shared and must be stored securely. If private keys are listed or compromised, the issuing certificate authority must be notified so they can be added to the certificate revocation list.
Certificate authority (or certification authority) An entity that issues digital certificates. A digital certificate certifies the ownership of a public key by the named subject of the certificate.
Certificate encoding/formats
  • Privacy Enhanced Mail (PEM): The full specification of PEM is in RFC 7468. PEM is the most commonly-used X509 certificate format. It's a base64-encoded string enclosed between:-----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----
  • Distinguished Encoding Rules (DER): Binary Format. Cannot be viewed in an editor.
  • Public Key Cryptography Standards (PKCS): These are a group of public key cryptography standards devised and published by RSA Security LLC. See https://datatracker.ietf.org/wg/pkix/documents/.
TrustStore A password-protected repository for trust or public certificates. The default location in Java is $JAVA_HOME/jre/lib/security/cacerts. All well known certificate authority root and intermediate certificates are available in the JDK truststore.
Keystore A password-protected repository to hold client or private certificates. Since this store holds private keys, it is imperative that the store resides in a secure location.
Certificate chain A certificate chain is an ordered list of certificates ending with the root certificate. For trust to be established, the entire certificate chain is traversed. Each certificate is validated by finding the public key of the next issuing certificate authority or intermediate certificate authority, until the root certificate is reached. Certificate chains are usually cached to validate the certificate locally.
The two most commonly used tools for SSL are the following:
Tool Description
keytool A JDK utility used to perform CRUD operations on a truststore and keystore and to administer certificates. All the commands require the password that was used to create the store. Consult your Java truststore documentation for the default password.
openssl This is a robust, commercial-grade, full-featured toolkit for the TLS and SSL protocols. It is also a general-purpose cryptography library.

Commands to Create a Client Certificate with the keytool Utility

Commonly used keytool commands are as follows.

Caution:

Replace the italicized variables in the commands below with values appropriate to your environment.
Description Command
List the entire contents of the store keytool -list -keystore path_to_the_keystore
List the contents in the store for a specific alias keytool -list -keystore path_to_the_keystore -alias alias_name
View the contents of a certificate keytool -printcert -v -file name_of_the_file
Export a certificate from the store keytool -export -alias alias_name -file certificate_name -keystore path_to_the_store
Import a new certificate into the store keytool -import -trustcacerts -file path_to_the_certificate -alias alias_name -keystore path_to_the_store

To create a client certificate:

Caution:

Italicized variables indicate placeholder variables for which you must supply particular values. If you copy the commands below, ensure that you replace the variables shown in italics with values appropriate to your environment.
  1. Go to the Java bin directory.
    %JAVA_HOME%/jre/bin
  2. Enter the following command to create a JKS keystore to hold the certificates.
    keytool -genkey -keyalg RSA -alias alias_name -keystore identityKeystore.jks -storepass password_for_the_keystore -validity 360 -keysize 2048
  3. When prompted, change the values provided based on your company's security policy.
    
What is your first and last name?
  [Unknown]:  <FQDN>
What is the name of your organizational unit?
  [Unknown]:  Your_functional_org
What is the name of your organization?
  [Unknown]:  Company
What is the name of your City or Locality?
  [Unknown]:  City_name
What is the name of your State or Province?
  [Unknown]:  State_name
What is the two-letter country code for this unit?
  [Unknown]:  US
Is CN=<>, OU=<>, O=<>, L=Redwood Shores, ST=California, C=US correct?
  [no]:  yes 
Enter key password for <oicclient>
        (RETURN if same as keystore password):
  4. Verify the existence of the JKS keystore file.
    ls
  5. Create a certificate that is ready to be signed.
    
keytool -certreq -alias alias_name -keystore name_of_keystore -storepass password -storetype JKS -file name_of_csr_certificate.csr
  6. List the JKS keystore and certificate files in the directory.
    
ls
  7. Validate your CSR file at the following site.
    https://ssltools.digicert.com/checker/views/csrCheck.jsp
  8. Provide the .csr certificate file to a signing authority. A signed certificate and any root and intermediate certificates are signed and returned by the authority. A self-signed certificate can be used for testing, but is not allowed in a production environment.
  9. If you have root and intermediate certificates, perform the following substeps. Otherwise, go to Step 10.
    1. If you have a root certificate, enter the following command to import the signed root certificate.
      keytool -import -keystore keystore_name -file path_to_root_certificate -alias root_alias_name

      The following example is what you see when importing the DigiCert root certificate.

      
Enter keystore password: 
Owner: CN=DigiCert Global Root CA, OU=www.digicert.com, O=DigiCert Inc, C=US
Issuer: CN=DigiCert Global Root CA, OU=www.digicert.com, O=DigiCert Inc, C=US
Serial number: 83be056904246b1a1756ac95991c74a
Valid from: Thu Nov 09 16:00:00 PST 2006 until: Sun Nov 09 16:00:00 PST 2031
Certificate fingerprints:
     MD5:  79:E4:A9:84:0D:7D:3A:96:D7:C0:4F:E2:43:4C:89:2E
     SHA1: A8:98:5D:3A:65:E5:E5:C4:B2:D7:D6:6D:40:C6:DD:2F:B1:9C:54:36
     SHA256: 43:48:A0:E9:44:4C:78:CB:26:5E:05:8D:5E:89:44:B4:D8:4F:96:62:BD:26:DB:25:7F:89:34:A4:43:C7:01:61
     Signature algorithm name: SHA1withRSA
     Version: 3Extensions:#1: ObjectId: 2.5.29.35 Criticality=false
AuthorityKeyIdentifier [
KeyIdentifier [
0000: 03 DE 50 35 56 D1 4C BB   66 F0 A3 E2 1B 1B C3 97  ..P5V.L.f.......
0010: B2 3D D1 55                                        .=.U
]
]#2: ObjectId: 2.5.29.19 Criticality=true
BasicConstraints:[
  CA:true
  PathLen:2147483647
]#3: ObjectId: 2.5.29.15 Criticality=true
KeyUsage [
  DigitalSignature
  Key_CertSign
  Crl_Sign
]#4: ObjectId: 2.5.29.14 Criticality=false
SubjectKeyIdentifier [
KeyIdentifier [
0000: 03 DE 50 35 56 D1 4C BB   66 F0 A3 E2 1B 1B C3 97  ..P5V.L.f.......
0010: B2 3D D1 55                                        .=.U
]
]Trust this certificate? [no]:  yes
Certificate was added to keystore
    2. If you have an intermediate certificate, enter the following command to import the signed intermediate certificate.
      keytool -import -keystore keystore_name -file path_to_intermediate_certificate -alias intermediate_certificate_alias
       
Enter keystore password: replace_with_strong_password
Certificate was added to keystore
  10. If you have only a single certificate, enter the following command to import the signed certificate.
    keytool -import -keystore keystore_name -file path_to_signed_certificate -alias the_same_alias_used_to_create_the_keystore
    
Enter keystore password: replace_with_strong_password
Certificate was added to keystore
  11. Check if all the certificates are in the store.
    keytool -list -keystore
  12. Export the public certifcate.
    keytool -export -alias certificate_alias -keystore identity_keystore -file your_public_certificate_filename
    Enter keystore password: replace_with_strong_password
  13. Export the public certificate to provide to the server.
    keytool -export -alias certificate_alias -keystore identityKeystore.jks -file your_public_certificate_filename
Enter keystore password: 
Certificate stored in file your_public_certificate_filename
  14. Import the new keystore into Oracle Integration as an X509 identity certificate.
  15. List the entire contents of the store.
    keytool -list -keystore path_to_the_keystore

Example: Create a Client Certificate with the keytool Utility

This section provides an example of how to create a client certificate. It uses actual file names. Replace those names with values appropriate to your environment.

  1. Enter the following command to create a JKS keystore to hold the certificates. 
    keytool -genkey -keyalg RSA -alias oicclient -keystore identityKeystore.jks -storepass replace_with_strong_password -validity 360 -keysize 2048
    Where the following values are entered for this example:
    • -alias is the oicclient keystore alias.
    • -keystore is the identityKeystore.jks keystore file.
  2. When prompted, change the values provided based on your company's security policy.
    
What is your first and last name?
  [Unknown]:  Joe Smith
What is the name of your organizational unit?
  [Unknown]:  Development
What is the name of your organization?
  [Unknown]:  GlobalChips
What is the name of your City or Locality?
  [Unknown]:  Redwood Shores
What is the name of your State or Province?
  [Unknown]:  California
What is the two-letter country code for this unit?
  [Unknown]:  US
Is CN=<>, OU=<>, O=<>, L=Redwood Shores, ST=California, C=US correct?
  [no]:  yes 
Enter key password for oicclient
        (RETURN if same as keystore password):
  3. Verify the existence of the JKS keystore file.
    ls
  4. Create a certificate that is ready to be signed.
    
keytool -certreq -alias oicclient -keystore identityKeystore.jks -storepass replace_with_strong_password  -storetype JKS -file oicclient.csr
    Where the following values are entered for this example:
    • -alias is the oicclient keystore alias.
    • -keystore is the identityKeystore.jks keystore file.
    • -file is the oicclient.csr certificate file.
  5. List the JKS keystore and certificate files in the directory.
    
ls
oicclient.csr  identityKeystore.jks
  6. Validate your .csr certificate file at the following site.
    https://ssltools.digicert.com/checker/views/csrCheck.jsp
  7. Provide the .csr certificate file to a signing authority. The certificate and any root and intermediate certificates are signed and returned by the authority. A self-signed certificate can be used for testing, but is not allowed in a production environment.
  8. If you have root and intermediate certificates, perform the following substeps. Otherwise, go to Step 9.
    1. If you have a root certificate, enter the following command to import the signed root certificate.
      keytool -import -keystore identityKeystore.jks -file DigiCertGlobalRootCA.crt -alias DigiCertCARoot
      Where the following values are entered for this example:
      • -keystore is the identityKeystore.jks keystore file.
      • -file is the DigiCertGlobalRootCA.crt signed root certificate file.
      • -alias is the DigiCertCARoot alias. 
      
Enter keystore password: replace_with_strong_password
Owner: CN=DigiCert Global Root CA, OU=www.digicert.com, O=DigiCert Inc, C=US
Issuer: CN=DigiCert Global Root CA, OU=www.digicert.com, O=DigiCert Inc, C=US
Serial number: 83be056904246b1a1756ac95991c74a
Valid from: Thu Nov 09 16:00:00 PST 2006 until: Sun Nov 09 16:00:00 PST 2031
Certificate fingerprints:
     MD5:  79:E4:A9:84:0D:7D:3A:96:D7:C0:4F:E2:43:4C:89:2E
     SHA1: A8:98:5D:3A:65:E5:E5:C4:B2:D7:D6:6D:40:C6:DD:2F:B1:9C:54:36
     SHA256: 43:48:A0:E9:44:4C:78:CB:26:5E:05:8D:5E:89:44:B4:D8:4F:96:62:BD:26:DB:25:7F:89:34:A4:43:C7:01:61
     Signature algorithm name: SHA1withRSA
     Version: 3Extensions:#1: ObjectId: 2.5.29.35 Criticality=false
AuthorityKeyIdentifier [
KeyIdentifier [
0000: 03 DE 50 35 56 D1 4C BB   66 F0 A3 E2 1B 1B C3 97  ..P5V.L.f.......
0010: B2 3D D1 55                                        .=.U
]
]#2: ObjectId: 2.5.29.19 Criticality=true
BasicConstraints:[
  CA:true
  PathLen:2147483647
]#3: ObjectId: 2.5.29.15 Criticality=true
KeyUsage [
  DigitalSignature
  Key_CertSign
  Crl_Sign
]#4: ObjectId: 2.5.29.14 Criticality=false
SubjectKeyIdentifier [
KeyIdentifier [
0000: 03 DE 50 35 56 D1 4C BB   66 F0 A3 E2 1B 1B C3 97  ..P5V.L.f.......
0010: B2 3D D1 55                                        .=.U
]
]Trust this certificate? [no]:  yes
Certificate was added to keystore
    2. If you have an intermediate certificate, enter the following command to import the signed intermediate certificate.
      keytool -import -keystore identityKeystore.jks -file DigiCertGlobalInterCA.crt -alias DigiCertCAInter
      Where the following values are entered for this example:
      • -keystore is the identityKeystore.jks keystore file.
      • -file is the DigiCertGlobalInterCA.crt signed intermediate certificate.
      • -alias is the DigiCertCAInter alias. 
       
Enter keystore password: replace_with_strong_password
Certificate was added to keystore
  9. If you have only a single certificate, enter the following command to import the signed certificate.
    keytool -import -keystore identityKeystore.jks -file my_company_signedcert.pem -alias oiclient
    Where the following values are entered for this example:
    • -keystore is the identityKeystore.jks keystore file.
    • -file is the my_company_signedcert.pem signed certificate.
    • -alias is the oiclient alias. 
    
Enter keystore password: replace_with_strong_password
Certificate was added to keystore
  10. Check if all the certificates are in the store.
    keytool -list -keystore identityKeystore.jks
  11. Export the public certificate corresponding to the private identity certificate. 
    keytool -export -alias oicclient -keystore identityKeystore.jks -file my_company_signedcert.pem
    Where the following values are entered for this example:
    • -alias is the oicclient keystore alias.
    • -keystore is the identityKeystore.jks keystore file.
    • -file is the my_company_signedcert.pem public certificate file. 
    Enter keystore password: replace_with_strong_password
Certificate stored in file my_company_signedcert.pem
  12. Import the new keystore (.jks file) into Oracle Integration as an X509 identity certificate.
  13. List the entire contents of the store. 
    keytool -list -keystore identityKeystore.jks

Manage Certificates with openSSL

Commonly used openssl commands are as follows:

Description Command
Check a certificate openssl x509 -in certificate_name -text -noout
Get all certificates from a server openssl s_client -connect host:ssl_port -showcerts
Convert a DER format certificate to PEM format openssl x509 -inform der -in path_to_DER_certificate -out path_to_PEM_certificate
Convert a .pfx file to a JKS store keytool -importkeystore -srckeystore path_to_.pfx_file -srcstoretype pkcs12 -destkeystore path_to_the_jks_file -deststoretype JKS -srcstorepass pfx_passwd -deststorepass pfx_passwd
Convert a .jks file to PKCS12 format keytool -importkeystore -srckeystore path_to_.jks_file -destkeystore full_path_to_.p12_file-srcstoretype JKS - deststoretype PKCS12 -deststorepass pkcs12_store_password
Extract a private key from a .pfx file openssl pkcs12 -info -in path_to_.pfx_file -nodes -nocerts -out private_key_file_name
Extract a public certificate from a .pfx file openssl pkcs12 -in path_to_.pfx_file -out path_to_certificate_file -nokeys

Certificate Management - Two-Way SSL or mTLS

See Debugging SSL/TLS Connections.

To upload an identity certificate:

  1. In the navigation pane, select Home > Settings > Certificates.
  2. Click Upload.
  3. Set the alias name to the alias listed in the keystore for the identity certificate. (Use keytool -list to see the contents of the keystore.)
  4. Make sure the certificate category is set to Identity.
  5. Upload the client certificate file in JKS format.
  6. Enter the keystore and key passwords used to create the JKS store. If there is a mismatch in the passwords, Oracle Integration cannot access the identity certificates.
  7. Create a new adapter connection (SOAP Adapter or REST Adapter connection) in Oracle Integration.
  8. On the Connections page, select the two-way SSL checkbox and associate the alias required by the connection to use to complete the SSL connection. This alias must match the value that was entered in the Upload Certificate dialog.

To test Mutual TLS authentication (mTLS):

  1. Test access to the endpoint from the browser first. Import the client certificate in .p12 format into the browser of choice.
  2. Enter the endpoint in the browser bar and press Enter. A message is displayed asking you to use the client certificate that was imported.
  3. Follow the prompts in the message. If the certificate is valid, content is loaded in the browser.
  4. If the browser test was successful, test the REST/SOAP adapter connection in Oracle Integration.