The keystore service allows you to manage and administer keys and certificates for Secure Sockets Layer (SSL), message security, encryption, and other tasks that require special certificates.
This chapter includes the following topics:
The keystore service allows you to manage keys and certificates for SSL, message security, encryption, and other tasks that require a key or a certificate. Typical keystore management tasks include the following:
Creating a keystore in the context of an application stripe, directly or by importing a keystore file from the file system.
Viewing the list of keystores and choosing some for updating.
Updating and deleting keystores.
Changing the keystore password.
Exporting and importing keystores.
The following topics introduce Keystore Service concepts:
A keystore is uniquely identified by application stripe and a keystore within that stripe. Keys and certificates created in keystores within stripes. Stripes names within the security store are unique in the security store, and keystore names within a stripe are unique in the stripe. For example,(stripe1,keystoreA), (stripe1,keystoreB), and(stripe2,keystoreA)refer to three distinct keystores.
Applications can create more than one keystore within the application stripe.
A keystore can contain the following entries, referenced by a unique alias within the keystore:
Asymmetric Keys, including public keys and private keys that and are used with SSL. Public keys are wrapped within a certificate.
Symmetric Keys, generally used for encryption.
Trusted Certificates, used to establish trust with an SSL peer.
The Keystore Service allows you create two types of keystores:
Keystores protected by a policy
These keystores are protected by policies and any access to them by runtime code is protected by codesource policies. The key data is encrypted with the domain encryption key.
Keystores protected by password
These keystores are protected by keystore and/or key passwords. Any access to them by runtime code requires access to the keystore and key password (if different from the keystore password). The key data is encrypted with the keystore/key password with password-based encryption.
Oracle recommends that you use password-protected keystores. However, if your application requires a high security level, then consider with a keystore protected by a codesource policy. You can export, import, and restore keys to a wallet.
In domains with multiple servers, the only supported store types are LDAP or DB. Do not use the keystore service to manage passwords or keys. Use instead the credential store for your application.
The truststore is a keystore that contains trusted certificates of most well-known third-party certificate authorities and a trusted certificate from the demonstration certification authority (CA), which is configured with the Keystore Service. If your application uses SSL, for example, it can point to the truststore for certificates, and you do not need a dedicated keystore to store them.
Caution:
The demonstration CA includes a hard-coded private key. Oracle recommends that you neither use nor trust the demonstration CA certificates in production environments. For information about third-party certificates, see Using Third-Party CA Signed Certificates.The truststore is shared by all products and applications in a domain. The decision to add or remove trust for a product may affect other products in the domain. Consider creating a custom truststore only if your product's trust management requirements are not met by the truststore.
A truststore is preconfigured for all products and applications to use, and applications can configure multiple keystores, according to their needs.
For one-way SSL, applications can use the truststore and you need not create a specific keystore.
For two-way SSL, applications create a keystore to keep just their identity certificate and use the truststore for other certificates.
Use the following tasks to manage keystores with Oracle Enterprise Manager Fusion Middleware Control (Fusion Middleware Control).
Task 1, Opening the Keystore Page
Log in to Fusion Middleware Control and go to Domain, then to Security, and then to Keystore. The Keystore page is displayed.
Choose the stripe in which to create the keystore. If necessary, then create a stripe.
Click Create Keystore. The Create Keystore dialog is displayed.
In this dialog, enter the following data:
Keystore Name: a unique name.
Protection Type: the protection mechanism for the keystore. Choose Policy or Password. For a password-protected keystore, provide a valid password.
Grant Permission: check this box to grant permissions to code URL.
Click OK. The new keystore is displayed under the stripe you chose.
When you delete a keystore, note that all certificates in it are also deleted.
Expand the stripe in which the keystore resides, and choose a row.
Click Delete. The Delete Keystore dialog is displayed.
If this is a password-protected keystore, then enter the password.
Click OK.
Task 4, Changing a Keystore Password
This task applies to password-protected keystores only.
Expand the stripe in which the keystore resides. Choose the row corresponding to the keystore.
Click Change Password. The Change Keystore Password dialog is displayed.
Enter the old and new passwords.
Click OK.
Use the following tasks to manage keystores with WebLogic Scripting Tool (WLST).
Use the createKeyStore WLST command. For example, assuming the stripe name is teststripe1, create a permission-based keystore:
svc.createKeyStore(appStripe='teststripe1', name='keystore1', password='mypassword',permission=true)
where mypassword is the password for keystore1. Any combination of characters is allowed for a new stripe name, but it is recommended that you do not use the forward slash (/) in it. The keystore name must unique.
Use the deleteKeyStore WLST command. For example, assuming the stripe is appstripe1, delete keystore1:
svc.deleteKeyStore(appStripe='appstripe1', name='keystore1', password='mypassword')
where mypassword is the password for keystore1.
Task 3, Changing a Keystore Password
Use the changeKeyStorePassword WLST command. For example, assuming the stripe name is system, change the password of keystore2:
svc.changeKeyStorePassword(appStripe='system', name='keystore2', currentpassword='currentpassword', newpassword='newpassword')
where currentpassword and newpassword are the old and new passwords.
Use the exportKeyStore WLST command.
To export a singe key to a file:
svc.exportKeyStore(appStripe='mystripe', name='keystore2', password='mypassword',aliases='myorakey', keypasswords='keypassword1', type='JKS',filepath='/tmp/file.jks')
To export multiple keys to a file, specify a comma-separated list of aliases and key passwords.
To export a symmetric key:
svc.exportKeyStore(appStripe='mystripe', name='keystore2', password='password',aliases='myorakey', keypasswords='keypassword1', type='JCEKS',filepath='/tmp/file.jks')
To export to a wallet, use the OracleWallet type:
svc.exportKeyStore(appStripe='mystripe', name='keystore3', password='mypassword',aliases='myorakey1,myorakey2', keypasswords='', type='OracleWallet',filepath='/tmp')
Use the importKeyStore WLST command.
To import a single key, such as myOrakey:
svc.importKeyStore(appStripe='mystripe', name='keystore2', password='password',aliases='myOrakey', keypasswords='keypassword1', type='JKS', permission=true, filepath='/tmp/file.jks')
To import multiple keys, specify a comma-separated list of aliases and key passwords.
To import keys from a wallet, use the OracleWallet type:
svc.importKeyStore(appStripe='mystripe', name='keystore4', password='owPwd1234',aliases='myorakey1,myorakey2', keypasswords='', type='OracleWallet', permission=true, filepath='/tmp')
The keystore service (KSS) keystore supports the Java Keystore (JKS), Java Cryptography Extension Keystore (JCEKS), and Oracle wallet certificate formats. Typical certificate management tasks include the following:
Creating a certificate for a key pair.
Generating a Certificate Signing Request (CSR) for the certificate and saving it to a file.
Sending the CSR to a certificate authority who verifies the sender, and signs and returns the certificate.
Importing user and trusted certificates into the keystore, by either pasting it into a text field or importing it from the file system.
Note:
Keystore Service supports importing PEM/BASE64-encoded certificates only. You cannot import DER-encoded certificates or trusted certificates into a keystore.Exporting certificates or trusted certificates from the keystore to a file.
Deleting certificates or trusted certificates from the keystore.
The following points regarding public CA certificates apply to domains upgraded to 12.2.1 and to new 12.2.1 Java Required Files (JRF) domains:
Well-known public CA certificates are no longer available in the trust keystore in the system stripe.
Use instead the publiccacerts keystore in the system stripe, which has been previously seeded with well-known public CA certificates from the Java SE Development Kit (JDK) cacerts file. Alternatively, import your own certificates as needed.
The merge.jdkcacerts.with.trust property specifies whether to return public CA certificates in the kss://system/ubliccacerts keystore when you query the kss://system/trust keystore. Set to true, to have all publicacerts certificates returned with the query. Do not set or set to false, to have no publicacerts certificates returned with the query.
Use the following tasks to manage keystores withFusion Middleware Control.
Log in to Fusion Middleware Control and go to Domain, then to Security, and then to Keystore. The Keystore page is displayed.
Expand the stripe in which the keystore resides. Choose the row corresponding to the keystore, and click Manage.
If the keystore is password-protected, then enter the keystore password and click OK. The Manage Certificates page is displayed.
Click Generate Keypair. The Generate Keypair dialog is displayed.
In this dialog, enter the following data:
Alias (required)
Common Name (required)
Organizational Unit
Organization
City
State
Country: Choose one from the drop-down list.
Key Type: Choose an algorithm from the drop-down list. The choices are Elliptic Curve Cryptography (ECC) or RSA.
Key Size: Choose a key size.
Click OK. The new certificate is displayed in the certificate list.
View the certificate details by clicking on the certificate alias.
The key pair is wrapped in a demonstration CA signed certificate and stored in the truststore. To use this certificate for SSL, applications must either use the truststore or import the demonstration CA certificate to a custom keystore.
Task 2, Generating a CSR for a Certificate
Log in to Fusion Middleware Control and go to Domain, then to Security, and then to Keystore. The Keystore page is displayed.
Expand the stripe in which the keystore resides. Choose the row corresponding to the keystore, and click Manage.
If the keystore is password-protected, then enter the keystore password and click OK. The Manage Certificates page is displayed.
Choose the row corresponding to the certificate and click Generate CSR. The Generate CSR dialog appears
Do one of the following:
Copy and paste the entire CSR into a text file, and click Close.
Click Export CSR to save the CSR to a file.
Send the generated certificate to a certificate authority which will return a signed certificate.
Task 3, Importing a Certificate
Log in to Fusion Middleware Control and go to Domain, then to Security, and then to Keystore. The Keystore page is displayed.
Expand the stripe in which the keystore resides. Choose the row corresponding to the keystore, and click Manage.
If the keystore is password-protected, then enter the password and click OK. The Manage Certificates page is displayed.
Click Import. The Import Certificate dialog is displayed.
Choose Certificate or Trusted Certificate from the drop-down.
Choose the alias from the drop-down.
Specify the certificate source. If using the Paste option, then copy and paste the certificate directly into the text field. If using the Select a file option, then click Browse to choose the file from the operating system.
Click OK. The imported certificate or trusted certificate is displayed in the list of certificates.
Task 4, Exporting a Certificate
Log in to Fusion Middleware Control and go to Domain, then to Security, that then to Keystore. The Keystore page is displayed.
Expand the stripe in which the keystore resides. Choose the row corresponding to the keystore, and click Manage.
If the keystore is password-protected, then enter the password and click OK. The Manage Certificates page is displayed.
Choose the row corresponding to the certificate and click Export. The certificate export dialog is displayed.
Do one of the following:
Copy and paste the entire certificate into a text file, and click Close.
Click Export Certificate to save the certificate to a file.
Task 5, Changing a Certificate Password
Log in to Fusion Middleware Control and go to Domain, then to Security, and then to Keystore. The Keystore page is displayed.
Expand the stripe in which the keystore resides. Choose the row corresponding to the keystore, and click Manage.
If the keystore is password-protected, then enter the password and click OK. The Manage Certificates page is displayed.
Choose the row corresponding to the certificate and click Change Password. The Change Key Password dialog appears
Enter the old and new passwords and click OK.
Task 6, Deleting a Certificate
Log in to Fusion Middleware Control and go to Domain, then to Security, and then to Keystore. The Keystore page is displayed.
Expand the stripe in which the keystore resides. Choose the row corresponding to the keystore, and click Manage.
If the keystore is password-protected, then enter the password and click OK. The Manage Certificates page is displayed.
Choose the row corresponding to the certificate and click Delete. The Delete Certificate dialog is displayed. Click OK.
Use the following tasks to manage certificates with WLST.
Use the generateKeyPair WLST command. For example, assuming an application stripe named appstripe2, the following command creates a key pair with the myalias alias using the ECC algorithm:
svc.generateKeyPair(appStripe='appstripe2', name='keystore2', password='mypassword', dn='cn=www.example.com', keysize='1024', alias='myalias', keypassword='keypassword', algorithm='EC')
where mypassword is the keystore password and keypassword is the password of the alias.
The key pair is wrapped in a demonstration CA certificate and stored in the truststore. If your applications not using the truststore, then you must import the demonstration CA certificate to a custom keystore.
Task 2, Generating a CSR for a Key Pair
Use the exportKeyStoreCertificateRequest WLST command. For example, assuming an application stripe is stripe1, the following command generates a CSR from the testalias key pair:
svc.exportKeyStoreCertificateRequest(appStripe='stripe1', name='keystore1', password='mypassword', alias='testalias', keypassword='keypassword', filepath='/tmp/csr-file')
where mypassword is the keystore password and keypassword is the password of the alias. The CSR is exported to an operating system file.
Task 3, Importing a Certificate
Use the importKeyStoreCertificate WLST command. For example, assuming the appstripe1 application stripe, the following command imports a certificate with mykey alias from an operating system file:
svc.importKeyStoreCertificate(appStripe='appstripe1', name='keystore2', password='mypassword', alias='mykey', keypassword='keypassword', type='Certificate', filepath='/tmp/cert.txt')
where mypassword is the keystore password and keypassword is the password of the alias.
Task 4, Exporting a Certificate
Use the exportKeyStoreCertificate WLST command. For example, assuming the appstripe1 application stripe, the following command exports a certificate with mykey alias to an operating system file:
svc.exportKeyStoreCertificate(appStripe='appstripe1', name='keystore2', password='mypassword', alias='mykey', keypassword='keypassword', type='Certificate', filepath='/tmp/cert.txt')
where mypassword is the keystore password and keypassword is the password of the alias.
Task 5, Changing a Certificate Password
Use the changeKeyPassword WLST command. For example, assuming the system1 system stripe, the following command deletes a certificate with testkey alias:
svc.changeKeyPassword(appStripe='system1', name='keystore', password='password', alias='testkey', currentkeypassword='currentkeypassword', newkeypassword='newkeypassword')
where password is the keystore password and keypassword is the password of the certificate alias.
Task 6, Deleting a Certificate
Use the deleteKeyStoreEntry WLST command. For example, assuming the appstripe application stripe, the following command deletes a certificate with orakey alias:
ssvc.deleteKeyStoreEntry(appStripe='appstripe', name='keystore2', password='password', alias='orakey', keypassword='keypassword')
where password is the keystore password and keypassword is the password of the alias.
It is recommended that you use third-party CA signed certificates when you deploy applications to a production environment. Use the following procedure to set up a third-party CA signed certificate.
Generate a key pair in KSS using a specified alias.
Generate a CSR the key pair.
Submit the new CSR to a third-party CA. The CA will sign the public key in the CSR and return a CA signed certificate and its own certificate.
Some CAs return a certificate chain containing both the CA signed certificate and its own certificate, instead of two separate certificates.
Import the CA signed certificate (or the certificate chain) using the alias specified to generate the key pair.
Import the CA signed certificate (or the certificate chain) as a trusted certificate using a new alias.
After configuring keystores in Oracle WebLogic Server, use them to generate keys and certificates. You can also configure Node Manager to use the Keystore Service.
See also:
Configuring SSL in Administering Security for Oracle WebLogic Server 12c
Configure Keystores in Oracle WebLogic Server Administration Console Online Help
Configuring Node Manager to Use the OPSS Keystore Service in Administering Oracle Fusion Middleware
Keys and certificates are kept in the security store. Oracle recommends that all Oracle Fusion Middleware stack components use this central store. However, because certain infrastructure components require starting before the security store is available, they use instead the local file instance.
Use the syncKeyStores command to create the local file instance from the central security store. Synchronization is a one-way procedure in which key data is read from the security store to synchronize data in the local file instance.
For example, when you update the central store, the local keystore copy used by WebLogic Server should be synchronized with the central store with the syncKeyStores command.
The syntax of the syncKeyStores command is:
syncKeyStores
This command looks for the system stripe in the central repository and download its contents into a file named keystores.xml in DOMAIN_HOME/config/fmwconfig. It also downloads the contents of the truststore into the same file.
To determine when to use the syncKeyStores command, consider the following guidelines:
If the keystore being updated belongs to WebLogic Server, then the keystore is located under the system stripe.
If the truststore is changed (a trusted certificate is added or removed), then call the synchronization command for WebLogic Server.
Updating the keystore for any layered component like Oracle Web Services Manager or Java EE applications does not require executing the synchronization command. Such components access their key material from the central security store directly.
KSS uses a dedicated set of commands for keystore operations such as creating and managing keystores, exporting certificates, and generating key pairs. While their usage is similar, these commands are distinct from other OPSS commands.
The starting point to all these commands is the getOpssService command, which gets an OPSS service command object that lets you:
Execute commands for the service
Obtain command help
The command syntax is:
getOpssService(name='service_name')
where the name argument specifies the service you want to obtain. The only valid value is 'KeyStoreService'.
variable stores the command object
S
For example:
svc = getOpssService(name='KeyStoreService')
To obtain help for any KSS command, start by obtaining a service command object. Then use this object in conjunction with the help command and the command in question.
To obtain the list of all Keystore Service commands, enter:
svc.help()
To obtain help for a specific command, enter:
svc.help('command-name')
For example, the following returns help for the exportKeyStore command:
svc.help('exportKeyStore')
For syntax and reference information about the KSS commands, see OPSS Keystore Service Commands in the Oracle Fusion Middleware Infrastructure Security WLST Command Reference.
Use the following procedures to configure SSL connections to the keystore:
To enable one-way SSL between multiple LDAPs and the keystore:
Export the store certificate from the LDAP directory with the export command.
Use the importKeyStoreCertificate command to import the store certificate from the external LDAP server into the shared domain truststore. For example:
svc.importKeyStoreCertificate(appStripe='system', name='trust', password='', alias='alias', keypassword='', type='TrustedCertificate',filepath='absolute _file_path')
where appStripe='system'name='trust' is the truststore.
Restart WebLogic Server.
To enable two-way SSL between multiple LDAPs and the keystore:
Export the store certificate from the LDAP directory with the LDAP server export utility.
Use importKeyStoreCertificate to import the certificate from external LDAP server into the shared domain truststore:
svc.importKeyStoreCertificate(appStripe='system', name='trust', password='', alias='alias', keypassword='', type='TrustedCertificate',filepath='absolute _file_path')
where appStripe='system'name='trust' is the truststore.
Create the keystore with the createKeyStore command passing the appStripe='libovd' and name='adapters' arguments:
svc.createKeyStore(appStripe='libovd',name='adapters',password='',permission=true)
Run generateKeyPair to generate a new signed certificate:
svc.generateKeyPair(appStripe='libovd',name='adapters',password='',dn='cn=directory manager', keysize='1024',alias='alias',keypassword='', algorithm='RSA’)
Export this certificate to a file with the exportKeyStoreCertificate command:
svc.exportKeyStoreCertificate(appStripe='libovd',name='adapters',password='',
alias='key1', type='Certificate',
filepath='/tmp/cert.txt')
Import the generated certificate to the LDAP server.
Change "property name="enabled" value="true"" to KSSKeyManager in provider.os_xml under DOMAIN_HOME/config/fmwconfig/ovd/default.
Restart WebLogic Server.
Use the following procedure to switch the LibOVD adapter from a configuration that uses JKS to a configuration that uses KSS.
Import the LDAP certificates from the LibOVD adapter (that uses JKS) to the truststore with the importKeyStore WLST command:
importKeyStore(appStripe='system', name='trust', password='welcome1', aliases='alias_names_from_JKS', keypasswords='',type='JKS', permission=true, filepath='DOMAIN_HOME/config/fmwconfig/ovd/<context_ name>/keystores/adapters.jks')
Open the DOMAIN_HOME/config/fmwconfig/ovd/<context_name>/provider.os_xml file and make the following changes to enable KSS:
Look for provider name=KSSTrustManager and change enabled to true.
Look for provider name=FileKeyManager and change enabled to false.
Look for provider name=FileTrustManager and change enabled to false.
If you were using two-way SSL, then:
Create the LibOVD keystore in KSS with the createKeyStore WLST command:
createKeyStore(appStripe='libovd',name='adapters',password='myPass',permission=true)
Import the generated key pair from adapters.jks to the LibOVD keystore with the importKeyStore WLST command:
importKeyStore(appStripe='libovd', name='adapters', password='myPassw', aliases='alias_names_from_JKS', keypasswords='',type='JKS', permission=true, filepath='DOMAIN_HOME/config/fmwconfig/ovd/default/keystores/adapters.jks')
Open the DOMAIN_HOME/config/fmwconfig/ovd/<context_name>/provider.os_xml file, look for KSSKeyManager, and replace enabled for true.
Restart WebLogic Server.
Establishing SSL connections between multiple LDAPs and JKS requires keystore certificates that are kept in multiple locations, such as the WebLogic Server truststore and the adapters.jks file.
Table 12-1 lists the procedure you use to configure SSL with JKS depending on the virtualize flag and the API:
| Virtualize Flag | Using the User and Role API | Using the Identity Directory API |
|---|---|---|
|
|
Specify the truststore as explained in Section 9.2.2. |
Use |
|
|
Use |
Use |
To establish one-way SSL between multiple LDAPs and JKS:
Create a keystore to contain the LDAP server certificate(s) for use by the service. You must provide passwords for Oracle WebLogic Server Administration Console and the keystore, respectively. Before running libovdconfig.sh., set ORACLE_HOME to oracle_common.
To create the keystore run MW_HOME/oracle_common/bin/libovdconfig.sh with the createKeystore option:
libovdconfig.sh -host wls_host -port wls_adminserver_port -userName wls_user_name -domainPath full_path_domain_home -createKeystore
where:
host is the server host
port is the WebLogic Administration Server port
username is the administrator user name
domainPath is the complete path to the domain home
Export the certificate from the LDAP directory with the LDAP utility export.
Import the certificate to the created keystore with the keytool command:
$JAVA_HOME/bin/keytool -importcert -keystore $DOMAIN_HOME/config/fmwconfig/ovd/default/keystores/adapters.jks -storepass keystore_password_used_in_libovdconfig.sh -alias alias_name -file full_path_to_LDAPCert_file -noprompt
Restart WebLogic Server.
To establish two-way SSL between multiple LDAPs and JKS:
Perform the procedure described in Section 12.11.1.
In the keystore that was created, generate a new signed certificate.
Export this certificate to a file.
Import the certificate into the domain keystore.