Skip Headers
Oracle® Fusion Middleware Application Security Guide
11g Release 1 (11.1.1)

Part Number E10043-12
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

11 Managing Keys and Certificates with the Keystore Service

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

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

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

11.1.2 Types of Keystores

The Keystore Service lets you create two types of keystores:

  • Keystores protected solely by Permission

    These types of key stores 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 per domain.

  • Keystores protected by both Permission and Password

    These types of key stores are protected both by authorization policies and key store and/or key passwords. Any access to them by runtime code requires both code source permissions as well as access to the key store and key password (if different from the key store password). The key data in the backend is encrypted using the key store/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 both password- and permission-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.

11.1.3 Domain Trust Store

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.

11.2 About Keystore Service Commands

The Keystore Service uses a dedicated set of commands for keystore operations such as creating and managing keystores, exporting certificates, and generating keypairs. 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:

The general syntax is:

variable = getOpssService(name='service_name')

where

For example:

svc = getOpssService(name='KeyStoreService')

11.3 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 11.2. 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') 

11.4 Keystore Service Command Reference

This section provides a reference to the keystore service commands, which are listed in Table 11-1.

Table 11-1 Keystore Service Commands

Command Description

changeKeyPassword

Changes the password for a key.

changeKeyStorePassword

Changes the password of a keystore.

createKeyStore

Creates a new keystore.

deleteKeyStore

Deletes the named keystore.

deleteKeyStoreEntry

Deletes a keystore entry.

exportKeyStore

Exports a keystore to file.

exportKeyStoreCertificate

Exports a certificate, trusted certificate, or certificate chain.

exportKeyStoreCertificateRequest

Generates and exports a certificate request.

generateKeyPair

Generates a key pair in a keystore.

generateSecretKey

Generates a symmetric key in a keystore.

getKeyStoreCertificates

Retrieves information about a certificate or trusted certificate.

getKeyStoreSecretKeyProperties

Retrieves secret key properties.

importKeyStore

Imports a keystore from a file.

importKeyStoreCertificate

Imports a certificate, trusted certificate or certificate chain.

listExpiringCertificates

Lists expiring certificates and optionally renews them.

listKeyStoreAliases

Lists the aliases in a keystore.

listKeyStores

Lists the keystores in a stripe.


11.4.1 changeKeyPassword

Description

Changes the password for a key.

Syntax

svc.changeKeyPassword(appStripe='stripe', name='keystore', password='password', alias='alias', currentkeypassword='currentkeypassword', newkeypassword='newkeypassword')

where:

  • svc=the service command object obtained through a call to getOpssService().

  • appStripe= the name of the stripe containing the keystore.

  • name= name of the keystore.

  • password= the keystore password.

  • alias= alias of the key entry whose password is changed.

  • currentkeypassword= the current key password.

  • newkeypassword= the new key password.

Example

svc.changeKeyPassword(appStripe='system', name='keystore', password='password', alias='orakey', currentkeypassword='currentkeypassword', newkeypassword='newkeypassword')

11.4.2 changeKeyStorePassword

Description

Changes the password of a keystore.

Syntax

svc.changeKeyStorePassword(appStripe='stripe', name='keystore', currentpassword='currentpassword', newpassword='newpassword')

where:

  • svc=the service command object obtained through a call to getOpssService().

  • appStripe= the name of the stripe containing the keystore.

  • name= the name of the keystore whose password is changed.

  • currentpassword= current keystore password.

  • newpassword= new keystore password

Example

svc.changeKeyStorePassword(appStripe='system', name='keystore2', currentpassword='currentpassword', newpassword='newpassword')

11.4.3 createKeyStore

Description

Creates a new keystore.

Syntax

svc.createKeyStore(appStripe='stripe', name='keystore', password='password',permission=true|false)

where:

  • svc=the service command object obtained through a call to getOpssService().

  • appStripe= the name of the stripe in which the keystore is created.

  • name= the name of the keystore.

  • password= Password of the keystore.

  • permission= true if keystore is protected by permission only, false if protected by both permission and password.

Example

svc.createKeyStore(appStripe='system', name='keystore1', password='password',permission=true)

11.4.4 deleteKeyStore

Description

Deletes the named keystore.

Syntax

svc.deleteKeyStore(appStripe='stripe', name='keystore', password='password')

where:

  • svc=the service command object obtained through a call to getOpssService().

  • appStripe= the name of the stripe in which keystore is deleted.

  • name= the name of the keystore to be deleted.

  • password= password of the keystore to be deleted.

Example

svc.deleteKeyStore(appStripe='system', name='keystore1', password='password')

11.4.5 deleteKeyStoreEntry

Description

Deletes a keystore entry.

Syntax

svc.deleteKeyStoreEntry(appStripe='stripe', name='keystore', password='password', alias='alias', keypassword='keypassword')

where:

  • svc=the service command object obtained through a call to getOpssService().

  • appStripe= the name of the stripe containing the keystore.

  • name= the name of the keystore.

  • password= the keystore password.

  • alias= alias of the entry to be deleted.

  • keypassword= the key password of the entry to be deleted.

Example

svc.deleteKeyStoreEntry(appStripe='system', name='keystore2', password='password', alias='orakey', keypassword='keypassword')

11.4.6 exportKeyStore

Description

Exports a keystore to a file.

Syntax

svc.exportKeyStore(appStripe='stripe', name='keystore', password='password', aliases='comma-separated-aliases', keypasswords='comma-separated-keypasswords', type='keystore-type', filepath='absolute_file_path')

where:

  • svc=the service command object obtained through a call to getOpssService().

  • appStripe= the name of the stripe containing the keystore.

  • name= the name of the keystore.

  • password= the keystore password.

  • aliases= comma separated list of aliases to be exported.

  • keypasswords= comma separated list of the key passwords correspo nding to aliases.

  • type= exported keystore type. Valid values are 'JKS' or 'JCEKS'.

  • filepath= absolute path of the file where keystore is exported.

Example

svc.exportKeyStore(appStripe='system', name='keystore2', password='password',aliases='orakey,seckey', keypasswords='keypassword1,keypassword2', type='JKS',filepath='/tmp/file.jks')

11.4.7 exportKeyStoreCertificate

Description

Exports a certificate, trusted certificate or certificate chain.

Syntax

svc.exportKeyStoreCertificate(appStripe='stripe', name='keystore', password='password', alias='alias', keypassword='keypassword', type='entrytype',filepath='absolute_file_path')

where:

  • svc=the service command object obtained through a call to getOpssService().

  • appStripe= the name of the stripe containing the keystore.

  • name= the name of the keystore.

  • password= the keystore password.

  • alias= alias of the entry to be exported.

  • keypassword= the key password.

  • type= type of keystore entry to be exported. Valid values are 'Certificate', 'TrustedCertificate' or 'CertificateChain'.

  • filepath= absolute path of the file where certificate, trusted certificate or certificate chain is exported.

Example

svc.exportKeyStoreCertificate(appStripe='system', name='keystore2', password='password', alias='orakey', keypassword='keypassword', type='Certificate', filepath='/tmp/cert.txt')

11.4.8 exportKeyStoreCertificateRequest

Description

Generates and exports a certificate request.

Syntax

svc.exportKeyStoreCertificateRequest(appStripe='stripe', name='keystore', password='password', alias='alias', keypassword='keypassword', filepath='absolute_file_path')

where:

  • svc=the service command object obtained through a call to getOpssService().

  • appStripe= the name of the stripe containing the keystore.

  • name= the name of the keystore.

  • password= the keystore password.

  • alias= alias of the key pair from which certifiate request is generated.

  • keypassword= the key pair password.

  • filepath= absolute path of the file where certificate request should be exported.

Example

svc.exportKeyStoreCertificateRequest(appStripe='system', name='keystore2', password='password', alias='orakey', keypassword='keypassword', filepath='/tmp/certreq.txt')

11.4.9 generateKeyPair

Description

Generates a key pair in a keystore and wraps it in a demo CA-signed certificate.

Syntax

svc.generateKeyPair(appStripe='stripe', name='keystore', password='password', dn='distinguishedname', keysize='keysize', alias='alias', keypassword='keypassword')

where:

  • svc=the service command object obtained through a call to getOpssService().

  • appStripe= the name of the stripe containing the keystore.

  • name= the name of the keystore where key pair is generated.

  • password= the keystore password.

  • dn= the distinguished name of the certificate wrapping the key pair.

  • keysize= the key size.

  • alias= the alias of the key pair entry.

  • keypassword= the key password.

Example

svc.generateKeyPair(appStripe='system', name='keystore2', password='password', dn='cn=www.oracle.com', keysize='1024', alias='orakey', keypassword='keypassword')

11.4.10 generateSecretKey

Description

Generates a symmetric key in a keystore.

Syntax

svc.generateSecretKey(appStripe='stripe', name='keystore', password='password', algorithm='algorithm', keysize='keysize', alias='alias', keypassword='keypassword')

where:

  • svc=the service command object obtained through a call to getOpssService().

  • appStripe= the name of the stripe containing the keystore.

  • name= the name of the keystore where symmetric key is generated.

  • password= the keystore password.

  • algorithm= the symmetric key algorithm.

  • keysize= the key size.

  • alias= the alias of the key entry.

  • keypassword= the key password.

Example

svc.generateSecretKey(appStripe='system', name='keystore2', password='password', algorithm='AES', keysize='128', alias='seckey', keypassword='keypassword')

11.4.11 getKeyStoreCertificates

Description

Retrieves information about a certificate or trusted certificate.

Syntax

svc.getKeyStoreCertificates(appStripe='stripe', name='keystore', password='password', alias='alias', keypassword='keypassword')

where:

  • svc=the service command object obtained through a call to getOpssService().

  • appStripe= the name of the stripe containing the keystore.

    keypassword= the key password.

  • name= the name of the keystore.

  • password= the keystore password.

  • alias= the alias of the certificate, trusted certificate, or certificate chain to be displayed.

Example

svc.getKeyStoreCertificates(appStripe='system', name='keystore3', password='password', alias='orakey', keypassword='keypassword')

11.4.12 getKeyStoreSecretKeyProperties

Description

Retrieves secret key properties like the algorithm.

Syntax

svc.getKeyStoreSecretKeyProperties(appStripe='stripe', name='keystore', password='password', alias='alias', keypassword='keypassword')

where:

  • svc=the service command object obtained through a call to getOpssService().

  • appStripe= the name of the stripe containing the keystore.

  • name= the name of the keystore.

  • password= the keystore password.

  • alias= the alias of the secret key whose properties are displayed.

  • keypassword= the secret key password.

Example

svc.getKeyStoreSecretKeyProperties(appStripe='system', name='keystore3', password='password', alias='seckey', keypassword='keypassword')

11.4.13 importKeyStore

Description

Imports a keystore from file.

Syntax

svc.importKeyStore(appStripe='stripe', name='keystore', password='password', aliases='comma-separated-aliases', keypasswords='comma-separated-keypasswords', type='keystore-type', permission=true|false, filepath='absolute_file_path')

where:

  • svc=the service command object obtained through a call to getOpssService().

  • appStripe= the name of the stripe containing the keystore.

  • name= the name of the keystore.

  • password= the keystore password.

  • aliases= comma separated aliases of the entries to be imported from file.

  • keypasswords= comma separated passwords of the keys in file.

  • type= Imported keystore type. Valid values are 'JKS' or 'JCEKS'.

  • filepath= absolute path of the keystore file to be imported.

Example

svc.importKeyStore(appStripe='system', name='keystore2', password='password',aliases='orakey,seckey', keypasswords='keypassword1, keypassword2', type='JKS', permission=true, filepath='/tmp/file.jks')

11.4.14 importKeyStoreCertificate

Description

Imports a certificate, trusted certificate or certificate chain.

Syntax

svc.importKeyStoreCertificate(appStripe='stripe', name='keystore', password='password', alias='alias', keypassword='keypassword', type='entrytype',filepath='absolute_file_path')

where:

  • svc=the service command object obtained through a call to getOpssService().

  • appStripe= the name of the stripe containing the keystore.

  • name= the name of the keystore.

  • password= the keystore password.

  • alias= alias of the entry to be imported.

  • keypassword= the key password of the newly imported entry.

  • type= type of keystore entry to be imported. Valid values are 'Certificate', 'TrustedCertificate' or 'CertificateChain'.

  • filepath= absolute path of the file from where certificate, trusted certificate or certificate chain is imported.

Example

svc.importKeyStoreCertificate(appStripe='system', name='keystore2', password='password', alias='orakey', keypassword='keypassword', type='Certificate', filepath='/tmp/cert.txt')

11.4.15 listExpiringCertificates

Description

Lists expiring certificates and optionally renews them.

Syntax

svc.listExpiringCertificates(days='days', autorenew=true|false)

where:

  • svc=the service command object obtained through a call to getOpssService().

  • days=only list certificates within these many days from expiration.

  • autorenew= true for automatically renewing expiring certificates, false for only listing them.

Example

svc.listExpiringCertificates(days='365', autorenew=true)

11.4.16 listKeyStoreAliases

Description

Lists the aliases in a keystore for a given type of entry.

Syntax

svc.listKeyStoreAliases(appStripe='stripe', name='keystore', password='password', type='entrytype')

where:

  • svc=the service command object obtained through a call to getOpssService().

  • appStripe= the name of the stripe containing the keystore.

  • name= the name of the keystore.

  • password= the keystore password.

  • type= the type of entry for which aliases are listed. Valid values are 'Certificate', 'TrustedCertificate', 'SecretKey' or '*'.

Examples

svc.listKeyStoreAliases(appStripe='system', name='keystore2', password='password', type='Certificate')

svc.listKeyStoreAliases(appStripe='system', name='keystore2', password='password', type='TrustedCertificate')

svc.listKeyStoreAliases(appStripe='system', name='keystore2', password='password', type='SecretKey')

svc.listKeyStoreAliases(appStripe='system', name='keystore2', password='password', type='*')

11.4.17 listKeyStores

Description

Lists all the keystores in a stripe.

Syntax

svc.listKeyStores(appStripe='stripe')

where:

  • svc=the service command object obtained through a call to getOpssService().

  • appStripe= the name of the stripe whose keystores are listed.

Examples

svc.listKeyStores(appStripe='system')

svc.listKeyStores(appStripe='*')