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