ssh-cmpclient(1) ssh-cmpclient(1)
NAME
ssh-cmpclient - CMP certificate enrollment client on z/OS
SYNOPSIS
ssh-cmpclient command [options ] access [name ]
The command parameter 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.
-Z provspec Specifies an external key provider for the private key.
The format of provspec is "provider:initstring".
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 Directory 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/absolute-key-file-path"
"file:/absolute-key-file-path"
CMP Enrollment Client December 1, 2006 1
ssh-cmpclient(1) ssh-cmpclient(1)
"file:relative-key-file-path"
"any-externalkey-provider-url" (provider-specific)
"any-key-file-path"
The key generation "savetype" can be:
- ssh2, secsh2 (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.
DESCRIPTION
The ssh-cmpclient command-line tool is a certificate
enrollment client that uses the CMP protocol. It can gen-
erate 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.
COMMANDS
The ssh-cmpclient 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 hard-
ware device.
INITIALIZE
Requests the user's initial certificate. The
request is authenticated using the reference num-
ber 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 her key. This request
is similar to initialize except that it is authen-
ticated using public-key methods.
CMP Enrollment Client December 1, 2006 2
ssh-cmpclient(1) ssh-cmpclient(1)
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 sim-
ilar 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 certifi-
cate-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.
OPTIONS
The ssh-cmpclient 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 com-
mand line, they should be enclosed in double quotes.
-B Requests private key backup to be performed for
initialize, enroll, and update commands.
-o prefix
Saves resulting certificates and CRLs into files
with this prefix. The prefix is first appended by
a number, followed by a suffix .crt or .crl,
depending on the type of object.
CMP Enrollment Client December 1, 2006 3
ssh-cmpclient(1) ssh-cmpclient(1)
-O filename
Saves the result into the specified absolute file-
name. If there are more than one result files, the
remaining results are rejected.
-C file Specifies the file path that contains the CA cer-
tificate. 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][/net-
work/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 CRMF or
the PKCS#10 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 the CMPv2.
-N file Specifies a file to be used as an entropy source
during key generation.
-Z provspec
Specifies an external key provider for the private
key. The value of provspec is "provider:init-
string". Currently, the only valid value for
provider is zos-saf. For the format of the init-
string, see ssh-externalkeys(5). Example of
provspec:
"zos-saf:keys(ring(SSH2-KEYS) label('U313 KEY1'))"
The usage line uses the following meta commands:
CMP Enrollment Client December 1, 2006 4
ssh-cmpclient(1) ssh-cmpclient(1)
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 command synopsis above.
-c file Path to the file that contains the certificate
issued to the public key given in the -k options
argument.
racerts In RA mode, the RA key and certificate for authen-
tication.
-k url URL specifying the private key location. This is
an external key URL whose format is specified in
the command synopsis above.
-R file Path to the file that contains the RA certificate
issued to the public key given in the -k options
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 command synopsis above.
CMP Enrollment Client December 1, 2006 5
ssh-cmpclient(1) ssh-cmpclient(1)
id Polling ID used if the certificate approval 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 iden-
tify the subject are read from this, but the user
may 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, nonRepudi-
ation, keyEncipherment, dataEncipherment, keyA-
greement, 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, ikeIn-
termediate, and smartCardLogon.
CMP Enrollment Client December 1, 2006 6
ssh-cmpclient(1) ssh-cmpclient(1)
access Specifies the CA's 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
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.
EXAMPLES
Initial Certificate Enrollment
This example provides commands for enrolling an initial
certificate for digital signature use. It generates a pri-
vate key into a PKCS #8 plaintext file named initial.prv,
and stores the enrolled certificate into file ini-
tial-0.crt. The user is authenticated to the CA with the
key identifier (refnum) 62154 and the key secret. The sub-
ject name and alternative IP address are given, as well as
key-usage flags. The CA address is pki.example.com, the
port 8080, and the CA name to access Test CA 1.
$ ssh-cmpclient INITIALIZE \
-p 62154:secret \
-P generate://pkcs8@rsa:1024/initial \
-s 'C=FI,O=SSH,CN=Example/initial;IP=1.2.3.4' -u digitalsignature \
-o initial \
http://pki.example.com:8080/pkix/ \
'C=FI, O=SSH, CN=Test CA 1'
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, CN=Test CA 1>
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 =
CMP Enrollment Client December 1, 2006 7
ssh-cmpclient(1) ssh-cmpclient(1)
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
Key update
Before the certificate expires, a new certificate with
updated validity period should be enrolled. ssh-cmpclient
supports key update, where 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. Present-
ing the result certificate has been left out.
$ ssh-cmpclient UPDATE \
-c initial-0.crt -k initial.prv \
-P generate://pkcs8@rsa:1024/updatedcert \
-o updatedcert \
http://pki.example.com:8080/pkix/ \
'C=FI, O=SSH, CN=Test CA 1'
The new key pair can be found in the files with the updat-
edcert prefix. The policy of the issuing CA needs to also
allow automatic key updates if ssh-cmpclient is used in
the UPDATE mode.
Certificate Enrollment for SAF Key
This example shows a command for enrolling a certificate
for a private key that is stored in the user's key ring in
SAF. The user is authenticated to the CA with the key
identifier (refnum) 18437 and the key test. The key
provider and the initialization string are given with the
-Z option. The URL to the private key is given with the -P
option. The certificate is stored in file test_1024_non-
icsf-0.crt. The subject name is also given (CN=Newuser).
The CA address is pki.example.com, the port 8080, and the
CA name to access is Test CA 1.
$ ssh-cmpclient INITIALIZE \
-p 18437:test \
-Z 'zos-saf:keys(ring(TESTUSER1))' \
-P 'zos-saf://0/TEST/TESTUSER1/TEST 1024 NON-ICSF' \
-s 'CN=Newuser' \
-o test_1024_non-icsf \
http://pki.example.com:8080/pkix/ \
CMP Enrollment Client December 1, 2006 8
ssh-cmpclient(1) ssh-cmpclient(1)
'C=FI, O=SSH, CN=Test CA 1'
To get the value for the external key URL for the -P
option, run ssh-ekview on the key ring, for example:
ssh-ekview -i "keys(ring(TESTUSER1))" zos-saf
See ssh-ekview(1)) for more information.
AUTHORS
SSH Communications Security Corp.
For more information, see http://www.ssh.com.
SEE ALSO
ssh-certview(1), ssh-ekview(1)
CMP Enrollment Client December 1, 2006 9