security/nss/lib/crmf/cmmf.h@6474c204b198
security/nss/lib/crmf/cmmf.h
Wed, 31 Dec 2014 06:09:35 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Wed, 31 Dec 2014 06:09:35 +0100
- changeset 0
- 6474c204b198
- permissions
- -rw-r--r--
Cloned upstream origin tor-browser at tor-browser-31.3.0esr-4.5-1-build1
revision ID fc1c9ff7c1b2defdbc039f12214767608f46423f for hacking purpose.
1 /* -*- Mode: C; tab-width: 8 -*-*/
2 /* This Source Code Form is subject to the terms of the Mozilla Public
3 * License, v. 2.0. If a copy of the MPL was not distributed with this
4 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
6 #ifndef _CMMF_H_
7 #define _CMMF_H_
8 /*
9 * These are the functions exported by the security library for
10 * implementing Certificate Management Message Formats (CMMF).
11 *
12 * This API is designed against July 1998 CMMF draft. Please read this
13 * draft before trying to use this API in an application that use CMMF.
14 */
15 #include "seccomon.h"
16 #include "cmmft.h"
17 #include "crmf.h"
19 SEC_BEGIN_PROTOS
21 /******************* Creation Functions *************************/
23 /*
24 * FUNCTION: CMMF_CreateCertRepContent
25 * INPUTS:
26 * NONE
27 * NOTES:
28 * This function will create an empty CMMFCertRepContent Structure.
29 * The client of the library must set the CMMFCertResponses.
30 * Call CMMF_CertRepContentSetCertResponse to accomplish this task.
31 * If the client of the library also wants to include the chain of
32 * CA certs required to make the certificates in CMMFCertResponse valid,
33 * then the user must also set the caPubs field of CMMFCertRepContent.
34 * Call CMMF_CertRepContentSetCAPubs to accomplish this. After setting
35 * the desired fields, the user can then call CMMF_EncodeCertRepContent
36 * to DER-encode the CertRepContent.
37 * RETURN:
38 * A pointer to the CMMFCertRepContent. A NULL return value indicates
39 * an error in allocating memory or failure to initialize the structure.
40 */
41 extern CMMFCertRepContent* CMMF_CreateCertRepContent(void);
43 /*
44 * FUNCTION: CMMF_CreateCertRepContentFromDER
45 * INPUTS
46 * db
47 * The certificate database where the certificates will be placed.
48 * The certificates will be placed in the temporary database associated
49 * with the handle.
50 * buf
51 * A buffer to the DER-encoded CMMFCertRepContent
52 * len
53 * The length in bytes of the buffer 'buf'
54 * NOTES:
55 * This function passes the buffer to the ASN1 decoder and creates a
56 * CMMFCertRepContent structure. The user must call
57 * CMMF_DestroyCertRepContent after the return value is no longer needed.
58 *
59 * RETURN:
60 * A pointer to the CMMFCertRepContent structure. A NULL return
61 * value indicates the library was unable to parse the DER.
62 */
63 extern CMMFCertRepContent*
64 CMMF_CreateCertRepContentFromDER(CERTCertDBHandle *db,
65 const char *buf,
66 long len);
68 /*
69 * FUNCTION: CMMF_CreateCertResponse
70 * INPUTS:
71 * inCertReqId
72 * The Certificate Request Id this response is for.
73 * NOTES:
74 * This creates a CMMFCertResponse. This response should correspond
75 * to a request that was received via CRMF. From the CRMF message you
76 * can get the Request Id to pass in as inCertReqId, in essence binding
77 * a CMRFCertRequest message to the CMMFCertResponse created by this
78 * function. If no requuest id is associated with the response to create
79 * then the user should pass in -1 for 'inCertReqId'.
80 *
81 * RETURN:
82 * A pointer to the new CMMFCertResponse corresponding to the request id
83 * passed in. A NULL return value indicates an error while trying to
84 * create the CMMFCertResponse.
85 */
86 extern CMMFCertResponse* CMMF_CreateCertResponse(long inCertReqId);
88 /*
89 * FUNCTION: CMMF_CreateKeyRecRepContent
90 * INPUTS:
91 * NONE
92 * NOTES:
93 * This function creates a new empty CMMFKeyRecRepContent structure.
94 * At the very minimum, the user must call
95 * CMMF_KeyRecRepContentSetPKIStatusInfoStatus field to have an
96 * encodable structure. Depending on what the response is, the user may
97 * have to set other fields as well to properly build up the structure so
98 * that it can be encoded. Refer to the CMMF draft for how to properly
99 * set up a CMMFKeyRecRepContent. This is the structure that an RA returns
100 * to an end entity when doing key recovery.
102 * The user must call CMMF_DestroyKeyRecRepContent when the return value
103 * is no longer needed.
104 * RETURN:
105 * A pointer to the empty CMMFKeyRecRepContent. A return value of NULL
106 * indicates an error in allocating memory or initializing the structure.
107 */
108 extern CMMFKeyRecRepContent *CMMF_CreateKeyRecRepContent(void);
110 /*
111 * FUNCTION: CMMF_CreateKeyRecRepContentFromDER
112 * INPUTS:
113 * db
114 * The handle for the certificate database where the decoded
115 * certificates will be placed. The decoded certificates will
116 * be placed in the temporary database associated with the
117 * handle.
118 * buf
119 * A buffer contatining the DER-encoded CMMFKeyRecRepContent
120 * len
121 * The length in bytes of the buffer 'buf'
122 * NOTES
123 * This function passes the buffer to the ASN1 decoder and creates a
124 * CMMFKeyRecRepContent structure.
125 *
126 * RETURN:
127 * A pointer to the CMMFKeyRecRepContent structure. A NULL return
128 * value indicates the library was unable to parse the DER.
129 */
130 extern CMMFKeyRecRepContent*
131 CMMF_CreateKeyRecRepContentFromDER(CERTCertDBHandle *db,
132 const char *buf,
133 long len);
135 /*
136 * FUNCTION: CMMF_CreatePOPODecKeyChallContent
137 * INPUTS:
138 * NONE
139 * NOTES:
140 * This function creates an empty CMMFPOPODecKeyChallContent. The user
141 * must add the challenges individually specifying the random number to
142 * be used and the public key to be used when creating each individual
143 * challenge. User can accomplish this by calling the function
144 * CMMF_POPODecKeyChallContentSetNextChallenge.
145 * RETURN:
146 * A pointer to a CMMFPOPODecKeyChallContent structure. Ther user can
147 * then call CMMF_EncodePOPODecKeyChallContent passing in the return
148 * value from this function after setting all of the challenges. A
149 * return value of NULL indicates an error while creating the
150 * CMMFPOPODecKeyChallContent structure.
151 */
152 extern CMMFPOPODecKeyChallContent*
153 CMMF_CreatePOPODecKeyChallContent(void);
155 /*
156 * FUNCTION: CMMF_CreatePOPODecKeyChallContentFromDER
157 * INPUTS
158 * buf
159 * A buffer containing the DER-encoded CMMFPOPODecKeyChallContent
160 * len
161 * The length in bytes of the buffer 'buf'
162 * NOTES:
163 * This function passes the buffer to the ASN1 decoder and creates a
164 * CMMFPOPODecKeyChallContent structure.
165 *
166 * RETURN:
167 * A pointer to the CMMFPOPODecKeyChallContent structure. A NULL return
168 * value indicates the library was unable to parse the DER.
169 */
170 extern CMMFPOPODecKeyChallContent*
171 CMMF_CreatePOPODecKeyChallContentFromDER(const char *buf, long len);
173 /*
174 * FUNCTION: CMMF_CreatePOPODecKeyRespContentFromDER
175 * INPUTS:
176 * buf
177 * A buffer contatining the DER-encoded CMMFPOPODecKeyRespContent
178 * len
179 * The length in bytes of the buffer 'buf'
180 * NOTES
181 * This function passes the buffer to the ASN1 decoder and creates a
182 * CMMFPOPODecKeyRespContent structure.
183 *
184 * RETURN:
185 * A pointer to the CMMFPOPODecKeyRespContent structure. A NULL return
186 * value indicates the library was unable to parse the DER.
187 */
188 extern CMMFPOPODecKeyRespContent*
189 CMMF_CreatePOPODecKeyRespContentFromDER(const char *buf, long len);
191 /************************** Set Functions *************************/
193 /*
194 * FUNCTION: CMMF_CertRepContentSetCertResponses
195 * INPUTS:
196 * inCertRepContent
197 * The CMMFCertRepContent to operate on.
198 * inCertResponses
199 * An array of pointers to CMMFCertResponse structures to
200 * add to the CMMFCertRepContent structure.
201 * inNumResponses
202 * The length of the array 'inCertResponses'
203 * NOTES:
204 * This function will add the CMMFCertResponse structure to the
205 * CMMFCertRepContent passed in. The CMMFCertResponse field of
206 * CMMFCertRepContent is required, so the client must call this function
207 * before calling CMMF_EncodeCertRepContent. If the user calls
208 * CMMF_EncodeCertRepContent before calling this function,
209 * CMMF_EncodeCertRepContent will fail.
210 *
211 * RETURN:
212 * SECSuccess if adding the CMMFCertResponses to the CMMFCertRepContent
213 * structure was successful. Any other return value indicates an error
214 * while trying to add the CMMFCertResponses.
215 */
216 extern SECStatus
217 CMMF_CertRepContentSetCertResponses(CMMFCertRepContent *inCertRepContent,
218 CMMFCertResponse **inCertResponses,
219 int inNumResponses);
221 /*
222 * FUNCTION: CMMF_CertRepContentSetCAPubs
223 * INPUTS:
224 * inCertRepContent
225 * The CMMFCertRepContent to operate on.
226 * inCAPubs
227 * The certificate list which makes up the chain of CA certificates
228 * required to make the issued cert valid.
229 * NOTES:
230 * This function will set the the certificates in the CA chain as part
231 * of the CMMFCertRepContent. This field is an optional member of the
232 * CMMFCertRepContent structure, so the client is not required to call
233 * this function before calling CMMF_EncodeCertRepContent.
234 *
235 * RETURN:
236 * SECSuccess if adding the 'inCAPubs' to the CERTRepContent was successful.
237 * Any other return value indicates an error while adding 'inCAPubs' to the
238 * CMMFCertRepContent structure.
239 *
240 */
241 extern SECStatus
242 CMMF_CertRepContentSetCAPubs (CMMFCertRepContent *inCertRepContent,
243 CERTCertList *inCAPubs);
245 /*
246 * FUNCTION: CMMF_CertResponseSetPKIStatusInfoStatus
247 * INPUTS:
248 * inCertResp
249 * The CMMFCertResponse to operate on.
250 * inPKIStatus
251 * The value to set for the PKIStatusInfo.status field.
252 * NOTES:
253 * This function will set the CertResponse.status.status field of
254 * the CMMFCertResponse structure. (View the definition of CertResponse
255 * in the CMMF draft to see exactly which value this talks about.) This
256 * field is a required member of the structure, so the user must call this
257 * function in order to have a CMMFCertResponse that can be encoded.
258 *
259 * RETURN:
260 * SECSuccess if setting the field with the passed in value was successful.
261 * Any other return value indicates an error while trying to set the field.
262 */
263 extern SECStatus
264 CMMF_CertResponseSetPKIStatusInfoStatus (CMMFCertResponse *inCertResp,
265 CMMFPKIStatus inPKIStatus);
267 /*
268 * FUNCTION: CMMF_CertResponseSetCertificate
269 * INPUTS:
270 * inCertResp
271 * The CMMFCertResponse to operate on.
272 * inCertificate
273 * The certificate to add to the
274 * CertResponse.CertifiedKeyPair.certOrEncCert.certificate field.
275 * NOTES:
276 * This function will take the certificate and make it a member of the
277 * CMMFCertResponse. The certificate should be the actual certificate
278 * being issued via the response.
279 *
280 * RETURN:
281 * SECSuccess if adding the certificate to the response was successful.
282 * Any other return value indicates an error in adding the certificate to
283 * the CertResponse.
284 */
285 extern SECStatus
286 CMMF_CertResponseSetCertificate (CMMFCertResponse *inCertResp,
287 CERTCertificate *inCertificate);
289 /*
290 * FUNCTION: CMMF_KeyRecRepContentSetPKIStatusInfoStatus
291 * INPUTS:
292 * inKeyRecRep
293 * The CMMFKeyRecRepContent to operate on.
294 * inPKIStatus
295 * The value to set the PKIStatusInfo.status field to.
296 * NOTES:
297 * This function sets the only required field for the KeyRecRepContent.
298 * In most cases, the user will set this field and other fields of the
299 * structure to properly create the CMMFKeyRecRepContent structure.
300 * Refer to the CMMF draft to see which fields need to be set in order
301 * to create the desired CMMFKeyRecRepContent.
302 *
303 * RETURN:
304 * SECSuccess if setting the PKIStatusInfo.status field was successful.
305 * Any other return value indicates an error in setting the field.
306 */
307 extern SECStatus
308 CMMF_KeyRecRepContentSetPKIStatusInfoStatus(CMMFKeyRecRepContent *inKeyRecRep,
309 CMMFPKIStatus inPKIStatus);
311 /*
312 * FUNCTION: CMMF_KeyRecRepContentSetNewSignCert
313 * INPUTS:
314 * inKeyRecRep
315 * The CMMFKeyRecRepContent to operate on.
316 * inNewSignCert
317 * The new signing cert to add to the CMMFKeyRecRepContent structure.
318 * NOTES:
319 * This function sets the new signeing cert in the CMMFKeyRecRepContent
320 * structure.
321 *
322 * RETURN:
323 * SECSuccess if setting the new signing cert was successful. Any other
324 * return value indicates an error occurred while trying to add the
325 * new signing certificate.
326 */
327 extern SECStatus
328 CMMF_KeyRecRepContentSetNewSignCert(CMMFKeyRecRepContent *inKeyRecRep,
329 CERTCertificate *inNewSignCert);
331 /*
332 * FUNCTION: CMMF_KeyRecRepContentSetCACerts
333 * INPUTS:
334 * inKeyRecRep
335 * The CMMFKeyRecRepContent to operate on.
336 * inCACerts
337 * The list of CA certificates required to construct a valid
338 * certificate chain with the certificates that will be returned
339 * to the end user via this KeyRecRepContent.
340 * NOTES:
341 * This function sets the caCerts that are required to form a chain with the
342 * end entity certificates that are being re-issued in this
343 * CMMFKeyRecRepContent structure.
344 *
345 * RETURN:
346 * SECSuccess if adding the caCerts was successful. Any other return value
347 * indicates an error while tring to add the caCerts.
348 */
349 extern SECStatus
350 CMMF_KeyRecRepContentSetCACerts(CMMFKeyRecRepContent *inKeyRecRep,
351 CERTCertList *inCACerts);
353 /*
354 * FUNCTION: CMMF_KeyRecRepContentSetCertifiedKeyPair
355 * INPUTS:
356 * inKeyRecRep
357 * The CMMFKeyRecRepContent to operate on.
358 * inCert
359 * The certificate to add to the CMMFKeyRecRepContent structure.
360 * inPrivKey
361 * The private key associated with the certificate above passed in.
362 * inPubKey
363 * The public key to use for wrapping the private key.
364 * NOTES:
365 * This function adds another certificate-key pair to the
366 * CMMFKeyRecRepcontent structure. There may be more than one
367 * certificate-key pair in the structure, so the user must call this
368 * function multiple times to add more than one cert-key pair.
369 *
370 * RETURN:
371 * SECSuccess if adding the certified key pair was successful. Any other
372 * return value indicates an error in adding certified key pair to
373 * CMMFKeyRecRepContent structure.
374 */
375 extern SECStatus
376 CMMF_KeyRecRepContentSetCertifiedKeyPair(CMMFKeyRecRepContent *inKeyRecRep,
377 CERTCertificate *inCert,
378 SECKEYPrivateKey *inPrivKey,
379 SECKEYPublicKey *inPubKey);
381 /*
382 * FUNCTION: CMMF_POPODecKeyChallContentSetNextChallenge
383 * INPUTS:
384 * inDecKeyChall
385 * The CMMFPOPODecKeyChallContent to operate on.
386 * inRandom
387 * The random number to use when generating the challenge,
388 * inSender
389 * The GeneralName representation of the sender of the challenge.
390 * inPubKey
391 * The public key to use when encrypting the challenge.
392 * passwdArg
393 * This value will be passed to the function used for getting a
394 * password. The password for getting a password should be registered
395 * by calling PK11_SetPasswordFunc before this function is called.
396 * If no password callback is registered and the library needs to
397 * authenticate to the slot for any reason, this function will fail.
398 * NOTES:
399 * This function adds a challenge to the end of the list of challenges
400 * contained by 'inDecKeyChall'. Refer to the CMMF draft on how the
401 * the random number passed in and the sender's GeneralName are used
402 * to generate the challenge and witness fields of the challenge. This
403 * library will use SHA1 as the one-way function for generating the
404 * witess field of the challenge.
405 *
406 * RETURN:
407 * SECSuccess if generating the challenge and adding to the end of list
408 * of challenges was successful. Any other return value indicates an error
409 * while trying to generate the challenge.
410 */
411 extern SECStatus
412 CMMF_POPODecKeyChallContentSetNextChallenge
413 (CMMFPOPODecKeyChallContent *inDecKeyChall,
414 long inRandom,
415 CERTGeneralName *inSender,
416 SECKEYPublicKey *inPubKey,
417 void *passwdArg);
420 /************************** Encoding Functions *************************/
422 /*
423 * FUNCTION: CMMF_EncodeCertRepContent
424 * INPUTS:
425 * inCertRepContent
426 * The CMMFCertRepContent to DER-encode.
427 * inCallback
428 * A callback function that the ASN1 encoder will call whenever it
429 * wants to write out DER-encoded bytes. Look at the defintion of
430 * CRMFEncoderOutputCallback in crmft.h for a description of the
431 * parameters to the function.
432 * inArg
433 * An opaque pointer to a user-supplied argument that will be passed
434 * to the callback funtion whenever the function is called.
435 * NOTES:
436 * The CMMF library will use the same DER-encoding scheme as the CRMF
437 * library. In other words, when reading CRMF comments that pertain to
438 * encoding, those comments apply to the CMMF libray as well.
439 * The callback function will be called multiple times, each time supplying
440 * the next chunk of DER-encoded bytes. The user must concatenate the
441 * output of each successive call to the callback in order to get the
442 * entire DER-encoded CMMFCertRepContent structure.
443 *
444 * RETURN:
445 * SECSuccess if encoding the CMMFCertRepContent was successful. Any
446 * other return value indicates an error while decoding the structure.
447 */
448 extern SECStatus
449 CMMF_EncodeCertRepContent (CMMFCertRepContent *inCertRepContent,
450 CRMFEncoderOutputCallback inCallback,
451 void *inArg);
453 /*
454 * FUNCTION: CMMF_EncodeKeyRecRepContent
455 * INPUTS:
456 * inKeyRecRep
457 * The CMMFKeyRepContent to DER-encode.
458 * inCallback
459 * A callback function that the ASN1 encoder will call whenever it
460 * wants to write out DER-encoded bytes. Look at the defintion of
461 * CRMFEncoderOutputCallback in crmft.h for a description of the
462 * parameters to the function.
463 * inArg
464 * An opaque pointer to a user-supplied argument that will be passed
465 * to the callback funtion whenever the function is called.
466 * NOTES:
467 * The CMMF library will use the same DER-encoding scheme as the CRMF
468 * library. In other words, when reading CRMF comments that pertain to
469 * encoding, those comments apply to the CMMF libray as well.
470 * The callback function will be called multiple times, each time supplying
471 * the next chunk of DER-encoded bytes. The user must concatenate the
472 * output of each successive call to the callback in order to get the
473 * entire DER-encoded CMMFCertRepContent structure.
474 *
475 * RETURN:
476 * SECSuccess if encoding the CMMFKeyRecRepContent was successful. Any
477 * other return value indicates an error while decoding the structure.
478 */
479 extern SECStatus
480 CMMF_EncodeKeyRecRepContent(CMMFKeyRecRepContent *inKeyRecRep,
481 CRMFEncoderOutputCallback inCallback,
482 void *inArg);
484 /*
485 * FUNCTION: CMMF_EncodePOPODecKeyChallContent
486 * INPUTS:
487 * inDecKeyChall
488 * The CMMFDecKeyChallContent to operate on.
489 * inCallback
490 * A callback function that the ASN1 encoder will call whenever it
491 * wants to write out DER-encoded bytes. Look at the defintion of
492 * CRMFEncoderOutputCallback in crmft.h for a description of the
493 * parameters to the function.
494 * inArg
495 * An opaque pointer to a user-supplied argument that will be passed
496 * to the callback function whenever the function is called.
497 * NOTES:
498 * The CMMF library will use the same DER-encoding scheme as the CRMF
499 * library. In other words, when reading CRMF comments that pertain to
500 * encoding, those comments apply to the CMMF libray as well.
501 * The callback function will be called multiple times, each time supplying
502 * the next chunk of DER-encoded bytes. The user must concatenate the
503 * output of each successive call to the callback in order to get the
504 * entire DER-encoded CMMFCertRepContent structure.
505 * The DER will be an encoding of the type POPODecKeyChallContents, which
506 * is just a sequence of challenges.
507 *
508 * RETURN:
509 * SECSuccess if encoding was successful. Any other return value indicates
510 * an error in trying to encode the Challenges.
511 */
512 extern SECStatus
513 CMMF_EncodePOPODecKeyChallContent(CMMFPOPODecKeyChallContent *inDecKeyChall,
514 CRMFEncoderOutputCallback inCallback,
515 void *inArg);
517 /*
518 * FUNCTION: CMMF_EncodePOPODecKeyRespContent
519 * INPUTS:
520 * inDecodedRand
521 * An array of integers to encode as the responses to
522 * CMMFPOPODecKeyChallContent. The integers must be in the same order
523 * as the challenges extracted from CMMFPOPODecKeyChallContent.
524 * inNumRand
525 * The number of random integers contained in the array 'inDecodedRand'
526 * inCallback
527 * A callback function that the ASN1 encoder will call whenever it
528 * wants to write out DER-encoded bytes. Look at the defintion of
529 * CRMFEncoderOutputCallback in crmft.h for a description of the
530 * parameters to the function.
531 * inArg
532 * An opaque pointer to a user-supplied argument that will be passed
533 * to the callback funtion whenever the function is called.
534 * NOTES:
535 * The CMMF library will use the same DER-encoding scheme as the CRMF
536 * library. In other words, when reading CRMF comments that pertain to
537 * encoding, those comments apply to the CMMF libray as well.
538 * The callback function will be called multiple times, each time supplying
539 * the next chunk of DER-encoded bytes. The user must concatenate the
540 * output of each successive call to the callback in order to get the
541 * entire DER-encoded POPODecKeyRespContent.
542 *
543 * RETURN:
544 * SECSuccess if encoding was successful. Any other return value indicates
545 * an error in trying to encode the Challenges.
546 */
547 extern SECStatus
548 CMMF_EncodePOPODecKeyRespContent(long *inDecodedRand,
549 int inNumRand,
550 CRMFEncoderOutputCallback inCallback,
551 void *inArg);
553 /*************** Accessor function ***********************************/
555 /*
556 * FUNCTION: CMMF_CertRepContentGetCAPubs
557 * INPUTS:
558 * inCertRepContent
559 * The CMMFCertRepContent to extract the caPubs from.
560 * NOTES:
561 * This function will return a copy of the list of certificates that
562 * make up the chain of CA's required to make the cert issued valid.
563 * The user must call CERT_DestroyCertList on the return value when
564 * done using the return value.
565 *
566 * Only call this function on a CertRepContent that has been decoded.
567 * The client must call CERT_DestroyCertList when the certificate list
568 * is no longer needed.
569 *
570 * The certs in the list will not be in the temporary database. In order
571 * to make these certificates a part of the permanent CA internal database,
572 * the user must collect the der for all of these certs and call
573 * CERT_ImportCAChain. Afterwards the certs will be part of the permanent
574 * database.
575 *
576 * RETURN:
577 * A pointer to the CERTCertList representing the CA chain associated
578 * with the issued cert. A NULL return value indicates that no CA Pubs
579 * were available in the CMMFCertRepContent structure.
580 */
581 extern CERTCertList*
582 CMMF_CertRepContentGetCAPubs (CMMFCertRepContent *inCertRepContent);
585 /*
586 * FUNCTION: CMMF_CertRepContentGetNumResponses
587 * INPUTS:
588 * inCertRepContent
589 * The CMMFCertRepContent to operate on.
590 * NOTES:
591 * This function will return the number of CertResponses that are contained
592 * by the CMMFCertRepContent passed in.
593 *
594 * RETURN:
595 * The number of CMMFCertResponses contained in the structure passed in.
596 */
597 extern int
598 CMMF_CertRepContentGetNumResponses (CMMFCertRepContent *inCertRepContent);
600 /*
601 * FUNCTION: CMMF_CertRepContentGetResponseAtIndex
602 * INPUTS:
603 * inCertRepContent
604 * The CMMFCertRepContent to operate on.
605 * inIndex
606 * The index of the CMMFCertResponse the user wants a copy of.
607 * NOTES:
608 * This function creates a copy of the CMMFCertResponse at the index
609 * corresponding to the parameter 'inIndex'. Indexing is done like a
610 * traditional C array, ie the valid indexes are (0...numResponses-1).
611 * The user must call CMMF_DestroyCertResponse after the return value is
612 * no longer needed.
613 *
614 * RETURN:
615 * A pointer to the CMMFCertResponse at the index corresponding to
616 * 'inIndex'. A return value of NULL indicates an error in copying
617 * the CMMFCertResponse.
618 */
619 extern CMMFCertResponse*
620 CMMF_CertRepContentGetResponseAtIndex (CMMFCertRepContent *inCertRepContent,
621 int inIndex);
623 /*
624 * FUNCTION: CMMF_CertResponseGetCertReqId
625 * INPUTS:
626 * inCertResp
627 * The CMMFCertResponse to operate on.
628 * NOTES:
629 * This function returns the CertResponse.certReqId from the
630 * CMMFCertResponse structure passed in. If the return value is -1, that
631 * means there is no associated certificate request with the CertResponse.
632 * RETURN:
633 * A long representing the id of the certificate request this
634 * CMMFCertResponse corresponds to. A return value of -1 indicates an
635 * error in extracting the value of the integer.
636 */
637 extern long CMMF_CertResponseGetCertReqId(CMMFCertResponse *inCertResp);
639 /*
640 * FUNCTION: CMMF_CertResponseGetPKIStatusInfoStatus
641 * INPUTS:
642 * inCertResp
643 * The CMMFCertResponse to operate on.
644 * NOTES:
645 * This function returns the CertResponse.status.status field of the
646 * CMMFCertResponse structure.
647 *
648 * RETURN:
649 * The enumerated value corresponding to the PKIStatus defined in the CMMF
650 * draft. See the CMMF draft for the definition of PKIStatus. See crmft.h
651 * for the definition of CMMFPKIStatus.
652 */
653 extern CMMFPKIStatus
654 CMMF_CertResponseGetPKIStatusInfoStatus(CMMFCertResponse *inCertResp);
656 /*
657 * FUNCTION: CMMF_CertResponseGetCertificate
658 * INPUTS:
659 * inCertResp
660 * The Certificate Response to operate on.
661 * inCertdb
662 * This is the certificate database where the function will place the
663 * newly issued certificate.
664 * NOTES:
665 * This function retrieves the CertResponse.certifiedKeyPair.certificate
666 * from the CMMFCertResponse. The user will get a copy of that certificate
667 * so the user must call CERT_DestroyCertificate when the return value is
668 * no longer needed. The certificate returned will be in the temporary
669 * certificate database.
670 *
671 * RETURN:
672 * A pointer to a copy of the certificate contained within the
673 * CMMFCertResponse. A return value of NULL indicates an error while trying
674 * to make a copy of the certificate.
675 */
676 extern CERTCertificate*
677 CMMF_CertResponseGetCertificate(CMMFCertResponse *inCertResp,
678 CERTCertDBHandle *inCertdb);
680 /*
681 * FUNCTION: CMMF_KeyRecRepContentGetPKIStatusInfoStatus
682 * INPUTS:
683 * inKeyRecRep
684 * The CMMFKeyRecRepContent structure to operate on.
685 * NOTES:
686 * This function retrieves the KeyRecRepContent.status.status field of
687 * the CMMFKeyRecRepContent structure.
688 * RETURN:
689 * The CMMFPKIStatus corresponding to the value held in the
690 * CMMFKeyRecRepContent structure.
691 */
692 extern CMMFPKIStatus
693 CMMF_KeyRecRepContentGetPKIStatusInfoStatus(CMMFKeyRecRepContent *inKeyRecRep);
695 /*
696 * FUNCTION: CMMF_KeyRecRepContentGetNewSignCert
697 * INPUTS:
698 * inKeyRecRep
699 * The CMMFKeyRecRepContent to operate on.
700 * NOTES:
701 * This function retrieves the KeyRecRepContent.newSignCert field of the
702 * CMMFKeyRecRepContent structure. The user must call
703 * CERT_DestroyCertificate when the return value is no longer needed. The
704 * returned certificate will be in the temporary database. The user
705 * must then place the certificate permanently in whatever token the
706 * user determines is the proper destination. A return value of NULL
707 * indicates the newSigCert field was not present.
708 */
709 extern CERTCertificate*
710 CMMF_KeyRecRepContentGetNewSignCert(CMMFKeyRecRepContent *inKeyRecRep);
712 /*
713 * FUNCTION: CMMF_KeyRecRepContentGetCACerts
714 * INPUTS:
715 * inKeyRecRep
716 * The CMMFKeyRecRepContent to operate on.
717 * NOTES:
718 * This function returns a CERTCertList which contains all of the
719 * certficates that are in the sequence KeyRecRepContent.caCerts
720 * User must call CERT_DestroyCertList when the return value is no longer
721 * needed. All of these certificates will be placed in the tempoaray
722 * database.
723 *
724 * RETURN:
725 * A pointer to the list of caCerts contained in the CMMFKeyRecRepContent
726 * structure. A return value of NULL indicates the library was not able to
727 * make a copy of the certifcates. This may be because there are no caCerts
728 * included in the CMMFKeyRecRepContent strucure or an internal error. Call
729 * CMMF_KeyRecRepContentHasCACerts to find out if there are any caCerts
730 * included in 'inKeyRecRep'.
731 */
732 extern CERTCertList*
733 CMMF_KeyRecRepContentGetCACerts(CMMFKeyRecRepContent *inKeyRecRep);
735 /*
736 * FUNCTION: CMMF_KeyRecRepContentGetNumKeyPairs
737 * INPUTS:
738 * inKeyRecRep
739 * The CMMFKeyRecRepContent to operate on.
740 * RETURN:
741 * This function returns the number of CMMFCertifiedKeyPair structures that
742 * that are stored in the KeyRecRepContent structure.
743 */
744 extern int
745 CMMF_KeyRecRepContentGetNumKeyPairs(CMMFKeyRecRepContent *inKeyRecRep);
747 /*
748 * FUNCTION: CMMF_KeyRecRepContentGetCertKeyAtIndex
749 * INPUTS:
750 * inKeyRecRepContent
751 * The CMMFKeyRecRepContent to operate on.
752 * inIndex
753 * The index of the desired CMMFCertifiedKeyPair
754 * NOTES:
755 * This function retrieves the CMMFCertifiedKeyPair structure at the index
756 * 'inIndex'. Valid indexes are 0...(numKeyPairs-1) The user must call
757 * CMMF_DestroyCertifiedKeyPair when the return value is no longer needed.
758 *
759 * RETURN:
760 * A pointer to the Certified Key Pair at the desired index. A return value
761 * of NULL indicates an error in extracting the Certified Key Pair at the
762 * desired index.
763 */
764 extern CMMFCertifiedKeyPair*
765 CMMF_KeyRecRepContentGetCertKeyAtIndex(CMMFKeyRecRepContent *inKeyRecRep,
766 int inIndex);
768 /*
769 * FUNCTION: CMMF_CertifiedKeyPairGetCertificate
770 * INPUTS:
771 * inCertKeyPair
772 * The CMMFCertifiedKeyPair to operate on.
773 * inCertdb
774 * The database handle for the database you want this certificate
775 * to wind up in.
776 * NOTES:
777 * This function retrieves the certificate at
778 * CertifiedKeyPair.certOrEncCert.certificate
779 * The user must call CERT_DestroyCertificate when the return value is no
780 * longer needed. The user must import this certificate as a token object
781 * onto PKCS#11 slot in order to make it a permanent object. The returned
782 * certificate will be in the temporary database.
783 *
784 * RETURN:
785 * A pointer to the certificate contained within the certified key pair.
786 * A return value of NULL indicates an error in creating the copy of the
787 * certificate.
788 */
789 extern CERTCertificate*
790 CMMF_CertifiedKeyPairGetCertificate(CMMFCertifiedKeyPair *inCertKeyPair,
791 CERTCertDBHandle *inCertdb);
793 /*
794 * FUNCTION: CMMF_POPODecKeyChallContentGetNumChallenges
795 * INPUTS:
796 * inKeyChallCont
797 * The CMMFPOPODecKeyChallContent to operate on.
798 * RETURN:
799 * This function returns the number of CMMFChallenges are contained in
800 * the CMMFPOPODecKeyChallContent structure.
801 */
802 extern int CMMF_POPODecKeyChallContentGetNumChallenges
803 (CMMFPOPODecKeyChallContent *inKeyChallCont);
805 /*
806 * FUNCTION: CMMF_POPODecKeyChallContentGetPublicValue
807 * ---------------------------------------------------
808 * INPUTS:
809 * inKeyChallCont
810 * The CMMFPOPODecKeyChallContent to operate on.
811 * inIndex
812 * The index of the Challenge within inKeyChallCont to operate on.
813 * Indexes start from 0, ie the Nth Challenge corresponds to index
814 * N-1.
815 * NOTES:
816 * This function retrieves the public value stored away in the Challenge at
817 * index inIndex of inKeyChallCont.
818 * RETURN:
819 * A pointer to a SECItem containing the public value. User must call
820 * SECITEM_FreeItem on the return value when the value is no longer necessary.
821 * A return value of NULL indicates an error while retrieving the public value.
822 */
823 extern SECItem* CMMF_POPODecKeyChallContentGetPublicValue
824 (CMMFPOPODecKeyChallContent *inKeyChallCont,
825 int inIndex);
828 /*
829 * FUNCTION: CMMF_POPODecKeyChallContentGetRandomNumber
830 * INPUTS:
831 * inChallContent
832 * The CMMFPOPODecKeyChallContent to operate on.
833 * inIndex
834 * The index of the challenge to look at. Valid indexes are 0 through
835 * (CMMF_POPODecKeyChallContentGetNumChallenges(inChallContent) - 1).
836 * inDest
837 * A pointer to a user supplied buffer where the library
838 * can place a copy of the random integer contatained in the
839 * challenge.
840 * NOTES:
841 * This function returns the value held in the decrypted Rand structure
842 * corresponding to the random integer. The user must call
843 * CMMF_POPODecKeyChallContentDecryptChallenge before calling this function. Call
844 * CMMF_ChallengeIsDecrypted to find out if the challenge has been
845 * decrypted.
846 *
847 * RETURN:
848 * SECSuccess indicates the witness field has been previously decrypted
849 * and the value for the random integer was successfully placed at *inDest.
850 * Any other return value indicates an error and that the value at *inDest
851 * is not a valid value.
852 */
853 extern SECStatus CMMF_POPODecKeyChallContentGetRandomNumber
854 (CMMFPOPODecKeyChallContent *inKeyChallCont,
855 int inIndex,
856 long *inDest);
858 /*
859 * FUNCTION: CMMF_POPODecKeyRespContentGetNumResponses
860 * INPUTS:
861 * inRespCont
862 * The POPODecKeyRespContent to operate on.
863 * RETURN:
864 * This function returns the number of responses contained in inRespContent.
865 */
866 extern int
867 CMMF_POPODecKeyRespContentGetNumResponses(CMMFPOPODecKeyRespContent *inRespCont);
869 /*
870 * FUNCTION: CMMF_POPODecKeyRespContentGetResponse
871 * INPUTS:
872 * inRespCont
873 * The POPODecKeyRespContent to operate on.
874 * inIndex
875 * The index of the response to retrieve.
876 * The Nth response is at index N-1, ie the 1st response is at index 0,
877 * the 2nd response is at index 1, and so on.
878 * inDest
879 * A pointer to a pre-allocated buffer where the library can put the
880 * value of the response located at inIndex.
881 * NOTES:
882 * The function returns the response contained at index inIndex.
883 * CMMFPOPODecKeyRespContent is a structure that the server will generally
884 * get in response to a CMMFPOPODecKeyChallContent. The server will expect
885 * to see the responses in the same order as it constructed them in
886 * the CMMFPOPODecKeyChallContent structure.
887 * RETURN:
888 * SECSuccess if getting the response at the desired index was successful. Any
889 * other return value indicates an errror.
890 */
891 extern SECStatus
892 CMMF_POPODecKeyRespContentGetResponse (CMMFPOPODecKeyRespContent *inRespCont,
893 int inIndex,
894 long *inDest);
896 /************************* Destructor Functions ******************************/
898 /*
899 * FUNCTION: CMMF_DestroyCertResponse
900 * INPUTS:
901 * inCertResp
902 * The CMMFCertResponse to destroy.
903 * NOTES:
904 * This function frees all the memory associated with the CMMFCertResponse
905 * passed in.
906 * RETURN:
907 * SECSuccess if freeing the memory was successful. Any other return value
908 * indicates an error while freeing the memory.
909 */
910 extern SECStatus CMMF_DestroyCertResponse(CMMFCertResponse *inCertResp);
912 /*
913 * FUNCTION: CMMF_DestroyCertRepContent
914 * INPUTS:
915 * inCertRepContent
916 * The CMMFCertRepContent to destroy
917 * NOTES:
918 * This function frees the memory associated with the CMMFCertRepContent
919 * passed in.
920 * RETURN:
921 * SECSuccess if freeing all the memory associated with the
922 * CMMFCertRepContent passed in is successful. Any other return value
923 * indicates an error while freeing the memory.
924 */
925 extern SECStatus
926 CMMF_DestroyCertRepContent (CMMFCertRepContent *inCertRepContent);
928 /*
929 * FUNCTION: CMMF_DestroyKeyRecRepContent
930 * INPUTS:
931 * inKeyRecRep
932 * The CMMFKeyRecRepContent to destroy.
933 * NOTES:
934 * This function destroys all the memory associated with the
935 * CMMFKeyRecRepContent passed in.
936 *
937 * RETURN:
938 * SECSuccess if freeing all the memory is successful. Any other return
939 * value indicates an error in freeing the memory.
940 */
941 extern SECStatus
942 CMMF_DestroyKeyRecRepContent(CMMFKeyRecRepContent *inKeyRecRep);
944 /*
945 * FUNCTION: CMMF_DestroyCertifiedKeyPair
946 * INPUTS:
947 * inCertKeyPair
948 * The CMMFCertifiedKeyPair to operate on.
949 * NOTES:
950 * This function frees up all the memory associated with 'inCertKeyPair'
951 *
952 * RETURN:
953 * SECSuccess if freeing all the memory associated with 'inCertKeyPair'
954 * is successful. Any other return value indicates an error while trying
955 * to free the memory.
956 */
957 extern SECStatus
958 CMMF_DestroyCertifiedKeyPair(CMMFCertifiedKeyPair *inCertKeyPair);
960 /*
961 * FUNCTION: CMMF_DestroyPOPODecKeyRespContent
962 * INPUTS:
963 * inDecKeyResp
964 * The CMMFPOPODecKeyRespContent structure to free.
965 * NOTES:
966 * This function frees up all the memory associate with the
967 * CMMFPOPODecKeyRespContent.
968 *
969 * RETURN:
970 * SECSuccess if freeing up all the memory associated with the
971 * CMMFPOPODecKeyRespContent structure is successful. Any other
972 * return value indicates an error while freeing the memory.
973 */
974 extern SECStatus
975 CMMF_DestroyPOPODecKeyRespContent(CMMFPOPODecKeyRespContent *inDecKeyResp);
978 /************************** Miscellaneous Functions *************************/
980 /*
981 * FUNCTION: CMMF_CertifiedKeyPairUnwrapPrivKey
982 * INPUTS:
983 * inCertKeyPair
984 * The CMMFCertifiedKeyPair to operate on.
985 * inPrivKey
986 * The private key to use to un-wrap the private key
987 * inNickName
988 * This is the nickname that will be associated with the private key
989 * to be unwrapped.
990 * inSlot
991 * The PKCS11 slot where the unwrapped private key should end up.
992 * inCertdb
993 * The Certificate database with which the new key will be associated.
994 * destPrivKey
995 * A pointer to memory where the library can place a pointer to the
996 * private key after importing the key onto the specified slot.
997 * wincx
998 * An opaque pointer that the library will use in a callback function
999 * to get the password if necessary.
1000 *
1001 * NOTES:
1002 * This function uses the private key passed in to unwrap the private key
1003 * contained within the CMMFCertifiedKeyPair structure. After this
1004 * function successfully returns, the private key has been unwrapped and
1005 * placed in the specified slot.
1006 *
1007 * RETURN:
1008 * SECSuccess if unwrapping the private key was successful. Any other
1009 * return value indicates an error while trying to un-wrap the private key.
1010 */
1011 extern SECStatus
1012 CMMF_CertifiedKeyPairUnwrapPrivKey(CMMFCertifiedKeyPair *inKeyPair,
1013 SECKEYPrivateKey *inPrivKey,
1014 SECItem *inNickName,
1015 PK11SlotInfo *inSlot,
1016 CERTCertDBHandle *inCertdb,
1017 SECKEYPrivateKey **destPrivKey,
1018 void *wincx);
1020 /*
1021 * FUNCTION: CMMF_KeyRecRepContentHasCACerts
1022 * INPUTS:
1023 * inKeyRecRecp
1024 * The CMMFKeyRecRepContent to operate on.
1025 * RETURN:
1026 * This function returns PR_TRUE if there are one or more certificates in
1027 * the sequence KeyRecRepContent.caCerts within the CMMFKeyRecRepContent
1028 * structure. The function will return PR_FALSE if there are 0 certificate
1029 * in the above mentioned sequence.
1030 */
1031 extern PRBool
1032 CMMF_KeyRecRepContentHasCACerts(CMMFKeyRecRepContent *inKeyRecRep);
1034 /*
1035 * FUNCTION: CMMF_POPODecKeyChallContDecryptChallenge
1036 * INPUTS:
1037 * inChalCont
1038 * The CMMFPOPODecKeyChallContent to operate on.
1039 * inIndex
1040 * The index of the Challenge to operate on. The 1st Challenge is
1041 * at index 0, the second at index 1 and so forth.
1042 * inPrivKey
1043 * The private key to use to decrypt the witness field.
1044 * NOTES:
1045 * This function uses the private key to decrypt the challenge field
1046 * contained in the appropriate challenge. Make sure the private key matches
1047 * the public key that was used to encrypt the witness. Use
1048 * CMMF_POPODecKeyChallContentGetPublicValue to get the public value of
1049 * the key used to encrypt the witness and then use that to determine the
1050 * appropriate private key. This can be done by calling PK11_MakeIDFromPubKey
1051 * and then passing that return value to PK11_FindKeyByKeyID. The creator of
1052 * the challenge will most likely be an RA that has the public key
1053 * from a Cert request. So the private key should be the private key
1054 * associated with public key in that request. This function will also
1055 * verify the witness field of the challenge. This function also verifies
1056 * that the sender and witness hashes match within the challenge.
1057 *
1058 * RETURN:
1059 * SECSuccess if decrypting the witness field was successful. This does
1060 * not indicate that the decrypted data is valid, since the private key
1061 * passed in may not be the actual key needed to properly decrypt the
1062 * witness field. Meaning that there is a decrypted structure now, but
1063 * may be garbage because the private key was incorrect.
1064 * Any other return value indicates the function could not complete the
1065 * decryption process.
1066 */
1067 extern SECStatus
1068 CMMF_POPODecKeyChallContDecryptChallenge(CMMFPOPODecKeyChallContent *inChalCont,
1069 int inIndex,
1070 SECKEYPrivateKey *inPrivKey);
1072 /*
1073 * FUNCTION: CMMF_DestroyPOPODecKeyChallContent
1074 * INPUTS:
1075 * inDecKeyCont
1076 * The CMMFPOPODecKeyChallContent to free
1077 * NOTES:
1078 * This function frees up all the memory associated with the
1079 * CMMFPOPODecKeyChallContent
1080 * RETURN:
1081 * SECSuccess if freeing up all the memory associatd with the
1082 * CMMFPOPODecKeyChallContent is successful. Any other return value
1083 * indicates an error while freeing the memory.
1084 *
1085 */
1086 extern SECStatus
1087 CMMF_DestroyPOPODecKeyChallContent (CMMFPOPODecKeyChallContent *inDecKeyCont);
1089 SEC_END_PROTOS
1090 #endif /* _CMMF_H_ */
