ssh-cmpclient-g3 — CMP enrollment client
ssh-cmpclient-g3 command [options] access [name] Where command is one of the following: INITIALIZE psk|racerts keypair template ENROLL certs|racerts keypair template UPDATE certs [keypair] POLL psk|certs|racerts id RECOVER psk|certs|racerts template REVOKE psk|certs|racerts template TUNNEL racerts template Most commands can accept the following options: -B Perform key backup for subject keys. -o prefix Save result into files with prefix. -O filename Save the result into the specified file. If there is more than one result file, the remaining results are rejected. -C file CA certificate from this file. -S url Use this SOCKS server to access the CA. -H url Use this HTTP proxy to access the CA. -E PoP by encryption (CA certificate needed). -v num Protocol version 1|2 of the CA platform. Default is 2. -y Non-interactive mode. All questions answered with 'y'. -N file Specifies a file to stir to the random pool. The following identifiers are used to specify options: psk -p refnum:key (reference number and pre-shared key) -p file (containing refnum:key) -i number (iteration count, default 1024) certs -c file (certificate file) -k url (private-key URL) racerts -R file (RA certificate file) -k url (RA private-key URL) keypair -P url (private-key URL) id -I number (polling ID) template -T file (certificate template) -s subject-ldap[;type=value] -u key-usage-name[;key-usage-name] -U extended-key-usage-name[;extended-key-usage-name] access URL where the CA listens for requests. name LDAP name for the issuing CA (if -C is not given). Key URLs are either valid external key paths or in the format: "generate://savetype:passphrase@keytype:size/save-file-prefix" "file://passphrase/relative-key-file-path" "file:relative-key-file-path" "any-key-file-path" The key generation "savetype" can be: - ssh2, secsh2, secsh (Secure Shell 2 key type) - ssh1, secsh1 (legacy Secure Shell 1 key type) - pkcs1 (PKCS #1 format) - pkcs8s (passphrase-protected PKCS #8, "shrouded PKCS #8") - pkcs8 (plain-text PKCS #8) - x509 (SSH-proprietary X.509 library key type) -h Prints usage message. -F Prints key usage extension and keytype instructions. -e Prints command-line examples.
The ssh-cmpclient-g3 command-line tool (ssh-cmpclient-g3.exe on Windows) is a certificate enrollment client that uses the CMP protocol. It can generate an RSA or DSA public-key pair and get certificates for their public components. CMP is specified by the IETF PKIX Working Group for certificate life-cycle management, and is supported by some CA platforms, such as Entrust PKI and RSA Keon.
The ssh-cmpclient-g3 command-line command keywords are listed below. Shorthands longer than three letters can be used to identify the command. The commands are case-insensitive. The user must specify the CA address URL for each command. Here the term "user" refers to a user, program, or hardware device.
INITIALIZE
Requests the user's initial certificate. The request is authenticated using the reference number and the corresponding key (PSK) received from the CA or RA using some out-of-band mechanism.
The user must specify the PSK, the asymmetric key pair, and a subject name.
ENROLL
Requests a new certificate when the user already has a valid
certificate for the key. This request is similar to
initialize
except that it is authenticated using
public-key methods.
POLL
Polls for a certificate when a request was not immediately accepted.
UPDATE
Requests an update of an existing certificate (replacement). The issued certificate will be similar to the existing certificate (names, flags, and other extensions). The user can change the key, and the validity times are updated by the CA. This request is authenticated by a valid existing key pair and a certificate.
RECOVER
Requests recovery of a backed-up key. This request is authenticated either by PSK-based or certificate-based authentication. The template describes the certificate whose private key has already been backed up and should be recovered. Users can only recover keys they have backed up themselves.
REVOKE
Requests revocation for a key specified in the template. Authentication of the request is made using a PSK or a certificate belonging to the same user as the subject of revocation.
TUNNEL
Operates in RA tunnel mode. Reads requests and optionally modifies the subject name, alternative names, and extensions based on the command line. Approves the request and sends it to the CA.
The ssh-cmpclient-g3 command-line options are listed below. Note that when a file name is specified, an existing file with the same name will be overwritten. When subject names or other strings that contain spaces are given on the command line, they should be enclosed in double quotes.
-B
Requests private key backup to be performed for the initialize, enroll, and update commands.
-o
prefix
Saves resulting certificates and CRLs into files with the given
prefix. The prefix is first appended by a number, followed by the file
extension .crt
or .crl
, depending on the
type of object.
-O
filename
Saves the result into the specified absolute filename. If there is more than one result file, the remaining results are rejected.
-C
file
Specifies the file path that contains the CA certificate. If key backup is done, the file name must be given, but in most cases the LDAP name of the CA can be given instead.
-S
url
Specifies the SOCKS URL if the CA is located behind a SOCKS-
enabled firewall. The format of the URL is:
socks://[username@]server[:port][/network/bits[,network/bits]]
-H
url
Uses the given HTTP proxy server to access the CA. The format of
the URL is: http://server[:port]/
-E
Performs encryption proof of possession if the CA supports it. In this method of PoP, the request is not signed, but instead the PoP is established based on the ability to decrypt the certificates received from the CA. The CA encrypts the certificates with the user's public key before sending them to the user.
-v
num
Selects the CMP protocol version. This is either value 1, for an RFC 2510-based protocol, or 2 (the default) for CMPv2.
-N
file
Specifies a file to be used as an entropy source during key generation.
The usage line uses the following meta commands:
psk
The reference number and the corresponding key value given by the CA or RA.
-p
refnum:key|file
refnum
and key
are character strings
shared among the CA and the user. refnum
identifies the
secret key
used to authenticate the message. The
refnum
string must not contain colon characters.
Alternatively, a filename containing the reference number and the key can be given as the argument.
-i
number
number
indicates the key hashing iteration count.
certs
The user's existing key and certificate for authentication.
-k
url
URL specifying the private key location. This is an external key URL whose format is specified in the section called “Synopsis”.
-c
file
Path to the file that contains the certificate issued to the
public key given in the -k
option argument.
racerts
In RA mode, the RA key and certificate for authentication.
-k
url
URL specifying the private key location. This is an external key URL whose format is specified in the section called “Synopsis”.
-R
file
Path to the file that contains the RA certificate issued to
the public key given in the -k
option
argument.
keypair
The subject key pair to be certified.
-P
url
URL specifying the private key location. This is an external key URL whose format is specified in the section called “Synopsis”.
id
Polling ID used if the PKI action is left pending.
-I
number
Polling transaction ID number
given by the RA or
CA if the action is left pending.
template
The subject name and flags to be certified.
-T
file
The file containing the certificate used as the template for the operation. Values used to identify the subject are read from this, but the user can overwrite the key, key-usage flags, or subject names.
-s
subject-ldap[;type=value]*
A subject name in reverse LDAP format, that is, the most
general component first, and alternative subject names. The name
subject-ldap
will be copied into the request verbatim.
A typical choice would be a DN in the format
"C=US,O=SSH,CN=Some Body"
, but in principle this can be
anything that is usable for the resulting certificate.
The possible type
values are ip
,
email
, dn
, dns
,
uri
, and rid
.
-u
key-usage-name[;key-usage-name]*
Requested key usage purpose code. The following codes are
recognized: digitalSignature
,
nonRepudiation
, keyEncipherment
,
dataEncipherment
, keyAgreement
,
keyCertSign
, cRLSign
,
encipherOnly
, decipherOnly
, and
help
. The special keyword help lists the supported key
usages which are defined in RFC 3280.
-U
extended-key-usage-name[;extended-key-usage-name]*
Requested extended key usage code. The following codes, in
addition to user-specified dotted OID values are recognized:
serverAuth
, clientAuth
,
codeSigning
, emailProtection
,
timeStamping
, ikeIntermediate
, and
smartCardLogon
.
access
Specifies the CA address in URL format. Possible access
methods are HTTP (http://host:port/path
), or plain TCP
(tcp://host:port/path
). If the host address is an IPv6
address, it must be enclosed in square brackets (http://[IPv6-address]:port/
).
name
Optionally specifies the destination CA name for the operation,
in case a CA certificate was not given using the option -C
.
This example provides commands for enrolling an initial certificate for
digital signature use. It generates a private key into a PKCS #8 plaintext file named
initial.prv
, and stores the enrolled certificate into file
initial-0.crt
. The user is authenticated to the CA with the key
identifier (refnum) 62154
and the key ssh
. The subject
name and alternative IP address are given, as well as key-usage flags.
The CA address is pki.ssh.com
, the port 8080
, and the CA name
to access Test CA 1
.
$ ssh-cmpclient-g3 INITIALIZE \ -P generate://pkcs8@rsa:1024/initial -o initial \ -p 62154:ssh \ -s 'C=FI,O=SSH,CN=Example/initial;IP=1.2.3.4' \ -u digitalsignature \ http://pki.ssh.com:8080/pkix/ \ 'C=FI, O=SSH Communications Security Corp, CN=SSH Test CA 1 No Liabilities'
As a response the command presents the issued certificate to the
user, and the user accepts it by typing yes
at the prompt.
Certificate = SubjectName = <C=FI, O=SSH, CN=Example/initial> IssuerName = <C=FI, O=SSH Communications Security Corp, CN=SSH Test CA 1 No Liabilities> SerialNumber= 8017690 SignatureAlgorithm = rsa-pkcs1-sha1 Validity = ... PublicKeyInfo = ... Extensions = Viewing specific name types = IP = 1.2.3.4 KeyUsage = DigitalSignature CRLDistributionPoints = ... AuthorityKeyID = KeyID = 3d:cb:be:20:64:49:16:1d:88:b7:98:67:93:f0:5d:42:81:2e:bd:0c SubjectKeyID = KeyId = 6c:f4:0e:ba:b9:ef:44:37:db:ad:1f:fc:46:e0:25:9f:c8:ce:cb:da Fingerprints = MD5 = b7:6d:5b:4d:e0:94:d1:1f:ec:ca:c2:ed:68:ac:bf:56 SHA-1 = 4f:de:73:db:ff:e8:7d:42:c4:7d:e1:79:1f:20:43:71:2f:81:ff:fa Do you accept the certificate above? yes
Before the certificate expires, a new certificate with updated validity period should be enrolled. ssh-cmpclient-g3 supports key update, where a new private key is generated and the key update request is authenticated with the old (still valid) certificate. The old certificate is also used as a template for issuing the new certificate, so the identity of the user will not be changed during the key update. With the following command you can update the key pair, which was enrolled in the previous example. Presenting the resulting certificate has been left out.
$ ssh-cmpclient-g3 UPDATE \ -k initial.prv -c initial-0.crt -P \ generate://pkcs8@rsa:1024/updatedcert -o updatedcert \ http://pki.ssh.com:8080/pkix/ \ "C=FI, O=SSH Communications Security Corp, CN=SSH Test CA 1 No Liabilities"
The new key pair can be found in the files with the updatedcert
prefix. The policy of the issuing CA needs to also allow automatic key
updates if ssh-cmpclient-g3 is used in the UPDATE
mode.