Oracle® Fusion Middleware Application Security Guide 11g Release 1 (11.1.1) Part Number E10043-12 |
|
|
PDF · Mobi · ePub |
This chapter explains how to use the Keystore Service to administer keys and certificates.
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.
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.
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.
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.
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:
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 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')
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 |
---|---|
Changes the password for a key. |
|
Changes the password of a keystore. |
|
Creates a new keystore. |
|
Deletes the named keystore. |
|
Deletes a keystore entry. |
|
Exports a keystore to file. |
|
Exports a certificate, trusted certificate, or certificate chain. |
|
Generates and exports a certificate request. |
|
Generates a key pair in a keystore. |
|
Generates a symmetric key in a keystore. |
|
Retrieves information about a certificate or trusted certificate. |
|
Retrieves secret key properties. |
|
Imports a keystore from a file. |
|
Imports a certificate, trusted certificate or certificate chain. |
|
Lists expiring certificates and optionally renews them. |
|
Lists the aliases in a keystore. |
|
Lists the keystores in a stripe. |
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')
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')
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)
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')
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')
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')
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')
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')
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')
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')
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')
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')
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')
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')
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)
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='*')
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='*')