1CMCRequest(1)           PKI CMC Request Generation Tool          CMCRequest(1)
2
3
4

NAME

6       CMCRequest  - Used to generate a CMC certificate issuance or revocation
7       request.
8
9

SYNOPSIS

11       CMCRequest config-file
12
13

DESCRIPTION

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

CONFIGURATION PARAMETERS

28       The following are supported configuration parameters for the configura‐
29       tion  file.   Each  parameter  is in the format of <name>=<value> (e.g.
30       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

EXAMPLES

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              ⟨http://www.dogtagpki.org/wiki/PKI_10.4_CMC_Fea
292       ture_Update_(RFC5272)#Practical_Usage_Scenarios⟩, and their examples.
293
294

SEE ALSO

296       CMCResponse(1), CMCSharedToken(1), CMCRevoke(1), pki(1)
297
298

AUTHORS

300       Christina Fu <cfu@redhat.com>.
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)
Impressum