1CMCRequest(1) PKI CMC Request Generation Tool CMCRequest(1)
2
3
4
6 CMCRequest - Used to generate a CMC certificate issuance or revocation
7 request.
8
9
11 CMCRequest config-file
12
13
15 The Certificate Management over Cryptographic Message Syntax (CMC)
16 Request 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
19 input. The resulting CMC request can be sent to the CA via tool such
20 as HttpClient.
21
22
23 CMCRequest takes a configuration file where various configuration
24 parameters are supported.
25
26
28 The following are supported configuration parameters for the configura‐
29 tion file. Each parameter is in the format of lt;namegt;=lt;valuegt;
30 (e.g. format=pkcs10).
31
32
33 numRequests
34 Total number of PKCS10 or CRMF requests. (note: lately the CA has only
35 been tested to work with one)
36
37
38 input
39 Full path for PKCS #10 or CRMF certificate request in PEM.
40
41
42 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
46
47 format
48 Request format. Either pkcs10 or crmf.
49
50
51 output
52 Full path for the resulting CMC request in ASN.1 DER encoded format.
53
54
55 Note that this would be the input in the HttpClient configuration file
56 if it is used to submit the CMC request.
57
58
59 dbdir
60 Directory for NSS database.
61
62
63 tokenname
64 Name of crypto token where user signing certificate key can be found
65 (default is internal).
66
67
68 nickname
69 The nickname of the user certificate that corresponds to the private
70 key that is used to sign the request.
71
72
73 This parameter is ignored if useSharedSecret or identityProofV2.enable
74 is true.
75
76
77 password
78 Password to the crypto token where the signing user's certificate and
79 keys are stored.
80
81
82 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
86
87 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
91
92 In addition, the identification control is also required for
93 popLinkWitnessV2 for locating the shared secret.
94
95
96 When identification.enable is true, identification should contain a
97 user id known by the CA.
98
99
100 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
104
105 This parameter is required by the following options: identityProofV2,
106 and popLinkWitnessV2.
107
108
109 See CMCSharedToken(1) for information on usage.
110
111
112 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
118
119 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
123
124 Supported identityProofV2.hashAlg are: SHA-256, SHA-384, and SHA-512.
125
126
127 Supported identityProofV2.macAlg are: SHA-256-HMAC, SHA-384-HMAC, and
128 SHA-512-HMAC.
129
130
131 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
135
136 These parameters could be accompanied by the popLinkWitnessV2 parameter
137 set if required by the CA.
138
139
140 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
144 employing calculation of a random value with a shared secret (see wit‐
145 ness.sharedSecret) known by the CA.
146
147
148 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
152
153 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
157
158 Supported keyGenAlg are: SHA-256, SHA-384, and SHA-512.
159
160
161 Supported macAlg are: SHA-256-HMAC, SHA-384-HMAC, and SHA-512-HMAC.
162
163
164 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
169
170 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
176
177 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
182
183 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 encryp‐
188 tion-only ceritifcate, or when doing a renewal or revocation.
189
190
191 By default, if unspecified, request.useSharedSecret is false.
192
193
194 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
198
199 If request.useSharedSecret is true, request.privKeyId must be speci‐
200 fied. It is crucial that the caller that employs this option has
201 access to the private key of the certificate request.
202
203
204 request.privKeyId
205 The request.privKeyId parameter is required in the following cases:
206 request.useSharedSecret, popLinkWitnessV2, and decryptedPop
207
208
209 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
223
224 decryptedPop.enable - set to true; default is false;
225
226
227 encryptedPopResponseFile - The input file that contains the CMCResponse
228 from first trip; It should contains the CMC EncryptedPop control.
229
230
231 decryptedPopRequestFile - The output file for the CMC request which
232 should contain the CMC DecryptedPOP control.
233
234
235 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
239
240 Please note that the PopLinkWitnessV2 control as well as the
241 request.useSharedSecret directive do not apply to EncryptedPOP/Decrypt‐
242 edPOP for the simple fact that the enrollment private key is not capa‐
243 ble of signing.
244
245
246 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
251
252 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
259
260 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
263 ignored.
264
265
266 revRequest.reason can have one of the following values: unspecified,
267 keyCompromise, caCompromise, affiliationChanged, superseded, cessa‐
268 tionOfOperation, certificateHold, removeFromCRL.
269
270
271 revRequest.serial is in Decimal.
272
273
274 revRequest.issuer is issuer subject DN.
275
276
277 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
281
282 revRequest.comment is optional.
283
284
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
289
290 Note: For examples on how to use this tool, please see Practical Usage
291 Scenarios ⟨https://www.dogtagpki.org/wiki/PKI_10.4_CMC_Fea‐
292 ture_Update_(RFC5272⟩#Practical_Usage_Scenarios), and their examples.
293
294
296 CMCResponse(1), CMCSharedToken(1), CMCRevoke(1), pki(1)
297
298
300 Christina Fu lt;cfu@redhat.comgt;.
301
302
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.
307
308
309
310PKI March 14, 2018 CMCRequest(1)