Home / Middleware / Oracle Platform Security Services

12 Managing Keys and Certificates with the Keystore Service

This chapter explains how to use the Keystore Service to administer keys and certificates.

This chapter contains these topics:

• About the Keystore Service

• Keystore Management with the Keystore Service

• Certificate Management with the Keystore Service

• How Oracle Fusion Middleware Components Use the Keystore Service

• About Keystore Service Commands

• Getting Help for Keystore Service Commands

• Keystore Service Command Reference

12.1 About the Keystore Service

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. The following topics introduce Keystore Service concepts:

• Structure of the Keystore Service

• Types of Keystores

• Domain Trust Store

• Keystores for Domains with Multiple Servers

• Troubleshooting Keystore Service

12.1.1 Structure of the Keystore Service

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.

12.1.2 Types of Keystores

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.

12.1.3 Domain Trust Store

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.

One-Way SSL

For one-way SSL, applications can simply use the domain trust store and do not need to create any keystore or trust store.

Two-Way SSL

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.

12.1.4 Keystores for Domains with Multiple Servers

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.

12.1.5 Troubleshooting Keystore Service

Troubleshooting topics related to the keystore service are addressed in Appendix J. Currently, the following topic may be of interest:

• Section J.9.6, "Invalid Key Size".

12.2 Keystore Management with the Keystore Service

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:

• About the Keystore Lifecycle

• Common Keystore Operations

12.2.1 About the Keystore Lifecycle

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 JKS and JCEKS certificate formats.

12.2.2 Common Keystore Operations

This section explains the following keystore operations that you can perform through Fusion Middleware Control or at the command line:

• Creating a Keystore with Fusion Middleware Control

• Creating a Keystore at the Command Line

• Deleting a Keystore with Fusion Middleware Control

• Deleting a Keystore at the Command Line

• Changing Keystore Password with Fusion Middleware Control

• Changing Keystore Password at the Command Line

• Exporting a Keystore at the Command Line

• Importing a Keystore at the Command Line

12.2.2.1 Creating a Keystore with Fusion Middleware Control

Take these steps to create a keystore:

1. Log in to Fusion Middleware Control.

2. From the navigation pane, locate the domain of interest.

3. Navigate to Security, then Keystore. The Keystore page appears.

4. Select the stripe in which the keystore is to be created. If necessary, create a stripe as follows:

   1. Click Create Stripe. The Create Stripe dialog appears.

      
      

   2. 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.

   3. Click Submit. The new stripe appears in the list of stripes and you can select it for keystore creation.

5. Click Create Keystore.

6. The Create Keystore dialog appears.

   
   

7. 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.

8. Click OK. The new keystore appears under the appropriate stripe.

12.2.2.2 Creating a Keystore at the Command Line

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 Reference

12.2.2.3 Deleting a Keystore with Fusion Middleware Control

When 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:

1. Log in to Fusion Middleware Control.

2. From the navigation pane, locate the domain of interest.

3. Navigate to Security, then Keystore. The Keystore page appears.

4. Expand the stripe in which the keystore resides. Select the row corresponding to the keystore.

5. Click Delete.

6. The Delete Keystore dialog appears.

   
   

7. If this is a password-protected keystore, enter the keystore password.

8. Click OK.

12.2.2.4 Deleting a Keystore at the Command Line

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 Reference

12.2.2.5 Changing Keystore Password with Fusion Middleware Control

To change the password for a password-protected keystore:

1. Log in to Fusion Middleware Control.

2. From the navigation pane, locate the domain of interest.

3. Navigate to Security, then Keystore. The Keystore page appears.

4. Expand the stripe in which the keystore resides. Select the row corresponding to the keystore.

5. Click Change Password.

6. The Change Keystore Password dialog appears.

   
   

7. Enter the old and new passwords.

8. Click OK.

12.2.2.6 Changing Keystore Password at the Command Line

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.

12.2.2.7 Exporting a Keystore at the Command Line

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')

See Also:

Oracle Fusion Middleware Infrastructure Security WLST Command Reference

12.2.2.8 Importing a Keystore at the Command Line

You 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.

See Also:

Oracle Fusion Middleware Infrastructure Security WLST Command Reference

12.3 Certificate Management with the Keystore Service

This section explains how to manage certificates with the Keystore Service. It contains these topics:

• About the Certificate Lifecycle

• Common Certificate Operations

12.3.1 About the Certificate Lifecycle

Typical lifecycle events for a certificate residing in a Keystore Service 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.

• Certificates or trusted certificates are exported from the keystore out to a file.

• Certificates or trusted certificates are deleted from the keystore.

12.3.2 Common Certificate Operations

This section explains the common certificate operations:

• Generating a Keypair with Fusion Middleware Control

• Generating a Keypair at the Command Line

• Generating CSR for a Certificate with Fusion Middleware Control

• Generating CSR for a Keypair at the Command Line

• Importing a Certificate or Trusted Certificate with Fusion Middleware Control

• Importing a Certificate at the Command Line

• Exporting a Certificate or Trusted Certificate with Fusion Middleware Control

• Exporting a Certificate or Trusted Certificate at the Command Line

• Deleting a Certificate with Fusion Middleware Control

• Deleting a Certificate at the Command Line

• Changing Certificate Password with Fusion Middleware Control

• Changing Certificate Password at the Command Line

12.3.2.1 Generating a Keypair with Fusion Middleware Control

To generate a certificate with an associated keypair:

1. Log in to Fusion Middleware Control.

2. From the navigation pane, locate the domain of interest.

3. Navigate to Security, then Keystore. The Keystore page appears.

4. Expand the stripe in which the keystore resides. Select the row corresponding to the keystore.

5. Click Manage.

6. If the keystore is password-protected, you are prompted for a password. Enter the keystore password and click OK.

7. The Manage Certificates page appears:

   
   

   The Expiration Date column enables you to quickly assess which certificates are expiring or already expired.

   Click Generate Keypair.

8. The Generate Keypair dialog appears:

   
   

9. 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.

10. Click OK.

    The new certificate appears in the list of certificates.

    
    

11. 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.

12.3.2.2 Generating a Keypair at the Command Line

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.

12.3.2.3 Generating CSR for a Certificate with Fusion Middleware Control

To generate a CSR for a certificate or trusted certificate:

1. Log in to Fusion Middleware Control.

2. From the navigation pane, locate the domain of interest.

3. Navigate to Security, then Keystore. The Keystore page appears.

4. Expand the stripe in which the keystore resides. Select the row corresponding to the keystore.

5. Click Manage.

6. If the keystore is password-protected, you are prompted for a password. Enter the keystore password and click OK.

7. The Manage Certificates page appears. Select the row corresponding to the certificate and click Generate CSR.

8. 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.

12.3.2.4 Generating CSR for a Keypair at the Command Line

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.

12.3.2.5 Importing a Certificate or Trusted Certificate with Fusion Middleware Control

To import a certificate into a password-protected keystore:

1. Log in to Fusion Middleware Control.

2. From the navigation pane, locate the domain of interest.

3. Navigate to Security, then Keystore. The Keystore page appears.

4. Expand the stripe in which the keystore resides. Select the row corresponding to the keystore.

5. Click Manage.

6. If the keystore is password-protected, you are prompted for a password. Enter the keystore password and click OK.

7. The Manage Certificates page appears. Click Import.

8. 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.

9. Click OK.

   The certificate appears in the list of certificates.

12.3.2.6 Importing a Certificate at the Command Line

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.

12.3.2.7 Exporting a Certificate or Trusted Certificate with Fusion Middleware Control

Take these steps to export a certificate or trusted certificate:

1. Log in to Fusion Middleware Control.

2. From the navigation pane, locate the domain of interest.

3. Navigate to Security, then Keystore. The Keystore page appears.

4. Expand the stripe in which the keystore resides. Select the row corresponding to the keystore.

5. Click Manage.

6. If the keystore is password-protected, you are prompted for a password. Enter the keystore password and click OK.

7. The Manage Certificates page appears. Select the row corresponding to the certificate and click Export.

8. 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.

12.3.2.8 Exporting a Certificate or Trusted Certificate at the Command Line

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.

12.3.2.9 Deleting a Certificate with Fusion Middleware Control

Take these steps to delete a certificate:

1. Log in to Fusion Middleware Control.

2. From the navigation pane, locate the domain of interest.

3. Navigate to Security, then Keystore. The Keystore page appears.

4. Expand the stripe in which the keystore resides. Select the row corresponding to the keystore.

5. Click Manage.

6. If the keystore is password-protected, you are prompted for a password. Enter the keystore password and click OK.

7. The Manage Certificates page appears. Select the row corresponding to the certificate and click Delete.

8. The Delete Certificate dialog appears:

   
   

   You are asked to confirm deletion. Click OK.

12.3.2.10 Deleting a Certificate at the Command Line

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.

12.3.2.11 Changing Certificate Password with Fusion Middleware Control

Take these steps to change certificate password:

1. Log in to Fusion Middleware Control.

2. From the navigation pane, locate the domain of interest.

3. Navigate to Security, then Keystore. The Keystore page appears.

4. Expand the stripe in which the keystore resides. Select the row corresponding to the keystore.

5. Click Manage.

6. If the keystore is password-protected, you are prompted for a password. Enter the keystore password and click OK.

7. The Manage Certificates page appears. Select the row corresponding to the certificate and click Change Password.

8. The Change Key Password dialog appears:

   
   

9. Enter the old and new passwords and click OK.

12.3.2.12 Changing Certificate Password at the Command Line

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.

12.4 How Oracle Fusion Middleware Components Use the Keystore Service

This section explains how components and services make use of the Keystore Service to manage keys and certificates. Topics include:

• Using the syncKeyStores Command

• Integrating with Oracle WebLogic Server

• Integrating with Node Manager

• Integrating with the Identity Store Service

12.4.1 Using the syncKeyStores Command

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.

• syncKeyStores Command Usage

• When to Use the syncKeyStores Command

12.4.1.1 syncKeyStores Command Usage

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.

12.4.1.2 When to Use the syncKeyStores Command

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.

12.4.2 Integrating with Oracle WebLogic Server

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.

12.4.3 Integrating with Node Manager

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.

12.4.4 Integrating with the Identity Store Service

You can configure SSL communication from the identity store to LDAP servers. For details, see Section 8.5.2.

12.5 About Keystore Service Commands

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')

12.6 Getting Help for Keystore Service Commands

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') 

12.7 Keystore Service Command Reference

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.