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.
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.
- Two-way SSL is not supported for calls to external services through the connectivity agent. Two-way SSL requires direct connectivity from Oracle Integration without the connectivity agent.
- 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 |
|
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. |
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
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.- Go to the Java
bin
directory.%JAVA_HOME%/jre/bin
- 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
- 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):
- Verify the existence of the JKS keystore file.
ls
- 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
- List the JKS keystore and certificate files in the
directory.
ls
- Validate your CSR file at the following
site.
https://ssltools.digicert.com/checker/views/csrCheck.jsp
- 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. - If you have root and intermediate certificates, perform
the following substeps. Otherwise, go to Step 10.
- 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
- 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
- If you have a root certificate, enter the following command
to import the signed root
certificate.
- 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
- Check if all the certificates are in the
store.
keytool -list -keystore
- Export the public
certifcate.
keytool -export -alias certificate_alias -keystore identity_keystore -file your_public_certificate_filename
Enter keystore password: replace_with_strong_password
- 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
- Import the new keystore into Oracle Integration as an X509 identity certificate.
- 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.
- 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 theoicclient
keystore alias.-keystore
is theidentityKeystore.jks
keystore file.
- 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):
- Verify the existence of the JKS keystore file.
ls
- 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 theoicclient
keystore alias.-keystore
is theidentityKeystore.jks
keystore file.-file
is theoicclient.csr
certificate file.
- List the JKS keystore and certificate files in the
directory.
ls oicclient.csr identityKeystore.jks
- Validate your
.csr
certificate file at the following site.https://ssltools.digicert.com/checker/views/csrCheck.jsp
- 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. - If you have root and intermediate certificates, perform the
following substeps. Otherwise, go to Step 9.
- 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 theidentityKeystore.jks
keystore file.-file
is theDigiCertGlobalRootCA.crt
signed root certificate file.-alias
is theDigiCertCARoot
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
- 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 theidentityKeystore.jks
keystore file.-file
is theDigiCertGlobalInterCA.crt
signed intermediate certificate.-alias
is theDigiCertCAInter
alias.
Enter keystore password: replace_with_strong_password Certificate was added to keystore
- If you have a root certificate, enter the following command
to import the signed root
certificate.
- 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 theidentityKeystore.jks
keystore file.-file
is themy_company_signedcert.pem
signed certificate.-alias
is theoiclient
alias.
Enter keystore password: replace_with_strong_password Certificate was added to keystore
- Check if all the certificates are in the
store.
keytool -list -keystore identityKeystore.jks
- 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 theoicclient
keystore alias.-keystore
is theidentityKeystore.jks
keystore file.-file
is themy_company_signedcert.pem
public certificate file.
Enter keystore password: replace_with_strong_password Certificate stored in file my_company_signedcert.pem
- Import the new keystore (
.jks
file) into Oracle Integration as an X509 identity certificate. - 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:
- In the navigation pane, select Home > Settings > Certificates.
- Click Upload.
- 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.) - Make sure the certificate category is set to Identity.
- Upload the client certificate file in JKS format.
- 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.
- Create a new adapter connection (SOAP Adapter or REST Adapter connection) in Oracle Integration.
- 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):
- Test access to the endpoint from the browser first. Import the
client certificate in
.p12
format into the browser of choice. - Enter the endpoint in the browser bar and press Enter. A message is displayed asking you to use the client certificate that was imported.
- Follow the prompts in the message. If the certificate is valid, content is loaded in the browser.
- If the browser test was successful, test the REST/SOAP adapter connection in Oracle Integration.