The Tor Browser / file comparison

comparison: security/nss/lib/crmf/crmf.h

security/nss/lib/crmf/crmf.h

branch
TOR_BUG_9701
changeset 15
b8a032363ba2
equal deleted inserted replaced
-1:000000000000 0:e4da7899bf96
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/. */
5
6
7 #ifndef _CRMF_H_
8 #define _CRMF_H_
9
10 #include "seccomon.h"
11 #include "cert.h"
12 #include "crmft.h"
13 #include "secoid.h"
14 #include "secpkcs7.h"
15
16 SEC_BEGIN_PROTOS
17
18 /*
19 * FUNCTION: CRMF_EncodeCertReqMsg
20 * INPUTS:
21 * inCertReqMsg
22 * The Certificate Request Message to be encoded.
23 * fn
24 * A Callback function that the ASN1 encoder calls whenever
25 * the encoder wants to write out some DER encoded bytes.
26 * arg
27 * An opaque pointer that gets passed to the function fn
28 * OUTPUT:
29 * The function fn will be called multiple times. Look at the
30 * comments in crmft.h where the CRMFEncoderOutputCallback type is
31 * defined for information on proper behavior of the function fn.
32 * RETURN:
33 * SECSuccess if encoding was successful. Any other return value
34 * indicates an error occurred during encoding.
35 */
36 extern SECStatus
37 CRMF_EncodeCertReqMsg (CRMFCertReqMsg *inCertReqMsg,
38 CRMFEncoderOutputCallback fn,
39 void *arg);
40
41 /*
42 * FUNCTION: CRMF_EncoderCertRequest
43 * INPUTS:
44 * inCertReq
45 * The Certificate Request to be encoded.
46 * fn
47 * A Callback function that the ASN1 encoder calls whenever
48 * the encoder wants to write out some DER encoded bytes.
49 * arg
50 * An opaque pointer that gets passed to the function fn.
51 * OUTPUT:
52 * The function fn will be called, probably multiple times whenever
53 * the ASN1 encoder wants to write out DER-encoded bytes. Look at the
54 * comments in crmft.h where the CRMFEncoderOutputCallback type is
55 * defined for information on proper behavior of the function fn.
56 * RETURN:
57 * SECSuccess if encoding was successful. Any other return value
58 * indicates an error occurred during encoding.
59 */
60 extern SECStatus CRMF_EncodeCertRequest (CRMFCertRequest *inCertReq,
61 CRMFEncoderOutputCallback fn,
62 void *arg);
63 /*
64 * FUNCTION: CRMF_EncodeCertReqMessages
65 * INPUTS:
66 * inCertReqMsgs
67 * An array of pointers to the Certificate Request Messages
68 * to encode. The user must place a NULL pointer in the index
69 * after the last message to be encoded. When the library runs
70 * into the NULL pointer, the library assumes there are no more
71 * messages to encode.
72 * fn
73 * A Callback function that the ASN1 encoder calls whenever
74 * the encoder wants to write out some DER encoded byts.
75 * arg
76 * An opaque pointer that gets passed to the function fn.
77 *
78 * NOTES:
79 * The parameter inCertReqMsgs needs to be an array with a NULL pointer
80 * to signal the end of messages. An array in the form of
81 * {m1, m2, m3, NULL, m4, ...} will only encode the messages m1, m2, and
82 * m3. All messages from m4 on will not be looked at by the library.
83 *
84 * OUTPUT:
85 * The function fn will be called, probably multiple times. Look at the
86 * comments in crmft.h where the CRMFEncoderOutputCallback type is
87 * defined for information on proper behavior of the function fn.
88 *
89 * RETURN:
90 * SECSuccess if encoding the Certificate Request Messages was successful.
91 * Any other return value indicates an error occurred while encoding the
92 * certificate request messages.
93 */
94 extern SECStatus
95 CRMF_EncodeCertReqMessages(CRMFCertReqMsg **inCertReqMsgs,
96 CRMFEncoderOutputCallback fn,
97 void *arg);
98
99
100 /*
101 * FUNCTION: CRMF_CreateCertReqMsg
102 * INPUTS:
103 * NONE
104 * OUTPUT:
105 * An empty CRMF Certificate Request Message.
106 * Before encoding this message, the user must set
107 * the ProofOfPossession field and the certificate
108 * request which are necessary for the full message.
109 * After the user no longer needs this CertReqMsg,
110 * the user must call CRMF_DestroyCertReqMsg to free
111 * all memory associated with the Certificate Request
112 * Message.
113 * RETURN:
114 * A pointer to a Certificate Request Message. The user
115 * must pass the return value of this function to
116 * CRMF_DestroyCertReqMsg after the Certificate Request
117 * Message is no longer necessary.
118 */
119 extern CRMFCertReqMsg* CRMF_CreateCertReqMsg(void);
120
121 /*
122 * FUNCTION: CRMF_DestroyCertReqMsg
123 * INPUTS:
124 * inCertReqMsg
125 * The Certificate Request Message to destroy.
126 * NOTES:
127 * This function frees all the memory used for the Certificate
128 * Request Message and all the memory used in making copies of
129 * fields of elelments of the message, eg. the Proof Of Possession
130 * filed and the Cetificate Request.
131 * RETURN:
132 * SECSuccess if destruction was successful. Any other return value
133 * indicates an error while trying to free the memory associated
134 * with inCertReqMsg.
135 *
136 */
137 extern SECStatus CRMF_DestroyCertReqMsg(CRMFCertReqMsg *inCertReqMsg);
138
139 /*
140 * FUNCTION: CRMF_CertReqMsgSetCertRequest
141 * INPUTS:
142 * inCertReqMsg
143 * The Certificate Request Message that the function will set
144 * the certificate request for.
145 * inCertReq
146 * The Certificate Request that will be added to the Certificate
147 * Request Message.
148 * NOTES:
149 * This function will make a copy of the Certificate Request passed in
150 * and store it as part of the Certificate Request Message. Therefore,
151 * the user must not call this function until the Certificate Request
152 * has been fully built and is ready to be encoded.
153 * RETURN:
154 * SECSuccess
155 * If copying the Certificate as a member of the Certificate
156 * request message was successful.
157 * Any other return value indicates a failure to copy the Certificate
158 * Request and make it a part of the Certificate Request Message.
159 */
160 extern SECStatus CRMF_CertReqMsgSetCertRequest(CRMFCertReqMsg *inCertReqMsg,
161 CRMFCertRequest *inCertReq);
162
163 /*
164 * FUNCTION: CRMF_CreateCertRequest
165 * INPUTS:
166 * inRequestID
167 * The ID that will be associated with this certificate request.
168 * OUTPUTS:
169 * A certificate request which only has the requestID set.
170 * NOTES:
171 * The user must call the function CRMF_DestroyCertRequest when
172 * the returned value is no longer needed. This is usually the
173 * case after fully constructing the Certificate Request and then
174 * calling the function CRMF_CertReqMsgSetCertRequest.
175 * RETURN:
176 * A pointer to the new Certificate Request. A NULL return value
177 * indicates an error in creating the Certificate Request.
178 */
179 extern CRMFCertRequest *CRMF_CreateCertRequest (PRUint32 inRequestID);
180
181 /*
182 * FUNCTION: CRMF_DestroyCertRequest
183 * INPUTS:
184 * inCertReq
185 * The Certificate Request that will be destroyed.
186 * RETURN:
187 * SECSuccess
188 * If freeing the memory associated with the certificate request
189 * was successful.
190 * Any other return value indicates an error while trying to free the
191 * memory.
192 */
193 extern SECStatus CRMF_DestroyCertRequest (CRMFCertRequest *inCertReq);
194
195 /*
196 * FUNCTION: CRMF_CreateCertExtension
197 * INPUTS:
198 * id
199 * The SECOidTag to associate with this CertExtension. This must
200 * correspond to a valid Certificate Extension, if not the function
201 * will fail.
202 * isCritical
203 * A boolean value stating if the extension value is crtical. PR_TRUE
204 * means the value is crtical. PR_FALSE indicates the value is not
205 * critical.
206 * data
207 * This is the data associated with the extension. The user of the
208 * library is responsible for making sure the value passed in is a
209 * valid interpretation of the certificate extension.
210 * NOTES:
211 * Use this function to create CRMFCertExtension Structures which will
212 * then be passed to CRMF_AddFieldToCertTemplate as part of the
213 * CRMFCertCreationInfo.extensions The user must call
214 * CRMF_DestroyCertExtension after the extension has been added to a certifcate
215 * and the extension is no longer needed.
216 *
217 * RETURN:
218 * A pointer to a newly created CertExtension. A return value of NULL
219 * indicates the id passed in was an invalid certificate extension.
220 */
221 extern CRMFCertExtension *CRMF_CreateCertExtension(SECOidTag id,
222 PRBool isCritical,
223 SECItem *data);
224
225 /*
226 * FUNCTION: CMRF_DestroyCertExtension
227 * INPUTS:
228 * inExtension
229 * The Cert Extension to destroy
230 * NOTES:
231 * Destroy a structure allocated by CRMF_CreateCertExtension.
232 *
233 * RETURN:
234 * SECSuccess if freeing the memory associated with the certificate extension
235 * was successful. Any other error indicates an error while freeing the
236 * memory.
237 */
238 extern SECStatus CRMF_DestroyCertExtension(CRMFCertExtension *inExtension);
239
240 /*
241 * FUNCTION: CRMF_CertRequestSetTemplateField
242 * INPUTS:
243 * inCertReq
244 * The Certificate Request to operate on.
245 * inTemplateField
246 * An enumeration that indicates which field of the Certificate
247 * template to add.
248 * data
249 * A generic pointer that will be type cast according to the
250 * table under NOTES and used as the key for adding to the
251 * certificate template;
252 * NOTES:
253 *
254 * Below is a table that tells what type to pass in as data
255 * depending on the template field one wants to set.
256 *
257 * Look in crmft.h for the definition of CRMFCertTemplateField.
258 *
259 * In all cases, the library makes copies of the data passed in.
260 *
261 * CRMFCertTemplateField Type of data What data means
262 * --------------------- ------------ ---------------
263 * crmfVersion long * The version of
264 * the certificate
265 * to be created.
266 *
267 * crmfSerialNumber long * The serial number
268 * for the cert to be
269 * created.
270 *
271 * crmfSigningAlg SECAlgorithm * The ASN.1 object ID for
272 * the algorithm used in encoding
273 * the certificate.
274 *
275 * crmfIssuer CERTName * Certificate Library
276 * representation of the ASN1 type
277 * Name from X.509
278 *
279 * crmfValidity CRMFValidityCreationInfo * At least one of the two
280 * fields in the structure must
281 * be present. A NULL pointer
282 * in the structure indicates
283 * that member should not be
284 * added.
285 *
286 * crmfSubject CERTName * Certificate Library
287 * representation of the ASN1 type
288 * Name from X.509
289 *
290 * crmfPublicKey CERTSubjectPublicKeyInfo * The public key info for the
291 * certificate being requested.
292 *
293 * crmfIssuerUID SECItem * A bit string representation
294 * of the issuer UID. NOTE: The
295 * length is the number of bits
296 * and not the number of bytes.
297 *
298 * crmfSubjectUID SECItem* A bit string representation
299 * of the subject UID. NOTE: The
300 * length is the number of bits
301 * and not the number of bytes.
302 *
303 * crmfExtension CRMFCertExtCreationInfo * A pointer to the structure
304 * populated with an array of
305 * of certificate extensions
306 * and an integer that tells
307 * how many elements are in the
308 * array. Look in crmft.h for
309 * the definition of
310 * CRMFCertExtCreationInfo
311 * RETURN:
312 * SECSuccess if adding the desired field to the template was successful.
313 * Any other return value indicates failure when trying to add the field
314 * to the template.
315 *
316 */
317 extern SECStatus
318 CRMF_CertRequestSetTemplateField(CRMFCertRequest *inCertReq,
319 CRMFCertTemplateField inTemplateField,
320 void *data);
321
322 /*
323 * FUNCTION: CRMF_CertRequestIsFieldPresent
324 * INPUTS:
325 * inCertReq
326 * The certificate request to operate on.
327 * inTemplateField
328 * The enumeration for the template field the user wants to query
329 * about.
330 * NOTES:
331 * This function checks to see if the the field associated with inTemplateField
332 * enumeration is already present in the certificate request passed in.
333 *
334 * RETURN:
335 * The function returns PR_TRUE if the field associated with inTemplateField
336 * is already present in the certificate request. If the field is not present
337 * the function returns PR_FALSE.
338 */
339 extern PRBool
340 CRMF_CertRequestIsFieldPresent(CRMFCertRequest *inCertReq,
341 CRMFCertTemplateField inTemplateField);
342
343 /*
344 * FUNCTION: CRMF_CertRequestIsControlPresent
345 * INPUTS:
346 * inCertReq
347 * The certificate request to operate on.
348 * inControlType
349 * The type of control to look for.
350 * NOTES:
351 * This function looks at the control present in the certificate request
352 * and returns PR_TRUE iff a control of type inControlType already exists.
353 * The CRMF draft does not explicitly state that two controls of the same
354 * type can not exist within the same request. So the library will not
355 * cause an error if you try to add a control and one of the same type
356 * already exists. It is up to the application to ensure that multiple
357 * controls of the same type do not exist, if that is the desired behavior
358 * by the application.
359 *
360 * RETURN:
361 * The function returns PR_TRUE if a control of type inControlType already
362 * exists in the certificate request. If a control of type inControlType
363 * does not exist, the function will return PR_FALSE.
364 */
365 extern PRBool
366 CRMF_CertRequestIsControlPresent(CRMFCertRequest *inCertReq,
367 CRMFControlType inControlType);
368
369
370 /*
371 * FUNCTION: CRMF_CertRequestSetRegTokenControl
372 * INPUTS:
373 * inCertReq
374 * The Certificate Request to operate on.
375 * value
376 * The UTF8 value which will be the Registration Token Control
377 * for this Certificate Request.
378 * NOTES:
379 * The library does no verification that the value passed in is
380 * a valid UTF8 value. The caller must make sure of this in order
381 * to get an encoding that is valid. The library will ultimately
382 * encode this value as it was passed in.
383 * RETURN:
384 * SECSucces on successful addition of the Registration Token Control.
385 * Any other return value indicates an unsuccessful attempt to add the
386 * control.
387 *
388 */
389 extern SECStatus CRMF_CertRequestSetRegTokenControl(CRMFCertRequest *inCertReq,
390 SECItem *value);
391
392 /*
393 * FUNCTION: CRMF_CertRequestSetAuthenticatorControl
394 * INPUTS:
395 * inCertReq
396 * The Certificate Request to operate on.
397 * value
398 * The UTF8 value that will become the Authenticator Control
399 * for the passed in Certificate Request.
400 * NOTES:
401 * The library does no verification that the value passed in is
402 * a valid UTF8 value. The caller must make sure of this in order
403 * to get an encoding that is valid. The library will ultimately
404 * encode this value as it was passed in.
405 * RETURN:
406 * SECSucces on successful addition of the Authenticator Control.
407 * Any other return value indicates an unsuccessful attempt to add the
408 * control.
409 */
410 extern SECStatus
411 CRMF_CertRequestSetAuthenticatorControl (CRMFCertRequest *inCertReq,
412 SECItem *value);
413
414 /*
415 * FUNCTION: CRMF_CreateEncryptedKeyWithencryptedValue
416 * INPUTS:
417 * inPrivKey
418 * This is the private key associated with a certificate that is
419 * being requested. This structure will eventually wind up as
420 * a part of the PKIArchiveOptions Control.
421 * inCACert
422 * This is the certificate for the CA that will be receiving the
423 * certificate request for the private key passed in.
424 * OUTPUT:
425 * A CRMFEncryptedKey that can ultimately be used as part of the
426 * PKIArchiveOptions Control.
427 *
428 * RETURN:
429 * A pointer to a CRMFEncyptedKey. A NULL return value indicates an erro
430 * during the creation of the encrypted key.
431 */
432 extern CRMFEncryptedKey*
433 CRMF_CreateEncryptedKeyWithEncryptedValue(SECKEYPrivateKey *inPrivKey,
434 CERTCertificate *inCACert);
435
436 /*
437 * FUNCTION: CRMF_DestroyEncryptedKey
438 * INPUTS:
439 * inEncrKey
440 * The CRMFEncryptedKey to be destroyed.
441 * NOTES:
442 * Frees all memory associated with the CRMFEncryptedKey passed in.
443 * RETURN:
444 * SECSuccess if freeing the memory was successful. Any other return
445 * value indicates an error while freeig the memroy.
446 */
447 extern SECStatus CRMF_DestroyEncryptedKey(CRMFEncryptedKey *inEncrKey);
448
449 /*
450 * FUNCTION: CRMF_CreatePKIArchiveOptions
451 * INPUTS:
452 * inType
453 * An enumeration value indicating which option for
454 * PKIArchiveOptions to use.
455 * data
456 * A pointer that will be type-cast and de-referenced according
457 * to the table under NOTES.
458 * NOTES:
459 * A table listing what should be passed in as data
460 * ------------------------------------------------
461 *
462 * inType data
463 * ------ ----
464 * crmfEncryptedPrivateKey CRMFEncryptedKey*
465 * crmfKeyGenParameters SECItem*(This needs to be an octet string)
466 * crmfArchiveRemGenPrivKey PRBool*
467 *
468 * RETURN:
469 * A pointer the a CRMFPKIArchiveOptions that can be added to a Certificate
470 * Request. A NULL pointer indicates an error occurred while creating
471 * the CRMFPKIArchiveOptions Structure.
472 */
473 extern CRMFPKIArchiveOptions*
474 CRMF_CreatePKIArchiveOptions(CRMFPKIArchiveOptionsType inType,
475 void *data);
476 /*
477 * FUNCTION: CRMF_DestroyPKIArchiveOptions
478 * INPUTS:
479 * inArchOpt
480 * A pointer to the CRMFPKIArchiveOptions structure to free.
481 * NOTES:
482 * Will free all memory associated with 'inArchOpt'.
483 * RETURN:
484 * SECSuccess if successful in freeing the memory used by 'inArchOpt'
485 * Any other return value indicates an error while freeing the memory.
486 */
487 extern SECStatus
488 CRMF_DestroyPKIArchiveOptions(CRMFPKIArchiveOptions *inArchOpt);
489
490 /*
491 * FUNCTION: CRMF_CertRequestSetPKIArchiveOptions
492 * INPUTS:
493 * inCertReq
494 * The Certificate Request to add the the options to.
495 * inOptions
496 * The Archive Options to add to the Certificate Request.
497 * NOTES:
498 * Adds the PKIArchiveOption to the Certificate Request. This is what
499 * enables Key Escrow to take place through CRMF. The library makes
500 * its own copy of the information.
501 * RETURN:
502 * SECSuccess if successful in adding the ArchiveOptions to the Certificate
503 * request. Any other return value indicates an error when trying to add
504 * the Archive Options to the Certificate Request.
505 */
506 extern SECStatus
507 CRMF_CertRequestSetPKIArchiveOptions(CRMFCertRequest *inCertReq,
508 CRMFPKIArchiveOptions *inOptions);
509
510 /*
511 * FUNCTION: CRMF_CertReqMsgGetPOPType
512 * INPUTS:
513 * inCertReqMsg
514 * The Certificate Request Message to operate on.
515 * NOTES:
516 * Returns an enumeration value indicating the method of Proof
517 * of Possession that was used for the passed in Certificate Request
518 * Message.
519 * RETURN:
520 * An enumeration indicating what method for Proof Of Possession is
521 * being used in this Certificate Request Message. Look in the file
522 * crmft.h for the definition of CRMFPOPChoice for the possible return
523 * values.
524 */
525 extern CRMFPOPChoice CRMF_CertReqMsgGetPOPType(CRMFCertReqMsg *inCertReqMsg);
526
527 /*
528 * FUNCTION: CRMF_CertReqMsgSetRAVerifiedPOP
529 * INPUT:
530 * InCertReqMsg
531 * The Certificate Request Message to operate on.
532 * NOTES:
533 * This function will set the method of Proof Of Possession to
534 * crmfRAVerified which means the RA has already verified the
535 * requester does possess the private key.
536 * RETURN:
537 * SECSuccess if adding RAVerified to the message is successful.
538 * Any other message indicates an error while trying to add RAVerified
539 * as the Proof of Possession.
540 */
541 extern SECStatus CRMF_CertReqMsgSetRAVerifiedPOP(CRMFCertReqMsg *inCertReqMsg);
542
543 /*
544 * FUNCTION: CRMF_CertReqMsgSetSignaturePOP
545 * INPUT:
546 * inCertReqMsg
547 * The Certificate Request Message to add the SignaturePOP to.
548 * inPrivKey
549 * The Private Key which corresponds to the the Certificate Request
550 * Message.
551 * inPubKey
552 * The Public Key which corresponds to the Private Key passed in.
553 * inCertForInput
554 * A Certificate that in the future may be used to create
555 * POPOSigningKeyInput.
556 * fn
557 * A callback for retrieving a password which may be used in the
558 * future to generate POPOSigningKeyInput.
559 * arg
560 * An opaque pointer that would be passed to fn whenever it is
561 * called.
562 * NOTES:
563 * Adds Proof Of Possession to the CertRequest using the signature field
564 * of the ProofOfPossession field. NOTE: In order to use this option,
565 * the certificate template must contain the publicKey at the very minimum.
566 *
567 * If you don't want the function to generate POPOSigningKeyInput, then
568 * make sure the cert template already contains the subject and public key
569 * values. Currently creating POPOSigningKeyInput is not supported, so
570 * a Message passed to this function must have the publicKey and the subject
571 * as part of the template
572 *
573 * This will take care of creating the entire POPOSigningKey structure
574 * that will become part of the message.
575 *
576 * inPrivKey is the key to be used in the signing operation when creating
577 * POPOSigningKey structure. This should be the key corresponding to
578 * the certificate being requested.
579 *
580 * inCertForInput will be used if POPOSigningKeyInput needs to be generated.
581 * It will be used in generating the authInfo.sender field. If the parameter
582 * is not passed in then authInfo.publicKeyMAC will be generated instead.
583 * If passed in, this certificate needs to be a valid certificate.
584 *
585 * The last 3 arguments are for future compatibility in case we ever want to
586 * support generating POPOSigningKeyInput. Pass in NULL for all 3 if you
587 * definitely don't want the function to even try to generate
588 * POPOSigningKeyInput. If you try to use POPOSigningKeyInput, the function
589 * will fail.
590 *
591 * RETURN:
592 * SECSuccess if adding the Signature Proof Of Possession worked.
593 * Any other return value indicates an error in trying to add
594 * the Signature Proof Of Possession.
595 */
596 extern SECStatus
597 CRMF_CertReqMsgSetSignaturePOP(CRMFCertReqMsg *inCertReqMsg,
598 SECKEYPrivateKey *inPrivKey,
599 SECKEYPublicKey *inPubKey,
600 CERTCertificate *inCertForInput,
601 CRMFMACPasswordCallback fn,
602 void *arg);
603
604 /*
605 * FUNCTION: CRMF_CertReqMsgSetKeyEnciphermentPOP
606 * INPUTS:
607 * inCertReqMsg
608 * The Certificate Request Message to operate on.
609 * inKeyChoice
610 * An enumeration indicating which POPOPrivKey Choice to use
611 * in constructing the KeyEnciphermentPOP.
612 * subseqMess
613 * This parameter must be provided iff inKeyChoice is
614 * crmfSubsequentMessage. This details how the RA is to respond
615 * in order to perform Proof Of Possession. Look in crmft.h under
616 * the definition of CRMFSubseqMessOptions for possible values.
617 * encPrivKey
618 * This parameter only needs to be provided if inKeyChoice is
619 * crmfThisMessage. The item should contain the encrypted private
620 * key.
621 *
622 * NOTES:
623 * Adds Proof Of Possession using the keyEncipherment field of
624 * ProofOfPossession.
625 *
626 * The function looks at the the inKeyChoice parameter and interprets it in
627 * in the following manner.
628 *
629 * If a parameter is not mentioned under interpretation, the function will not
630 * look at its value when implementing that case.
631 *
632 * inKeyChoice Interpretation
633 * ----------- --------------
634 * crmfThisMessage This options requires that the encrypted private key
635 * be included in the thisMessage field of POPOPrivKey.
636 * We don't support this yet, so any clients who want
637 * to use this feature have to implement a wrapping
638 * function and agree with the server on how to properly
639 * wrap the key. That encrypted key must be passed in
640 * as the encPrivKey parameter.
641 *
642 * crmfSubequentMessage Must pass in a value for subseqMess. The value must
643 * be either CRMFEncrCert or CRMFChallengeResp. The
644 * parameter encPrivKey will not be looked at in this
645 * case.
646 *
647 * crmfDHMAC This is not a valid option for this function. Passing
648 * in this value will result in the function returning
649 * SECFailure.
650 * RETURN:
651 * SECSuccess if adding KeyEnciphermentPOP was successful. Any other return
652 * value indicates an error in adding KeyEnciphermentPOP.
653 */
654 extern SECStatus
655 CRMF_CertReqMsgSetKeyEnciphermentPOP(CRMFCertReqMsg *inCertReqMsg,
656 CRMFPOPOPrivKeyChoice inKeyChoice,
657 CRMFSubseqMessOptions subseqMess,
658 SECItem *encPrivKey);
659
660 /*
661 * FUNCTION: CRMF_CertReqMsgSetKeyAgreementPOP
662 * INPUTS:
663 * inCertReqMsg
664 * The Certificate Request Message to operate on.
665 * inKeyChoice
666 * An enumeration indicating which POPOPrivKey Choice to use
667 * in constructing the KeyAgreementPOP.
668 * subseqMess
669 * This parameter must be provided iff inKeyChoice is
670 * crmfSubsequentMessage. This details how the RA is to respond
671 * in order to perform Proof Of Possession. Look in crmft.h under
672 * the definition of CRMFSubseqMessOptions for possible values.
673 * encPrivKey
674 * This parameter only needs to be provided if inKeyChoice is
675 * crmfThisMessage. The item should contain the encrypted private
676 * key.
677 * Adds Proof Of Possession using the keyAgreement field of
678 * ProofOfPossession.
679 *
680 * The function looks at the the inKeyChoice parameter and interprets it in
681 * in the following manner.
682 *
683 * If a parameter is not mentioned under interpretation, the function will not
684 * look at its value when implementing that case.
685 *
686 * inKeyChoice Interpretation
687 * ----------- --------------
688 * crmfThisMessage This options requires that the encrypted private key
689 * be included in the thisMessage field of POPOPrivKey.
690 * We don't support this yet, so any clients who want
691 * to use this feature have to implement a wrapping
692 * function and agree with the server on how to properly
693 * wrap the key. That encrypted key must be passed in
694 * as the encPrivKey parameter.
695 *
696 * crmfSubequentMessage Must pass in a value for subseqMess. The value must
697 * be either crmfEncrCert or crmfChallengeResp. The
698 * parameter encPrivKey will not be looked at in this
699 * case.
700 *
701 * crmfDHMAC This option is not supported.
702 */
703 extern SECStatus
704 CRMF_CertReqMsgSetKeyAgreementPOP(CRMFCertReqMsg *inCertReqMsg,
705 CRMFPOPOPrivKeyChoice inKeyChoice,
706 CRMFSubseqMessOptions subseqMess,
707 SECItem *encPrivKey);
708
709 /*
710 * FUNCTION: CRMF_CreateCertReqMsgFromDER
711 * INPUTS:
712 * buf
713 * A buffer to the DER-encoded Certificate Request Message.
714 * len
715 * The length in bytes of the buffer 'buf'
716 * NOTES:
717 * This function passes the buffer to the ASN1 decoder and creates a
718 * CRMFCertReqMsg structure. Do not try adding any fields to a message
719 * returned from this function. Specifically adding more Controls or
720 * Extensions may cause your program to crash.
721 *
722 * RETURN:
723 * A pointer to the Certificate Request Message structure. A NULL return
724 * value indicates the library was unable to parse the DER.
725 */
726 extern CRMFCertReqMsg* CRMF_CreateCertReqMsgFromDER(const char *buf, long len);
727
728 /*
729 * FUNCTION: CRMF_CreateCertReqMessagesFromDER
730 * INPUTS:
731 * buf
732 * A buffer to the DER-encoded Certificate Request Messages.
733 * len
734 * The length in bytes of buf
735 * NOTES:
736 * This function passes the buffer to the ASN1 decoder and creates a
737 * CRMFCertReqMessages structure. Do not try adding any fields to a message
738 * derived from this function. Specifically adding more Controls or
739 * Extensions may cause your program to crash.
740 * The user must call CRMF_DestroyCertReqMessages after the return value is
741 * no longer needed, ie when all individual messages have been extracted.
742 *
743 * RETURN:
744 * A pointer to the Certificate Request Messages structure. A NULL return
745 * value indicates the library was unable to parse the DER.
746 */
747 extern CRMFCertReqMessages*
748 CRMF_CreateCertReqMessagesFromDER(const char *buf, long len);
749
750 /*
751 * FUNCTION: CRMF_DestroyCertReqMessages
752 * INPUTS
753 * inCertReqMsgs
754 * The Messages to destroy.
755 * RETURN:
756 * SECSuccess if freeing the memory was done successfully. Any other
757 * return value indicates an error in freeing up memory.
758 */
759 extern SECStatus
760 CRMF_DestroyCertReqMessages(CRMFCertReqMessages *inCertReqMsgs);
761
762 /*
763 * FUNCTION: CRMF_CertReqMessagesGetNumMessages
764 * INPUTS:
765 * inCertReqMsgs
766 * The Request Messages to operate on.
767 * RETURN:
768 * The number of messages contained in the in the Request Messages
769 * strucure.
770 */
771 extern int
772 CRMF_CertReqMessagesGetNumMessages(CRMFCertReqMessages *inCertReqMsgs);
773
774 /*
775 * FUNCTION: CRMF_CertReqMessagesGetCertReqMsgAtIndex
776 * INPUTS:
777 * inReqMsgs
778 * The Certificate Request Messages to operate on.
779 * index
780 * The index of the single message the user wants a copy of.
781 * NOTES:
782 * This function returns a copy of the request messages stored at the
783 * index corresponding to the parameter 'index'. Indexing of the messages
784 * is done in the same manner as a C array. Meaning the valid index are
785 * 0...numMessages-1. User must call CRMF_DestroyCertReqMsg when done using
786 * the return value of this function.
787 *
788 * RETURN:
789 * SECSuccess if copying the message at the requested index was successful.
790 * Any other return value indicates an invalid index or error while copying
791 * the single request message.
792 */
793 extern CRMFCertReqMsg*
794 CRMF_CertReqMessagesGetCertReqMsgAtIndex(CRMFCertReqMessages *inReqMsgs,
795 int index);
796
797
798 /*
799 * FUNCTION: CRMF_CertReqMsgGetID
800 * INPUTS:
801 * inCertReqMsg
802 * The Certificate Request Message to get the ID from.
803 * destID
804 * A pointer to where the library can place the ID of the Message.
805 * RETURN:
806 * SECSuccess if the function was able to retrieve the ID and place it
807 * at *destID. Any other return value indicates an error meaning the value
808 * in *destId is un-reliable and should not be used by the caller of this
809 * function.
810 *
811 */
812 extern SECStatus CRMF_CertReqMsgGetID(CRMFCertReqMsg *inCertReqMsg,
813 long *destID);
814
815 /*
816 * FUNCTION: CRMF_DoesRequestHaveField
817 * INPUTS:
818 * inCertReq
819 * The Certificate Request to operate on.
820 * inField
821 * An enumeration indicating which filed of the certificate template
822 * to look for.
823 * NOTES:
824 * All the fields in a certificate template are optional. This function
825 * checks to see if the requested field is present. Look in crmft.h at the
826 * definition of CRMFCertTemplateField for possible values for possible
827 * querying.
828 *
829 * RETURN:
830 * PR_TRUE iff the field corresponding to 'inField' has been specified as part
831 * of 'inCertReq'
832 * PR_FALSE iff the field corresponding to 'inField' has not been speicified
833 * as part of 'inCertReq'
834 *
835 */
836 extern PRBool CRMF_DoesRequestHaveField(CRMFCertRequest *inCertReq,
837 CRMFCertTemplateField inField);
838
839 /*
840 * FUNCTION: CRMF_CertReqMsgGetCertRequest
841 * INPUTS:
842 * inCertReqMsg
843 * The Certificate Request Message to operate on.
844 * NOTES:
845 * This function returns a copy of the Certificate Request to the user.
846 * The user can keep adding to this request and then making it a part
847 * of another message. After the user no longer wants to use the
848 * returned request, the user must call CRMF_DestroyCertRequest and
849 * pass it the request returned by this function.
850 * RETURN:
851 * A pointer to a copy of the certificate request contained by the message.
852 * A NULL return value indicates an error occurred while copying the
853 * certificate request.
854 */
855 extern CRMFCertRequest *
856 CRMF_CertReqMsgGetCertRequest(CRMFCertReqMsg *inCertReqMsg);
857
858 /*
859 * FUNCTION: CRMF_CertRequestGetCertTemplateVersion
860 * INPUTS:
861 * inCertReq
862 * The Certificate Request to operate on.
863 * version
864 * A pointer to where the library can store the version contatined
865 * in the certificate template within the certifcate request.
866 * RETURN:
867 * SECSuccess if the Certificate template contains the version field. In
868 * this case, *version will hold the value of the certificate template
869 * version.
870 * SECFailure indicates that version field was not present as part of
871 * of the certificate template.
872 */
873 extern SECStatus
874 CRMF_CertRequestGetCertTemplateVersion(CRMFCertRequest *inCertReq,
875 long *version);
876
877 /*
878 * FUNCTION: CRMF_CertRequestGetCertTemplateSerialNumber
879 * INPUTS:
880 * inCertReq
881 * The certificate request to operate on.
882 * serialNumber
883 * A pointer where the library can put the serial number contained
884 * in the certificate request's certificate template.
885 * RETURN:
886 * If a serial number exists in the CertTemplate of the request, the function
887 * returns SECSuccess and the value at *serialNumber contains the serial
888 * number.
889 * If no serial number is present, then the function returns SECFailure and
890 * the value at *serialNumber is un-changed.
891 */
892 extern SECStatus
893 CRMF_CertRequestGetCertTemplateSerialNumber(CRMFCertRequest *inCertReq,
894 long *serialNumber);
895
896 /*
897 * FUNCTION: CRMF_CertRequestGetCertTemplateSigningAlg
898 * INPUT:
899 * inCertReq
900 * The Certificate Request to operate on.
901 * destAlg
902 * A Pointer to where the library can place a copy of the signing alg
903 * used in the cert request's cert template.
904 * RETURN:
905 * If the signingAlg is present in the CertRequest's CertTemplate, then
906 * the function returns SECSuccess and places a copy of sigingAlg in
907 * *destAlg.
908 * If no signingAlg is present, then the function returns SECFailure and
909 * the value at *destAlg is un-changed
910 */
911 extern SECStatus
912 CRMF_CertRequestGetCertTemplateSigningAlg(CRMFCertRequest *inCertReq,
913 SECAlgorithmID *destAlg);
914 /*
915 * FUNCTION: CRMF_CertRequestGetCertTemplateIssuer
916 * INPUTS:
917 * inCertReq
918 * The Certificate Request to operate on.
919 * destIssuer
920 * A pointer to where the library can place a copy of the cert
921 * request's cert template issuer field.
922 * RETURN:
923 * If the issuer is present in the cert request cert template, the function
924 * returns SECSuccess and places a copy of the issuer in *destIssuer.
925 * If there is no issuer present, the function returns SECFailure and the
926 * value at *destIssuer is unchanged.
927 */
928 extern SECStatus
929 CRMF_CertRequestGetCertTemplateIssuer(CRMFCertRequest *inCertReq,
930 CERTName *destIssuer);
931
932 /*
933 * FUNCTION: CRMF_CertRequestGetCertTemplateValidity
934 * INPUTS:
935 * inCertReq
936 * The Certificate Request to operate on.
937 * destValdity
938 * A pointer to where the library can place a copy of the validity
939 * info in the cert request cert template.
940 * NOTES:
941 * Pass the pointer to
942 * RETURN:
943 * If there is an OptionalValidity field, the function will return SECSuccess
944 * and place the appropriate values in *destValidity->notBefore and
945 * *destValidity->notAfter. (Each field is optional, but at least one will
946 * be present if the function returns SECSuccess)
947 *
948 * If there is no OptionalValidity field, the function will return SECFailure
949 * and the values at *destValidity will be un-changed.
950 */
951 extern SECStatus
952 CRMF_CertRequestGetCertTemplateValidity(CRMFCertRequest *inCertReq,
953 CRMFGetValidity *destValidity);
954 /*
955 * FUNCTION: CRMF_DestroyGetValidity
956 * INPUTS:
957 * inValidity
958 * A pointer to the memroy to be freed.
959 * NOTES:
960 * The function will free the memory allocated by the function
961 * CRMF_CertRequestGetCertTemplateValidity. That means only memory pointed
962 * to within the CRMFGetValidity structure. Since
963 * CRMF_CertRequestGetCertTemplateValidity does not allocate memory for the
964 * structure passed into it, it will not free it. Meaning this function will
965 * free the memory at inValidity->notBefore and inValidity->notAfter, but not
966 * the memory directly at inValdity.
967 *
968 * RETURN:
969 * SECSuccess if freeing the memory was successful. Any other return value
970 * indicates an error while freeing the memory.
971 */
972 extern SECStatus
973 CRMF_DestroyGetValidity(CRMFGetValidity *inValidity);
974
975 /*
976 * FUNCTION: CRMF_CertRequestGetCertTemplateSubject
977 * INPUTS:
978 * inCertReq
979 * The Certificate Request to operate on.
980 * destSubject
981 * A pointer to where the library can place a copy of the subject
982 * contained in the request's cert template.
983 * RETURN:
984 * If there is a subject in the CertTemplate, then the function returns
985 * SECSuccess and a copy of the subject is placed in *destSubject.
986 *
987 * If there is no subject, the function returns SECFailure and the values at
988 * *destSubject is unchanged.
989 */
990 extern SECStatus
991 CRMF_CertRequestGetCertTemplateSubject (CRMFCertRequest *inCertReq,
992 CERTName *destSubject);
993
994 /*
995 * FUNCTION: CRMF_CertRequestGetCertTemplatePublicKey
996 * INPUTS:
997 * inCertReq
998 * The Cert request to operate on.
999 * destPublicKey
1000 * A pointer to where the library can place a copy of the request's
1001 * cert template public key.
1002 * RETURN:
1003 * If there is a publicKey parameter in the CertRequest, the function returns
1004 * SECSuccess, and places a copy of the publicKey in *destPublicKey.
1005 *
1006 * If there is no publicKey, the function returns SECFailure and the value
1007 * at *destPublicKey is un-changed.
1008 */
1009 extern SECStatus
1010 CRMF_CertRequestGetCertTemplatePublicKey(CRMFCertRequest *inCertReq,
1011 CERTSubjectPublicKeyInfo *destPublicKey);
1012
1013 /*
1014 * FUNCTION: CRMF_CertRequestGetCertTemplateIssuerUID
1015 * INPUTS:
1016 * inCertReq
1017 * The Cert request to operate on.
1018 * destIssuerUID
1019 * A pointer to where the library can store a copy of the request's
1020 * cert template destIssuerUID.
1021 *
1022 * NOTES:
1023 * destIssuerUID is a bit string and will be returned in a SECItem as
1024 * a bit string. Meaning the len field contains the number of valid bits as
1025 * opposed to the number of bytes allocated.
1026 *
1027 * RETURN:
1028 * If the CertTemplate has an issuerUID, the function returns SECSuccess and
1029 * places a copy of the issuerUID in *destIssuerUID.
1030 *
1031 * If there is no issuerUID, the function returns SECFailure and the value
1032 * *destIssuerUID is unchanged.
1033 */
1034 extern SECStatus
1035 CRMF_CertRequestGetCertTemplateIssuerUID(CRMFCertRequest *inCertReq,
1036 SECItem *destIssuerUID);
1037
1038 /*
1039 * FUNCTION: CRMF_CertRequestGetCertTemplateSubjectUID
1040 * inCertReq
1041 * The Cert request to operate on.
1042 * destSubjectUID
1043 * A pointer to where the library can store a copy of the request's
1044 * cert template destIssuerUID.
1045 *
1046 * NOTES:
1047 * destSubjectUID is a bit string and will be returned in a SECItem as
1048 * a bit string. Meaning the len field contains the number of valid bits as
1049 * opposed to the number of bytes allocated.
1050 *
1051 * RETURN:
1052 * If the CertTemplate has an issuerUID, the function returns SECSuccess and
1053 * places a copy of the issuerUID in *destIssuerUID.
1054 *
1055 * If there is no issuerUID, the function returns SECSuccess and the value
1056 * *destIssuerUID is unchanged.
1057 */
1058 extern SECStatus CRMF_GetCertTemplateSubjectUID(CRMFCertRequest *inCertReq,
1059 SECItem *destSubjectUID);
1060
1061 /*
1062 * FUNCTION: CRMF_CertRequestGetNumberOfExtensions
1063 * INPUTS:
1064 * inCertReq
1065 * The cert request to operate on.
1066 * RETURN:
1067 * Returns the number of extensions contained by the Cert Request.
1068 */
1069 extern int CRMF_CertRequestGetNumberOfExtensions(CRMFCertRequest *inCertReq);
1070
1071 /*
1072 * FUNCTION: CRMF_CertRequestGetExtensionAtIndex
1073 * INPUTS:
1074 * inCertReq
1075 * The Certificate request to operate on.
1076 * index
1077 * The index of the extension array whihc the user wants to access.
1078 * NOTES:
1079 * This function retrieves the extension at the index corresponding to the
1080 * parameter "index" indicates. Indexing is done like a C array.
1081 * (0 ... numElements-1)
1082 *
1083 * Call CRMF_DestroyCertExtension when done using the return value.
1084 *
1085 * RETURN:
1086 * A pointer to a copy of the extension at the desired index. A NULL
1087 * return value indicates an invalid index or an error while copying
1088 * the extension.
1089 */
1090 extern CRMFCertExtension *
1091 CRMF_CertRequestGetExtensionAtIndex(CRMFCertRequest *inCertReq,
1092 int index);
1093 /*
1094 * FUNCTION: CRMF_CertExtensionGetOidTag
1095 * INPUTS:
1096 * inExtension
1097
1098 * The extension to operate on.
1099 * RETURN:
1100 * Returns the SECOidTag associated with the cert extension passed in.
1101 */
1102 extern SECOidTag CRMF_CertExtensionGetOidTag(CRMFCertExtension *inExtension);
1103
1104 /*
1105 * FUNCTION: CRMF_CertExtensionGetIsCritical
1106 * INPUT:
1107 * inExt
1108 * The cert extension to operate on.
1109 *
1110 * RETURN:
1111 * PR_TRUE if the extension is critical.
1112 * PR_FALSE if the extension is not critical.
1113 */
1114 extern PRBool CRMF_CertExtensionGetIsCritical(CRMFCertExtension *inExt);
1115
1116 /*
1117 * FUNCTION: CRMF_CertExtensionGetValue
1118 * INPUT:
1119 * inExtension
1120 * The extension to operate on.
1121 * NOTES:
1122 * Caller is responsible for freeing the memory associated with the return
1123 * value. Call SECITEM_FreeItem(retVal, PR_TRUE) when done using the return
1124 * value.
1125 *
1126 * RETURN:
1127 * A pointer to an item containig the value for the certificate extension.
1128 * A NULL return value indicates an error in copying the information.
1129 */
1130 extern SECItem* CRMF_CertExtensionGetValue(CRMFCertExtension *inExtension);
1131
1132 /*
1133 * FUNCTION: CRMF_CertReqMsgGetPOPOSigningKey
1134 * INPUTS:
1135 * inCertReqMsg
1136 * The certificate request message to operate on.
1137 * destKey
1138 * A pointer to where the library can place a pointer to
1139 * a copy of the Proof Of Possession Signing Key used
1140 * by the message.
1141 *
1142 * RETURN:
1143 * Get the POPOSigningKey associated with this CRMFCertReqMsg.
1144 * If the CertReqMsg does not have a pop, the function returns
1145 * SECFailure and the value at *destKey is un-changed..
1146 *
1147 * If the CertReqMsg does have a pop, then the CertReqMsg's
1148 * POPOSigningKey will be placed at *destKey.
1149 */
1150 extern SECStatus
1151 CRMF_CertReqMsgGetPOPOSigningKey(CRMFCertReqMsg *inCertReqMsg,
1152 CRMFPOPOSigningKey **destKey);
1153
1154 /*
1155 * FUNCTION: CRMF_DestroyPOPOSigningKey
1156 * INPUTS:
1157 * inKey
1158 * The signing key to free.
1159 *
1160 * RETURN:
1161 * SECSuccess if freeing the memory was successful. Any other return value
1162 * indicates an error while freeing memory.
1163 */
1164 extern SECStatus CRMF_DestroyPOPOSigningKey (CRMFPOPOSigningKey *inKey);
1165
1166 /*
1167 * FUNCTION: CRMF_POPOSigningKeyGetAlgID
1168 * INPUTS:
1169 * inSignKey
1170 * The Signing Key to operate on.
1171 * RETURN:
1172 * Return the algorithmID used by the CRMFPOPOSigningKey. User must
1173 * call SECOID_DestroyAlgorithmID(destID, PR_TRUE) when done using the
1174 * return value.
1175 */
1176 extern SECAlgorithmID*
1177 CRMF_POPOSigningKeyGetAlgID(CRMFPOPOSigningKey *inSignKey);
1178
1179 /*
1180 * FUNCTION: CRMF_POPOSigningKeyGetSignature
1181 * INPUTS:
1182 * inSignKey
1183 * The Signing Key to operate on.
1184 *
1185 * RETURN:
1186 * Get the actual signature stored away in the CRMFPOPOSigningKey. SECItem
1187 * returned is a BIT STRING, so the len field is the number of bits as opposed
1188 * to the total number of bytes allocatd. User must call
1189 * SECITEM_FreeItem(retVal,PR_TRUE) when done using the return value.
1190 */
1191 extern SECItem* CRMF_POPOSigningKeyGetSignature(CRMFPOPOSigningKey *inSignKey);
1192
1193 /*
1194 * FUNCTION: CRMF_POPOSigningKeyGetInput
1195 * INPUTS:
1196 * inSignKey
1197 * The Signing Key to operate on.
1198 * NOTES:
1199 * This function will return the der encoded input that was read in while
1200 * decoding. The API does not support this option when creating, so you
1201 * cannot add this field.
1202 *
1203 * RETURN:
1204 * Get the poposkInput that is part of the of the POPOSigningKey. If the
1205 * optional field is not part of the POPOSigningKey, the function returns
1206 * NULL.
1207 *
1208 * If the optional field is part of the POPOSingingKey, the function will
1209 * return a copy of the der encoded poposkInput.
1210 */
1211 extern SECItem* CRMF_POPOSigningKeyGetInput(CRMFPOPOSigningKey *inSignKey);
1212
1213 /*
1214 * FUNCTION: CRMF_CertReqMsgGetPOPKeyEncipherment
1215 * INPUTS:
1216 * inCertReqMsg
1217 * The certificate request message to operate on.
1218 * destKey
1219 * A pointer to where the library can place a pointer to a
1220 * copy of the POPOPrivKey representing Key Encipherment
1221 * Proof of Possession.
1222 *NOTES:
1223 * This function gets the POPOPrivKey associated with this CRMFCertReqMsg
1224 * for Key Encipherment.
1225 *
1226 * RETURN:
1227 * If the CertReqMsg did not use Key Encipherment for Proof Of Possession, the
1228 * function returns SECFailure and the value at *destKey is un-changed.
1229 *
1230 * If the CertReqMsg did use Key Encipherment for ProofOfPossession, the
1231 * function returns SECSuccess and places the POPOPrivKey representing the
1232 * Key Encipherment Proof Of Possessin at *destKey.
1233 */
1234 extern SECStatus
1235 CRMF_CertReqMsgGetPOPKeyEncipherment(CRMFCertReqMsg *inCertReqMsg,
1236 CRMFPOPOPrivKey **destKey);
1237
1238 /*
1239 * FUNCTION: CRMF_CertReqMsgGetPOPKeyAgreement
1240 * INPUTS:
1241 * inCertReqMsg
1242 * The certificate request message to operate on.
1243 * destKey
1244 * A pointer to where the library can place a pointer to a
1245 * copy of the POPOPrivKey representing Key Agreement
1246 * Proof of Possession.
1247 * NOTES:
1248 * This function gets the POPOPrivKey associated with this CRMFCertReqMsg for
1249 * Key Agreement.
1250 *
1251 * RETURN:
1252 * If the CertReqMsg used Key Agreement for Proof Of Possession, the
1253 * function returns SECSuccess and the POPOPrivKey for Key Agreement
1254 * is placed at *destKey.
1255 *
1256 * If the CertReqMsg did not use Key Agreement for Proof Of Possession, the
1257 * function return SECFailure and the value at *destKey is unchanged.
1258 */
1259 extern SECStatus
1260 CRMF_CertReqMsgGetPOPKeyAgreement(CRMFCertReqMsg *inCertReqMsg,
1261 CRMFPOPOPrivKey **destKey);
1262
1263 /*
1264 * FUNCTION: CRMF_DestroyPOPOPrivKey
1265 * INPUTS:
1266 * inPrivKey
1267 * The POPOPrivKey to destroy.
1268 * NOTES:
1269 * Destroy a structure allocated by CRMF_GetPOPKeyEncipherment or
1270 * CRMF_GetPOPKeyAgreement.
1271 *
1272 * RETURN:
1273 * SECSuccess on successful destruction of the POPOPrivKey.
1274 * Any other return value indicates an error in freeing the
1275 * memory.
1276 */
1277 extern SECStatus CRMF_DestroyPOPOPrivKey(CRMFPOPOPrivKey *inPrivKey);
1278
1279 /*
1280 * FUNCTION: CRMF_POPOPrivKeyGetChoice
1281 * INPUT:
1282 * inKey
1283 * The POPOPrivKey to operate on.
1284 * RETURN:
1285 * Returns which choice was used in constructing the POPPOPrivKey. Look at
1286 * the definition of CRMFPOPOPrivKeyChoice in crmft.h for the possible return
1287 * values.
1288 */
1289 extern CRMFPOPOPrivKeyChoice CRMF_POPOPrivKeyGetChoice(CRMFPOPOPrivKey *inKey);
1290
1291 /*
1292 * FUNCTION: CRMF_POPOPrivKeyGetThisMessage
1293 * INPUTS:
1294 * inKey
1295 * The POPOPrivKey to operate on.
1296 * destString
1297 * A pointer to where the library can place a copy of the This Message
1298 * field stored in the POPOPrivKey
1299 *
1300 * RETURN:
1301 * Returns the field thisMessage from the POPOPrivKey.
1302 * If the POPOPrivKey did not use the field thisMessage, the function
1303 * returns SECFailure and the value at *destString is unchanged.
1304 *
1305 * If the POPOPrivKey did use the field thisMessage, the function returns
1306 * SECSuccess and the BIT STRING representing thisMessage is placed
1307 * at *destString. BIT STRING representation means the len field is the
1308 * number of valid bits as opposed to the total number of bytes.
1309 */
1310 extern SECStatus CRMF_POPOPrivKeyGetThisMessage(CRMFPOPOPrivKey *inKey,
1311 SECItem *destString);
1312
1313 /*
1314 * FUNCTION: CRMF_POPOPrivKeyGetSubseqMess
1315 * INPUTS:
1316 * inKey
1317 * The POPOPrivKey to operate on.
1318 * destOpt
1319 * A pointer to where the library can place the value of the
1320 * Subsequent Message option used by POPOPrivKey.
1321 *
1322 * RETURN:
1323 * Retrieves the field subsequentMessage from the POPOPrivKey.
1324 * If the POPOPrivKey used the subsequentMessage option, the function
1325 * returns SECSuccess and places the appropriate enumerated value at
1326 * *destMessageOption.
1327 *
1328 * If the POPOPrivKey did not use the subsequenMessage option, the function
1329 * returns SECFailure and the value at *destOpt is un-changed.
1330 */
1331 extern SECStatus CRMF_POPOPrivKeyGetSubseqMess(CRMFPOPOPrivKey *inKey,
1332 CRMFSubseqMessOptions *destOpt);
1333
1334 /*
1335 * FUNCTION: CRMF_POPOPrivKeyGetDHMAC
1336 * INPUTS:
1337 * inKey
1338 * The POPOPrivKey to operate on.
1339 * destMAC
1340 * A pointer to where the library can place a copy of the dhMAC
1341 * field of the POPOPrivKey.
1342 *
1343 * NOTES:
1344 * Returns the field dhMAC from the POPOPrivKey. The populated SECItem
1345 * is in BIT STRING format.
1346 *
1347 * RETURN:
1348 * If the POPOPrivKey used the dhMAC option, the function returns SECSuccess
1349 * and the BIT STRING for dhMAC will be placed at *destMAC. The len field in
1350 * destMAC (ie destMAC->len) will be the valid number of bits as opposed to
1351 * the number of allocated bytes.
1352 *
1353 * If the POPOPrivKey did not use the dhMAC option, the function returns
1354 * SECFailure and the value at *destMAC is unchanged.
1355 *
1356 */
1357 extern SECStatus CRMF_POPOPrivKeyGetDHMAC(CRMFPOPOPrivKey *inKey,
1358 SECItem *destMAC);
1359
1360 /*
1361 * FUNCTION: CRMF_CertRequestGetNumControls
1362 * INPUTS:
1363 * inCertReq
1364 * The Certificate Request to operate on.
1365 * RETURN:
1366 * Returns the number of Controls registered with this CertRequest.
1367 */
1368 extern int CRMF_CertRequestGetNumControls (CRMFCertRequest *inCertReq);
1369
1370 /*
1371 * FUNCTION: CRMF_CertRequestGetControlAtIndex
1372 * INPUTS:
1373 * inCertReq
1374 * The certificate request to operate on.
1375 * index
1376 * The index of the control the user wants a copy of.
1377 * NOTES:
1378 * Function retrieves the Control at located at index. The Controls
1379 * are numbered like a traditional C array (0 ... numElements-1)
1380 *
1381 * RETURN:
1382 * Returns a copy of the control at the index specified. This is a copy
1383 * so the user must call CRMF_DestroyControl after the return value is no
1384 * longer needed. A return value of NULL indicates an error while copying
1385 * the control or that the index was invalid.
1386 */
1387 extern CRMFControl*
1388 CRMF_CertRequestGetControlAtIndex(CRMFCertRequest *inCertReq,
1389 int index);
1390
1391 /*
1392 * FUNCTION: CRMF_DestroyControl
1393 * INPUTS:
1394 * inControl
1395 * The Control to destroy.
1396 * NOTES:
1397 * Destroy a CRMFControl allocated by CRMF_GetControlAtIndex.
1398 *
1399 * RETURN:
1400 * SECSuccess if freeing the memory was successful. Any other return
1401 * value indicates an error while freeing the memory.
1402 */
1403 extern SECStatus CRMF_DestroyControl(CRMFControl *inControl);
1404
1405 /*
1406 * FUNCTION: CRMF_ControlGetControlType
1407 * INPUTS:
1408 * inControl
1409 * The control to operate on.
1410 * NOTES:
1411 * The function returns an enumertion which indicates the type of control
1412 * 'inControl'.
1413 *
1414 * RETURN:
1415 * Look in crmft.h at the definition of the enumerated type CRMFControlType
1416 * for the possible return values.
1417 */
1418 extern CRMFControlType CRMF_ControlGetControlType(CRMFControl *inControl);
1419
1420 /*
1421 * FUNCTION: CRMF_ControlGetRegTokenControlValue
1422 * INPUTS:
1423 * inControl
1424 * The Control to operate on.
1425 * NOTES:
1426 * The user must call SECITEM_FreeItem passing in the return value
1427 * after the returnvalue is no longer needed.
1428
1429 * RETURN:
1430 * Return the value for a Registration Token Control.
1431 * The SECItem returned should be in UTF8 format. A NULL
1432 * return value indicates there was no Registration Control associated
1433 * with the Control.
1434 * (This library will not verify format. It assumes the client properly
1435 * formatted the strings when adding it or the message decoded was properly
1436 * formatted. The library will just give back the bytes it was given.)
1437 */
1438 extern SECItem* CRMF_ControlGetRegTokenControlValue(CRMFControl *inControl);
1439
1440 /*
1441 * FUNCTION: CRMF_ControlGetAuthenticatorControlValue
1442 * INPUTS:
1443 * inControl
1444 * The Control to operate on.
1445 * NOTES:
1446 * The user must call SECITEM_FreeItem passing in the return value
1447 * after the returnvalue is no longer needed.
1448 *
1449 * RETURN:
1450 * Return the value for the Authenticator Control.
1451 * The SECItem returned should be in UTF8 format. A NULL
1452 * return value indicates there was no Authenticator Control associated
1453 * with the CRMFControl..
1454 * (This library will not verify format. It assumes the client properly
1455 * formatted the strings when adding it or the message decoded was properly
1456 * formatted. The library will just give back the bytes it was given.)
1457 */
1458 extern SECItem* CRMF_ControlGetAuthicatorControlValue(CRMFControl *inControl);
1459
1460 /*
1461 * FUNCTION: CRMF_ControlGetPKIArchiveOptions
1462 * INPUTS:inControl
1463 * The Control tooperate on.
1464 * NOTES:
1465 * This function returns a copy of the PKIArchiveOptions. The user must call
1466 * the function CRMF_DestroyPKIArchiveOptions when the return value is no
1467 * longer needed.
1468 *
1469 * RETURN:
1470 * Get the PKIArchiveOptions associated with the Control. A return
1471 * value of NULL indicates the Control was not a PKIArchiveOptions
1472 * Control.
1473 */
1474 extern CRMFPKIArchiveOptions*
1475 CRMF_ControlGetPKIArchiveOptions(CRMFControl *inControl);
1476
1477 /*
1478 * FUNCTION: CMRF_DestroyPKIArchiveOptions
1479 * INPUTS:
1480 * inOptions
1481 * The ArchiveOptions to destroy.
1482 * NOTE:
1483 * Destroy the CRMFPKIArchiveOptions structure.
1484 *
1485 * RETURN:
1486 * SECSuccess if successful in freeing all the memory associated with
1487 * the PKIArchiveOptions. Any other return value indicates an error while
1488 * freeing the PKIArchiveOptions.
1489 */
1490 extern SECStatus
1491 CRMF_DestroyPKIArchiveOptions(CRMFPKIArchiveOptions *inOptions);
1492
1493 /*
1494 * FUNCTION: CRMF_PKIArchiveOptionsGetOptionType
1495 * INPUTS:
1496 * inOptions
1497 * The PKIArchiveOptions to operate on.
1498 * RETURN:
1499 * Returns the choice used for the PKIArchiveOptions. Look at the definition
1500 * of CRMFPKIArchiveOptionsType in crmft.h for possible return values.
1501 */
1502 extern CRMFPKIArchiveOptionsType
1503 CRMF_PKIArchiveOptionsGetOptionType(CRMFPKIArchiveOptions *inOptions);
1504
1505 /*
1506 * FUNCTION: CRMF_PKIArchiveOptionsGetEncryptedPrivKey
1507 * INPUTS:
1508 * inOpts
1509 * The PKIArchiveOptions to operate on.
1510 *
1511 * NOTES:
1512 * The user must call CRMF_DestroyEncryptedKey when done using this return
1513 * value.
1514 *
1515 * RETURN:
1516 * Get the encryptedPrivKey field of the PKIArchiveOptions structure.
1517 * A return value of NULL indicates that encryptedPrivKey was not used as
1518 * the choice for this PKIArchiveOptions.
1519 */
1520 extern CRMFEncryptedKey*
1521 CRMF_PKIArchiveOptionsGetEncryptedPrivKey(CRMFPKIArchiveOptions *inOpts);
1522
1523 /*
1524 * FUNCTION: CRMF_EncryptedKeyGetChoice
1525 * INPUTS:
1526 * inEncrKey
1527 * The EncryptedKey to operate on.
1528 *
1529 * NOTES:
1530 * Get the choice used for representing the EncryptedKey.
1531 *
1532 * RETURN:
1533 * Returns the Choice used in representing the EncryptedKey. Look in
1534 * crmft.h at the definition of CRMFEncryptedKeyChoice for possible return
1535 * values.
1536 */
1537 extern CRMFEncryptedKeyChoice
1538 CRMF_EncryptedKeyGetChoice(CRMFEncryptedKey *inEncrKey);
1539
1540
1541 /*
1542 * FUNCTION: CRMF_EncryptedKeyGetEncryptedValue
1543 * INPUTS:
1544 * inKey
1545 * The EncryptedKey to operate on.
1546 *
1547 * NOTES:
1548 * The user must call CRMF_DestroyEncryptedValue passing in
1549 * CRMF_GetEncryptedValue's return value.
1550 *
1551 * RETURN:
1552 * A pointer to a copy of the EncryptedValue contained as a member of
1553 * the EncryptedKey.
1554 */
1555 extern CRMFEncryptedValue*
1556 CRMF_EncryptedKeyGetEncryptedValue(CRMFEncryptedKey *inKey);
1557
1558 /*
1559 * FUNCTION: CRMF_DestroyEncryptedValue
1560 * INPUTS:
1561 * inEncrValue
1562 * The EncryptedValue to destroy.
1563 *
1564 * NOTES:
1565 * Free up all memory associated with 'inEncrValue'.
1566 *
1567 * RETURN:
1568 * SECSuccess if freeing up the memory associated with the EncryptedValue
1569 * is successful. Any other return value indicates an error while freeing the
1570 * memory.
1571 */
1572 extern SECStatus CRMF_DestroyEncryptedValue(CRMFEncryptedValue *inEncrValue);
1573
1574 /*
1575 * FUNCTION: CRMF_EncryptedValueGetEncValue
1576 * INPUTS:
1577 * inEncValue
1578 * The EncryptedValue to operate on.
1579 * NOTES:
1580 * Function retrieves the encValue from an EncryptedValue structure.
1581 *
1582 * RETURN:
1583 * A poiner to a SECItem containing the encValue of the EncryptedValue
1584 * structure. The return value is in BIT STRING format, meaning the
1585 * len field of the return structure represents the number of valid bits
1586 * as opposed to the allocated number of bytes.
1587 * ANULL return value indicates an error in copying the encValue field.
1588 */
1589 extern SECItem* CRMF_EncryptedValueGetEncValue(CRMFEncryptedValue *inEncValue);
1590
1591 /*
1592 * FUNCTION: CRMF_EncryptedValueGetIntendedAlg
1593 * INPUTS
1594 * inEncValue
1595 * The EncryptedValue to operate on.
1596 * NOTES:
1597 * Retrieve the IntendedAlg field from the EncryptedValue structure.
1598 * Call SECOID_DestroyAlgorithmID (destAlgID, PR_TRUE) after done using
1599 * the return value. When present, this alogorithm is the alogrithm for
1600 * which the private key will be used.
1601 *
1602 * RETURN:
1603 * A Copy of the intendedAlg field. A NULL return value indicates the
1604 * optional field was not present in the structure.
1605 */
1606 extern SECAlgorithmID*
1607 CRMF_EncryptedValueGetIntendedAlg(CRMFEncryptedValue *inEncValue);
1608
1609
1610 /*
1611 * FUNCTION: CRMF_EncryptedValueGetSymmAlg
1612 * INPUTS
1613 * inEncValue
1614 * The EncryptedValue to operate on.
1615 * NOTES:
1616 * Retrieve the symmAlg field from the EncryptedValue structure.
1617 * Call SECOID_DestroyAlgorithmID (destAlgID, PR_TRUE) after done using
1618 * the return value. When present, this is algorithm used to
1619 * encrypt the encValue of the EncryptedValue.
1620 *
1621 * RETURN:
1622 * A Copy of the symmAlg field. A NULL return value indicates the
1623 * optional field was not present in the structure.
1624 */
1625 extern SECAlgorithmID*
1626 CRMF_EncryptedValueGetSymmAlg(CRMFEncryptedValue *inEncValue);
1627
1628
1629 /*
1630 * FUNCTION: CRMF_EncryptedValueGetKeyAlg
1631 * INPUTS
1632 * inEncValue
1633 * The EncryptedValue to operate on.
1634 * NOTES:
1635 * Retrieve the keyAlg field from the EncryptedValue structure.
1636 * Call SECOID_DestroyAlgorithmID (destAlgID, PR_TRUE) after done using
1637 * the return value. When present, this is the algorithm used to encrypt
1638 * the symmetric key in the encSymmKey field of the EncryptedValue structure.
1639 *
1640 * RETURN:
1641 * A Copy of the keyAlg field. A NULL return value indicates the
1642 * optional field was not present in the structure.
1643 */
1644 extern SECAlgorithmID*
1645 CRMF_EncryptedValueGetKeyAlg(CRMFEncryptedValue *inEncValue);
1646
1647 /*
1648 * FUNCTION: CRMF_EncryptedValueGetValueHint
1649 * INPUTS:
1650 * inEncValue
1651 * The EncryptedValue to operate on.
1652 *
1653 * NOTES:
1654 * Return a copy of the der-encoded value hint.
1655 * User must call SECITEM_FreeItem(retVal, PR_TRUE) when done using the
1656 * return value. When, present, this is a value that the client which
1657 * originally issued a certificate request can use to reproduce any data
1658 * it wants. The RA does not know how to interpret this data.
1659 *
1660 * RETURN:
1661 * A copy of the valueHint field of the EncryptedValue. A NULL return
1662 * value indicates the optional valueHint field is not present in the
1663 * EncryptedValue.
1664 */
1665 extern SECItem*
1666 CRMF_EncryptedValueGetValueHint(CRMFEncryptedValue *inEncValue);
1667
1668 /*
1669 * FUNCTION: CRMF_EncrypteValueGetEncSymmKey
1670 * INPUTS:
1671 * inEncValue
1672 * The EncryptedValue to operate on.
1673 *
1674 * NOTES:
1675 * Return a copy of the encSymmKey field. This field is the encrypted
1676 * symmetric key that the client uses in doing Public Key wrap of a private
1677 * key. When present, this is the symmetric key that was used to wrap the
1678 * private key. (The encrypted private key will be stored in encValue
1679 * of the same EncryptedValue structure.) The user must call
1680 * SECITEM_FreeItem(retVal, PR_TRUE) when the return value is no longer
1681 * needed.
1682 *
1683 * RETURN:
1684 * A copy of the optional encSymmKey field of the EncryptedValue structure.
1685 * The return value will be in BIT STRING format, meaning the len field will
1686 * be the number of valid bits as opposed to the number of bytes. A return
1687 * value of NULL means the optional encSymmKey field was not present in
1688 * the EncryptedValue structure.
1689 */
1690 extern SECItem*
1691 CRMF_EncryptedValueGetEncSymmKey(CRMFEncryptedValue *inEncValue);
1692
1693 /*
1694 * FUNCTION: CRMF_PKIArchiveOptionsGetKeyGenParameters
1695 * INPUTS:
1696 * inOptions
1697 * The PKiArchiveOptions to operate on.
1698 *
1699 * NOTES:
1700 * User must call SECITEM_FreeItem(retVal, PR_TRUE) after the return
1701 * value is no longer needed.
1702 *
1703 * RETURN:
1704 * Get the keyGenParameters field of the PKIArchiveOptions.
1705 * A NULL return value indicates that keyGenParameters was not
1706 * used as the choice for this PKIArchiveOptions.
1707 *
1708 * The SECItem returned is in BIT STRING format (ie, the len field indicates
1709 * number of valid bits as opposed to allocated number of bytes.)
1710 */
1711 extern SECItem*
1712 CRMF_PKIArchiveOptionsGetKeyGenParameters(CRMFPKIArchiveOptions *inOptions);
1713
1714 /*
1715 * FUNCTION: CRMF_PKIArchiveOptionsGetArchiveRemGenPrivKey
1716 * INPUTS:
1717 * inOpt
1718 * The PKIArchiveOptions to operate on.
1719 * destVal
1720 * A pointer to where the library can place the value for
1721 * arciveRemGenPrivKey
1722 * RETURN:
1723 * If the PKIArchiveOptions used the archiveRemGenPrivKey field, the
1724 * function returns SECSuccess and fills the value at *destValue with either
1725 * PR_TRUE or PR_FALSE, depending on what the PKIArchiveOptions has as a
1726 * value.
1727 *
1728 * If the PKIArchiveOptions does not use the archiveRemGenPrivKey field, the
1729 * function returns SECFailure and the value at *destValue is unchanged.
1730 */
1731 extern SECStatus
1732 CRMF_PKIArchiveOptionsGetArchiveRemGenPrivKey(CRMFPKIArchiveOptions *inOpt,
1733 PRBool *destVal);
1734
1735 /* Helper functions that can be used by other libraries. */
1736 /*
1737 * A quick helper function to get the best wrap mechanism.
1738 */
1739 extern CK_MECHANISM_TYPE CRMF_GetBestWrapPadMechanism(PK11SlotInfo *slot);
1740
1741 /*
1742 * A helper function to get a randomly generated IV from a mechanism
1743 * type.
1744 */
1745 extern SECItem* CRMF_GetIVFromMechanism(CK_MECHANISM_TYPE mechType);
1746
1747 SEC_END_PROTOS
1748 #endif /*_CRMF_H_*/
1749
1750

Mercurial Repository: The Tor Browser

Europalab SCM Repository Server

mercurial