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 <CMCRequest configuration filename>
12
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 as
20 HttpClient.
21 CMCRequest takes a configuration file where various configuration
23 parametrs are supported.
24
27 The following are supported configuration parameters for the configura‐
28 tion file. Each parameter is in the format of <name>=<value> (e.g.
29 format=pkcs10).
30 numRequests
32 Total number of PKCS10 or CRMF requests. (note: lately the CA
33 has only been tested to work with one)
34 input full path for PKCS #10 or CRMF certificate request in PEM.
37 For example if PKCS10Client or CRMFPopClient are used to gener‐
39 ate the PKCS#10 or CRMF requests respectively, this value should
40 be the value of the "-o" option of those command line tools.
41 format request format. Either pkcs10 or crmf.
44 output full path for the resulting CMC request in ASN.1 DER encoded
47 format.
48 Note that this would be the input in the HttpClient configura‐
50 tion file if it is used to submit the CMC request.
51 dbdir directory for NSS database: cert8.db, key3.db and secmod.db
54 tokenname
57 name of crypto token where user signing certificate key can be
58 found (default is internal)
59 nickname
62 The nickname of the user certificate that corresponds to the
63 private key that is used to sign the request.
64 This parameter is ignored if useSharedSecret or identi‐
66 tyProofV2.enable is true.
67 password
70 password to the crypto token where the signing user's certifi‐
71 cate and keys are stored.
72 identification[.enable]
75 RFC 5272 allows the CA to require inclusion of the identifica‐
76 tion control to accompany the identityProofV2 control in a CMC
77 request.
78 In Dogtag, CA employs the identification control to assist in
80 locating the shared secret required for verification of the
81 shared secret computed in the identityProofV2.
82 In addition, the identification control is also required for
84 popLinkWitnessV2 for locating the shared secret.
85 When identification.eanble is true, identification should con‐
87 tain a user id known by the CA.
88 witness.sharedSecret
91 The witness.sharedSecret should contain a passphrase that is
92 known by the CA. One usually obtains it from the CA administra‐
93 tor.
94 This parameter is required by the following options: identi‐
96 tyProofV2, and popLinkWitnessV2.
97 See man pages for CMCSharedToken for information on usage.
99 identityProofV2.[enable, hashAlg, macAlg]
102 Identity Proof V2 allows one to provide proof of identity with‐
103 out a signing certificate. It does so by embedding a "witness"
104 value that's calculated from a shared secret (see wit‐
105 ness.sharedSecret) known by the CA.
106 The identityProofV2 parameter set allows a user to specify the
108 hashing algorithm as well as MAC (Message Authentication Code)
109 algorithm used to compute the value of the witness value.
110 Supported identityProofV2.hashAlg are: SHA-256, SHA-384, and
112 SHA-512
113 Supported identityProofV2.macAlg are: SHA-256-HMAC,
115 SHA-384-HMAC, and SHA-512-HMAC
116 When identityProofV2.eanble is true, these parameters must be
118 accompanied by the identification as well as the witness.shared‐
119 Secret parameters.
120 These parameters could be accompanied by the popLinkWitnessV2
122 parameter set if required by the CA.
123 popLinkWitnessV2.[enable, keyGenAlg, macAlg]
126 The POPLinkWitnessV2 control is a mechanim that links the POP
127 (Proof of Possession) to the identity, which adds more credibil‐
128 ity to the otherwise distinct POP and Proof of Identity mecha‐
129 nisms. It does so by employing calculation of a random value
130 with a shared secret (see witness.sharedSecret) known by the CA.
131 The POP Link Witness V2 value must be baked into the PKCS#10 or
133 CRMF requests. It is therefore crutial that the caller that
134 employs this option has access to the private key of the cer‐
135 tificate request.
136 If popLinkWitnessV2 is used, then identification and wit‐
138 ness.sharedSecret must be supplied, and the identityProofV2
139 parameter set is in general used.
140 Supported keyGenAlg are: SHA-256, SHA-384, and SHA-512
142 Supported macAlg are: SHA-256-HMAC, SHA-384-HMAC, and
144 SHA-512-HMAC
145 request.useSharedSecret
148 true or false. If useSharedSecret is true, the CMC request will
149 be "signed" with the pairing private key of the enrollment
150 request; and in which case the nickname parameter will be
151 ignored.
152 request.useSharedSecret is only used if a signing certificate
154 (of the agent or user herself) is not available to sign. Because
155 the request itself is not signed with a certificate (a proven
156 identity), the proof of origin (proof of identification) must be
157 provided by some other means.
158 In Dogtag, if request.useSharedSecret is true, it must be used
160 in conjunction with the identityProofV2 and identification
161 parameters. And in that case the Proof Of Origin is accom‐
162 plished by the Shared Secret (witness.sharedSecret) mechanism.
163 The request.useSharedSecret option is normally used to enroll
165 for a user's first signing certificate while auto-approval
166 (without agent's pre-approval) is preferred. In general, once a
167 user has obtained the first signing certificate, such signing
168 certificate can be used to sign (thus proving origin) and obtain
169 other certificate such as encryption-only ceritifcate, or when
170 doing a renewal or revocation.
171 By default, if unspecified, request.useSharedSecret is false.
173 Note: to employ the request.useSharedSecret option, the PKCS#10
175 or CRMF requests must have the SubjectKeyIdentifier extension.
176 (hint: CRMFPopClient and PKCS10Client should be called with the
177 "-y" option)
178 If request.useSharedSecret is true, request.privKeyId must be
180 specified. It is crutial that the caller that employs this
181 option has access to the private key of the certificate request.
182 request.privKeyId
185 The request.privKeyId parameter is required in the following
186 cases:
187 request.useSharedSecret, popLinkWitnessV2, and decryptedPop
189 decryptedPop.enable, encryptedPopResponseFile, decryptedPopRequestFile
192 In case when the enrolling key is an encryption-only key, the
193 traditional POP (Proof of Possession) that employs signing of
194 the request is not possible, CMC provides the Encrypted‐
195 POP/DecryptedPOP mechanism to allow the CA to challenge the
196 client. This mechanism requires two trips. Frist trip (a CMC
197 request without POP) would trigger the CA to generate a chal‐
198 lenge and encrypt the challenge with the request public key in
199 the certificate response (one should find the EncryptedPOP con‐
200 trol as well as status with "failedInfo=POP required" in the
201 CMCResponse); while second trip from the client would contain
202 proof that the client has decrypted the challenge and thereby
203 proving ownership of the private key to the enrollment request.
204 When preparing for the second trip, the following parameters
205 must be present:
206 decryptedPop.enable - set to true; default is false;
208 encryptedPopResponseFile - the input file that contains the
210 CMCResponse from first trip; It should contains the CMC Encrypt‐
211 edPop control.
212 decryptedPopRequestFile - the output file for the CMC request
214 which should contain the CMC DecryptedPOP control.
215 request.privKeyId - see descripton for request.privKeyId; It is
217 used to decrypt the EncryptedPop, thereby proving the possession
218 of the private key.
219 Please note that the PopLinkWitnessV2 control as well as the
221 request.useSharedSecret directive do not apply to Encrypted‐
222 POP/DecryptedPOP for the simple fact that the enrollment private
223 key is not capable of signing.
224 revRequest.[enable, serial, reason, comment, issuer, sharedSecret]
227 Revocation can be done either by signing with user's own valid
228 signing certificate, or by authenticating with user's shared
229 secret (see witness.sharedSecret) known by the CA.
230 For revocation request signed with user's own valid signing cer‐
232 tificate, the nicname parameter should be a valid user signing
233 certificate that belongs to the same user subject as that of the
234 certificate to be revoked (but not necessarily the same certifi‐
235 cate); Also, revRequest.issuer and revRequest.sharedSecret are
236 ignored, while revRequest.serial and revRequest.reason must con‐
237 tain valid values.
238 For revocation by authenticating with user's shared secret, the
240 following parameters are required: revRequest.serial, revRe‐
241 quest.reason, revRequest.issuer, revRequest.sharedSecret, while
242 nickname will be ignored.
243 revRequest.reason can have one of the following values: unspeci‐
245 fied, keyCompromise, caCompromise, affiliationChanged, super‐
246 seded, cessationOfOperation, certificateHold, removeFromCRL.
247 revRequest.serial is in Decimal.
249 revRequest.issuer is issuer subject DN.
251 revRequest.invalidityDatePresent is optional. true or false.
253 When true, the invalidityDate of the RevokeRequest will be set
254 to the current time when this tool is being run.
255 revRequest.comment is optional.
257
260 CMC requests must be submitted to the CA to be processed. Tool sup‐
261 ported by Dogtag for submitting these requests is HttpClient.
262 Note: For examples on how to use this tool, please see http://www.dog‐
264 tagpki.org/wiki/PKI_10.4_CMC_Feature_Update_(RFC5272)#Practi‐
265 cal_Usage_Scenarios for Practical Usage Scenarios, and their examples.
266
269 Christina Fu <cfu@redhat.com>.
270
273 Copyright (c) 2018 Red Hat, Inc. This is licensed under the GNU General
274 Public License, version 2 (GPLv2). A copy of this license is available
275 at http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt.
276
279 CMCResponse(1),[22mCMCSharedToken(1),CMCRevoke(1),[22mpki(1)
280version 10.5 March 14, 2018 CMCRequest(1)