PageRenderTime 38ms CodeModel.GetById 16ms app.highlight 14ms RepoModel.GetById 1ms app.codeStats 1ms

/gecko_api/include/cmmf.h

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