security/nss/lib/crmf/cmmf.h

   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
  51 SEC_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  */
  73 extern 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  */
  95 extern 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  */
 118 extern 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  */
 140 extern 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  */
 162 extern 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  */
 184 extern 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  */
 202 extern 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  */
 220 extern 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  */
 248 extern 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  */
 273 extern 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  */
 295 extern 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  */
 317 extern 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  */
 339 extern SECStatus
 340 CMMF_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  */
 359 extern 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  */
 381 extern 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  */
 407 extern 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  */
 443 extern SECStatus
 444 CMMF_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  */
 480 extern 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  */
 511 extern 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  */
 544 extern SECStatus
 545 CMMF_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  */
 579 extern 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  */
 613 extern 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  */
 629 extern 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  */
 651 extern CMMFCertResponse*
 652 CMMF_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  */
 669 extern 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  */
 685 extern 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  */
 708 extern 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  */
 724 extern CMMFPKIStatus
 725 CMMF_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  */
 741 extern 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  */
 764 extern 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  */
 776 extern 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  */
 796 extern 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  */
 821 extern 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  */
 834 extern 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  */
 855 extern 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  */
 885 extern 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  */
 898 extern 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  */
 923 extern 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  */
 942 extern 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  */
 957 extern 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  */
 973 extern 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  */
 989 extern 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  */
1006 extern 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  */
1043 extern 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  */
1063 extern 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  */
1099 extern 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  */
1118 extern SECStatus
1119  CMMF_DestroyPOPODecKeyChallContent (CMMFPOPODecKeyChallContent *inDecKeyCont);
1120
1121 SEC_END_PROTOS
1122 #endif /* _CMMF_H_ */