This chapter explains how to use the Keystore Service to administer keys and certificates.
This chapter contains these topics:
The OPSS Keystore Service enables you to manage keys and certificates for SSL, message security, encryption, and related tasks. You use the Keystore Service to create and maintain keystores that contain keys, certificates, and other artifacts. You can also import or export to Oracle Wallet, a feature useful for system components such as Oracle HTTP Server that use wallets at runtime.
The following topics introduce Keystore Service concepts:
Each keystore created with the Keystore Service is uniquely referenced by an application stripe and keystore.
Application Stripe
Keys and certificates created in the keystore reside in an application stripe or product, and each stripe in a domain is uniquely named.
Keystore
The keystore name is unique within an application stripe. Each product or application is allowed to create more than one keystore within its application stripe.
Thus (appstripe1, keystoreA)
is unique and distinct from (appstripe1, keystoreB)
, which is distinct from (appstripe2, keystoreA)
.
In turn, each keystore may contain the following entries, referenced by an alias that is unique within the keystore:
Asymmetric Keys - These include the public key and the corresponding private key, and are typically used for SSL communication. The public key is wrapped in a certificate.
Symmetric Keys - These keys are generally used for encryption.
Trusted Certificates - These certificates are typically used to establish trust with an SSL peer.
The Keystore Service lets you create two types of keystores:
Keystores protected by Permission
These types of keystores are protected by authorization policies and any access to them by runtime code is protected by code source permissions. The key data in the backend is encrypted using an encryption key that is generated uniquely for each domain.
Keystores protected by Password
These types of 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 in the back-end is encrypted using the keystore/key password through password-based encryption (PBE).
It is recommended that you use permission-protected keystores for applications. If you require high security and are willing to manage passwords, however, consider using keystores that are password-protected.
Note:
The Keystore Service does not manage passwords for keystore or keys. The product or application is responsible for managing them in an appropriate repository. For example, you may choose to store the passwords for your applications in a credential store.Export/Import Between Keystore and Wallet
You can export or import a keystore to/from Oracle Wallet, a feature useful for system components such as Oracle HTTP Server that use wallets at runtime.
For details, see Section 12.2.2.7 and Section 12.2.2.8.
Caution:
The Demo CA has a well known hard-coded private key, Care should be taken not to trust the certificates signed by the Demo CA. As such, the Demo CA certificate in the trust store should not be used in production. It should be removed from the domain trust store in production.Although each application may configure multiple keystores for its SSL usage, a domain-level trust store comes pre-configured for all products and applications to use for trust management.
This domain trust store contains the trusted certificates of most well-known third-party Certificate Authorities (CAs) as well as the trusted certificate of the demo CA that is configured with the Keystore Service. Each application can simply point to this domain trust store for its SSL needs, eliminating the need to create a dedicated trust store for this task.
For one-way SSL, applications can simply use the domain trust store and do not need to create any keystore or trust store.
For two-way SSL, applications should create only the keystore containing their identity certificate and use the domain trust store for trust.
Note:
The domain trust store is a shared store for all products and applications in a domain. The decision to add or remove trust should not be taken lightly since it may affect all other products in the domain.Consider creating a custom trust store only if a product's trust management requirements are not met by the domain trust store.
For a domain with multiple servers, the only recommended store types are LDAP or DB. Do not configure a file-based store in such an environment.
Troubleshooting topics related to the keystore service are addressed in Appendix J. Currently, the following topic may be of interest:
This section describes the typical lifecycle of keystores and certificates, and how to use the keystore service to create and maintain keystores and certificates. It includes these topics:
Typical lifecycle events for a KSS keystore are as follows:
The keystore is created in the context of an application stripe. Keystores can be created directly or by importing a keystore file from the file system.
The list of available keystores is viewed and specific keystores selected for update.
Keystores are updated or deleted. For a password-protected keystore, update operations require that the keystore password be entered.
The keystore password can be changed.
The keystore can be deleted.
Keystores can be exported and imported. KSS supports migration for these certificate formats:
JKS
JCEKS
Oracle Wallet
This section explains the following keystore operations that you can perform through Fusion Middleware Control or at the command line:
Take these steps to create a keystore:
Log in to Fusion Middleware Control.
From the navigation pane, locate the domain of interest.
Navigate to Security, then Keystore. The Keystore page appears.
Select the stripe in which the keystore is to be created. If necessary, create a stripe as follows:
Click Create Stripe. The Create Stripe dialog appears.
Provide a unique stripe name. Any combination of characters is possible, but it is recommended that you do not use the forward slash (/) in the name.
Click Submit. The new stripe appears in the list of stripes and you can select it for keystore creation.
Click Create Keystore.
The Create Keystore dialog appears.
Complete the dialog form as follows:
Keystore Name: Enter a unique keystore name. Do not use any special (non-ascii) characters or characters from a different encoding or locale.
Protection Type: Select the protection mechanism for the keystore; choose between Policy and Password.
For a password-protected keystore, enter a valid password.
Grant Permission: Check this box to grant permissions using code URL.
Click OK. The new keystore appears under the appropriate stripe.
You can create a keystore using the createKeyStore
script at the command line. For example, assuming the stripe name is teststripe1
, use this command to create a permission-based keystore:
svc.createKeyStore(appStripe='teststripe1', name='keystore1', password='password',permission=true)
where password
is the password for this keystore. Section 12.5 explains how to obtain the OPSS service command object.
Any combination of characters is possible when specifying a new stripe, but it is recommended that you do not use the forward slash (/) in the name.
Enter a unique keystore name. Do not use any special (non-ascii) characters or characters from a different encoding or locale.
See Also:
Oracle Fusion Middleware Infrastructure Security WLST Command ReferenceWhen you delete a keystore, be aware that all certificates in the keystore are also deleted. If any functions rely on these certificates, they will be rendered unusable as a result.
Take these steps to delete a keystore:
Log in to Fusion Middleware Control.
From the navigation pane, locate the domain of interest.
Navigate to Security, then Keystore. The Keystore page appears.
Expand the stripe in which the keystore resides. Select the row corresponding to the keystore.
Click Delete.
The Delete Keystore dialog appears.
If this is a password-protected keystore, enter the keystore password.
Click OK.
You can delete a keystore using the deleteKeyStore
script at the command line. For example, assuming the stripe is named appstripe1
, use this command to delete a keystore:
svc.deleteKeyStore(appStripe='appstripe1', name='keystore1', password='password')
where password
is the password for this keystore. Section 12.5 explains how to obtain the OPSS service command object.
See Also:
Oracle Fusion Middleware Infrastructure Security WLST Command ReferenceTo change the password for a password-protected keystore:
Log in to Fusion Middleware Control.
From the navigation pane, locate the domain of interest.
Navigate to Security, then Keystore. The Keystore page appears.
Expand the stripe in which the keystore resides. Select the row corresponding to the keystore.
Click Change Password.
The Change Keystore Password dialog appears.
Enter the old and new passwords.
Click OK.
You can change a keystore's password using the changeKeyStorePassword
script at the command line. For example, assuming the instance name is system, use this command to change the keystore password:
svc.changeKeyStorePassword(appStripe='system', name='keystore2', currentpassword='currentpassword', newpassword='newpassword')
where currentpassword
is the current password for this keystore, and newpassword
is the new password. Section 12.5 explains how to obtain the OPSS service command object.
You can export a keystore using the exportKeyStore
script at the command line.
For example, assuming stripe name mystripe, alias named myorakey to be exported, alias password keypassword1, the following command exports the keystore to a file:
svc.exportKeyStore(appStripe='mystripe', name='keystore2', password='password',aliases='myorakey', keypasswords='keypassword1', type='JKS',filepath='/tmp/file.jks')
where password
is the password for this keystore. Section 12.5 explains how to obtain the OPSS service command object.
To export multiple keys using this command, specify a comma-separated list of aliases and key passwords.
When exporting a keystore containing a symmetric key, use the JCEKS
type. For example:
svc.exportKeyStore(appStripe='mystripe', name='keystore2', password='password',aliases='myorakey', keypasswords='keypassword1', type='JCEKS',filepath='/tmp/file.jks')
To export a keystore to an Oracle Wallet, use the type 'OracleWallet'. For example:
svc.exportKeyStore(appStripe='mystripe', name='keystore3', password='mypassword',aliases='myorakey1,myorakey2', keypasswords='', type='OracleWallet',path='/tmp')
See Also:
Oracle Fusion Middleware Infrastructure Security WLST Command ReferenceYou can import a keystore using the importKeyStore
script at the command line.
For example, assuming stripe name mystripe, alias named myorakey to be imported, alias password keypassword1, the following command imports a keystore from an operating system file:
svc.importKeyStore(appStripe='mystripe', name='keystore2', password='password',aliases='myorakey', keypasswords='keypassword1', type='JKS', permission=true, filepath='/tmp/file.jks')
where password
is the keystore password. Section 12.5 explains how to obtain the OPSS service command object.
To import multiple keys using this command, specify a comma-separated list of aliases and key passwords.
To import one or more keys from an Oracle Wallet, use the type 'OracleWallet'. For example:
svc.importKeyStore(appStripe='mystripe', name='keystore4', password='owPwd1234',aliases='myorakey1,myorakey2', keypasswords='', type='OracleWallet', permission=true, filepath='/tmp')
See Also:
Oracle Fusion Middleware Infrastructure Security WLST Command ReferenceThis section explains how to manage certificates with the Keystore Service. It contains these topics:
Typical lifecycle events for a certificate residing in a Keystore Service (KSS) keystore are as follows:
A self-signed certificate is automatically created for the keypair.
A certificate signing request (CSR) is generated for the certificate, and can be saved to a file.
The CSR is sent to a certificate authority, who verifies the sender, signs and returns the signed certificate.
Certificates are imported into the keystore. A certificate can either be pasted into a text box or imported from the file system. You can import both user certificates and trusted certificates (also known as CA certificates) in this way.
Note:
Keystore Service supports import of PEM/BASE64-encoded certificates only. You cannot import DER-encoded certificates or trusted certificates into a KSS keystore.Certificates or trusted certificates are exported from the keystore out to a file.
Certificates or trusted certificates are deleted from the keystore.
This section explains the common certificate operations:
Generating CSR for a Certificate with Fusion Middleware Control
Importing a Certificate or Trusted Certificate with Fusion Middleware Control
Exporting a Certificate or Trusted Certificate with Fusion Middleware Control
Exporting a Certificate or Trusted Certificate at the Command Line
Changing Certificate Password with Fusion Middleware Control
To generate a certificate with an associated keypair:
Log in to Fusion Middleware Control.
From the navigation pane, locate the domain of interest.
Navigate to Security, then Keystore. The Keystore page appears.
Expand the stripe in which the keystore resides. Select the row corresponding to the keystore.
Click Manage.
If the keystore is password-protected, you are prompted for a password. Enter the keystore password and click OK.
The Manage Certificates page appears:
The Expiration Date column enables you to quickly assess which certificates are expiring or already expired.
Click Generate Keypair.
The Generate Keypair dialog appears:
Provide the following information:
Alias (required)
Common Name (required)
Organizational Unit
Organization
City
State
Country: Choose from the drop-down box.
RSA Key Size: Choose from the drop-down box. Default is 1024 bytes.
Click OK.
The new certificate appears in the list of certificates.
You can view the certificate details by clicking on the certificate alias:
The generated keypair is wrapped in a CA signed certificate (using a Demo CA). To use this certificate for SSL or where trust needs to be established, applications must either use the domain trust store as their trust store (since it contains the Demo CA certificate) or import the certificate to a custom application-specific trust store.
You can generate a keypair for a keystore using the generateKeyPair
script at the command line. For example, assuming an application stripe named appstripe2, the following command creates a keypair with alias myalias:
svc.generateKeyPair(appStripe='appstripe2', name='keystore2', password='password', dn='cn=www.example.com', keysize='1024', alias='myalias', keypassword='keypassword')
where password
is the keystore password and keypassword
is the password of the alias. Section 12.5 explains how to obtain the OPSS service command object.
See Also:
Oracle Fusion Middleware Infrastructure Security WLST Command Reference.The generated keypair is wrapped in a CA signed certificate (using a Demo CA). To use this certificate for SSL or where trust needs to be established, applications must either use the domain trust store as their trust store (since it contains the Demo CA certificate) or import the certificate to a custom application-specific trust store.
To generate a CSR for a certificate or trusted certificate:
Log in to Fusion Middleware Control.
From the navigation pane, locate the domain of interest.
Navigate to Security, then Keystore. The Keystore page appears.
Expand the stripe in which the keystore resides. Select the row corresponding to the keystore.
Click Manage.
If the keystore is password-protected, you are prompted for a password. Enter the keystore password and click OK.
The Manage Certificates page appears. Select the row corresponding to the certificate and click Generate CSR.
The Generate CSR dialog appears:
You can:
Copy and paste the entire CSR into a text file, and click Close.
or
Click Export CSR to automatically save the CSR to a file.
You can send the resulting certificate request to a certificate authority (CA) which will return a signed certificate.
You can generate a CSR for a keypair using the exportKeyStoreCertificateRequest
script at the command line. For example, assuming an application stripe stripe1, the following command generates a CSR from the keypair testalias:
svc.exportKeyStoreCertificateRequest(appStripe='stripe1', name='keystore1', password='password', alias='testalias', keypassword='keypassword', filepath='/tmp/csr-file')
where password
is the keystore password and keypassword
is the password of the alias. The CSR is exported to an operating system file. Section 12.5 explains how to obtain the OPSS service command object.
See Also:
Oracle Fusion Middleware Infrastructure Security WLST Command Reference.To import a certificate into a password-protected keystore:
Log in to Fusion Middleware Control.
From the navigation pane, locate the domain of interest.
Navigate to Security, then Keystore. The Keystore page appears.
Expand the stripe in which the keystore resides. Select the row corresponding to the keystore.
Click Manage.
If the keystore is password-protected, you are prompted for a password. Enter the keystore password and click OK.
The Manage Certificates page appears. Click Import.
The Import Certificate dialog appears:
Complete this form as follows:
Select the certificate type, either Certificate or Trusted Certificate, from the drop-down.
Select the alias from the drop-down.
Specify the certificate source. If using the Paste option, copy and paste the certificate directly into the text box. If using the Select a file option, click Browse to select the file from the operating system.
Click OK. The imported certificate or trusted certificate appears in the list of certificates.
Click OK.
The certificate appears in the list of certificates.
You can import a certificate using the importKeyStoreCertificate script at the command line. For example, assuming an application stripe appstripe1, the following command imports a certificate with alias mykey
from an operating system file:
svc.importKeyStoreCertificate(appStripe='appstripe1', name='keystore2', password='password', alias='mykey', keypassword='keypassword', type='Certificate', filepath='/tmp/cert.txt')
where password
is the keystore password and keypassword
is the password of the alias. Section 12.5 explains how to obtain the OPSS service command object.
See Also:
Oracle Fusion Middleware Infrastructure Security WLST Command Reference.Take these steps to export a certificate or trusted certificate:
Log in to Fusion Middleware Control.
From the navigation pane, locate the domain of interest.
Navigate to Security, then Keystore. The Keystore page appears.
Expand the stripe in which the keystore resides. Select the row corresponding to the keystore.
Click Manage.
If the keystore is password-protected, you are prompted for a password. Enter the keystore password and click OK.
The Manage Certificates page appears. Select the row corresponding to the certificate and click Export.
The certificate export dialog appears:
You can:
Copy and paste the entire certificate into a text file, and click Close.
or
Click Export Certificate to automatically save the certificate to a file.
You can export a certificate using the exportKeyStoreCertificate script at the command line. For example, assuming an application stripe appstripe1, the following command exports a certificate with alias mykey
to an operating system file:
svc.exportKeyStoreCertificate(appStripe='appstripe1', name='keystore2', password='password', alias='mykey', keypassword='keypassword', type='Certificate', filepath='/tmp/cert.txt')
where password
is the keystore password and keypassword
is the password of the alias. Section 12.5 explains how to obtain the OPSS service command object.
See Also:
Oracle Fusion Middleware Infrastructure Security WLST Command Reference.Take these steps to delete a certificate:
Log in to Fusion Middleware Control.
From the navigation pane, locate the domain of interest.
Navigate to Security, then Keystore. The Keystore page appears.
Expand the stripe in which the keystore resides. Select the row corresponding to the keystore.
Click Manage.
If the keystore is password-protected, you are prompted for a password. Enter the keystore password and click OK.
The Manage Certificates page appears. Select the row corresponding to the certificate and click Delete.
The Delete Certificate dialog appears:
You are asked to confirm deletion. Click OK.
You can delete a certificate from a keystore using the deleteKeyStoreEntry script at the command line. For example, assuming an application stripe appstripe, the following command deletes a certificate with alias orakey:
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. Section 12.5 explains how to obtain the OPSS service command object.
See Also:
Oracle Fusion Middleware Infrastructure Security WLST Command Reference.Take these steps to change certificate password:
Log in to Fusion Middleware Control.
From the navigation pane, locate the domain of interest.
Navigate to Security, then Keystore. The Keystore page appears.
Expand the stripe in which the keystore resides. Select the row corresponding to the keystore.
Click Manage.
If the keystore is password-protected, you are prompted for a password. Enter the keystore password and click OK.
The Manage Certificates page appears. Select 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.
You can change a certificate password using the changeKeyPassword script at the command line. For example, assuming an application stripe system1, the following command deletes a certificate with alias testkey:
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. Section 12.5 explains how to obtain the OPSS service command object.
See Also:
Oracle Fusion Middleware Infrastructure Security WLST Command Reference.This section explains how components and services make use of the Keystore Service to manage keys and certificates. Topics include:
In the Oracle WebLogic Server environment, the "source of truth" for keystores and truststores is the OPSS security store, which acts as the central security store. Oracle recommends that all Oracle Fusion Middleware stack components use this central store; however, certain infrastructure components (like Oracle WebLogic Server and Node Manager) require bootstrapping for which the local keystore instance is used.
The WLST syncKeyStores
command is used 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 database security store to synchronize the local file instance.
For example, when you update the domain trust store in the central security store, the local keystore copy used by Oracle Weblogic Server can be synchronized with the central store using this command.
The syntax of the syncKeyStores command is as follows:
syncKeyStores ()
This command looks for the "system" stripe in the central repository and download its contents into a file named keystores.xml
under the DOMAIN_HOME/config/fmwconfig
directory. It also downloads the contents of the domain truststore into the same file.
Use the following guidelines to determine when you should use the syncKeyStores
command:
If the keystore being updated belongs to Oracle WebLogic Server, such a keystore would likely be present under the "system" stripe; for example "demoidentity" keystore.
If the domain trust store is updated (either a trusted certificate is added or removed), then invoke the synchronization command for Oracle WebLogic Server.
Updating the keystore for any layered component like Web Services, Oracle Web Services Manager, or JavaEE applications does not require executing the synchronization command. Such components directly access their key material from the central security store.
When configuring keystores for use with Oracle WebLogic Server, you can use Keystore Service to generate the keys and certificates.
For details about keystore and SSL configuration in Oracle WebLogic Server see:
"Configure Keystores" in the Oracle WebLogic Server Administration Console Online Help
"Configuring SSL" in Administering Security for Oracle WebLogic Server.
You can configure Node Manager to use the Keystore Service. For details, see "Configuring Node Manager to Use the OPSS Keystore Service" in Administering Oracle Fusion Middleware.
For more information about Node Manager, see Administering Node Manager for Oracle WebLogic Server.
You can configure SSL communication from the identity store to LDAP servers. For details, see Section 8.5.2.
The Keystore Service uses a dedicated set of command-line 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 for using the Keystore Service command set is getOpssService
, which gets an OPSS service command object that enables you to:
execute commands for the service
obtain command help
The general syntax is:
variable = getOpssService(name='service_name')
where
the variable
stores the command object
the service name refers to the service whose command object is to be obtained. The only valid value is 'KeyStoreService
'.
For example:
svc = getOpssService(name='KeyStoreService')
To obtain help for any Keystore Service command, start by obtaining a service command object as explained in Section 12.5. Use this object in conjunction with the help command and the command in question.
To obtain a 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 Keystore Service commands, see "OPSS Keystore Service Commands" in the Oracle Fusion Middleware Infrastructure Security WLST Command Reference.