OPSS Keystore Service Commands

4 OPSS Keystore Service Commands

This chapter describes the WLST commands used with the OPSS keystore service.

Note:

You need to acquire an OPSS handle to use keystore service commands; this handle is denoted by 'svc' in the discussion that follows. See Managing Keys and Certificates in Securing Applications with Oracle Platform Security Services.

Table 4-1 lists the WLST commands used to manage the keystore service.

Table 4-1 OPSS Keystore Service Commands

Use this Command...	to...	Use with WLST...
changeKeyPassword	Change the password for a key.	Online
changeKeyStorePassword	Change the password on a keystore.	Online
createKeyStore	Create a keystore.	Online
deleteKeyStore	Delete a keystore.	Online
deleteKeyStoreEntry	Delete an entry in a keystore.	Online
exportKeyStore	Export a keystore to file.	Online
exportKeyStoreCertificate	Export a certificate to a file.	Online
exportKeyStoreCertificateRequest	Export a certificate request to a file.	Online
generateKeyPair	Generate a keypair.	Online
generateSecretKey	Generate a secret key.	Online
getKeyStoreCertificates	Get information about a certificate or trusted certificate.	Online
getKeyStoreSecretKeyProperties	Get the secret key properties.	Online
importKeyStore	Import a keystore from file.	Online
importKeyStoreCertificate	Import a certificate or other object.	Online
listExpiringCertificates	List certificates expiring in a specified period.	Online
listKeyStoreAliases	List aliases in a keystore.	Online
listKeyStores	List all the keystores in a stripe.	Online
syncKeyStores	Synchronizes the keystores in the administration server with keystores in the security store.	Online

changeKeyPassword

Changes a key password.

Description

Changes the password for a key.

Syntax

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

Argument	Definition
svc	Specifies the service command object obtained through a call to getOpssService().
appStripe	Specifies the name of the stripe containing the keystore
name	Specifies the name of the keystore
password	Specifies the keystore password
alias	Specifies the alias of the key entry whose password is changed
currentkeypassword	Specifies the current key password
newkeypassword	Specifies the new key password

Example

The following example changes the password on the key entry orakey:

wls:/mydomain/serverConfig> svc.changeKeyPassword(appStripe='system', 
name='keystore', password='password', 
alias='orakey', currentkeypassword='currentkeypassword', 
newkeypassword='newkeypassword')

Parent topic: OPSS Keystore Service Commands

changeKeyStorePassword

Changes the password of a keystore.

Description

Changes the password of the specified keystore.

Syntax

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

Argument	Definition
svc	Specifies the service command object obtained through a call to getOpssService().
appStripe	Specifies the name of the stripe containing the keystore
name	Specifies the name of the keystore
currentpassword	Specifies the current keystore password
newpassword	Specifies the new keystore password

Example

The following example changes the password for keystore2.

wls:/mydomain/serverConfig> svc.changeKeyStorePassword(appStripe='system', name='keystore2', 
currentpassword='currentpassword', newpassword='newpassword')

Parent topic: OPSS Keystore Service Commands

createKeyStore

This keystore service command creates a new keystore.

Description

Creates a new keystore on the given application stripe.

Syntax

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

Argument	Definition
svc	Specifies the service command object obtained through a call to getOpssService().
appStripe	Specifies the name of the stripe where the keystore is created.
name	Specifies the name of the new keystore.
password	Specifies the keystore password.
permission	This parameter is true if the keystore is protected by permission only, false if protected by both permission and password.

Example

The following example creates a keystore named keystore1.

wls:/mydomain/serverConfig> svc.createKeyStore(appStripe='system', 
name='keystore1', password='password', permission=true)

Parent topic: OPSS Keystore Service Commands

deleteKeyStore

Deletes the named keystore.

Description

This keystore service command deletes a specified keystore.

Syntax

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

Argument	Definition
svc	Specifies the service command object obtained through a call to getOpssService().
appStripe	Specifies the name of the stripe where the keystore resides.
name	Specifies the name of the keystore to be deleted.
password	Specifies the keystore password.

Example

The following example deletes the keystore named keystore1.

wls:/mydomain/serverConfig> svc.deleteKeyStore(appStripe='system', name='keystore1', password='password')

Parent topic: OPSS Keystore Service Commands

deleteKeyStoreEntry

Deletes a keystore entry.

Description

This command deletes the specified entry in a keystore.

Syntax

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

Argument	Definition
svc	Specifies the service command object obtained through a call to getOpssService().
appStripe	Specifies the name of the stripe where the keystore resides.
name	Specifies the name of the keystore.
password	Specifies the keystore password.
alias	Specifies the alias of the entry to be deleted
keypassword	Specifies the key password of the entry to be deleted

Example

The following example deletes a keystore entry denoted by alias orakey.

wls:/mydomain/serverConfig> svc.deleteKeyStoreEntry(appStripe='system', name='keystore2', password='password', alias='orakey', keypassword='keypassword')

Parent topic: OPSS Keystore Service Commands

exportKeyStore

Exports a keystore to a file.

Description

Exports a keystore to a specified 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')

Argument	Definition
svc	Specifies the service command object obtained through a call to getOpssService().
appStripe	Specifies the name of the stripe where the keystore resides.
name	Specifies the name of the keystore.
password	Specifies the keystore password. The value also applies to the output file, based on the current usage of the command: For password-protected keystores of all types, this will be the password of the output file; For permission-protected keystores of type JKS or JCEKS, this will be the password of the output file; For permission-protected keystores of type OracleWallet, if the password value is non-empty, this will be the password of the output file; an empty value will create an auto-login wallet. If the keystore is password-based, the value of this argument must be the same as the password specified when the password-based keystore was created. Otherwise, if the keystore is not password-based, any value is valid.
aliases	Specifies a comma separated list of aliases to be exported.
keypasswords	Specifies the password(s) of the key(s) being exported. The usage depends on the keystore type: If type is JKS or JCEKS, and the keystore is permission-protected, this is a comma separated list of the key passwords corresponding to aliases in the output file. If type is JKS or JCEKS, and the keystore is password-protected, this is a comma separated list of the key passwords corresponding to aliases in both the source keystore and the output file. If type is OracleWallet, this parameter is ignored.
type	Exported keystore type. Valid values are 'JKS' or 'JCEKS' or 'OracleWallet'.
filepath	For type JKS or JCEKS, the absolute path of the file where the keystore is exported, including filename. For type OracleWallet, the absolute path of the directory where the keystore is exported.

Examples

The following example exports two aliases from the specified keystore.

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

The following example exports a keystore to create an Oracle Wallet file:

wls:/mydomain/serverConfig> svc.exportKeyStore(appStripe='system', name='keystore2', 
password='password',aliases='orakey,seckey', 
keypasswords='', type='OracleWallet',filepath='/tmp')

Parent topic: OPSS Keystore Service Commands

exportKeyStoreCertificate

Exports a certificate.

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

Argument	Definition
svc	Specifies the service command object obtained through a call to getOpssService().
appStripe	Specifies the name of the stripe where the keystore resides.
name	Specifies the name of the keystore.
password	Specifies the keystore password.
alias	Specifies the alias of the entry to be exported
keypassword	Specifies the key password.
type	Specifies the type of keystore entry to be exported. Valid values are 'Certificate', 'TrustedCertificate' or 'CertificateChain'.
filepath	Specifies the absolute path of the file where certificate, trusted certificate or certificate chain is exported.

Example

The following example exports a certificate corresponding to the orakey alias:

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

Parent topic: OPSS Keystore Service Commands

exportKeyStoreCertificateRequest

Exports a certificate request.

Description

Generates and exports a certificate request from a keystore.

Syntax

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

Argument	Definition
svc	Specifies the service command object obtained through a call to getOpssService().
appStripe	Specifies the name of the stripe where the keystore resides.
name	Specifies the name of the keystore.
password	Specifies the keystore password.
alias	Specifies the entry's alias name.
keypassword	Specifies the key password.
filepath	Specifies the absolute path of the file where certificate request is exported.

Example

The following example exports a certificate request corresponding to the orakey alias.

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

Parent topic: OPSS Keystore Service Commands

generateKeyPair

Generates a key pair in a keystore.

Description

Generates a key pair using a specified algorithm, 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'[, algorithm='algorithm'][,ext_san='ext_san'])

Argument	Definition
svc	Specifies the service command object obtained through a call to getOpssService().
appStripe	Specifies the name of the stripe where the keystore resides.
name	Specifies the name of the keystore.
password	Specifies the keystore password.
`ext_san`	Specifies the Subject Alternative Name (SAN) extension. The format for the argument is `"type:value,...,type:value".` Only the DNS type is supported.
dn	Specifies the distinguished name of the certificate wrapping the key pair.
keysize	Specifies the key size.
alias	Specifies the alias of the key pair entry.
keypassword	Specifies the key password.
algorithm	Specifies the algorithm to use to encrypt the generated keys. The only valid values are RSA or EC (Elliptic Curve Cryptography). Optional. If not specified, the command uses the RSA algorithm.

Examples

The following example generates a keypair in keystore2 using the default RSA algorithm:

wls:/mydomain/serverConfig> svc.generateKeyPair(appStripe='system', name='keystore2', password='password', dn='cn=www.oracle.com', keysize='1024', alias='orakey', keypassword='keypassword')

The following example generates a keypair in keystore2 using the RSA algorithm:

wls:/mydomain/serverConfig> svc.generateKeyPair(appStripe='system', name='keystore2', password='password', dn='cn=www.oracle.com', keysize='1024', alias='orakey', keypassword='keypassword', algorithm='RSA')

The following example generates a keypair in keystore2. using the ECC (Elliptic Curve Cryptography) algorithm:

wls:/mydomain/serverConfig> svc.generateKeyPair(appStripe='system', name='keystore2', password='password', dn='cn=www.oracle.com', keysize='1024', alias='orakey', keypassword='keypassword', algorithm='EC')

The following example generates a keypair with SAN in keystore2 using the default RSA algorithm:

svc.generateKeyPair(appStripe='system', name='keystore2', password='<password>', dn='cn=www.oracle.com', keysize='2048', alias='orakey', keypassword='<keypassword>', ext_san='DNS:server1.oracle.com,DNS:www.oracle.com')

Parent topic: OPSS Keystore Service Commands

generateSecretKey

Generates a secret key. This command creates only a symmetric key, not a public/private key pair. To view the properties after creating the symmetric key, use getKeyStoreSecretKeyProperties.

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

Argument	Definition
svc	Specifies the service command object obtained through a call to getOpssService().
appStripe	Specifies the name of the stripe where the keystore resides.
name	Specifies the name of the keystore.
password	Specifies the keystore password.
algorithm	Specifies the symmetric key algorithm.
keysize	Specifies the key size.
alias	Specifies the alias of the key entry.
keypassword	Specifies the key password.

Example

The following example generates a keypair with keysize 128 in keystore2.

wls:/mydomain/serverConfig> svc.generateSecretKey(appStripe='system', name='keystore2', password='password', 
algorithm='AES', keysize='128', alias='seckey', keypassword='keypassword')

Parent topic: OPSS Keystore Service Commands

getKeyStoreCertificates

Gets a certificate from the keystore. Use this command to view the contents of the public key and X509 certificate that you have imported from a keystore (supported keystore types are JKS or JCEKS), or that you have created using the generateKeyPair command.

Description

Retrieves information about a certificate or trusted certificate.

Syntax

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

Argument	Definition
svc	Specifies the service command object obtained through a call to getOpssService().
appStripe	Specifies the name of the stripe where the keystore resides.
name	Specifies the name of the keystore.
password	Specifies the keystore password.
alias	Specifies the alias of the certificate, trusted certificate or certificate chain to be displayed.
keypassword	Specifies the key password.

Example

The following example gets certificates associated with keystore3.

wls:/mydomain/serverConfig> svc.getKeyStoreCertificates(appStripe='system', name='keystore3', password='password', alias='orakey', keypassword='keypassword')

Parent topic: OPSS Keystore Service Commands

getKeyStoreSecretKeyProperties

Retrieves secret key properties.

Description

Retrieves secret key properties like the algorithm.

Syntax

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

Argument	Definition
svc	Specifies the service command object obtained through a call to getOpssService().
appStripe	Specifies the name of the stripe where the keystore resides.
name	Specifies the name of the keystore.
password	Specifies the keystore password.
alias	Specifies the alias of the secret key whose properties are displayed.
keypassword	Specifies the secret key password.

Example

The following example gets properties for secret key seckey:

wls:/mydomain/serverConfig> svc.getKeyStoreSecretKeyProperties(appStripe='system', name='keystore3', 
password='password', alias='seckey', keypassword='keypassword')

Parent topic: OPSS Keystore Service Commands

importKeyStore

Imports a keystore from file. This command imports any public key, private key, symmetric key, and trusted certificates from the key store file into OPSS Keystore Service keystore.

Description

Imports a keystore from a system 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')

Argument	Definition
svc	Specifies the service command object obtained through a call to getOpssService().
appStripe	Specifies the name of the stripe where the keystore will reside.
name	Specifies the name of the keystore.
password	Specifies the keystore password. These rules apply: If importing an auto-login Oracle Wallet file, no password is needed. If importing a password-protected Oracle Wallet file (ewallet.p12), enter a password of minimum eight characters.
aliases	Specifies the comma-separated aliases of the entries to be imported from the file. If type is set to OracleWallet, it is not required; otherwise, it is a required argument.
keypasswords	Specifies the passwords of the keys in the file. These rules apply: If type is JKS or JCEKS, enter comma-separated passwords of the keys. If `type` is OracleWallet, no password is needed. The key passwords will be the same as the keystore password.
type	Specifies the imported keystore type. Valid values are 'JKS' or 'JCEKS' or 'OracleWallet'.
filepath	If `type` is set to JKS or JCEKS, it specifies rthe absolute path of the keystore file to be imported, including filname. If type is set to OracleWallet, it specifies the absolute path of the directory where the Oracle Wallet is located.
permission	Specifies true if keystore is protected by permission only, false if protected by both permission and password. If set to true, the imported file is permission protected, so when call getKeyStore or getKey, set password to null.

Example

The following example imports a JKS keystore file to keystore2:

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

The following example imports an Oracle Wallet to keystore2:

svc.importKeyStore(appStripe='system', name='keystore2', 
password='password',aliases='orakey,seckey', keypasswords='', type='OracleWallet', permission=true, filepath='/tmp')

Parent topic: OPSS Keystore Service Commands

importKeyStoreCertificate

Imports a certificate or other specified object.

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

Argument	Definition
svc	Specifies the service command object obtained through a call to getOpssService().
appStripe	Specifies the name of the stripe where the keystore resides.
name	Specifies the name of the keystore.
password	Specifies the keystore password.
alias	Specifies the alias of the entry to be imported.
keypassword	Specifies the key password of the newly imported entry.
type	Specifies the type of keystore entry to be imported. Valid values are 'Certificate', 'TrustedCertificate' or 'CertificateChain'.
filepath	Specifies the absolute path of the file from where certificate, trusted certificate or certificate chain is imported.

Example

The following example imports a certificate into keystore2.

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

Parent topic: OPSS Keystore Service Commands

listExpiringCertificates

Lists expiring certificates.

Description

Lists expiring certificates and optionally renews them.

Syntax

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

Argument	Definition
svc	Specifies the service command object obtained through a call to getOpssService().
days	Specifies that the list should only include certificates within this many days from expiration.
autorenew	Specifies true for automatically renewing expiring certificates, false for only listing them.

Example

The following example lists certificates expiring within one year, and requests that they be renewed:

wls:/mydomain/serverConfig> svc.listExpiringCertificates(days='365', autorenew=true)

Parent topic: OPSS Keystore Service Commands

listKeyStoreAliases

Lists the aliases in a keystore.

Description

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

Syntax

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

Argument	Definition
svc	Specifies the service command object obtained through a call to getOpssService().
appStripe	Specifies the name of the stripe where the keystore resides.
name	Specifies the name of the keystore.
password	Specifies the keystore password.
type	Specifies the type of entry for which aliases are listed. Valid values are 'Certificate', 'TrustedCertificate', 'SecretKey' or '*'.

Example

The following example lists secret keys in keystore2:

wls:/mydomain/serverConfig> svc.listKeyStoreAliases(appStripe='system', name='keystore2', 
password='password', type='SecretKey')

Parent topic: OPSS Keystore Service Commands

listKeyStores

Lists all the keystores in a stripe.

Description

Lists all the keystores in the specified stripe.

Syntax

svc.listKeyStores(appStripe='stripe')

Argument	Definition
svc	Specifies the service command object obtained through a call to getOpssService().
appStripe	Specifies the name of the stripe whose keystores are listed.

Example

The following example lists all keystores on all stripes.

wls:/mydomain/serverConfig> svc.listKeyStores(appStripe='*')

Parent topic: OPSS Keystore Service Commands

syncKeyStores

Synchronizes keystores from the OPSS security store to the local repository.

Description

Downloads keystores from an application stripe in the security store to the specified directory on the file system, in the given format.

If the target format is Oracle Wallet, the command downloads the contents of all KSS keystores for a given stripe into auto-login wallets on the server. The contents of the domain trust store are automatically included in each wallet.

Syntax

The syntax is as follows:

syncKeyStores(appStripe='<application_stripe>', keystoreFormat='exported_file_format',
rootDirectory='root_dir_absolute_path')

Argument Definition

Argument	Definition
appStripe	Name of the KSS application stripe containing the keystores that need to be synchronized with the local repository.
keystoreFormat	Specifies the format of the target keystore. Valid formats are 'KSS' and 'OracleWallet'. If the `keystoreFormat` is 'OracleWallet', then the keystores in this stripe must be permission-protected only. You cannot use password-protected keystores in an Oracle wallet.
rootDirectory	For the Oracle Wallet format, specifies the absolute path of the server directory where the wallet(s) are created.

appStripe

Name of the KSS application stripe containing the keystores that need to be synchronized with the local repository.

keystoreFormat

Specifies the format of the target keystore. Valid formats are 'KSS' and 'OracleWallet'.

If the keystoreFormat is 'OracleWallet', then the keystores in this stripe must be permission-protected only. You cannot use password-protected keystores in an Oracle wallet.

rootDirectory

For the Oracle Wallet format, specifies the absolute path of the server directory where the wallet(s) are created.

Note:

The svc argument does not apply to this command.

Example

The following example looks up the security store for the "system" stripe and downloads its contents into the keystores.xml file under the DOMAIN_HOME/config/fmwconfig directory.

wls:/mydomain/serverConfig> syncKeyStores((appStripe='system', keystoreFormat='KSS')

The following example generates Oracle Wallets corresponding to all keystores in the stripe 'ohs':

syncKeyStores(appStripe="ohs", 
keystoreFormat="OracleWallet", rootDirectory="/tmp/bin")

Parent topic: OPSS Keystore Service Commands