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