Policy Server Guides › Policy Server Administration Guide › Policy Server Tools › CA SiteMinder® Key Tool

CA SiteMinder® Key Tool

The CA SiteMinder® key tool utility (smkeytool):

• Lets you manage the 12.51 certificate data store.
• Gives you access to a legacy smkeydatabase during an upgrade to 12.51. You use the access legacy key store flag (-accessLegacyKS) to resolve all data collisions that can result in a failed migration to the certificate data store.
• Is installed to the following location:

  siteminder_home\bin

  siteminder_home

  Specifies the Policy Server installation path.

Follow these steps:

1. Open a command line or shell.
2. Run one of the following commands:
   • (Windows) smkeytool.bat -option [-arguments]
   • (UNIX) smkeytool.sh -option [-arguments]

Use smkeytool to:

• Add client certificate keys

  If you are using a root or chain Certificate Authority (CA) at the consuming authority that is not listed in the smkeydatabase, add it to the smkeydatabase.

  For example, a signed VeriSign CA server-side certificate is used to SSL-enable the producer-side web server that is installed with the Web Agent Option Pack. To use this certificate for Basic over SSL authentication, add the VeriSign certificate to the smkeydatabase at the consumer. The addition of the certificate helps ensure that the consumer is communicating with a producer with a server-side certificate. The presence of the certificate also helps ensure that a trusted CA verified the certificate.

Add a Private Key and Certificate Pair

Use the addPrivKey option to import only a private key/certificate pair into the certificate data store. Consider the following items:

• You can have multiple private key/certificate pairs in the store, but CA SiteMinder® supports only RSA keys in the store.
• Only private key/certificate pairs are stored in encrypted form.
• A Policy Server at a producing authority:
  • Uses a single private key/certificate pair to sign SAML assertions.
  • Uses the certificate to decrypt encrypted SAML assertions received from the consuming authority.

  Typically, the key is the first private key/certificate pair found in the certificate data store.

• Delete the certificate metadata from the certificate file before importing it. Import only the data starting with the --BEGIN CERTIFICATE-- marker and ending with the --END CERTIFICATE-- marker. Be sure to include the markers.

Arguments for this option include the following:

-accessLegacyKS

Specifies that the option applies to the legacy smkeydatabase. If you do not supply this argument, the option applies to the 12.51 certificate data store.

-alias alias

Required. Assigns an alias to a private key/certificate pair in the database. The alias must be a unique string and can contain only alphanumeric characters.

-certfile cert_file

Specifies the full path to the location of the certificate that is associated with the private key/certificate pair. Required for keys in PKCS1, PKCS5, and PKCS8 format.

-keyfile private_key_file

Specifies the full path to the location of the private key file. Required for keys in PKCS1, PKCS5, and PKCS8 format.

-keycertfile key_cert_file

Specifies the full path to the location of the PKCS12 file that contains the private key/certificate pair data. Required for keys in PKCS12 format.

-password password

(Optional) Specifies the password that was used to encrypt the private key/certificate pair when the pair was created. Supply this password to decrypt the key/certificate pair before it gets written to the certificate data store.

Note: This password is not stored in the certificate data store.

After the key/certificate pair is decrypted and placed in the certificate data store, CA SiteMinder® encrypts the pair again using its own password.

Add a Certificate

Use the addCert option to add a public certificate or trusted CA certificate to the certificate data store.

Consider the following items:

• The certificate can be a certificate that is associated with a private key/certificate pair. However, only the certificate is added to the certificate data store.
• If you trust a certificate as a Certificate Authority, this certificate is always treated as a CA certificate.
• For X.509 certificate formats, CA SiteMinder® supports V1, V2, and V3 versions. For encoding formats, CA SiteMinder® supports DER and PEM formats.
• Restart the Web Agent when you add a Certificate Authority certificate.
• Delete the certificate metadata from the certificate file before importing it. Import only the data starting with the --BEGIN CERTIFICATE-- marker and ending with the --END CERTIFICATE-- marker. Be sure to include the markers.

Arguments for this option include the following:

-accessLegacyKS

Specifies that the option applies to the legacy smkeydatabase. If you do not supply this argument, the option applies to the 12.51 certificate data store.

-alias alias

Required. Specifies the alias to the certificate associated with the private key in the certificate data store.

Limit: A unique string that contains only alphanumeric characters.

-infile cert_file

Required. Specifies the full path to the location of the newly added certificate.

-trustcacert

Optional. Checks that the user provider certificate being added is a CA certificate. The utility checks that the certificate has a digital signature extension and that the certificate has the same IssuerDN and Subject DN values.

-noprompt

(Optional) The user is not prompted to confirm the addition of the certificate.

Add Revocation Information

Use the addRevocationInfo option to specify the location of a CRL. The certificate data store references the location of the CRL.

Arguments for this option include the following:

-accessLegacyKS

Specifies that the option applies to the legacy smkeydatabase. If you do not supply this argument, the option applies to the 12.51 certificate data store.

-issueralias issuer_alias

Required. Specifies the alias of the Certificate Authority who issues the CRL.

Example: -issueralias verisignCA

-type (ldapcrl | filecrl)

Required. Specifies if the CRL is LDAP–based or file–based.

-location location

Required. Specifies the location of the CRL.

• (File-based) The full path to the file.

  Example: -location c:\crls\siteminder_root_ca.crl

• (LDAP directory service) The full path to the LDAP server node.

  Example: -location "http://localhost:880/sn=siteminderroot, dc=crls,dc=com"

Delete Revocation Information

Use the deleteRevocationInfo option to delete a CRL from the certificate data store.

Arguments for this option include the following:

-accessLegacyKS

Specifies that the option applies to the legacy smkeydatabase. If you do not supply this argument, the option applies to the 12.51 certificate data store.

-issueralias issuer_alias

(Required) Specifies the name of the Certificate Authority who issues the CRL.

-noprompt

(Optional) The user is not prompted to confirm that the CRL can be deleted.

Remove Certificate Data

Use the removeAllCertificateData option to remove all certificate data from the certificate data store.

The argument for this option is the following:

-noprompt

(Optional) The user is not prompted to confirm that the certificate data can be removed.

Delete a Certificate

Use the delete option to remove a certificate from the certificate data store. If the certificate has an associated private key, the key is also deleted.

Arguments for this option include the following:

-accessLegacyKS

Specifies that the option applies to the legacy smkeydatabase. If you do not supply this argument, the option applies to the 12.51 certificate data store.

-alias <alias>

(Required) Specifies the alias of the certificate that the option is to remove.

-noprompt

(Optional) The user is not prompted to confirm that the certificate can be removed.

Export a Certificate or Private Key

Use the export option to export a certificate or private key to a file.

Consider the following items:

• Certificate data is exported using PEM encoding.
• Private key data is exported using DER encoded PKCS8 format.

Arguments for this option include the following:

-accessLegacyKS

Specifies that the option applies to the legacy smkeydatabase. If you do not supply this argument, the option applies to the 12.51 certificate data store.

-alias alias

(Required) Identifies the certificate or key to be exported.

-outfile out_file

(Required) Specifies the full path to the file to which the data is exported.

-type (key|cert)

(Optional) Specifies whether a certificate or key is being exported.

Default: certificate.

-password password

Required only when exporting a private key. Specifies the password that is used to encrypt the private key when exported. You do not need a password to export the certificate holding the public key because certificates are exported in clear text.

To add this private key back to the certificate data store, use the addPrivKey option with this password.

Find an Alias

Use the findAlias option to find the alias that is associated with a certificate in the certificate data store.

Arguments for this option include the following:

-accessLegacyKS

Specifies that the option applies to the legacy smkeydatabase. If you do not supply this argument, the option applies to the 12.51 certificate data store.

-infile cert_file

(Required) Specifies the full path to the certificate file associated with the alias you want.

-password password

Required only when a password–protected P12 file is specified as the certificate file.

Import Default CA Certificates

Use the importDefaultCACerts option to import all default trusted Certificate Authority certificates that are included with CA SiteMinder® to the certificate data store.

The argument for this option is the following:

-accessLegacyKS

Specifies that the option applies to the legacy smkeydatabase. If you do not supply this argument, the option applies to the 12.51 certificate data store.

List Metadata for all Certificates

Use the listCerts option to list some metadata of all certificates stored in the certificate data store.

Arguments for this option include the following:

-accessLegacyKS

Specifies that the option applies to the legacy smkeydatabase. If you do not supply this argument, the option applies to the 12.51 certificate data store.

-alias alias

(Optional) Lists the metadata details of the certificate and key that are associated with the alias specified.

This option supports an asterisk (*) as a wildcard character. Use the wildcard at the

• Beginning or end of an alias value.
• Beginning and end of an alias value.

Enclose the wildcard in quotes to prevent a command shell from interpreting the wildcard character.

List Revocation Information

Use the listRevocationInfo option to display a list of certificate revocation lists in the certificate data store. The following items are listed:

• The CRL name.
• Whether the CRL is file–based or LDAP–based.
• The CRL location.

Arguments for this option include the following:

-accessLegacyKS

Specifies that the option applies to the legacy smkeydatabase. If you do not supply this argument, the option applies to the 12.51 certificate data store.

-issueralias issuer_alias

(Optional) Name of the Certificate Authority who issues the CRL.

This option supports an asterisk (*) as a wildcard character. Use the wildcard at the:

• Beginning or end of an alias value.
• Beginning and end of an alias value.

Enclose the wildcard in quotes to prevent a command shell from interpreting the wildcard character.

Display Certificate Metadata

Use the printCert option to display some metadata for a specified certificate. This command is useful on systems where viewing certificate properties is difficult.

Arguments for this option include the following:

-accessLegacyKS

Specifies that the option applies to the legacy smkeydatabase. If you do not supply this argument, the option applies to the 12.51 certificate data store.

-infile cert_file

Required. Location of the certificate file.

-password password

The password is required only when a password-protected P12 file is specified as the certificate file.

Rename an Alias

Use the renameAlias option to rename an alias that is associated with a certificate.

Arguments for this option include the following:

-accessLegacyKS

Specifies that the option applies to the legacy smkeydatabase. If you do not supply this argument, the option applies to the 12.51 certificate data store.

-alias current_alias

(Required) Specifies the alias that is associated with a certificate.

-newalias new_alias

(Required) Specifies the new alias name.

Limits: Must be a unique string that contains only alphanumeric characters.

Validate a Certificate

Use the validateCert option to determine if a certificate is revoked.

Arguments for this option include the following:

-accessLegacyKS

Specifies that the option applies to the legacy smkeydatabase. If you do not supply this argument, the option applies to the 12.51 certificate data store.

-alias alias

(Required) Specifies the alias to the certificate associated with the private key in the certificate data store

Limits: Must be a unique string that contains only alphanumeric characters.

-infile crl_file

(Optional) Specifies the CRL that you want the utility to look in for the certificate to validate it.

Load the the OCSP Configuration File

Use the loadOCSPConfigFile option to reload the OCSP configuration file into the certificate data store without restarting the Policy Server. When the file loads, any existing OCSP configuration is removed from the data store and the configuration is replaced with the contents of the file. The OCSPUpdater picks up the configuration changes the next time that it wakes.

The name of the OCSP configuration file is SMocsp.conf.

The command syntax for Windows is:

smkeytool.bat -loadOCSPConfigFile

The command syntax for UNIX is:

smkeytool.sh -loadOCSPConfigFile