SSH-CERTTOOL

Index

NAME
SYNOPSIS
DESCRIPTION
OPTIONS
EXAMPLES
COPYRIGHT
SEE ALSO

NAME

ssh-certtool - certificate management tool.

SYNOPSIS

ssh-certtool [options] action [arguments]

The value for action can be either pkcs10 (to create a PKCS#10 certificate request) or pkcs12 (to create a PKCS#12 package). The applicable arguments depend on which action you specify as shown here:

ssh-certtool [options] pkcs10 subject [keyUsage] [extendedKeyUsage]
ssh-certtool [options] pkcs12 [file1] ... [fileN]

To see help about each of these two options, you can use the following:

ssh-certtool --help pkcs10
ssh-certtool --help pkcs12

DESCRIPTION

You can use ssh-certtool to create a PKCS#10 certificate request or to create a PKCS#12 package containing a private key and one or more certificates.

Creating a PKCS#10 certificate request

The general syntax for creating a PKCS#10 file is:

ssh-certtool [options] pkcs10 subject [keyUsage] [extendedKeyUsage]

Note: req is supported as a synonym for pkcs10.

The value you specify as subject defines the certificate's Subject field. The subject name is required. Use the distinguished name syntax specified by RFC2253. Use commas to separate Subject elements (RDNs). RDNs can be specified using standard abbreviations (CN) or OIDs (2.5.4.3). Quotation marks are required if the subject name contains embedded white space.

Note: SubjectName elements in the subject argument must be specified in uppercase (CN,DC,OU,O,C). For example, "CN=Steve Kille,O=Isode Limited,C=GB".

The filename of the generated certificate request is based on the prefix specified by the -o option, with .pkcs10 appended. The default filename of a generated private key, when -o is not specified, is output.pkcs10.

To create a request using an existing private key use -p to specify the key. To generate a new private key for the request, omit the -p option. By default, ssh-certtool creates a 2048-bit RSA key. To specify a key type, use type -n. To specify key size, use -b. The filename of the generated private key is based on the prefix specified by the -o option, with .ssh2 appended. The default filename of a generated private key, when -o is not specified, is output.ssh2. If a key with the same name already exists, you are prompted to overwrite it. If you elect not to overwrite it, ssh-certtool exits with a return code of zero.

You can use optional flags to set keyUsage and extendedKeyUsage fields. Use commas, spaces or tabs to separate items. All Key Usage and Extended Key Usage flags are marked as critical in the PKCS#10 request. Valid keyUsage flags are digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment, keyAgreement, keyCertSign, cRLSign, encipherOnly and decipherOnly. If you omit this argument, the digitalSignature and keyEncipherment flags are set by default. Valid extendedKeyUsage flags are anyExtendedKeyUsage, serverAuth, clientAuth, codeSigning and emailProtection. No extended key usage flags are set by default.

Creating a PKCS#12 package

The general syntax for creating a PKCS#12 package is:

ssh-certtool [options] pkcs12 [file1] ... [fileN]

This constructs a PKCS#12 package file containing one private key and multiple certificates read from the file arguments. The PKCS#12 package file contains one safe, which contains the private key and all the certificates. The filename of the generated package file is based on the prefix specified by the -o option, with .p12 appended. The default filename of the generated PKCS#12 package, when -o is not specified, is output.p12. The PKCS#12 package is protected by an HMAC, and ssh-certtool prompts you for a passphrase before creating the package.

File arguments containing private keys can be read in naked PKCS#8 format, in ssh2 PEM format, or in openSSH PEM format. If the key is protected by a passphrase, ssh-certtool prompts for the passphrase. File arguments containing certificates are recognized in both DER-encoded and PEM-encoded format.

By default, the individual private key and certificates are saved into the PKCS#12 output file using default PBE protection schemes. The default scheme for key encryption is pbeWithSHA1And3-KeyTripleDES-CBC. The default for safe encryption is pbeWithSHA1And40BitRC2-CBC format. You can use the -z option to configure different PBE protection schemes.

OPTIONS

Options are available in both a single-character form (such as -o) and a descriptive equivalent (--option). Single characters are shown here. To view the descriptive equivalents, use the -h command line option.

-b bits: Specifies the key size used for generated keys. The default for RSA keys is 2048 bits and for DSA keys is 1024 bits. The value for a DSA key must be an integral multiple of 64. This option is valid for PKCS#10 file creation only.
-c comment: Specifies a comment to include in the private key file. This option is valid for PKCS#10 file creation only.
-d debug_level: Enables debug output. Use 1, 2, 3, or 99. (Values 4-98 are accepted, but are equivalent to 3.)
-f: Enables FIPS mode. This mode forces all keys generated using ssh-certtool to meet FIPS standards, and ensures that any PKCS#10 certificate requests you create include keys that meet FIPS standards. Note: Using this option does not place any limits on keys included in PKCS#12 packages.
-h [action]: Displays a brief summary of command options. Specify an action (either pkcs10 or pkcs12) to see additional information about that action.
-n algorithm: Specifies the algorithm used for key generation. Possible values are "rsa" and "dsa". The default is "rsa". This option is valid for PKCS#10 file creation only.
-o output_file_prefix: Specifies the first portion of the filename for output files. You can include an absolute path to generate the file in a different location. The default is "output". (The filename suffix is generated based on the file type: the suffix for PKCS#10 files is .pkcs10, for PKCS#12 is.p12, and for private keys is .ssh2.)
-p private_key: Specifies a private key to use in a certificate request. This option is valid for PKCS#10 file creation only.
-P: Saves the private key with an empty passphrase. This option is valid for PKCS#10 file creation only.
--passphrase passphrase: Specifies a passphrase for the private key. This option is valid for PKCS#10 file creation only.
-V: Displays product name and version information and exits. If other options are specified on the command line, they are ignored.
-z Key=Value: Specifies certificate options for PKCS#10 requests, and encryption options for PKCS#12 packages.
: For PKCS#10 requests, Key can be DNS, Email, UPN, or IP. Use these to set values for the corresponding extensions in the SubjectAltName field of the certificate. These extensions are not marked as critical. There should be no white space in this option, including before or after the equal sign, unless the value literally contains white space characters in its name. For IP, specify any valid IPv4 or IPv6 address. You can configure multiple extensions, but you can only set one value for each extension type. To specify more than one extension, repeat the -z option. For example:
: -z Email=joe@microfocus.com -z IP=10.10.10.10
: For PKCS#12 packages, Key must be either KeyPBE or SafePBE (case-insensitive). There should be no whitespace in this option, including before or after the equal sign. KeyPBE sets the key encryption and hmac scheme. SafePBE sets the safe encryption and hmac scheme. Values are listed below. The default for KeyPBE is PBE-SHA1-3DES. The default for SafePBE is PBE-SHA1-RC2-40. The long names in parentheses are synonyms.
: None
: PBE-SHA1-RC4-128 (pbeWithSHA1And128BitRC4)
: PBE-SHA1-RC4-40 (pbeWithSHA1And40BitRC4)
: PBE-SHA1-3DES (pbeWithSHA1And3-KeyTripleDES-CBC)
: PBE-SHA1-2DES (pbeWithSHA1And2-KeyTripleDES-CBC)
: PBE-SHA1-RC2-128 (pbeWithSHA1And128BitRC2-CBC)
: PBE-SHA1-DES (pbeWithSHA1AndDES-CBC)
: PBE-SHA1-RC2-40 (pbeWithSHA1And40BitRC2-CBC)
: PBE-MD2-RC2-64 (pbeWithMD2AndRC2-CBC)
: PBE-MD5-RC2-64 (pbeWithMD5AndRC2-CBC)

EXAMPLES

To create a PKCS#10 request using a newly generated key:

: ssh-certtool -n RSA -z DNS=steves.dns.server.com -z Email=steved@myorg.org pkcs10 CN=steved,O=myorg.org,OU=rsit,C=US DigitalSignature,nonRepudiation ServerAuth,ClientAuth

To create a PKCS#12 package file and specify encryption for the key and safe:

: ssh-certtool -z keyPBE=default -z safePBE=PBE-SHA1-RC4-40 -ofile pkcs12 id_rsa.crt id_rsa