.nh
.TH CMCRequest 1 "March 14, 2018" PKI "PKI CMC Request Generation Tool"
.SH NAME
.PP
CMCRequest - Used to generate a CMC certificate issuance or revocation request.

.SH SYNOPSIS
.PP
\fBCMCRequest\fP \fIconfig-file\fP

.SH DESCRIPTION
.PP
The Certificate Management over Cryptographic Message Syntax (CMC) Request Generation utility, \fBCMCRequest\fP,
provides a command-line utility used to generate a CMC certificate issuance or revocation request.
For issuance request, it requires either a PKCS#10 or CRMF request as input.
The resulting CMC request can be sent to the CA via tool such as \fBHttpClient\fP\&.

.PP
\fBCMCRequest\fP takes a configuration file where various configuration parameters are supported.

.SH CONFIGURATION PARAMETERS
.PP
The following are supported configuration parameters for the configuration file.
Each parameter is in the format of <name>=<value> (e.g. format=pkcs10).

.SS numRequests
.PP
Total number of PKCS10 or CRMF requests.
(note: lately the CA has only been tested to work with one)

.SS input
.PP
Full path for PKCS #10 or CRMF certificate request in PEM.

.PP
For example if \fBPKCS10Client\fP or \fBCRMFPopClient\fP are used to generate the PKCS#10 or CRMF requests respectively,
this value should be the value of the \fB-o\fP option of those command line tools.

.SS format
.PP
Request format. Either \fBpkcs10\fP or \fBcrmf\fP\&.

.SS output
.PP
Full path for the resulting CMC request in ASN.1 DER encoded format.

.PP
Note that this would be the \fBinput\fP in the \fBHttpClient\fP configuration file
if it is used to submit the CMC request.

.SS dbdir
.PP
Directory for NSS database.

.SS tokenname
.PP
Name of crypto token where user signing certificate key can be found (default is internal).

.SS nickname
.PP
The nickname of the user certificate that corresponds to the private key that is used to sign the request.

.PP
This parameter is ignored if \fBuseSharedSecret\fP or \fBidentityProofV2.enable\fP is true.

.SS password
.PP
Password to the crypto token where the signing user's certificate and keys are stored.

.SS identification[.enable]
.PP
RFC 5272 allows the CA to require inclusion of the \fBidentification\fP control
to accompany the \fBidentityProofV2\fP control in a CMC request.

.PP
In PKI, CA employs the \fBidentification\fP control to assist in locating the shared secret
required for verification of the shared secret computed in the \fBidentityProofV2\fP\&.

.PP
In addition, the \fBidentification\fP control is also required for \fBpopLinkWitnessV2\fP
for locating the shared secret.

.PP
When \fBidentification.enable\fP is true, \fBidentification\fP should contain a user id known by the CA.

.SS witness.sharedSecret
.PP
The \fBwitness.sharedSecret\fP should contain a passphrase that is known by the CA.
One usually obtains it from the CA administrator.

.PP
This parameter is required by the following options: \fBidentityProofV2\fP, and \fBpopLinkWitnessV2\fP\&.

.PP
See \fBCMCSharedToken(1)\fP for information on usage.

.SS identityProofV2.[enable, hashAlg, macAlg]
.PP
Identity Proof V2 allows one to provide proof of identity without a signing certificate.
It does so by embedding a "witness" value that's calculated from a shared secret (see \fBwitness.sharedSecret\fP)
known by the CA.

.PP
The \fBidentityProofV2\fP parameter set allows a user to specify the hashing algorithm
as well as MAC (Message Authentication Code) algorithm used to compute the value of the witness value.

.PP
Supported \fBidentityProofV2.hashAlg\fP are: \fBSHA-256\fP, \fBSHA-384\fP, and \fBSHA-512\fP\&.

.PP
Supported \fBidentityProofV2.macAlg\fP are: \fBSHA-256-HMAC\fP, \fBSHA-384-HMAC\fP, and \fBSHA-512-HMAC\fP\&.

.PP
When \fBidentityProofV2.enable\fP is true, these parameters must be accompanied by the \fBidentification\fP
as well as the \fBwitness.sharedSecret\fP parameters.

.PP
These parameters could be accompanied by the \fBpopLinkWitnessV2\fP parameter set if required by the CA.

.SS popLinkWitnessV2.[enable, keyGenAlg, macAlg]
.PP
The POPLinkWitnessV2 control is a mechanim that links the POP (Proof of Possession) to the identity,
which adds more credibility to the otherwise distinct POP and Proof of Identity mechanisms.
It does so by employing calculation of a random value with a shared secret (see \fBwitness.sharedSecret\fP)
known by the CA.

.PP
The POP Link Witness V2 value must be baked into the PKCS#10 or CRMF requests.
It is therefore crutial that the caller that employs this option has access
to the private key of the certificate request.

.PP
If \fBpopLinkWitnessV2\fP is used, then \fBidentification\fP and \fBwitness.sharedSecret\fP must be supplied,
and the \fBidentityProofV2\fP parameter set is in general used.

.PP
Supported keyGenAlg are: \fBSHA-256\fP, \fBSHA-384\fP, and \fBSHA-512\fP\&.

.PP
Supported macAlg are: \fBSHA-256-HMAC\fP, \fBSHA-384-HMAC\fP, and \fBSHA-512-HMAC\fP\&.

.SS request.useSharedSecret
.PP
\fBtrue\fP or \fBfalse\fP\&.
If \fBuseSharedSecret\fP is true, the CMC request will be "signed" with the pairing private key of the enrollment request;
and in which case the \fBnickname\fP parameter will be ignored.

.PP
\fBrequest.useSharedSecret\fP is only used if a signing certificate (of the agent or user herself)
is not available to sign.
Because the request itself is not signed with a certificate (a proven identity),
the proof of origin (proof of identification) must be provided by some other means.

.PP
In PKI, if \fBrequest.useSharedSecret\fP is true,
it must be used in conjunction with the \fBidentityProofV2\fP and \fBidentification\fP parameters.
And in that case the Proof Of Origin is accomplished by the Shared Secret (\fBwitness.sharedSecret\fP) mechanism.

.PP
The \fBrequest.useSharedSecret\fP option is normally used to enroll for a user's first signing certificate
while auto-approval (without agent's pre-approval) is preferred.
In general, once a user has obtained the first signing certificate,
such signing certificate can be used to sign (thus proving origin)
and obtain other certificate such as encryption-only ceritifcate,
or when doing a renewal or revocation.

.PP
By default, if unspecified, \fBrequest.useSharedSecret\fP is false.

.PP
\fBNote\fP: to employ the \fBrequest.useSharedSecret\fP option,
the PKCS#10 or CRMF requests must have the \fBSubjectKeyIdentifier extension\fP\&.
(hint: \fBCRMFPopClient\fP and \fBPKCS10Client\fP should be called with the "-y" option)

.PP
If \fBrequest.useSharedSecret\fP is true, \fBrequest.privKeyId\fP must be specified.
It is crucial that the caller that employs this option has access to the private key of the certificate request.

.SS request.privKeyId
.PP
The \fBrequest.privKeyId\fP parameter is required in the following cases:
\fBrequest.useSharedSecret\fP, \fBpopLinkWitnessV2\fP, and \fBdecryptedPop\fP

.SS decryptedPop.enable, encryptedPopResponseFile, decryptedPopRequestFile
.PP
In case when the enrolling key is an encryption-only key,
the traditional POP (Proof of Possession) that employs signing of the request is not possible,
CMC provides the EncryptedPOP/DecryptedPOP  mechanism to allow the CA to challenge the client.
This mechanism requires two trips.
First trip (a CMC request without POP) would trigger the CA to generate a challenge
and encrypt the challenge with the request public key in the certificate response
(one should find the EncryptedPOP control as well as status with "failedInfo=POP required" in the CMCResponse);
while second trip from the client would contain proof that the client has decrypted the challenge
and thereby proving ownership of the private key to the enrollment request.
When preparing for the second trip, the following parameters must be present:

.PP
\fBdecryptedPop.enable\fP - set to true; default is false;

.PP
\fBencryptedPopResponseFile\fP - The input file that contains the CMCResponse from first trip;
It should contains the CMC EncryptedPop control.

.PP
\fBdecryptedPopRequestFile\fP - The output file for the CMC request which should contain the CMC DecryptedPOP control.

.PP
\fBrequest.privKeyId\fP - see descripton for \fBrequest.privKeyId\fP;
It is used to decrypt the EncryptedPop, thereby proving the possession of the private key.

.PP
Please note that the \fBPopLinkWitnessV2\fP control as well as the \fBrequest.useSharedSecret\fP directive
do not apply to EncryptedPOP/DecryptedPOP for the simple fact that
the enrollment private key is not capable of signing.

.SS revRequest.[enable, serial, reason, comment, issuer, sharedSecret]
.PP
Revocation can be done either by signing with user's own valid signing certificate,
or by authenticating with user's shared secret (see \fBwitness.sharedSecret\fP) known by the CA.

.PP
For revocation request signed with user's own valid signing certificate,
the \fBnickname\fP parameter should be a valid user signing certificate
that belongs to the same user subject as that of the certificate to be revoked
(but not necessarily the same certificate);
Also, \fBrevRequest.issuer\fP and \fBrevRequest.sharedSecret\fP are ignored,
while \fBrevRequest.serial\fP and \fBrevRequest.reason\fP must contain valid values.

.PP
For revocation by authenticating with user's shared secret, the following parameters are required:
\fBrevRequest.serial\fP, \fBrevRequest.reason\fP, \fBrevRequest.issuer\fP, \fBrevRequest.sharedSecret\fP,
while \fBnickname\fP will be ignored.

.PP
\fBrevRequest.reason\fP  can have one of the following values: \fBunspecified\fP, \fBkeyCompromise\fP, \fBcaCompromise\fP,
\fBaffiliationChanged\fP, \fBsuperseded\fP, \fBcessationOfOperation\fP, \fBcertificateHold\fP, \fBremoveFromCRL\fP\&.

.PP
\fBrevRequest.serial\fP is in Decimal.

.PP
\fBrevRequest.issuer\fP is issuer subject DN.

.PP
\fBrevRequest.invalidityDatePresent\fP is optional. \fBtrue\fP or \fBfalse\fP\&.
When true, the invalidityDate of the RevokeRequest will be set to the current time
when this tool is being run.

.PP
\fBrevRequest.comment\fP is optional.

.SH EXAMPLES
.PP
CMC requests must be submitted to the CA to be processed.
Tool supported by PKI for submitting these requests is \fBHttpClient\fP\&.

.PP
\fBNote:\fP For examples on how to use this tool, please see
Practical Usage Scenarios
\[la]https://www.dogtagpki.org/wiki/PKI_10.4_CMC_Feature_Update_(RFC5272\[ra]#Practical_Usage_Scenarios),
and their examples.

.SH SEE ALSO
.PP
\fBCMCResponse(1)\fP, \fBCMCSharedToken(1)\fP, \fBCMCRevoke(1)\fP, \fBpki(1)\fP

.SH AUTHORS
.PP
Christina Fu <cfu@redhat.com>\&.

.SH COPYRIGHT
.PP
Copyright (c) 2018 Red Hat, Inc.
This is licensed under the GNU General Public License, version 2 (GPLv2).
A copy of this license is available at http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt.