gskkyman

The gskkyman utility is used for key database management and z/OS® PKCS #11 token management.

Format

gskkyman

gskkyman -dc|-dcv [-k filename|-t tokenname] [-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 and record length
-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.
-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. This option is mutually exclusive with the -t option. You are prompted for the key database file name if either this option or the -t 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. 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. You are prompted for the file name if this option is not specified.
-t: Specifies the name of the token to be managed. This option is mutually exclusive with the -k 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 areallowed 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 or a key database and its associated request database. Interactive menus are displayed if no command options are specified. Otherwise, the requested token/database function is performed and the gskkyman utility exits.

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 does not specify the -t option, then it is assumed that the function is to be performed for a key database. If the -k option and the -t option are not supplied, the user is prompted for a key database file name.

If both -k and -t are specified, the command is rejected and an error message is displayed.

For commands applied to a key database:

The key database contains certificates and private keys and normally has a file name extension of '.kdb'. The request database contains requests for new certificates and always has a file name extension of '.rdb'. The database stash file contains the masked database password and always has a file name extension of '.sth'. 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.