Back to index

lightning-sunbird  0.9+nobinonly
cmmf.h
Go to the documentation of this file.
00001 /* -*- Mode: C; tab-width: 8 -*-*/
00002 /* ***** BEGIN LICENSE BLOCK *****
00003  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
00004  *
00005  * The contents of this file are subject to the Mozilla Public License Version
00006  * 1.1 (the "License"); you may not use this file except in compliance with
00007  * the License. You may obtain a copy of the License at
00008  * http://www.mozilla.org/MPL/
00009  *
00010  * Software distributed under the License is distributed on an "AS IS" basis,
00011  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
00012  * for the specific language governing rights and limitations under the
00013  * License.
00014  *
00015  * The Original Code is the Netscape security libraries.
00016  *
00017  * The Initial Developer of the Original Code is
00018  * Netscape Communications Corporation.
00019  * Portions created by the Initial Developer are Copyright (C) 1994-2000
00020  * the Initial Developer. All Rights Reserved.
00021  *
00022  * Contributor(s):
00023  *
00024  * Alternatively, the contents of this file may be used under the terms of
00025  * either the GNU General Public License Version 2 or later (the "GPL"), or
00026  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
00027  * in which case the provisions of the GPL or the LGPL are applicable instead
00028  * of those above. If you wish to allow use of your version of this file only
00029  * under the terms of either the GPL or the LGPL, and not to allow others to
00030  * use your version of this file under the terms of the MPL, indicate your
00031  * decision by deleting the provisions above and replace them with the notice
00032  * and other provisions required by the GPL or the LGPL. If you do not delete
00033  * the provisions above, a recipient may use your version of this file under
00034  * the terms of any one of the MPL, the GPL or the LGPL.
00035  *
00036  * ***** END LICENSE BLOCK ***** */
00037 
00038 #ifndef _CMMF_H_
00039 #define _CMMF_H_
00040 /*
00041  * These are the functions exported by the security library for 
00042  * implementing Certificate Management Message Formats (CMMF).
00043  *
00044  * This API is designed against July 1998 CMMF draft.  Please read this
00045  * draft before trying to use this API in an application that use CMMF.
00046  */
00047 #include "seccomon.h"
00048 #include "cmmft.h"
00049 #include "crmf.h"
00050 
00051 SEC_BEGIN_PROTOS
00052 
00053 /******************* Creation Functions *************************/
00054 
00055 /*
00056  * FUNCTION: CMMF_CreateCertRepContent
00057  * INPUTS:
00058  *    NONE
00059  * NOTES:
00060  *    This function will create an empty CMMFCertRepContent Structure.  
00061  *    The client of the library must set the CMMFCertResponses.
00062  *    Call CMMF_CertRepContentSetCertResponse to accomplish this task.
00063  *    If the client of the library also wants to include the chain of 
00064  *    CA certs required to make the certificates in CMMFCertResponse valid, 
00065  *    then the user must also set the caPubs field of CMMFCertRepContent.
00066  *    Call CMMF_CertRepContentSetCAPubs to accomplish this.  After setting
00067  *    the desired fields, the user can then call CMMF_EncodeCertRepContent 
00068  *    to DER-encode the CertRepContent.
00069  * RETURN:
00070  *    A pointer to the CMMFCertRepContent.  A NULL return value indicates 
00071  *    an error in allocating memory or failure to initialize the structure.
00072  */
00073 extern CMMFCertRepContent* CMMF_CreateCertRepContent(void);
00074 
00075 /*
00076  * FUNCTION: CMMF_CreateCertRepContentFromDER
00077  * INPUTS
00078  *    db
00079  *        The certificate database where the certificates will be placed.
00080  *        The certificates will be placed in the temporary database associated
00081  *        with the handle. 
00082  *    buf
00083  *        A buffer to the DER-encoded CMMFCertRepContent
00084  *    len
00085  *        The length in bytes of the buffer 'buf'
00086  * NOTES:
00087  *    This function passes the buffer to the ASN1 decoder and creates a
00088  *    CMMFCertRepContent structure.  The user must call 
00089  *    CMMF_DestroyCertRepContent after the return value is no longer needed.
00090  *
00091  * RETURN:
00092  *    A pointer to the CMMFCertRepContent structure.  A NULL return
00093  *    value indicates the library was unable to parse the DER.
00094  */
00095 extern CMMFCertRepContent* 
00096        CMMF_CreateCertRepContentFromDER(CERTCertDBHandle *db, 
00097                                    const char       *buf, 
00098                                    long              len);
00099 
00100 /*
00101  * FUNCTION: CMMF_CreateCertResponse
00102  * INPUTS:
00103  *    inCertReqId
00104  *        The Certificate Request Id this response is for.
00105  * NOTES:
00106  *    This creates a CMMFCertResponse.  This response should correspond
00107  *    to a request that was received via CRMF.  From the CRMF message you
00108  *    can get the Request Id to pass in as inCertReqId, in essence binding 
00109  *    a CMRFCertRequest message to the CMMFCertResponse created by this
00110  *    function.  If no requuest id is associated with the response to create
00111  *    then the user should pass in -1 for 'inCertReqId'.
00112  *
00113  * RETURN:
00114  *    A pointer to the new CMMFCertResponse corresponding to the request id 
00115  *    passed in.  A NULL return value indicates an error while trying to 
00116  *    create the CMMFCertResponse.
00117  */
00118 extern CMMFCertResponse* CMMF_CreateCertResponse(long inCertReqId);
00119 
00120 /*
00121  * FUNCTION: CMMF_CreateKeyRecRepContent
00122  * INPUTS:
00123  *    NONE
00124  * NOTES:
00125  *    This function creates a new empty CMMFKeyRecRepContent structure.
00126  *    At the very minimum, the user  must call 
00127  *    CMMF_KeyRecRepContentSetPKIStatusInfoStatus field to have an
00128  *    encodable structure.  Depending on what the response is, the user may
00129  *    have to set other fields as well to properly build up the structure so
00130  *    that it can be encoded.  Refer to the CMMF draft for how to properly
00131  *    set up a CMMFKeyRecRepContent. This is the structure that an RA returns
00132  *    to an end entity when doing key recovery.
00133 
00134  *    The user must call CMMF_DestroyKeyRecRepContent when the return value
00135  *    is no longer needed.
00136  * RETURN:
00137  *    A pointer to the empty CMMFKeyRecRepContent.  A return value of NULL
00138  *    indicates an error in allocating memory or initializing the structure.
00139  */
00140 extern CMMFKeyRecRepContent *CMMF_CreateKeyRecRepContent(void);
00141 
00142 /*
00143  * FUNCTION: CMMF_CreateKeyRecRepContentFromDER
00144  * INPUTS:
00145  *    db
00146  *        The handle for the certificate database where the decoded 
00147  *        certificates will be placed.  The decoded certificates will
00148  *        be placed in the temporary database associated with the 
00149  *        handle.
00150  *    buf
00151  *        A buffer contatining the DER-encoded CMMFKeyRecRepContent
00152  *    len
00153  *        The length in bytes of the buffer 'buf'
00154  * NOTES
00155  *    This function passes the buffer to the ASN1 decoder and creates a 
00156  *    CMMFKeyRecRepContent structure.
00157  *
00158  * RETURN:
00159  *    A pointer to the CMMFKeyRecRepContent structure.  A NULL return
00160  *    value indicates the library was unable to parse the DER.
00161  */
00162 extern CMMFKeyRecRepContent* 
00163        CMMF_CreateKeyRecRepContentFromDER(CERTCertDBHandle *db,
00164                                      const char       *buf,
00165                                      long              len);
00166 
00167 /*
00168  * FUNCTION: CMMF_CreatePOPODecKeyChallContent
00169  * INPUTS:
00170  *    NONE
00171  * NOTES:
00172  *    This function creates an empty CMMFPOPODecKeyChallContent.  The user
00173  *    must add the challenges individually specifying the random number to
00174  *    be used and the public key to be used when creating each individual 
00175  *    challenge.  User can accomplish this by calling the function 
00176  *    CMMF_POPODecKeyChallContentSetNextChallenge.
00177  * RETURN:
00178  *    A pointer to a CMMFPOPODecKeyChallContent structure.  Ther user can
00179  *    then call CMMF_EncodePOPODecKeyChallContent passing in the return
00180  *    value from this function after setting all of the challenges.  A 
00181  *    return value of NULL indicates an error while creating the 
00182  *    CMMFPOPODecKeyChallContent structure.
00183  */
00184 extern CMMFPOPODecKeyChallContent*
00185        CMMF_CreatePOPODecKeyChallContent(void);
00186 
00187 /*
00188  * FUNCTION: CMMF_CreatePOPODecKeyChallContentFromDER
00189  * INPUTS
00190  *    buf
00191  *        A buffer containing the DER-encoded CMMFPOPODecKeyChallContent
00192  *    len
00193  *        The length in bytes of the buffer 'buf'
00194  * NOTES:
00195  *    This function passes the buffer to the ASN1 decoder and creates a
00196  *    CMMFPOPODecKeyChallContent structure.  
00197  *
00198  * RETURN:
00199  *    A pointer to the CMMFPOPODecKeyChallContent structure.  A NULL return
00200  *    value indicates the library was unable to parse the DER.
00201  */
00202 extern CMMFPOPODecKeyChallContent*
00203        CMMF_CreatePOPODecKeyChallContentFromDER(const char *buf, long len);
00204 
00205 /*
00206  * FUNCTION: CMMF_CreatePOPODecKeyRespContentFromDER
00207  * INPUTS:
00208  *    buf
00209  *        A buffer contatining the DER-encoded CMMFPOPODecKeyRespContent
00210  *    len
00211  *        The length in bytes of the buffer 'buf'
00212  * NOTES
00213  *    This function passes the buffer to the ASN1 decoder and creates a 
00214  *    CMMFPOPODecKeyRespContent structure.
00215  *
00216  * RETURN:
00217  *    A pointer to the CMMFPOPODecKeyRespContent structure.  A NULL return
00218  *    value indicates the library was unable to parse the DER.
00219  */
00220 extern CMMFPOPODecKeyRespContent*
00221        CMMF_CreatePOPODecKeyRespContentFromDER(const char *buf, long len);
00222 
00223 /************************** Set Functions *************************/
00224 
00225 /*
00226  * FUNCTION: CMMF_CertRepContentSetCertResponses
00227  * INPUTS:
00228  *    inCertRepContent
00229  *        The CMMFCertRepContent to operate on.
00230  *    inCertResponses
00231  *        An array of pointers to CMMFCertResponse structures to 
00232  *        add to the CMMFCertRepContent structure.
00233  *    inNumResponses
00234  *        The length of the array 'inCertResponses'
00235  * NOTES:
00236  *    This function will add the CMMFCertResponse structure to the 
00237  *    CMMFCertRepContent passed in.  The CMMFCertResponse field of 
00238  *    CMMFCertRepContent is required, so the client must call this function
00239  *    before calling CMMF_EncodeCertRepContent.  If the user calls 
00240  *    CMMF_EncodeCertRepContent before calling this function, 
00241  *    CMMF_EncodeCertRepContent will fail.
00242  *
00243  * RETURN:
00244  *    SECSuccess if adding the CMMFCertResponses to the CMMFCertRepContent
00245  *    structure was successful.  Any other return value indicates an error
00246  *    while trying to add the CMMFCertResponses.
00247  */
00248 extern SECStatus 
00249       CMMF_CertRepContentSetCertResponses(CMMFCertRepContent *inCertRepContent,
00250                                      CMMFCertResponse  **inCertResponses,
00251                                      int                 inNumResponses);
00252 
00253 /*
00254  * FUNCTION: CMMF_CertRepContentSetCAPubs
00255  * INPUTS:
00256  *    inCertRepContent
00257  *        The CMMFCertRepContent to operate on.
00258  *    inCAPubs
00259  *        The certificate list which makes up the chain of CA certificates
00260  *        required to make the issued cert valid.
00261  * NOTES:
00262  *    This function will set the the certificates in the CA chain as part
00263  *    of the CMMFCertRepContent.  This field is an optional member of the 
00264  *    CMMFCertRepContent structure, so the client is not required to call
00265  *    this function before calling CMMF_EncodeCertRepContent.
00266  *
00267  * RETURN:
00268  *    SECSuccess if adding the 'inCAPubs' to the CERTRepContent was successful.
00269  *    Any other return value indicates an error while adding 'inCAPubs' to the 
00270  *    CMMFCertRepContent structure.
00271  * 
00272  */
00273 extern SECStatus 
00274        CMMF_CertRepContentSetCAPubs (CMMFCertRepContent  *inCertRepContent,
00275                                  CERTCertList        *inCAPubs);
00276 
00277 /*
00278  * FUNCTION: CMMF_CertResponseSetPKIStatusInfoStatus
00279  * INPUTS:
00280  *    inCertResp
00281  *        The CMMFCertResponse to operate on.
00282  *     inPKIStatus
00283  *        The value to set for the PKIStatusInfo.status field.
00284  * NOTES:
00285  *    This function will set the CertResponse.status.status field of 
00286  *    the CMMFCertResponse structure.  (View the definition of CertResponse
00287  *    in the CMMF draft to see exactly which value this talks about.)  This
00288  *    field is a required member of the structure, so the user must call this
00289  *    function in order to have a CMMFCertResponse that can be encoded.
00290  *
00291  * RETURN:
00292  *    SECSuccess if setting the field with the passed in value was successful.
00293  *    Any other return value indicates an error while trying to set the field.
00294  */
00295 extern SECStatus 
00296      CMMF_CertResponseSetPKIStatusInfoStatus (CMMFCertResponse *inCertResp,
00297                                          CMMFPKIStatus     inPKIStatus);
00298 
00299 /*
00300  * FUNCTION: CMMF_CertResponseSetCertificate
00301  * INPUTS:
00302  *    inCertResp
00303  *        The CMMFCertResponse to operate on.
00304  *    inCertificate
00305  *        The certificate to add to the 
00306  *        CertResponse.CertifiedKeyPair.certOrEncCert.certificate field.
00307  * NOTES:
00308  *    This function will take the certificate and make it a member of the
00309  *    CMMFCertResponse.  The certificate should be the actual certificate
00310  *    being issued via the response.
00311  *
00312  * RETURN:
00313  *    SECSuccess if adding the certificate to the response was successful.
00314  *    Any other return value indicates an error in adding the certificate to
00315  *    the CertResponse.
00316  */
00317 extern SECStatus 
00318        CMMF_CertResponseSetCertificate (CMMFCertResponse *inCertResp,
00319                                    CERTCertificate  *inCertificate);
00320 
00321 /*
00322  * FUNCTION: CMMF_KeyRecRepContentSetPKIStatusInfoStatus
00323  * INPUTS: 
00324  *    inKeyRecRep
00325  *        The CMMFKeyRecRepContent to operate on.
00326  *    inPKIStatus
00327  *        The value to set the PKIStatusInfo.status field to.
00328  * NOTES:
00329  *    This function sets the only required field for the KeyRecRepContent.
00330  *    In most cases, the user will set this field and other fields of the
00331  *    structure to properly create the CMMFKeyRecRepContent structure.  
00332  *    Refer to the CMMF draft to see which fields need to be set in order
00333  *    to create the desired CMMFKeyRecRepContent.
00334  * 
00335  * RETURN:
00336  *    SECSuccess if setting the PKIStatusInfo.status field was successful.
00337  *    Any other return value indicates an error in setting the field.
00338  */
00339 extern SECStatus 
00340 CMMF_KeyRecRepContentSetPKIStatusInfoStatus(CMMFKeyRecRepContent *inKeyRecRep,
00341                                        CMMFPKIStatus         inPKIStatus);
00342 
00343 /*
00344  * FUNCTION: CMMF_KeyRecRepContentSetNewSignCert
00345  * INPUTS:
00346  *    inKeyRecRep
00347  *        The CMMFKeyRecRepContent to operate on.
00348  *    inNewSignCert
00349  *        The new signing cert to add to the CMMFKeyRecRepContent structure.
00350  * NOTES:
00351  *    This function sets the new signeing cert in the CMMFKeyRecRepContent
00352  *    structure.
00353  *
00354  * RETURN:
00355  *    SECSuccess if setting the new signing cert was successful.  Any other 
00356  *    return value indicates an error occurred while trying to add the
00357  *    new signing certificate.
00358  */
00359 extern SECStatus 
00360        CMMF_KeyRecRepContentSetNewSignCert(CMMFKeyRecRepContent *inKeyRecRep,
00361                                       CERTCertificate     *inNewSignCert);
00362 
00363 /*
00364  * FUNCTION: CMMF_KeyRecRepContentSetCACerts
00365  * INPUTS:
00366  *    inKeyRecRep
00367  *        The CMMFKeyRecRepContent to operate on.
00368  *    inCACerts
00369  *        The list of CA certificates required to construct a valid 
00370  *        certificate chain with the certificates that will be returned
00371  *        to the end user via this KeyRecRepContent.
00372  * NOTES:
00373  *    This function sets the caCerts that are required to form a chain with the
00374  *    end entity certificates that are being re-issued in this 
00375  *    CMMFKeyRecRepContent structure.
00376  *
00377  * RETURN:
00378  *    SECSuccess if adding the caCerts was successful.  Any other return value
00379  *    indicates an error while tring to add the caCerts.
00380  */
00381 extern SECStatus 
00382        CMMF_KeyRecRepContentSetCACerts(CMMFKeyRecRepContent *inKeyRecRep,
00383                                    CERTCertList         *inCACerts);
00384 
00385 /*
00386  * FUNCTION: CMMF_KeyRecRepContentSetCertifiedKeyPair
00387  * INPUTS:
00388  *    inKeyRecRep
00389  *        The CMMFKeyRecRepContent to operate on.
00390  *    inCert
00391  *        The certificate to add to the CMMFKeyRecRepContent structure.
00392  *    inPrivKey
00393  *        The private key associated with the certificate above passed in.
00394  *    inPubKey
00395  *        The public key to use for wrapping the private key.
00396  * NOTES:
00397  *    This function adds another certificate-key pair to the 
00398  *    CMMFKeyRecRepcontent structure.  There may be more than one 
00399  *    certificate-key pair in the structure, so the user must call this 
00400  *    function multiple times to add more than one cert-key pair.
00401  *
00402  * RETURN:
00403  *    SECSuccess if adding the certified key pair was successful.  Any other
00404  *    return value indicates an error in adding certified key pair to 
00405  *    CMMFKeyRecRepContent structure.
00406  */
00407 extern SECStatus 
00408     CMMF_KeyRecRepContentSetCertifiedKeyPair(CMMFKeyRecRepContent *inKeyRecRep,
00409                                         CERTCertificate      *inCert,
00410                                         SECKEYPrivateKey     *inPrivKey,
00411                                         SECKEYPublicKey      *inPubKey);
00412 
00413 /*
00414  * FUNCTION: CMMF_POPODecKeyChallContentSetNextChallenge
00415  * INPUTS:
00416  *    inDecKeyChall
00417  *        The CMMFPOPODecKeyChallContent to operate on.
00418  *    inRandom
00419  *        The random number to use when generating the challenge,
00420  *    inSender
00421  *        The GeneralName representation of the sender of the challenge.
00422  *    inPubKey
00423  *        The public key to use when encrypting the challenge.
00424  *    passwdArg
00425  *        This value will be passed to the function used for getting a
00426  *        password.  The password for getting a password should be registered
00427  *        by calling PK11_SetPasswordFunc before this function is called. 
00428  *        If no password callback is registered and the library needs to 
00429  *        authenticate to the slot for any reason, this function will fail.
00430  * NOTES:
00431  *    This function adds a challenge to the end of the list of challenges
00432  *    contained by 'inDecKeyChall'.  Refer to the CMMF draft on how the
00433  *    the random number passed in and the sender's GeneralName are used
00434  *    to generate the challenge and witness fields of the challenge.  This
00435  *    library will use SHA1 as the one-way function for generating the 
00436  *    witess field of the challenge.
00437  *
00438  * RETURN:
00439  *    SECSuccess if generating the challenge and adding to the end of list
00440  *    of challenges was successful.  Any other return value indicates an error
00441  *    while trying to generate the challenge.
00442  */
00443 extern SECStatus
00444 CMMF_POPODecKeyChallContentSetNextChallenge
00445                                    (CMMFPOPODecKeyChallContent *inDecKeyChall,
00446                                 long                        inRandom,
00447                                 CERTGeneralName            *inSender,
00448                                 SECKEYPublicKey            *inPubKey,
00449                                 void                       *passwdArg);
00450 
00451 
00452 /************************** Encoding Functions *************************/
00453 
00454 /*
00455  * FUNCTION: CMMF_EncodeCertRepContent
00456  * INPUTS:
00457  *    inCertRepContent
00458  *        The CMMFCertRepContent to DER-encode.
00459  *    inCallback
00460  *        A callback function that the ASN1 encoder will call whenever it 
00461  *        wants to write out DER-encoded bytes.  Look at the defintion of 
00462  *        CRMFEncoderOutputCallback in crmft.h for a description of the
00463  *        parameters to the function.
00464  *    inArg
00465  *        An opaque pointer to a user-supplied argument that will be passed
00466  *        to the callback funtion whenever the function is called.
00467  * NOTES:
00468  *    The CMMF library will use the same DER-encoding scheme as the CRMF 
00469  *    library.  In other words, when reading CRMF comments that pertain to
00470  *    encoding, those comments apply to the CMMF libray as well.  
00471  *    The callback function will be called multiple times, each time supplying
00472  *    the next chunk of DER-encoded bytes.  The user must concatenate the 
00473  *    output of each successive call to the callback in order to get the
00474  *    entire DER-encoded CMMFCertRepContent structure.
00475  *
00476  * RETURN:
00477  *    SECSuccess if encoding the CMMFCertRepContent was successful.  Any 
00478  *    other return value indicates an error while decoding the structure.
00479  */
00480 extern SECStatus 
00481        CMMF_EncodeCertRepContent (CMMFCertRepContent        *inCertRepContent,
00482                               CRMFEncoderOutputCallback  inCallback,
00483                               void                      *inArg);
00484 
00485 /*
00486  * FUNCTION: CMMF_EncodeKeyRecRepContent
00487  * INPUTS:
00488  *    inKeyRecRep
00489  *        The CMMFKeyRepContent to DER-encode.
00490  *    inCallback
00491  *        A callback function that the ASN1 encoder will call whenever it 
00492  *        wants to write out DER-encoded bytes.  Look at the defintion of 
00493  *        CRMFEncoderOutputCallback in crmft.h for a description of the
00494  *        parameters to the function.
00495  *    inArg
00496  *        An opaque pointer to a user-supplied argument that will be passed
00497  *        to the callback funtion whenever the function is called.
00498  * NOTES:
00499  *    The CMMF library will use the same DER-encoding scheme as the CRMF 
00500  *    library.  In other words, when reading CRMF comments that pertain to
00501  *    encoding, those comments apply to the CMMF libray as well.  
00502  *    The callback function will be called multiple times, each time supplying
00503  *    the next chunk of DER-encoded bytes.  The user must concatenate the 
00504  *    output of each successive call to the callback in order to get the
00505  *    entire DER-encoded CMMFCertRepContent structure.
00506  *
00507  * RETURN:
00508  *    SECSuccess if encoding the CMMFKeyRecRepContent was successful.  Any 
00509  *    other return value indicates an error while decoding the structure.
00510  */
00511 extern SECStatus
00512        CMMF_EncodeKeyRecRepContent(CMMFKeyRecRepContent      *inKeyRecRep,
00513                                CRMFEncoderOutputCallback  inCallback,
00514                                void                      *inArg);
00515 
00516 /*
00517  * FUNCTION: CMMF_EncodePOPODecKeyChallContent
00518  * INPUTS:
00519  *    inDecKeyChall
00520  *        The CMMFDecKeyChallContent to operate on.
00521  *    inCallback
00522  *        A callback function that the ASN1 encoder will call whenever it 
00523  *        wants to write out DER-encoded bytes.  Look at the defintion of 
00524  *        CRMFEncoderOutputCallback in crmft.h for a description of the
00525  *        parameters to the function.
00526  *    inArg
00527  *        An opaque pointer to a user-supplied argument that will be passed
00528  *        to the callback function whenever the function is called.
00529  * NOTES:
00530  *    The CMMF library will use the same DER-encoding scheme as the CRMF 
00531  *    library.  In other words, when reading CRMF comments that pertain to
00532  *    encoding, those comments apply to the CMMF libray as well.  
00533  *    The callback function will be called multiple times, each time supplying
00534  *    the next chunk of DER-encoded bytes.  The user must concatenate the 
00535  *    output of each successive call to the callback in order to get the
00536  *    entire DER-encoded CMMFCertRepContent structure.
00537  *    The DER will be an encoding of the type POPODecKeyChallContents, which
00538  *    is just a sequence of challenges.
00539  *
00540  * RETURN:
00541  *    SECSuccess if encoding was successful.  Any other return value indicates
00542  *    an error in trying to encode the Challenges.
00543  */
00544 extern SECStatus 
00545 CMMF_EncodePOPODecKeyChallContent(CMMFPOPODecKeyChallContent *inDecKeyChall,
00546                               CRMFEncoderOutputCallback inCallback,
00547                               void                     *inArg);
00548 
00549 /*
00550  * FUNCTION: CMMF_EncodePOPODecKeyRespContent
00551  * INPUTS:
00552  *    inDecodedRand
00553  *        An array of integers to encode as the responses to 
00554  *        CMMFPOPODecKeyChallContent.  The integers must be in the same order
00555  *        as the challenges extracted from CMMFPOPODecKeyChallContent.
00556  *    inNumRand
00557  *        The number of random integers contained in the array 'inDecodedRand'
00558  *    inCallback
00559  *        A callback function that the ASN1 encoder will call whenever it 
00560  *        wants to write out DER-encoded bytes.  Look at the defintion of 
00561  *        CRMFEncoderOutputCallback in crmft.h for a description of the
00562  *        parameters to the function.
00563  *    inArg
00564  *        An opaque pointer to a user-supplied argument that will be passed
00565  *        to the callback funtion whenever the function is called.
00566  * NOTES:
00567  *    The CMMF library will use the same DER-encoding scheme as the CRMF 
00568  *    library.  In other words, when reading CRMF comments that pertain to
00569  *    encoding, those comments apply to the CMMF libray as well.  
00570  *    The callback function will be called multiple times, each time supplying
00571  *    the next chunk of DER-encoded bytes.  The user must concatenate the 
00572  *    output of each successive call to the callback in order to get the
00573  *    entire DER-encoded  POPODecKeyRespContent.
00574  *
00575  * RETURN:
00576  *    SECSuccess if encoding was successful.  Any other return value indicates
00577  *    an error in trying to encode the Challenges.
00578  */
00579 extern SECStatus 
00580       CMMF_EncodePOPODecKeyRespContent(long                     *inDecodedRand,
00581                                    int                       inNumRand,
00582                                    CRMFEncoderOutputCallback inCallback,
00583                                    void                     *inArg); 
00584 
00585 /***************  Accessor function  ***********************************/
00586 
00587 /*
00588  * FUNCTION: CMMF_CertRepContentGetCAPubs
00589  * INPUTS:
00590  *    inCertRepContent
00591  *        The CMMFCertRepContent to extract the caPubs from.
00592  * NOTES:
00593  *    This function will return a copy of the list of certificates that
00594  *    make up the chain of CA's required to make the cert issued valid.
00595  *    The user must call CERT_DestroyCertList on the return value when 
00596  *    done using the return value.  
00597  *
00598  *    Only call this function on a CertRepContent that has been decoded.
00599  *    The client must call CERT_DestroyCertList when the certificate list
00600  *    is no longer needed. 
00601  *
00602  *    The certs in the list will not be in the temporary database.  In order
00603  *    to make these certificates a part of the permanent CA internal database,
00604  *    the user must collect the der for all of these certs and call 
00605  *    CERT_ImportCAChain.  Afterwards the certs will be part of the permanent
00606  *    database.
00607  *    
00608  * RETURN:
00609  *    A pointer to the CERTCertList representing the CA chain associated 
00610  *    with the issued cert.  A NULL return value indicates  that no CA Pubs
00611  *    were available in the CMMFCertRepContent structure. 
00612  */
00613 extern CERTCertList* 
00614        CMMF_CertRepContentGetCAPubs (CMMFCertRepContent *inCertRepContent);
00615 
00616 
00617 /*
00618  * FUNCTION: CMMF_CertRepContentGetNumResponses
00619  * INPUTS:
00620  *    inCertRepContent
00621  *        The CMMFCertRepContent to operate on.
00622  * NOTES:
00623  *    This function will return the number of CertResponses that are contained
00624  *    by the CMMFCertRepContent passed in.
00625  * 
00626  * RETURN:
00627  *    The number of CMMFCertResponses contained in the structure passed in.
00628  */
00629 extern int 
00630  CMMF_CertRepContentGetNumResponses (CMMFCertRepContent *inCertRepContent);
00631 
00632 /*
00633  * FUNCTION: CMMF_CertRepContentGetResponseAtIndex
00634  * INPUTS:
00635  *    inCertRepContent
00636  *        The CMMFCertRepContent to operate on.
00637  *    inIndex
00638  *        The index of the CMMFCertResponse the user wants a copy of.
00639  * NOTES:
00640  *    This funciton creates a copy of the CMMFCertResponse at the index 
00641  *    corresponding to the parameter 'inIndex'.  Indexing is done like a
00642  *    traditional C array, ie the valid indexes are (0...numResponses-1).
00643  *    The user must call CMMF_DestroyCertResponse after the return value is 
00644  *    no longer needed.
00645  *
00646  * RETURN:
00647  *    A pointer to the CMMFCertResponse at the index corresponding to 
00648  *    'inIndex'.  A return value of NULL indicates an error in copying 
00649  *    the CMMFCertResponse.
00650  */
00651 extern CMMFCertResponse*
00652 CMMF_CertRepContentGetResponseAtIndex (CMMFCertRepContent *inCertRepContent,
00653                                    int                 inIndex);
00654 
00655 /*
00656  * FUNCTION: CMMF_CertResponseGetCertReqId
00657  * INPUTS:
00658  *    inCertResp
00659  *        The CMMFCertResponse to operate on.
00660  * NOTES:
00661  *    This function returns the CertResponse.certReqId from the 
00662  *    CMMFCertResponse structure passed in.  If the return value is -1, that
00663  *    means there is no associated certificate request with the CertResponse.
00664  * RETURN:
00665  *    A long representing the id of the certificate request this 
00666  *    CMMFCertResponse corresponds to.  A return value of -1 indicates an
00667  *    error in extracting the value of the integer.
00668  */
00669 extern long CMMF_CertResponseGetCertReqId(CMMFCertResponse *inCertResp);
00670 
00671 /*
00672  * FUNCTION: CMMF_CertResponseGetPKIStatusInfoStatus
00673  * INPUTS:
00674  *    inCertResp
00675  *        The CMMFCertResponse to operate on.
00676  * NOTES:
00677  *    This function returns the CertResponse.status.status field of the 
00678  *    CMMFCertResponse structure.
00679  *
00680  * RETURN:
00681  *    The enumerated value corresponding to the PKIStatus defined in the CMMF
00682  *    draft.  See the CMMF draft for the definition of PKIStatus.  See crmft.h
00683  *    for the definition of CMMFPKIStatus.
00684  */
00685 extern CMMFPKIStatus 
00686        CMMF_CertResponseGetPKIStatusInfoStatus(CMMFCertResponse *inCertResp);
00687 
00688 /*
00689  * FUNCTION: CMMF_CertResponseGetCertificate
00690  * INPUTS:
00691  *    inCertResp
00692  *        The Certificate Response to operate on.
00693  *    inCertdb
00694  *        This is the certificate database where the function will place the
00695  *        newly issued certificate.
00696  * NOTES:
00697  *    This function retrieves the CertResponse.certifiedKeyPair.certificate
00698  *    from the CMMFCertResponse.  The user will get a copy of that certificate
00699  *    so  the user must call CERT_DestroyCertificate when the return value is 
00700  *    no longer needed.  The certificate returned will be in the temporary 
00701  *    certificate database.
00702  *
00703  * RETURN:
00704  *    A pointer to a copy of the certificate contained within the 
00705  *    CMMFCertResponse.  A return value of NULL indicates an error while trying
00706  *    to make a copy of the certificate.
00707  */
00708 extern CERTCertificate*
00709        CMMF_CertResponseGetCertificate(CMMFCertResponse *inCertResp,
00710                                        CERTCertDBHandle *inCertdb);
00711 
00712 /*
00713  * FUNCTION: CMMF_KeyRecRepContentGetPKIStatusInfoStatus
00714  * INPUTS:
00715  *    inKeyRecRep
00716  *        The CMMFKeyRecRepContent structure to operate on.
00717  * NOTES:
00718  *    This function retrieves the KeyRecRepContent.status.status field of 
00719  *    the CMMFKeyRecRepContent structure.
00720  * RETURN:
00721  *    The CMMFPKIStatus corresponding to the value held in the 
00722  *    CMMFKeyRecRepContent structure.
00723  */
00724 extern CMMFPKIStatus 
00725 CMMF_KeyRecRepContentGetPKIStatusInfoStatus(CMMFKeyRecRepContent *inKeyRecRep);
00726 
00727 /*
00728  * FUNCTION: CMMF_KeyRecRepContentGetNewSignCert
00729  * INPUTS:
00730  *    inKeyRecRep
00731  *        The CMMFKeyRecRepContent to operate on.
00732  * NOTES:
00733  *    This function retrieves the KeyRecRepContent.newSignCert field of the
00734  *    CMMFKeyRecRepContent structure.  The user must call 
00735  *    CERT_DestroyCertificate when the return value is no longer needed. The
00736  *    returned certificate will be in the temporary database.  The user 
00737  *    must then place the certificate permanently in whatever token the
00738  *    user determines is the proper destination.  A return value of NULL
00739  *    indicates the newSigCert field was not present.
00740  */
00741 extern CERTCertificate*
00742        CMMF_KeyRecRepContentGetNewSignCert(CMMFKeyRecRepContent *inKeyRecRep);
00743 
00744 /*
00745  * FUNCTION: CMMF_KeyRecRepContentGetCACerts
00746  * INPUTS:
00747  *    inKeyRecRep
00748  *        The CMMFKeyRecRepContent to operate on.
00749  * NOTES:
00750  *    This function returns a CERTCertList which contains all of the 
00751  *    certficates that are in the sequence KeyRecRepContent.caCerts
00752  *    User must call CERT_DestroyCertList when the return value is no longer 
00753  *    needed.  All of these certificates will be placed in the tempoaray
00754  *    database.
00755  *
00756  * RETURN:
00757  *    A pointer to the list of caCerts contained in the CMMFKeyRecRepContent
00758  *    structure.  A return value of NULL indicates the library was not able to 
00759  *    make a copy of the certifcates.  This may be because there are no caCerts
00760  *    included in the CMMFKeyRecRepContent strucure or an internal error.  Call
00761  *    CMMF_KeyRecRepContentHasCACerts to find out if there are any caCerts 
00762  *    included in 'inKeyRecRep'.
00763  */
00764 extern CERTCertList*
00765        CMMF_KeyRecRepContentGetCACerts(CMMFKeyRecRepContent *inKeyRecRep);
00766 
00767 /*
00768  * FUNCTION: CMMF_KeyRecRepContentGetNumKeyPairs
00769  * INPUTS:
00770  *    inKeyRecRep
00771  *        The CMMFKeyRecRepContent to operate on.
00772  * RETURN:
00773  *    This function returns the number of CMMFCertifiedKeyPair structures that
00774  *    that are stored in the KeyRecRepContent structure.
00775  */
00776 extern int 
00777        CMMF_KeyRecRepContentGetNumKeyPairs(CMMFKeyRecRepContent *inKeyRecRep);
00778 
00779 /*
00780  * FUNCTION: CMMF_KeyRecRepContentGetCertKeyAtIndex
00781  * INPUTS:
00782  *    inKeyRecRepContent
00783  *        The CMMFKeyRecRepContent to operate on.
00784  *    inIndex
00785  *        The index of the desired CMMFCertifiedKeyPair
00786  * NOTES:
00787  *    This function retrieves the CMMFCertifiedKeyPair structure at the index
00788  *    'inIndex'.  Valid indexes are 0...(numKeyPairs-1)  The user must call 
00789  *    CMMF_DestroyCertifiedKeyPair when the return value is no longer needed.
00790  *
00791  * RETURN:
00792  *    A pointer to the Certified Key Pair at the desired index.  A return value
00793  *    of NULL indicates an error in extracting the Certified Key Pair at the 
00794  *    desired index.
00795  */
00796 extern CMMFCertifiedKeyPair*
00797       CMMF_KeyRecRepContentGetCertKeyAtIndex(CMMFKeyRecRepContent *inKeyRecRep,
00798                                         int                   inIndex);
00799 
00800 /*
00801  * FUNCTION: CMMF_CertifiedKeyPairGetCertificate
00802  * INPUTS:
00803  *    inCertKeyPair
00804  *        The CMMFCertifiedKeyPair to operate on.
00805  *    inCertdb
00806  *        The database handle for the database you want this certificate
00807  *        to wind up in.
00808  * NOTES:
00809  *    This function retrieves the certificate at 
00810  *    CertifiedKeyPair.certOrEncCert.certificate
00811  *    The user must call CERT_DestroyCertificate when the return value is no
00812  *    longer needed.  The user must import this certificate as a token object
00813  *    onto PKCS#11 slot in order to make it a permanent object.  The returned
00814  *    certificate will be in the temporary database.
00815  * 
00816  * RETURN:
00817  *    A pointer to the certificate contained within the certified key pair.
00818  *    A return value of NULL indicates an error in creating the copy of the 
00819  *    certificate.
00820  */
00821 extern CERTCertificate*
00822       CMMF_CertifiedKeyPairGetCertificate(CMMFCertifiedKeyPair *inCertKeyPair,
00823                                      CERTCertDBHandle     *inCertdb);
00824 
00825 /*
00826  * FUNCTION: CMMF_POPODecKeyChallContentGetNumChallenges
00827  * INPUTS:
00828  *    inKeyChallCont
00829  *        The CMMFPOPODecKeyChallContent to operate on.
00830  * RETURN:
00831  *    This function returns the number of CMMFChallenges are contained in 
00832  *    the CMMFPOPODecKeyChallContent structure.
00833  */
00834 extern int CMMF_POPODecKeyChallContentGetNumChallenges
00835                                   (CMMFPOPODecKeyChallContent *inKeyChallCont);
00836 
00837 /*
00838  * FUNCTION: CMMF_POPODecKeyChallContentGetPublicValue
00839  * ---------------------------------------------------
00840  * INPUTS:
00841  *    inKeyChallCont
00842  *        The CMMFPOPODecKeyChallContent to operate on.
00843  *    inIndex
00844  *        The index of the Challenge within inKeyChallCont to operate on.
00845  *        Indexes start from 0, ie the Nth Challenge corresponds to index
00846  *        N-1.
00847  * NOTES:
00848  * This function retrieves the public value stored away in the Challenge at
00849  * index inIndex of inKeyChallCont.
00850  * RETURN:
00851  * A pointer to a SECItem containing the public value.  User must call 
00852  * SECITEM_FreeItem on the return value when the value is no longer necessary.
00853  * A return value of NULL indicates an error while retrieving the public value.
00854  */
00855 extern SECItem* CMMF_POPODecKeyChallContentGetPublicValue
00856                                    (CMMFPOPODecKeyChallContent *inKeyChallCont,
00857                                 int                         inIndex);
00858 
00859 
00860 /*
00861  * FUNCTION: CMMF_POPODecKeyChallContentGetRandomNumber
00862  * INPUTS:
00863  *    inChallContent
00864  *        The CMMFPOPODecKeyChallContent to operate on.
00865  *    inIndex
00866  *        The index of the challenge to look at.  Valid indexes are 0 through
00867  *        (CMMF_POPODecKeyChallContentGetNumChallenges(inChallContent) - 1).
00868  *    inDest
00869  *        A pointer to a user supplied buffer where the library
00870  *        can place a copy of the random integer contatained in the
00871  *        challenge.
00872  * NOTES:
00873  *    This function returns the value held in the decrypted Rand structure
00874  *    corresponding to the random integer.  The user must call 
00875  *    CMMF_POPODecKeyChallContentDecryptChallenge before calling this function.  Call 
00876  *    CMMF_ChallengeIsDecrypted to find out if the challenge has been 
00877  *    decrypted.
00878  *
00879  * RETURN:
00880  *    SECSuccess indicates the witness field has been previously decrypted
00881  *    and the value for the random integer was successfully placed at *inDest.
00882  *    Any other return value indicates an error and that the value at *inDest
00883  *    is not a valid value.
00884  */
00885 extern SECStatus CMMF_POPODecKeyChallContentGetRandomNumber
00886                                       (CMMFPOPODecKeyChallContent *inKeyChallCont,
00887                                    int                          inIndex,
00888                                    long                        *inDest);
00889 
00890 /*
00891  * FUNCTION: CMMF_POPODecKeyRespContentGetNumResponses
00892  * INPUTS:
00893  *    inRespCont
00894  *        The POPODecKeyRespContent to operate on.
00895  * RETURN:
00896  * This function returns the number of responses contained in inRespContent.
00897  */
00898 extern int 
00899  CMMF_POPODecKeyRespContentGetNumResponses(CMMFPOPODecKeyRespContent *inRespCont);
00900 
00901 /*
00902  * FUNCTION: CMMF_POPODecKeyRespContentGetResponse
00903  * INPUTS:
00904  *    inRespCont
00905  *        The POPODecKeyRespContent to operate on.
00906  *    inIndex
00907  *        The index of the response to retrieve.
00908  *        The Nth response is at index N-1, ie the 1st response is at index 0,
00909  *        the 2nd response is at index 1, and so on.
00910  *    inDest
00911  *        A pointer to a pre-allocated buffer where the library can put the 
00912  *        value of the response located at inIndex.
00913  * NOTES:
00914  * The function returns the response contained at index inIndex.  
00915  * CMMFPOPODecKeyRespContent is a structure that the server will generally 
00916  * get in response to a CMMFPOPODecKeyChallContent.  The server will expect
00917  * to see the responses in the same order as it constructed them in 
00918  * the CMMFPOPODecKeyChallContent structure.
00919  * RETURN:
00920  * SECSuccess if getting the response at the desired index was successful.  Any
00921  * other return value indicates an errror.
00922  */
00923 extern SECStatus
00924      CMMF_POPODecKeyRespContentGetResponse (CMMFPOPODecKeyRespContent *inRespCont,
00925                                        int                        inIndex,
00926                                        long                      *inDest);
00927 
00928 /************************* Destructor Functions ******************************/
00929 
00930 /*
00931  * FUNCTION: CMMF_DestroyCertResponse
00932  * INPUTS:
00933  *    inCertResp
00934  *        The CMMFCertResponse to destroy.
00935  * NOTES:
00936  *    This function frees all the memory associated with the CMMFCertResponse
00937  *    passed in.
00938  * RETURN:
00939  *    SECSuccess if freeing the memory was successful.  Any other return value
00940  *    indicates an error while freeing the memory.
00941  */
00942 extern SECStatus CMMF_DestroyCertResponse(CMMFCertResponse *inCertResp);
00943 
00944 /*
00945  * FUNCTION: CMMF_DestroyCertRepContent
00946  * INPUTS:
00947  *    inCertRepContent
00948  *        The CMMFCertRepContent to destroy
00949  * NOTES:
00950  *    This function frees the memory associated with the CMMFCertRepContent
00951  *    passed in.
00952  * RETURN:
00953  *    SECSuccess if freeing all the memory associated with the 
00954  *    CMMFCertRepContent passed in is successful.  Any other return value 
00955  *    indicates an error while freeing the memory.
00956  */
00957 extern SECStatus 
00958        CMMF_DestroyCertRepContent (CMMFCertRepContent *inCertRepContent);
00959 
00960 /*
00961  * FUNCTION: CMMF_DestroyKeyRecRepContent
00962  * INPUTS:
00963  *    inKeyRecRep
00964  *        The CMMFKeyRecRepContent to destroy.
00965  * NOTES:
00966  *    This function destroys all the memory associated with the 
00967  *    CMMFKeyRecRepContent passed in.
00968  *
00969  * RETURN:
00970  *    SECSuccess if freeing all the memory is successful.  Any other return 
00971  *    value indicates an error in freeing the memory.
00972  */
00973 extern SECStatus 
00974        CMMF_DestroyKeyRecRepContent(CMMFKeyRecRepContent *inKeyRecRep);
00975 
00976 /*
00977  * FUNCTION: CMMF_DestroyCertifiedKeyPair
00978  * INPUTS:
00979  *    inCertKeyPair
00980  *        The CMMFCertifiedKeyPair to operate on.
00981  * NOTES: 
00982  *    This function frees up all the memory associated with 'inCertKeyPair'
00983  *
00984  * RETURN:
00985  *    SECSuccess if freeing all the memory associated with 'inCertKeyPair'
00986  *    is successful.  Any other return value indicates an error while trying
00987  *    to free the memory.
00988  */
00989 extern SECStatus 
00990        CMMF_DestroyCertifiedKeyPair(CMMFCertifiedKeyPair *inCertKeyPair);
00991 
00992 /*
00993  * FUNCTION: CMMF_DestroyPOPODecKeyRespContent
00994  * INPUTS:
00995  *    inDecKeyResp
00996  *        The CMMFPOPODecKeyRespContent structure to free.
00997  * NOTES:
00998  *    This function frees up all the memory associate with the 
00999  *    CMMFPOPODecKeyRespContent.
01000  *
01001  * RETURN:
01002  *    SECSuccess if freeing up all the memory associated with the
01003  *    CMMFPOPODecKeyRespContent structure is successful.  Any other
01004  *    return value indicates an error while freeing the memory.
01005  */
01006 extern SECStatus
01007        CMMF_DestroyPOPODecKeyRespContent(CMMFPOPODecKeyRespContent *inDecKeyResp);
01008 
01009 
01010 /************************** Miscellaneous Functions *************************/
01011  
01012 /*
01013  * FUNCTION: CMMF_CertifiedKeyPairUnwrapPrivKey
01014  * INPUTS:
01015  *    inCertKeyPair
01016  *        The CMMFCertifiedKeyPair to operate on.
01017  *    inPrivKey
01018  *        The private key to use to un-wrap the private key
01019  *    inNickName
01020  *        This is the nickname that will be associated with the private key
01021  *        to be unwrapped.
01022  *    inSlot
01023  *        The PKCS11 slot where the unwrapped private key should end up.
01024  *    inCertdb
01025  *        The Certificate database with which the new key will be associated.
01026  *    destPrivKey
01027  *        A pointer to memory where the library can place a pointer to the
01028  *        private key after importing the key onto the specified slot.
01029  *    wincx
01030  *        An opaque pointer that the library will use in a callback function
01031  *        to get the password if necessary.
01032  *    
01033  * NOTES:
01034  *    This function uses the private key passed in to unwrap the private key
01035  *    contained within the CMMFCertifiedKeyPair structure. After this 
01036  *    function successfully returns, the private key has been unwrapped and
01037  *    placed in the specified slot. 
01038  *
01039  * RETURN:
01040  *    SECSuccess if unwrapping the private key was successful.  Any other 
01041  *    return value indicates an error while trying to un-wrap the private key.
01042  */
01043 extern SECStatus 
01044        CMMF_CertifiedKeyPairUnwrapPrivKey(CMMFCertifiedKeyPair *inKeyPair,
01045                                      SECKEYPrivateKey     *inPrivKey,
01046                                      SECItem              *inNickName,
01047                                      PK11SlotInfo         *inSlot,
01048                                           CERTCertDBHandle     *inCertdb,
01049                                      SECKEYPrivateKey    **destPrivKey,
01050                                      void                 *wincx);
01051 
01052 /*
01053  * FUNCTION: CMMF_KeyRecRepContentHasCACerts
01054  * INPUTS:
01055  *    inKeyRecRecp
01056  *        The CMMFKeyRecRepContent to operate on.
01057  * RETURN:
01058  *    This function returns PR_TRUE if there are one or more certificates in 
01059  *    the sequence KeyRecRepContent.caCerts within the CMMFKeyRecRepContent
01060  *    structure.  The function will return PR_FALSE if there are 0 certificate
01061  *    in the above mentioned sequence.
01062  */
01063 extern PRBool 
01064        CMMF_KeyRecRepContentHasCACerts(CMMFKeyRecRepContent *inKeyRecRep);
01065 
01066 /*
01067  * FUNCTION: CMMF_POPODecKeyChallContDecryptChallenge
01068  * INPUTS:
01069  *    inChalCont
01070  *        The CMMFPOPODecKeyChallContent to operate on.
01071  *    inIndex
01072  *        The index of the Challenge to operate on.  The 1st Challenge is
01073  *        at index 0, the second at index 1 and so forth.
01074  *    inPrivKey
01075  *        The private key to use to decrypt the witness field.
01076  * NOTES:
01077  *    This function uses the private key to decrypt the challenge field
01078  *    contained in the appropriate challenge.  Make sure the private key matches 
01079  *    the public key that was used to encrypt the witness.  Use 
01080  *    CMMF_POPODecKeyChallContentGetPublicValue to get the public value of
01081  *    the key used to encrypt the witness and then use that to determine the
01082  *    appropriate private key.  This can be done by calling PK11_MakeIDFromPubKey
01083  *    and then passing that return value to PK11_FindKeyByKeyID.  The creator of 
01084  *    the challenge will most likely be an RA that has the public key
01085  *    from a Cert request.  So the private key should be the private key
01086  *    associated with public key in that request.  This function will also
01087  *    verify the witness field of the challenge.  This function also verifies
01088  *    that the sender and witness hashes match within the challenge.
01089  *
01090  * RETURN:
01091  *    SECSuccess if decrypting the witness field was successful.  This does
01092  *    not indicate that the decrypted data is valid, since the private key 
01093  *    passed in may not be the actual key needed to properly decrypt the 
01094  *    witness field.  Meaning that there is a decrypted structure now, but
01095  *    may be garbage because the private key was incorrect.
01096  *    Any other return value indicates the function could not complete the
01097  *    decryption process.
01098  */
01099 extern SECStatus 
01100   CMMF_POPODecKeyChallContDecryptChallenge(CMMFPOPODecKeyChallContent *inChalCont,
01101                                       int                         inIndex,
01102                                       SECKEYPrivateKey           *inPrivKey);
01103 
01104 /*
01105  * FUNCTION: CMMF_DestroyPOPODecKeyChallContent
01106  * INPUTS:
01107  *    inDecKeyCont
01108  *        The CMMFPOPODecKeyChallContent to free
01109  * NOTES:
01110  *    This function frees up all the memory associated with the 
01111  *    CMMFPOPODecKeyChallContent 
01112  * RETURN:
01113  *    SECSuccess if freeing up all the memory associatd with the 
01114  *    CMMFPOPODecKeyChallContent is successful.  Any other return value
01115  *    indicates an error while freeing the memory.
01116  *
01117  */
01118 extern SECStatus 
01119  CMMF_DestroyPOPODecKeyChallContent (CMMFPOPODecKeyChallContent *inDecKeyCont);
01120 
01121 SEC_END_PROTOS
01122 #endif /* _CMMF_H_ */