1CMCRequest(1) PKI CMC Request Generation Tool CMCRequest(1)
2
6 CMCRequest - Used to generate a CMC certificate issuance or revocation
7 request.
8
11 CMCRequest config-file
12
15 The Certificate Management over Cryptographic Message Syntax (CMC) Re‐
16 quest Generation utility, CMCRequest, provides a command-line utility
17 used to generate a CMC certificate issuance or revocation request. For
18 issuance request, it requires either a PKCS#10 or CRMF request as in‐
19 put. The resulting CMC request can be sent to the CA via tool such as
20 HttpClient.
21 CMCRequest takes a configuration file where various configuration pa‐
24 rameters are supported.
25
28 The following are supported configuration parameters for the configura‐
29 tion file. Each parameter is in the format of
30 <name>=<value> (e.g. format=pkcs10).
31 numRequests
34 Total number of PKCS10 or CRMF requests. (note: lately the CA has only
35 been tested to work with one)
36 input
39 Full path for PKCS #10 or CRMF certificate request in PEM.
40 For example if PKCS10Client or CRMFPopClient are used to generate the
43 PKCS#10 or CRMF requests respectively, this value should be the value
44 of the -o option of those command line tools.
45 format
48 Request format. Either pkcs10 or crmf.
49 output
52 Full path for the resulting CMC request in ASN.1 DER encoded format.
53 Note that this would be the input in the HttpClient configuration file
56 if it is used to submit the CMC request.
57 dbdir
60 Directory for NSS database.
61 tokenname
64 Name of crypto token where user signing certificate key can be found
65 (default is internal).
66 nickname
69 The nickname of the user certificate that corresponds to the private
70 key that is used to sign the request.
71 This parameter is ignored if useSharedSecret or identityProofV2.enable
74 is true.
75 password
78 Password to the crypto token where the signing user's certificate and
79 keys are stored.
80 identification[.enable]
83 RFC 5272 allows the CA to require inclusion of the identification con‐
84 trol to accompany the identityProofV2 control in a CMC request.
85 In PKI, CA employs the identification control to assist in locating the
88 shared secret required for verification of the shared secret computed
89 in the identityProofV2.
90 In addition, the identification control is also required for
93 popLinkWitnessV2 for locating the shared secret.
94 When identification.enable is true, identification should contain a
97 user id known by the CA.
98 witness.sharedSecret
101 The witness.sharedSecret should contain a passphrase that is known by
102 the CA. One usually obtains it from the CA administrator.
103 This parameter is required by the following options: identityProofV2,
106 and popLinkWitnessV2.
107 See CMCSharedToken(1) for information on usage.
110 identityProofV2.[enable, hashAlg, macAlg]
113 Identity Proof V2 allows one to provide proof of identity without a
114 signing certificate. It does so by embedding a "witness" value that's
115 calculated from a shared secret (see witness.sharedSecret) known by the
116 CA.
117 The identityProofV2 parameter set allows a user to specify the hashing
120 algorithm as well as MAC (Message Authentication Code) algorithm used
121 to compute the value of the witness value.
122 Supported identityProofV2.hashAlg are: SHA-256, SHA-384, and SHA-512.
125 Supported identityProofV2.macAlg are: SHA-256-HMAC, SHA-384-HMAC, and
128 SHA-512-HMAC.
129 When identityProofV2.enable is true, these parameters must be accompa‐
132 nied by the identification as well as the witness.sharedSecret parame‐
133 ters.
134 These parameters could be accompanied by the popLinkWitnessV2 parameter
137 set if required by the CA.
138 popLinkWitnessV2.[enable, keyGenAlg, macAlg]
141 The POPLinkWitnessV2 control is a mechanim that links the POP (Proof of
142 Possession) to the identity, which adds more credibility to the other‐
143 wise distinct POP and Proof of Identity mechanisms. It does so by em‐
144 ploying calculation of a random value with a shared secret (see wit‐
145 ness.sharedSecret) known by the CA.
146 The POP Link Witness V2 value must be baked into the PKCS#10 or CRMF
149 requests. It is therefore crutial that the caller that employs this
150 option has access to the private key of the certificate request.
151 If popLinkWitnessV2 is used, then identification and witness.sharedSe‐
154 cret must be supplied, and the identityProofV2 parameter set is in gen‐
155 eral used.
156 Supported keyGenAlg are: SHA-256, SHA-384, and SHA-512.
159 Supported macAlg are: SHA-256-HMAC, SHA-384-HMAC, and SHA-512-HMAC.
162 request.useSharedSecret
165 true or false. If useSharedSecret is true, the CMC request will be
166 "signed" with the pairing private key of the enrollment request; and in
167 which case the nickname parameter will be ignored.
168 request.useSharedSecret is only used if a signing certificate (of the
171 agent or user herself) is not available to sign. Because the request
172 itself is not signed with a certificate (a proven identity), the proof
173 of origin (proof of identification) must be provided by some other
174 means.
175 In PKI, if request.useSharedSecret is true, it must be used in conjunc‐
178 tion with the identityProofV2 and identification parameters. And in
179 that case the Proof Of Origin is accomplished by the Shared Secret
180 (witness.sharedSecret) mechanism.
181 The request.useSharedSecret option is normally used to enroll for a
184 user's first signing certificate while auto-approval (without agent's
185 pre-approval) is preferred. In general, once a user has obtained the
186 first signing certificate, such signing certificate can be used to sign
187 (thus proving origin) and obtain other certificate such as encryption-
188 only ceritifcate, or when doing a renewal or revocation.
189 By default, if unspecified, request.useSharedSecret is false.
192 Note: to employ the request.useSharedSecret option, the PKCS#10 or CRMF
195 requests must have the SubjectKeyIdentifier extension. (hint: CRMFPop‐
196 Client and PKCS10Client should be called with the "-y" option)
197 If request.useSharedSecret is true, request.privKeyId must be speci‐
200 fied. It is crucial that the caller that employs this option has ac‐
201 cess to the private key of the certificate request.
202 request.privKeyId
205 The request.privKeyId parameter is required in the following cases: re‐
206 quest.useSharedSecret, popLinkWitnessV2, and decryptedPop
207 decryptedPop.enable, encryptedPopResponseFile, decryptedPopRequestFile
210 In case when the enrolling key is an encryption-only key, the tradi‐
211 tional POP (Proof of Possession) that employs signing of the request is
212 not possible, CMC provides the EncryptedPOP/DecryptedPOP mechanism to
213 allow the CA to challenge the client. This mechanism requires two
214 trips. First trip (a CMC request without POP) would trigger the CA to
215 generate a challenge and encrypt the challenge with the request public
216 key in the certificate response (one should find the EncryptedPOP con‐
217 trol as well as status with "failedInfo=POP required" in the CMCRe‐
218 sponse); while second trip from the client would contain proof that the
219 client has decrypted the challenge and thereby proving ownership of the
220 private key to the enrollment request. When preparing for the second
221 trip, the following parameters must be present:
222 decryptedPop.enable - set to true; default is false;
225 encryptedPopResponseFile - The input file that contains the CMCResponse
228 from first trip; It should contains the CMC EncryptedPop control.
229 decryptedPopRequestFile - The output file for the CMC request which
232 should contain the CMC DecryptedPOP control.
233 request.privKeyId - see descripton for request.privKeyId; It is used to
236 decrypt the EncryptedPop, thereby proving the possession of the private
237 key.
238 Please note that the PopLinkWitnessV2 control as well as the re‐
241 quest.useSharedSecret directive do not apply to EncryptedPOP/Decrypted‐
242 POP for the simple fact that the enrollment private key is not capable
243 of signing.
244 revRequest.[enable, serial, reason, comment, issuer, sharedSecret]
247 Revocation can be done either by signing with user's own valid signing
248 certificate, or by authenticating with user's shared secret (see wit‐
249 ness.sharedSecret) known by the CA.
250 For revocation request signed with user's own valid signing certifi‐
253 cate, the nickname parameter should be a valid user signing certificate
254 that belongs to the same user subject as that of the certificate to be
255 revoked (but not necessarily the same certificate); Also, revRe‐
256 quest.issuer and revRequest.sharedSecret are ignored, while revRe‐
257 quest.serial and revRequest.reason must contain valid values.
258 For revocation by authenticating with user's shared secret, the follow‐
261 ing parameters are required: revRequest.serial, revRequest.reason,
262 revRequest.issuer, revRequest.sharedSecret, while nickname will be ig‐
263 nored.
264 revRequest.reason can have one of the following values: unspecified,
267 keyCompromise, caCompromise, affiliationChanged, superseded, cessa‐
268 tionOfOperation, certificateHold, removeFromCRL.
269 revRequest.serial is in Decimal.
272 revRequest.issuer is issuer subject DN.
275 revRequest.invalidityDatePresent is optional. true or false. When
278 true, the invalidityDate of the RevokeRequest will be set to the cur‐
279 rent time when this tool is being run.
280 revRequest.comment is optional.
283
286 CMC requests must be submitted to the CA to be processed. Tool sup‐
287 ported by PKI for submitting these requests is HttpClient.
288 Note: For examples on how to use this tool, please see Practical Usage
291 Scenarios ⟨https://www.dogtagpki.org/wiki/PKI_10.4_CMC_Feature_Up‐
292 date_(RFC5272⟩#Practical_Usage_Scenarios), and their examples.
293
296 CMCResponse(1), CMCSharedToken(1), CMCRevoke(1), pki(1)
297
300 Christina Fu <cfu@redhat.com>.
301
304 Copyright (c) 2018 Red Hat, Inc. This is licensed under the GNU Gen‐
305 eral Public License, version 2 (GPLv2). A copy of this license is
306 available at http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt.
307PKI March 14, 2018 CMCRequest(1)