gskkyman

The gskkyman utility is used for key database management, z/OS PKCS #11 token management, and to display the certificates within GSKIT CMS V4 key databases and PKCS #12 files.

Format

gskkyman

gskkyman -dc|-dcv [-k filename|-t tokenname|-p12 filename|-der filename] [-l label]
gskkyman -dk [-k filename]
gskkyman -e|-i [-k filename|-t tokenname] [-l label] [-p filename]
gskkyman -g [-x days] [-cr filename] [-ct filename] [-k filename|-t tokenname]
  [-l label] [-kt {ecgen|ecdsa|ecdh}] [-ca] [-ic]
gskkyman -h|-?
gskkyman -s [-k filename]

Parameters

function

The function to be performed. It must follow the command name. The acceptable values are:

-dc: Display certificate details.
-dcv: Display certificate verbose details.
-dk: Display key database expiration, record length and type.
-e: Export a certificate and its associated private key.
-g: Sign a certificate for a certificate request.
-h: Display the command syntax.
-i: Import a certificate and its associated private key.
-s: Store the database password in the stash file.
-?: Display the command syntax.

option

The parameters necessary to accomplish the function. If the option provides a value, then the value must follow the option:

The acceptable values are:

-ca: A certification authority certificate is generated if -ca is specified. An end user certificate is generated if -ca is not specified.
-cr: Specifies the name of the certificate request file. You are prompted for the file name if this option is not specified.
-ct: Specifies the name of the output generated signed certificate file. You are prompted for the file name if this option is not specified. You may specify any name. If you specify an existing file name, the file is overwritten.
-der: Specifies the name of the X.509 certificate file. The specified file must contain either a binary ASN.1 DER-encoded certificate or the Base64-encoding of a binary ASN.1 stream. A Base64-encoded certificate must be in the local code page. The fully-qualified certificate file name must be less than 251 characters. This option is mutually exclusive with the -k option, the -t option, and the -p12 option. The -l option is not supported.
-ic: The certification chain certificates are included in the certificate file if -ic is specified. Otherwise, just the signed certificate is included in the certificate file.
-k: Specifies the name of the key database or GSKIT CMS V4 key database. This option is mutually exclusive with the -t option, the -p12 option, and the -der option. You are prompted for the key database file name if neither this option nor the -t option, the -p12 option, or the -der option is specified. The length of the fully qualified file name cannot exceed 251 characters. If the file name does not end with an extension of 1-3 characters, the length of the fully qualified file name cannot exceed 247 characters. Finally, the key database name cannot end with .rdb or .sth.
-kt: Specifies the key type of the certificate to be created. This option is valid when signing an end user certificate or certificate request containing an ECC public key and affects the settings of the keyUsage extension of the certificate created. Valid key type options are ecgen, ecdsa and ecdh. ecgen creates a certificate with digitalSignature, nonRepudiation and keyAgreement set, ecdsa creates a certificate with digitalSignature and nonRepudiation set, and ecdh creates a certificate with keyAgreement set. If the -kt option is not specified for an end user ECC certificate or certificate request, the default option is ecgen. For other certificate types the -kt option is ignored.
-l: Specifies the certificate label. This option is not supported with the -der option. The label must be enclosed in double quotation marks if it contains one or more spaces. If the certificate is being used to sign a certificate request (sign function), the certificate must be a CA. The label for the default key is used if this option is not specified (export or sign function) or you are prompted for the label (import function). If more than one certificate with the specified label exists (can occur for tokens), the user is prompted to either cancel or choose the required certificate from a list that summarizes significant fields in the certificate.
-p: Specifies the name of the PKCS #12 file to be used to import or export certificates. You are prompted for the file name if this option is not specified.
-p12: Specifies the name of the PKCS #12 file containing the certificates to be displayed. This option is mutually exclusive with the -k option, the -t option, and the -der option. The length of the fully qualified file name cannot exceed 251 characters. If the file name does not end with an extension of 1-3 characters, the length of the fully qualified file name cannot exceed 247 characters. Lastly, the PKCS #12 file cannot end with .kdb, .rdb or .sth.
-t: Specifies the name of the token to be managed. This option is mutually exclusive with the -k option and the -p12 option. The name must consist of characters that are alphanumeric, national (@ x5B, # x7B, $ x7C) or period (.x4B). The first character must be alphabetic or national. Lowercase letters are allowed, but are folded to uppercase.
-x: Specifies the number of days until the signed certificate expires and must be between 1 and 9999 days. The certificate expires in 365 days if this option is not specified.

Results

If gskkyman is specified with no arguments the interactive menu-driven interface is used.

Usage

The gskkyman utility is used to manage a token, a key database and its associated request database, or to list the contents of a GSKIT CMS V4 key database or PKCS #12 file. Interactive menus are displayed if no command options are specified. Otherwise, the requested token/database/PKCS #12 file function is performed and the gskkyman utility exits.

Note: The ability to display the contents of a PKCS #12 file or a GSKIT CMS V4 key database is not supported through the interactive menu-driven interface.

If the command specifies the -t (token name) option, then the requested function is performed for the identified token. If the specified PKCS #11 token certificate contains a secure private key, then only display functions -dc and -dcv are supported. If the gskkyman utility supplies both the -t and -l (label name) options, then only the PKCS #11 certificate with the matching label is checked for a secure private key. If the certificate does not have a secure private key, then both the -e (export) or -g (sign) functions can be processed.

If the command specifies the -p12 (PKCS #12 file) option on the display functions -dc or -dcv, if -l option is used, the certificate with matching label is displayed. If -l option is not used, all certificates within the file are displayed.

If the command does not specify the -t or the -p12 option, then it is assumed that the function is to be performed for a key database. If the -k option, the -t option, and the -p12 option are not supplied, the user is prompted for a key database file name.

If any combination of -k, -t, and -p12 is specified, the command is rejected and an error message is displayed.

For commands applied to a GSKIT CMS V4 key database:

If the command specifies a -k option on the display functions -dc or -dcv, if -l option is used, the certificate with matching label is displayed. If -l option is not used, all certificates within the file are displayed.
If the command specifies a -k option on the display function -dk, the key database information is displayed.

For commands applied to a key database:

The key database contains certificates and private keys and normally has the .kdb file name extension. The request database contains requests for new certificates and always has a .rdb file name extension. The database stash file contains the masked database password and always has a .sth file name extension. Access to these files should be restricted to the database owner.
A certificate or request database consists of fixed-length records. The record length is specified when the database is created and must be large enough to contain the largest certificate entry. A record length of 5000 should be sufficient for most applications. The record length can be increased if necessary after the database is created.
A temporary database file is created when a database is updated during gskkyman processing. The temporary database file is created using the same name as the database file with .new appended to the name. The database file is then rewritten and the temporary database file is deleted upon successful completion of the rewrite operation. The temporary database file is not deleted if an error occurs while rewriting the database file. If this happens, you can replace the database file with the temporary database file to recover from the error. If an error does occur and you do not rename or delete the temporary file, you receive an error on the next database update operation indicating the backup file exists.
If all certificates in a key database are displayed with the -dc or -dcv command, then all certificates with private keys are outputted, followed by all certificates without private keys. When displaying all certificates in a token, the certificates are displayed in the order that is returned from the token so that certificates with private keys might be interspersed with certificates without private keys.