You can use the Jython or Jacl scripting languages to configure
security with the wsadmin tool. The commands and parameters in the
PersonalCertificateCommands group can be used to create and manage
personal or signer certificates.
The PersonalCertificateCommands command group for the AdminTask
object includes the following commands:
createChainedCertificate
The
createChainedCertificate command creates a new self-signed certificate
and stores the certificate in a keystore.
Avoid trouble: To
use the IBMi5OSKeyStore key store, verify that the signer for each
part of the chain exists in the keystore before creating the new certificate.
You must import the signer into the IBMi5OSKeyStore keystore before
creating the new certificate.
gotcha
Target
object
None.
Required parameters
- -keyStoreName
- Specifies the name that uniquely identifies the keystore configuration
object. (String, required)
- -certificateAlias
- Specifies the name that uniquely identifies the certificate request
in a keystore. (String, required)
- -certificateSize
- Specifies the size of the certificate. (Integer, required)
- -certificateCommonName
- Specifies the common name of the certificate. (String, required)
- -certificateOrganization
- Specifies the organization of the certificate. (String, optional)
Optional parameters
- -rootCertificateAlias
- Specifies a unique name to identify the root certificated to use
for signing. The default root certificate alias is root.
(String, optional)
- -certificateVersion
- Specifies the version of the certificate. (String, optional)
- -keyStoreScope
- Specifies the scope name of the keystore. (String, optional)
- -certificateOrganization
- Specifies the organization of the certificate. (String, optional)
- -certificateOrganizationalUnit
- Specifies the organizational unit of the certificate. (String,
optional)
- -certificateLocality
- Specifies the locality of the certificate. (String, optional)
- -certificateState
- Specifies the state of the certificate. (String, optional)
- -certificateZip
- Specifies the zip code of the certificate. (String, optional)
- -certificateCountry
- Specifies the country of the certificate. (String, optional)
- -certificateValidDays
- Specifies the amount of time in days for which the certificate
is valid. (Integer, optional)
Return value
The
command does not return output.
Batch mode
example usage
- Using Jython string:
AdminTask.createChainedCertificate('-keyStoreName myKeystore -certificateAlias
newCertificate -certificateSize 10 -certificateCommonName localhost
-certificateOrganization ibm')
- Using Jython list:
AdminTask.createChainedCertificate('-keyStoreName', 'myKeystore', '-certificateAlias',
'newCertificate', '-certificateSize', '10', '-certificateCommonName', 'localhost',
'-certificateOrganization', 'ibm')
Interactive mode example usage
- Using Jython:
AdminTask.createChainedCertificate('-interactive')
createSelfSignedCertificate
The createSelfSignedCertificate
command creates a self-signed personal certificate in a keystore.
Target object
None.
Required parameters
- -keyStoreName
- The name that uniquely identifies the keystore configuration object.
(String, required)
- -certificateAlias
- The name that uniquely identifies the certificate request in a
keystore. (String, required)
- -certificateVersion
- The version of the certificate. (String, required)
- -certificateSize
- The size of the certificate. (Integer, required)
- -certificateCommonName
- The common name of the certificate. (String, required)
Optional parameters
- -keyStoreScope
- The scope name of the keystore. (String, optional)
- -certificateOrganization
- The organization of the certificate. (String, optional)
- -certificateOrganizationalUnit
- The organizational unit of the certificate. (String, optional)
- -certificateLocality
- The locality of the certificate. (String, optional)
- -certificateState
- The state of the certificate. (String, optional)
- -certificateZip
- The zip code of the certificate. (String, optional)
- -certificateCountry
- The country of the certificate. (String, optional)
- -certificateValidDays
- The amount of time in days for which the certificate is valid.
(Integer, optional)
Example output
The
command does not return output.
Examples
Batch
mode example usage:
- Using Jacl:
$AdminTask createSelfSignedCertificate {-keyStoreName testKeyStore -certificateAlias
default -certificateCommonName localhost -certificateOrganization ibm}
- Using Jython string:
AdminTask.createSelfSignedCertificate('[-keyStoreName testKeyStore -certificateAlias
default -certificateCommonName localhost -certificateOrganization ibm]')
- Using Jython list:
AdminTask.createSelfSignedCertificate(['-keyStoreName', 'testKeyStore', '-certificateAlias',
'default', '-certificateCommonName', 'localhost', '-certificateOrganization', 'ibm'])
Interactive mode example usage:
deleteCertificate
The deleteCertificate
command deletes a personal certificate from a keystore. The command
saves a copy of the certificate in the delete keystore.
Target object
None.
Required parameters
- -keyStoreName
- The name that uniquely identifies the keystore configuration object.
(String, required)
- -certificateAlias
- The name that uniquely identifies the certificate request in a
keystore. (String, required)
Optional parameters
- -keyStoreScope
- The scope name of the keystore. (String, optional)
Example output
The
command does not return output.
Examples
Interactive
mode example usage:
exportCertificate
The exportCertificate
command exports a personal certificate from one keystore to another.
Target object
None.
Required parameters
- -keyStoreName
- The name that uniquely identifies the keystore configuration object.
(String, required)
- -keyStorePassword
- The password to the keystore. (String, required)
- -keyFilePath
- The full path to a keystore file that is located in a file system.
The store from where a certificate will be imported or exported. (String,
required)
- -keyFilePassword
- The password to the keystore file. (String, required)
- -keyFileType
- The type of the key file. (String, required)
- -certificateAlias
- The name that uniquely identifies the certificate request in a
keystore. (String, required)
Optional parameters
- -keyStoreScope
- The scope name of the keystore. (String, optional)
- -aliasInKeyStore
- (String, optional)
Example output
The
command does not return output.
Examples
Interactive
mode example usage:
exportCertToManagedKS
The
exportCertToManagedKS command exports a personal certificate to a
managed keystore in the configuration.
Target
object
None.
Required parameters
- -keyStoreName
- Specifies the name that uniquely identifies the keystore configuration
object. (String, required)
- -keyStorePassword
- The password to the keystore. (String, required)
- -toKeyStoreName
- Specifies the unique name of the keystore to export the certificate
to. (String, required)
- -certificateAlias
- Specifies the alias of the certificate of interest. (String, required)
Optional parameters
- -keyStoreScope
- Specifies the keystore of the certificate of interest. (String,
optional)
- -toKeyStoreScope
- Specifies the scope of the keystore to export to. (String, optional)
- -aliasInKeyStore
- Specifies the alias that identifies the certificate in the keystore.
(String, optional)
Return value
The
command does not return output.
Batch
mode example usage
- Using Jython string:
AdminTask.exportCertificateToManagedKS('-keyStoreName myKS -keyStorePassword myKSpw
-toKeyStoreName myKS2 -certificateAlias testingKeyStore')
- Using Jython list:
AdminTask.exportCertificateToManagedKS(['-keyStoreName', 'myKS', '-keyStorePassword',
'myKSpw', '-toKeyStoreName', 'myKS2', '-certificateAlias', 'testingKeyStore'])
Interactive mode example usage
- Using Jython:
AdminTask.exportCertificateToManagedKS('-interactive')
extractCertificate
The extractCertificate
command extracts the signer part of a personal certificate to a certificate
file. The certificate in the file can later be added to a keystore
to establish trust.
Target object
None.
Required parameters
- -keyStoreName
- The name that uniquely identifies the keystore configuration object.
(String, required)
- -certificateAlias
- The name that uniquely identifies the certificate request in a
keystore. (String, required)
- -certificateFilePath
- The full path of the request file that contains the certificate.
(String, required)
- -base64Encoded
- Set the value of this parameter to true if the certificate
is a Base64 encoded ASCII file type. Set the value of this parameter
to false if the certificate is binary. (Boolean, required)
Optional parameters
- -keyStoreScope
- The scope name of the keystore. (String, optional)
Example output
The
command does not return output.
Examples
Batch
mode example usage:
- Using Jacl:
$AdminTask extractCertificate {-keyStoreName testKeyStore -certificateFilePath
c:/temp/CertFile.arm -certificateAlias testCertificate}
![[may2010]](../../deltaend.gif)
may2010
$AdminTask extractCertificate {-keyStoreName testKeyStore -certificateFilePath
/temp/CertFile.arm -certificateAlias testCertificate}
- Using Jython string:
AdminTask.extractCertificate('[-keyStoreName testKeyStore -certificateFilePath
c:/temp/CertFile.arm -certificateAlias testCertificate]')
![[may2010]](../../deltaend.gif)
may2010
AdminTask.extractCertificate('[-keyStoreName testKeyStore -certificateFilePath
/temp/CertFile.arm -certificateAlias testCertificate]')
- Using Jython list:
AdminTask.extractCertificate(['-keyStoreName', 'testKeyStore', '-certificateFilePath',
'c:/temp/CertFile.arm', '-certificateAlias', 'testCertificate'])
![[may2010]](../../deltaend.gif)
may2010
AdminTask.extractCertificate(['-keyStoreName', 'testKeyStore', '-certificateFilePath',
'/temp/CertFile.arm', '-certificateAlias', 'testCertificate'])
Interactive mode example usage:
getCertificate
The getCertificate command
obtains information about a particular personal certificate in a keystore.
If the certificate of interest was created with the requestCACertificate
command, the certificate can be in the COMPLETE or REVOKED state.
Certificate requests can be in the PENDING state. Use the
getCertificateRequest command to determine if a certificate request
is in the PENDING state.
Target
object
None.
Required parameters
- -keyStoreName
- The name that uniquely identifies the keystore configuration object.
(String, required)
- -certificateAlias
- The name that uniquely identifies the certificate request in a
keystore. (String, required)
Optional parameters
- -keyStoreScope
- The scope name of the keystore. (String, optional)
Example output
The
command returns information about the certificate request.
Examples
Interactive mode example
usage:
getCertificateChain
The getCertificateChain
command queries your configuration for information about each personal
certificate in a certificate chain.
Target
object
None.
Required parameters and
return values
- -keyStoreName
- Specifies the name of the keystore object that stores the CA certificate.
Use the listKeyStores command to display a list of available keystores.
(String, required)
- -certificateAlias
- Specifies the unique alias of the certificate. (String, required)
Optional parameters
- -keyStoreScope
- Specifies the management scope of the keystore. For a deployment
manager profile, the default value is the cell scope. For an application
server profile, the default value is the node scope. (String, optional)
Example output
The
command returns an array of attribute lists that contain configuration
information for each certificate in a chain.
Examples
Batch mode example usage:
- Using Jacl:
$AdminTask getCertificateChain {-certificateAlias newCertificate
-keyStoreName CellDefaultKeyStore}
- Using Jython string:
AdminTask.getCertificateChain('-certificateAlias newCertificate
-keyStoreName CellDefaultKeyStore')
- Using Jython list:
AdminTask.getCertificateChain(['-certificateAlias', 'newCertificate',
'-keyStoreName', 'CellDefaultKeyStore'])
Interactive mode example usage:
importCertificate
The importCertificate
command imports a personal certificate from a keystore.
Target object
None.
Required parameters
- -keyStoreName
- The name that uniquely identifies the keystore configuration object.
(String, required)
- -keyFilePath
- The full path to a keystore file that is located in a file system.
The store from where a certificate will be imported or exported. (String,
required)
- -keyFilePassword
- The password to the keystore file. (String, required)
- -keyFileType
- The type of the key file. (String, required)
- -certificateAliasFromKeyFile
- The certificate alias in the key file from which the certificate
is being imported. (String, required)
- -certificateAlias
- The name that uniquely identifies the certificate request in a
keystore. (String, required)
Optional parameters
- -keyStoreScope
- The scope name of the keystore. (String, optional)
Example output
The
command does not return output.
Examples
Interactive
mode example usage:
importCertFromManagedKS
The
importCertFromManagedKS command imports a personal certificate from
a managed keystore in the configuration.
Target
object
None.
Required parameters
- -keyStoreName
- Specifies the name that uniquely identifies the keystore configuration
object. (String, required)
- -fromKeyStoreName
- Specifies the name that uniquely identifies the keystore from
which the system imports the certificate. (String, required)
- -fromKeyStorePassword
- Specifies the password for the keystore from which the system
imports the certificate. (String, required)
- -certificateAliasFromKeyStore
- Specifies the alias of the certificate in the keystore. (String,
required)
Optional parameters
- -keyStoreScope
- Specifies the scope of the keystore to import the certificate
to. (String, optional)
- -fromKeyStoreScope
- Specifies the scope of the keystore to import the certificate
from. (String, optional)
- -certificateAlias
- Specifies the alias of the certificate for the destination keystore.
(String, optional)
Return value
The
command does not return output.
Batch
mode example usage
- Using Jython string:
AdminTask.importCertFromManagedKS('-keyStoreName myKeystore -fromKeyStoreName
oldKeystore -fromKeyStorePassword my122password -certificateAliasFromKeyStore
myCertificate')
- Using Jython list:
AdminTask.importCertFromManagedKS('-keyStoreName', 'myKeystore', '-fromKeyStoreName',
'oldKeystore', '-fromKeyStorePassword', 'my122password', '-certificateAliasFromKeyStore',
'myCertificate')
Interactive mode example usage
- Using Jython:
AdminTask.importCertFromManagedKS('-interactive')
listPersonalCertificates
The listPersonalCertificates
command lists the personal certificates in a particular keystore.
Target object
None.
Required parameters
- -keyStoreName
- The name that uniquely identifies the keystore configuration object.
The value of this field is not a path to the keystore file. (String,
required)
Optional parameters
- -keyStoreScope
- The scope name of the keystore. To obtain a list of the keystore
scope values, see the listManagementScopes command,
which is part of the ManagementScopeCommands command
group. (String, optional)
Example output
The
command returns a list of attributes for each personal certificate
in a keystore.
Examples
Batch
mode example usage:
- Using Jython string:
AdminTask.listPersonalCertificates('-keyStoreName myKS')
- Using Jython list:
AdminTask.listPersonalCertificates(['-keyStoreName', 'myKS'])
Interactive mode example usage:
queryCACertificate
The queryCACertificate
command queries your configuration to determine if the CA has completed
the certificate. If the CA returns a personal certificate, then the
system marks the certificate as COMPLETE. Otherwise, it remains
marked as PENDING.
Target
object
None.
Required parameters and
return values
- -keyStoreName
- Specifies the name of the keystore object that stores the CA certificate.
Use the listKeyStores command to display a list of available keystores.
(String, required)
- -certificateAlias
- Specifies the unique alias of the certificate. (String, required)
Optional parameters
- -keyStoreScope
- Specifies the management scope of the keystore. For a deployment
manager profile, the default value is the cell scope. For an application
server profile, the default value is the node scope. (String, optional)
Example output
The
command returns one of two values: Certificate COMPLETE or certificate
PENDING. If the command returns the Certificate COMPLETE message,
the certificate authority returned the requested certificate and the
default personal certificate is replaced. If the command returns the certificate
PENDING message, the certificate authority did not yet return
a certificate.
Examples
Batch
mode example usage:
- Using Jacl:
$AdminTask queryCACertificate {-certificateAlias newCertificate
-keyStoreName CellDefaultKeyStore}
- Using Jython string:
AdminTask.queryCACertificate('-certificateAlias newCertificate
-keyStoreName CellDefaultKeyStore')
- Using Jython list:
AdminTask.queryCACertificate(['-certificateAlias', 'newCertificate',
'-keyStoreName', 'CellDefaultKeyStore'])
Interactive mode example usage:
receiveCertificate
The receiveCertificate
command receives a signer certificate from a file to a personal certificate.
Target object
None.
Required parameters
- -keyStoreName
- The name that uniquely identifies the keystore configuration object.
(String, required)
- -certificateAlias
- The name that uniquely identifies the certificate request in a
keystore. (String, required)
- -certificateFilePath
- The full path of the file that contains the certificate. (String,
required)
- -base64Encoded
- Set the value of this parameter to true if the certificate
is ascii base 64 encoded. Set the value of this parameter to false if
the certificate is binary. (Boolean, required)
Optional parameters
- -keyStoreScope
- The scope name of the keystore. (String, optional)
Example output
The
command does not return output.
Examples
Batch
mode example usage:
Interactive mode example usage:
renewCertificate
The
renewCertificate command renews a certificate with a new generated
certificate.
Target object
None.
Required parameters
- -keyStoreName
- Specifies the unique name that identifies the keystore. (String,
required)
- -certificateAlias
- Specifies the unique name that identifies the certificate. (String,
required)
Optional parameters
- -keyStoreScope
- Specifies the scope of the keystore. (String, optional)
- -deleteOldSigners
- Specifies whether to delete the old signers that are associated
with the old certificate. Specify false to retain the old
signers. (Boolean, optional)
Return value
The
command does not return output.
Batch
mode example usage
- Using Jython string:
AdminTask.renewCertificate('-keyStoreName myKS -certificateAlias
testCertificate')
- Using Jython list:
AdminTask.renewCertificate(['-keyStoreName', 'myKS', '-certificateAlias',
'testCertificate'])
Interactive mode example usage
- Using Jython:
AdminTask.renewCertificate('-interactive')
replaceCertificate
The replaceCertificate
command replaces a personal certificate with another personal certificate.
The command finds each reference to the old certificate alias in
the configuration and replaces the alias with the new one. The command
also replaces each signer certificate from the old personal certificate
with the signer from the new personal certificate.
Target object
None.
Required parameters and return values
- -keyStoreName
- The name that uniquely identifies the keystore configuration object.
(String, required)
- -certificateAlias
- The name that uniquely identifies the certificate request in a
keystore. (String, required)
- -replacementCertificateAlias
- The alias of the certificate that is used to replace a different
certificate. (String, required)
Optional parameters
- -keyStoreScope
- The scope name of the keystore. (String, optional)
- -deleteOldCert
- Set the value of this parameter to true if you want to
delete the old signer certificates during certificate replacement.
Otherwise, set the value of this parameter to false. (Boolean,
optional)
- -deleteOldSigners
- Set the value of this parameter to true if you want to
delete the old certificates during certificate replacement. Otherwise,
set the value of this parameter to false. (Boolean, optional)
Example output
The
command does not return output.
Examples
Batch
mode example usage:
- Using Jacl:
$AdminTask replaceCertificate {-keyStoreName testKeyStore -certificateAlias
default -replacementCertificateAlias replaceCert -deleteOldCert true
-deleteOldSigners true}
- Using Jython string:
AdminTask.replaceCertificate('[-keyStoreName testKeyStore -certificateAlias
default -replacementCertificateAlias replaceCert -deleteOldCert true
-deleteOldSigners true]')
- Using Jython list:
AdminTask.replaceCertificate(['-keyStoreName', 'testKeyStore', '-certificateAlias',
'default', '-replacementCertificateAlias', 'replaceCert', '-deleteOldCert',
'true', '-deleteOldSigners', 'true'])
Interactive mode example usage:
requestCACertificate
The requestCACertificate
command creates a certificate request and sends the request to a certificate
authority (CA). If the certificate authority returns a personal certificate,
then the returned certificate replaces the certificate request in
the keystore. The command also works with a preexisting certificate
request that was created with the createCertificateRequest command.
When the CA returns a personal certificate, the system marks the
certificate as COMPLETE and the command returns a message
stating that the certificate is complete. If the CA does not return
a personal certificate, then the system marks the certificate request
as PENDING and the command returns a message stating that
the certificate is PENDING.
Avoid trouble: To
use the IBMi5OSKeyStore key store, verify that the signer for each
part of the chain exists in the keystore before creating the new certificate.
You must import the signer into the IBMi5OSKeyStore keystore before
creating the new certificate.
gotcha
Target
object
None.
Required parameters and
return values
- -certificateAlias
- Specifies the alias of the certificate. You can specify a predefined
certificate request. (String, required)
- -keyStoreName
- Specifies the name of the keystore object that stores the CA certificate.
Use the listKeyStores command to display a list of available keystores.
(String, required)
- -caClientName
- Specifies the name of the CA client that was used to create the
CA certificate. (String, required)
- -revocationPassword
- Specifies the password to use to revoke the certificate at a later
date. (String, required)
Optional parameters
- -keyStoreScope
- Specifies the management scope of the keystore. For a deployment
manager profile, the default value is the cell scope. For an application
server profile, the default value is the node scope. (String, optional)
- -caClientScope
- Specifies the management scope of the CA client. For a deployment
manager profile, the default value is the cell scope. For an application
server profile, the default value is the node scope. (String, optional)
- -certificateCommonName
- Specifies the common name (CN) part of the full distinguished
name (DN) of the certificate. This common name can represent a person,
company, or machine. For Web sites, the common name is frequently
the DNS host name where the server resides. (String, optional)
- -certificateOrganization
- Specifies the organization part of the full distinguished name
(DN) of the certificate. (String, optional)
- -certificateOrganizationalUnity
- Specifies the organization unit part of the full distinguished
name (DN) of the certificate. (String, optional)
- -certificateLocality
- Specifies the locality part of the full distinguished name (DN)
of the certificate. (String, optional)
- -certificateState
- Specifies the state part of the full distinguished name (DN) of
the certificate. (String, optional)
- -certificateZip
- Specifies the zip code part of the full distinguished name (DN)
of the certificate. (String, optional)
- -certificateCountry
- Specifies the country part of the full distinguished name (DN)
of the certificate. (String, optional)
- -certificateSize
- Specifies the size of the certificate key. The valid values are
512, 1024, and 2048. The default value is 1024. (String, optional)
Example output
The
command returns one of two values: Certificate COMPLETE or certificate
PENDING.
Examples
Batch
mode example usage:
- Using Jacl:
$AdminTask requestCACertificate {-certificateAlias newCertificate -keyStoreName
CellDefaultKeyStore -CAClientName myCAClient -revocationPassword revokeCApw}
- Using Jython string:
AdminTask.requestCACertificate('-certificateAlias newCertificate -keyStoreName
CellDefaultKeyStore -CAClientName myCAClient -revocationPassword revokeCApw')
- Using Jython list:
AdminTask.requestCACertificate(['-certificateAlias','newCertificate','-keyStoreName',
'CellDefaultKeyStore','-CAClientName','myCAClient','-revocationPassword',
'revokeCApw'])
Interactive mode example usage:
revokeCACertificate
The revokeCACertificate
command sends a request to the CA to revoke the CA personal certificate
of interest.
Target object
None.
Required parameters and return values
- -certificateAlias
- Specifies the unique name that identifies the CA personal certificate
object and the alias name of the certificate in the keystore. (String,
required)
- -keyStoreName
- Specifies the name of the keystore where the CA personal certificate
is stored. (String, required)
- -revocationPassword
- Specifies the password needed to revoke the certificate. This
is the same password that was provided when the certificate was created.
(String, required)
Optional parameters
- -keyStoreScope
- Specifies the management scope of the keystore. For a deployment
manager profile, the default value is the cell scope. For an application
server profile, the default value is the node scope. (String, optional)
- -revocationReason
- Specifies the reason for revoking the certificate of interest.
The default value for this parameter is unspecified. (String,
optional)
Example output
The
command does not return output. Use the getCertificate command to
view the current status of the certificate, as the following example
displays:
AdminTask.getCertificate('-certificateAlias myCertificate -keyStoreName CellDefaultKeyStore')
Examples
Batch mode example usage:
- Using Jacl:
$AdminTask revokeCACertificate {-keyStoreName CellDefaultKeyStore -certificateAlias
myCertificate -revocationPassword pw4revoke}
- Using Jython string:
AdminTask.revokeCACertificate('[-keyStoreName CellDefaultKeyStore -certificateAlias
myCertificate -revocationPassword pw4revoke]')
- Using Jython list:
AdminTask.revokeCACertificate(['-keyStoreName', 'CellDefaultKeyStore', '-certificateAlias',
'myCertificate', '-revocationPassword', 'pw4revoke'])
Interactive mode example usage: