path: root/security/nss/lib/crmf/cmmf.h

/* -*- Mode: C; tab-width: 8 -*-*/
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#ifndef _CMMF_H_
#define _CMMF_H_
/*
 * These are the functions exported by the security library for
 * implementing Certificate Management Message Formats (CMMF).
 *
 * This API is designed against July 1998 CMMF draft.  Please read this
 * draft before trying to use this API in an application that use CMMF.
 */
#include "seccomon.h"
#include "cmmft.h"
#include "crmf.h"

SEC_BEGIN_PROTOS

/******************* Creation Functions *************************/

/*
 * FUNCTION: CMMF_CreateCertRepContent
 * INPUTS:
 *    NONE
 * NOTES:
 *    This function will create an empty CMMFCertRepContent Structure.
 *    The client of the library must set the CMMFCertResponses.
 *    Call CMMF_CertRepContentSetCertResponse to accomplish this task.
 *    If the client of the library also wants to include the chain of
 *    CA certs required to make the certificates in CMMFCertResponse valid,
 *    then the user must also set the caPubs field of CMMFCertRepContent.
 *    Call CMMF_CertRepContentSetCAPubs to accomplish this.  After setting
 *    the desired fields, the user can then call CMMF_EncodeCertRepContent
 *    to DER-encode the CertRepContent.
 * RETURN:
 *    A pointer to the CMMFCertRepContent.  A NULL return value indicates
 *    an error in allocating memory or failure to initialize the structure.
 */
extern CMMFCertRepContent *CMMF_CreateCertRepContent(void);

/*
 * FUNCTION: CMMF_CreateCertRepContentFromDER
 * INPUTS
 *    db
 *        The certificate database where the certificates will be placed.
 *        The certificates will be placed in the temporary database associated
 *        with the handle.
 *    buf
 *        A buffer to the DER-encoded CMMFCertRepContent
 *    len
 *        The length in bytes of the buffer 'buf'
 * NOTES:
 *    This function passes the buffer to the ASN1 decoder and creates a
 *    CMMFCertRepContent structure.  The user must call
 *    CMMF_DestroyCertRepContent after the return value is no longer needed.
 *
 * RETURN:
 *    A pointer to the CMMFCertRepContent structure.  A NULL return
 *    value indicates the library was unable to parse the DER.
 */
extern CMMFCertRepContent *
CMMF_CreateCertRepContentFromDER(CERTCertDBHandle *db,
                                 const char *buf,
                                 long len);

/*
 * FUNCTION: CMMF_CreateCertResponse
 * INPUTS:
 *    inCertReqId
 *        The Certificate Request Id this response is for.
 * NOTES:
 *    This creates a CMMFCertResponse.  This response should correspond
 *    to a request that was received via CRMF.  From the CRMF message you
 *    can get the Request Id to pass in as inCertReqId, in essence binding
 *    a CMRFCertRequest message to the CMMFCertResponse created by this
 *    function.  If no requuest id is associated with the response to create
 *    then the user should pass in -1 for 'inCertReqId'.
 *
 * RETURN:
 *    A pointer to the new CMMFCertResponse corresponding to the request id
 *    passed in.  A NULL return value indicates an error while trying to
 *    create the CMMFCertResponse.
 */
extern CMMFCertResponse *CMMF_CreateCertResponse(long inCertReqId);

/*
 * FUNCTION: CMMF_CreateKeyRecRepContent
 * INPUTS:
 *    NONE
 * NOTES:
 *    This function creates a new empty CMMFKeyRecRepContent structure.
 *    At the very minimum, the user  must call
 *    CMMF_KeyRecRepContentSetPKIStatusInfoStatus field to have an
 *    encodable structure.  Depending on what the response is, the user may
 *    have to set other fields as well to properly build up the structure so
 *    that it can be encoded.  Refer to the CMMF draft for how to properly
 *    set up a CMMFKeyRecRepContent. This is the structure that an RA returns
 *    to an end entity when doing key recovery.

 *    The user must call CMMF_DestroyKeyRecRepContent when the return value
 *    is no longer needed.
 * RETURN:
 *    A pointer to the empty CMMFKeyRecRepContent.  A return value of NULL
 *    indicates an error in allocating memory or initializing the structure.
 */
extern CMMFKeyRecRepContent *CMMF_CreateKeyRecRepContent(void);

/*
 * FUNCTION: CMMF_CreateKeyRecRepContentFromDER
 * INPUTS:
 *    db
 *        The handle for the certificate database where the decoded
 *        certificates will be placed.  The decoded certificates will
 *        be placed in the temporary database associated with the
 *        handle.
 *    buf
 *        A buffer contatining the DER-encoded CMMFKeyRecRepContent
 *    len
 *        The length in bytes of the buffer 'buf'
 * NOTES
 *    This function passes the buffer to the ASN1 decoder and creates a
 *    CMMFKeyRecRepContent structure.
 *
 * RETURN:
 *    A pointer to the CMMFKeyRecRepContent structure.  A NULL return
 *    value indicates the library was unable to parse the DER.
 */
extern CMMFKeyRecRepContent *
CMMF_CreateKeyRecRepContentFromDER(CERTCertDBHandle *db,
                                   const char *buf,
                                   long len);

/*
 * FUNCTION: CMMF_CreatePOPODecKeyChallContent
 * INPUTS:
 *    NONE
 * NOTES:
 *    This function creates an empty CMMFPOPODecKeyChallContent.  The user
 *    must add the challenges individually specifying the random number to
 *    be used and the public key to be used when creating each individual
 *    challenge.  User can accomplish this by calling the function
 *    CMMF_POPODecKeyChallContentSetNextChallenge.
 * RETURN:
 *    A pointer to a CMMFPOPODecKeyChallContent structure.  Ther user can
 *    then call CMMF_EncodePOPODecKeyChallContent passing in the return
 *    value from this function after setting all of the challenges.  A
 *    return value of NULL indicates an error while creating the
 *    CMMFPOPODecKeyChallContent structure.
 */
extern CMMFPOPODecKeyChallContent *
CMMF_CreatePOPODecKeyChallContent(void);

/*
 * FUNCTION: CMMF_CreatePOPODecKeyChallContentFromDER
 * INPUTS
 *    buf
 *        A buffer containing the DER-encoded CMMFPOPODecKeyChallContent
 *    len
 *        The length in bytes of the buffer 'buf'
 * NOTES:
 *    This function passes the buffer to the ASN1 decoder and creates a
 *    CMMFPOPODecKeyChallContent structure.
 *
 * RETURN:
 *    A pointer to the CMMFPOPODecKeyChallContent structure.  A NULL return
 *    value indicates the library was unable to parse the DER.
 */
extern CMMFPOPODecKeyChallContent *
CMMF_CreatePOPODecKeyChallContentFromDER(const char *buf, long len);

/*
 * FUNCTION: CMMF_CreatePOPODecKeyRespContentFromDER
 * INPUTS:
 *    buf
 *        A buffer contatining the DER-encoded CMMFPOPODecKeyRespContent
 *    len
 *        The length in bytes of the buffer 'buf'
 * NOTES
 *    This function passes the buffer to the ASN1 decoder and creates a
 *    CMMFPOPODecKeyRespContent structure.
 *
 * RETURN:
 *    A pointer to the CMMFPOPODecKeyRespContent structure.  A NULL return
 *    value indicates the library was unable to parse the DER.
 */
extern CMMFPOPODecKeyRespContent *
CMMF_CreatePOPODecKeyRespContentFromDER(const char *buf, long len);

/************************** Set Functions *************************/

/*
 * FUNCTION: CMMF_CertRepContentSetCertResponses
 * INPUTS:
 *    inCertRepContent
 *        The CMMFCertRepContent to operate on.
 *    inCertResponses
 *        An array of pointers to CMMFCertResponse structures to
 *        add to the CMMFCertRepContent structure.
 *    inNumResponses
 *        The length of the array 'inCertResponses'
 * NOTES:
 *    This function will add the CMMFCertResponse structure to the
 *    CMMFCertRepContent passed in.  The CMMFCertResponse field of
 *    CMMFCertRepContent is required, so the client must call this function
 *    before calling CMMF_EncodeCertRepContent.  If the user calls
 *    CMMF_EncodeCertRepContent before calling this function,
 *    CMMF_EncodeCertRepContent will fail.
 *
 * RETURN:
 *    SECSuccess if adding the CMMFCertResponses to the CMMFCertRepContent
 *    structure was successful.  Any other return value indicates an error
 *    while trying to add the CMMFCertResponses.
 */
extern SECStatus
CMMF_CertRepContentSetCertResponses(CMMFCertRepContent *inCertRepContent,
                                    CMMFCertResponse **inCertResponses,
                                    int inNumResponses);

/*
 * FUNCTION: CMMF_CertRepContentSetCAPubs
 * INPUTS:
 *    inCertRepContent
 *        The CMMFCertRepContent to operate on.
 *    inCAPubs
 *        The certificate list which makes up the chain of CA certificates
 *        required to make the issued cert valid.
 * NOTES:
 *    This function will set the the certificates in the CA chain as part
 *    of the CMMFCertRepContent.  This field is an optional member of the
 *    CMMFCertRepContent structure, so the client is not required to call
 *    this function before calling CMMF_EncodeCertRepContent.
 *
 * RETURN:
 *    SECSuccess if adding the 'inCAPubs' to the CERTRepContent was successful.
 *    Any other return value indicates an error while adding 'inCAPubs' to the
 *    CMMFCertRepContent structure.
 *
 */
extern SECStatus
CMMF_CertRepContentSetCAPubs(CMMFCertRepContent *inCertRepContent,
                             CERTCertList *inCAPubs);

/*
 * FUNCTION: CMMF_CertResponseSetPKIStatusInfoStatus
 * INPUTS:
 *    inCertResp
 *        The CMMFCertResponse to operate on.
 *     inPKIStatus
 *        The value to set for the PKIStatusInfo.status field.
 * NOTES:
 *    This function will set the CertResponse.status.status field of
 *    the CMMFCertResponse structure.  (View the definition of CertResponse
 *    in the CMMF draft to see exactly which value this talks about.)  This
 *    field is a required member of the structure, so the user must call this
 *    function in order to have a CMMFCertResponse that can be encoded.
 *
 * RETURN:
 *    SECSuccess if setting the field with the passed in value was successful.
 *    Any other return value indicates an error while trying to set the field.
 */
extern SECStatus
CMMF_CertResponseSetPKIStatusInfoStatus(CMMFCertResponse *inCertResp,
                                        CMMFPKIStatus inPKIStatus);

/*
 * FUNCTION: CMMF_CertResponseSetCertificate
 * INPUTS:
 *    inCertResp
 *        The CMMFCertResponse to operate on.
 *    inCertificate
 *        The certificate to add to the
 *        CertResponse.CertifiedKeyPair.certOrEncCert.certificate field.
 * NOTES:
 *    This function will take the certificate and make it a member of the
 *    CMMFCertResponse.  The certificate should be the actual certificate
 *    being issued via the response.
 *
 * RETURN:
 *    SECSuccess if adding the certificate to the response was successful.
 *    Any other return value indicates an error in adding the certificate to
 *    the CertResponse.
 */
extern SECStatus
CMMF_CertResponseSetCertificate(CMMFCertResponse *inCertResp,
                                CERTCertificate *inCertificate);

/*
 * FUNCTION: CMMF_KeyRecRepContentSetPKIStatusInfoStatus
 * INPUTS:
 *    inKeyRecRep
 *        The CMMFKeyRecRepContent to operate on.
 *    inPKIStatus
 *        The value to set the PKIStatusInfo.status field to.
 * NOTES:
 *    This function sets the only required field for the KeyRecRepContent.
 *    In most cases, the user will set this field and other fields of the
 *    structure to properly create the CMMFKeyRecRepContent structure.
 *    Refer to the CMMF draft to see which fields need to be set in order
 *    to create the desired CMMFKeyRecRepContent.
 *
 * RETURN:
 *    SECSuccess if setting the PKIStatusInfo.status field was successful.
 *    Any other return value indicates an error in setting the field.
 */
extern SECStatus
CMMF_KeyRecRepContentSetPKIStatusInfoStatus(CMMFKeyRecRepContent *inKeyRecRep,
                                            CMMFPKIStatus inPKIStatus);

/*
 * FUNCTION: CMMF_KeyRecRepContentSetNewSignCert
 * INPUTS:
 *    inKeyRecRep
 *        The CMMFKeyRecRepContent to operate on.
 *    inNewSignCert
 *        The new signing cert to add to the CMMFKeyRecRepContent structure.
 * NOTES:
 *    This function sets the new signeing cert in the CMMFKeyRecRepContent
 *    structure.
 *
 * RETURN:
 *    SECSuccess if setting the new signing cert was successful.  Any other
 *    return value indicates an error occurred while trying to add the
 *    new signing certificate.
 */
extern SECStatus
CMMF_KeyRecRepContentSetNewSignCert(CMMFKeyRecRepContent *inKeyRecRep,
                                    CERTCertificate *inNewSignCert);

/*
 * FUNCTION: CMMF_KeyRecRepContentSetCACerts
 * INPUTS:
 *    inKeyRecRep
 *        The CMMFKeyRecRepContent to operate on.
 *    inCACerts
 *        The list of CA certificates required to construct a valid
 *        certificate chain with the certificates that will be returned
 *        to the end user via this KeyRecRepContent.
 * NOTES:
 *    This function sets the caCerts that are required to form a chain with the
 *    end entity certificates that are being re-issued in this
 *    CMMFKeyRecRepContent structure.
 *
 * RETURN:
 *    SECSuccess if adding the caCerts was successful.  Any other return value
 *    indicates an error while tring to add the caCerts.
 */
extern SECStatus
CMMF_KeyRecRepContentSetCACerts(CMMFKeyRecRepContent *inKeyRecRep,
                                CERTCertList *inCACerts);

/*
 * FUNCTION: CMMF_KeyRecRepContentSetCertifiedKeyPair
 * INPUTS:
 *    inKeyRecRep
 *        The CMMFKeyRecRepContent to operate on.
 *    inCert
 *        The certificate to add to the CMMFKeyRecRepContent structure.
 *    inPrivKey
 *        The private key associated with the certificate above passed in.
 *    inPubKey
 *        The public key to use for wrapping the private key.
 * NOTES:
 *    This function adds another certificate-key pair to the
 *    CMMFKeyRecRepcontent structure.  There may be more than one
 *    certificate-key pair in the structure, so the user must call this
 *    function multiple times to add more than one cert-key pair.
 *
 * RETURN:
 *    SECSuccess if adding the certified key pair was successful.  Any other
 *    return value indicates an error in adding certified key pair to
 *    CMMFKeyRecRepContent structure.
 */
extern SECStatus
CMMF_KeyRecRepContentSetCertifiedKeyPair(CMMFKeyRecRepContent *inKeyRecRep,
                                         CERTCertificate *inCert,
                                         SECKEYPrivateKey *inPrivKey,
                                         SECKEYPublicKey *inPubKey);

/*
 * FUNCTION: CMMF_POPODecKeyChallContentSetNextChallenge
 * INPUTS:
 *    inDecKeyChall
 *        The CMMFPOPODecKeyChallContent to operate on.
 *    inRandom
 *        The random number to use when generating the challenge,
 *    inSender
 *        The GeneralName representation of the sender of the challenge.
 *    inPubKey
 *        The public key to use when encrypting the challenge.
 *    passwdArg
 *        This value will be passed to the function used for getting a
 *        password.  The password for getting a password should be registered
 *        by calling PK11_SetPasswordFunc before this function is called.
 *        If no password callback is registered and the library needs to
 *        authenticate to the slot for any reason, this function will fail.
 * NOTES:
 *    This function adds a challenge to the end of the list of challenges
 *    contained by 'inDecKeyChall'.  Refer to the CMMF draft on how the
 *    the random number passed in and the sender's GeneralName are used
 *    to generate the challenge and witness fields of the challenge.  This
 *    library will use SHA1 as the one-way function for generating the
 *    witess field of the challenge.
 *
 * RETURN:
 *    SECSuccess if generating the challenge and adding to the end of list
 *    of challenges was successful.  Any other return value indicates an error
 *    while trying to generate the challenge.
 */
extern SECStatus
CMMF_POPODecKeyChallContentSetNextChallenge(CMMFPOPODecKeyChallContent *inDecKeyChall,
                                            long inRandom,
                                            CERTGeneralName *inSender,
                                            SECKEYPublicKey *inPubKey,
                                            void *passwdArg);

/************************** Encoding Functions *************************/

/*
 * FUNCTION: CMMF_EncodeCertRepContent
 * INPUTS:
 *    inCertRepContent
 *        The CMMFCertRepContent to DER-encode.
 *    inCallback
 *        A callback function that the ASN1 encoder will call whenever it
 *        wants to write out DER-encoded bytes.  Look at the defintion of
 *        CRMFEncoderOutputCallback in crmft.h for a description of the
 *        parameters to the function.
 *    inArg
 *        An opaque pointer to a user-supplied argument that will be passed
 *        to the callback funtion whenever the function is called.
 * NOTES:
 *    The CMMF library will use the same DER-encoding scheme as the CRMF
 *    library.  In other words, when reading CRMF comments that pertain to
 *    encoding, those comments apply to the CMMF libray as well.
 *    The callback function will be called multiple times, each time supplying
 *    the next chunk of DER-encoded bytes.  The user must concatenate the
 *    output of each successive call to the callback in order to get the
 *    entire DER-encoded CMMFCertRepContent structure.
 *
 * RETURN:
 *    SECSuccess if encoding the CMMFCertRepContent was successful.  Any
 *    other return value indicates an error while decoding the structure.
 */
extern SECStatus
CMMF_EncodeCertRepContent(CMMFCertRepContent *inCertRepContent,
                          CRMFEncoderOutputCallback inCallback,
                          void *inArg);

/*
 * FUNCTION: CMMF_EncodeKeyRecRepContent
 * INPUTS:
 *    inKeyRecRep
 *        The CMMFKeyRepContent to DER-encode.
 *    inCallback
 *        A callback function that the ASN1 encoder will call whenever it
 *        wants to write out DER-encoded bytes.  Look at the defintion of
 *        CRMFEncoderOutputCallback in crmft.h for a description of the
 *        parameters to the function.
 *    inArg
 *        An opaque pointer to a user-supplied argument that will be passed
 *        to the callback funtion whenever the function is called.
 * NOTES:
 *    The CMMF library will use the same DER-encoding scheme as the CRMF
 *    library.  In other words, when reading CRMF comments that pertain to
 *    encoding, those comments apply to the CMMF libray as well.
 *    The callback function will be called multiple times, each time supplying
 *    the next chunk of DER-encoded bytes.  The user must concatenate the
 *    output of each successive call to the callback in order to get the
 *    entire DER-encoded CMMFCertRepContent structure.
 *
 * RETURN:
 *    SECSuccess if encoding the CMMFKeyRecRepContent was successful.  Any
 *    other return value indicates an error while decoding the structure.
 */
extern SECStatus
CMMF_EncodeKeyRecRepContent(CMMFKeyRecRepContent *inKeyRecRep,
                            CRMFEncoderOutputCallback inCallback,
                            void *inArg);

/*
 * FUNCTION: CMMF_EncodePOPODecKeyChallContent
 * INPUTS:
 *    inDecKeyChall
 *        The CMMFDecKeyChallContent to operate on.
 *    inCallback
 *        A callback function that the ASN1 encoder will call whenever it
 *        wants to write out DER-encoded bytes.  Look at the defintion of
 *        CRMFEncoderOutputCallback in crmft.h for a description of the
 *        parameters to the function.
 *    inArg
 *        An opaque pointer to a user-supplied argument that will be passed
 *        to the callback function whenever the function is called.
 * NOTES:
 *    The CMMF library will use the same DER-encoding scheme as the CRMF
 *    library.  In other words, when reading CRMF comments that pertain to
 *    encoding, those comments apply to the CMMF libray as well.
 *    The callback function will be called multiple times, each time supplying
 *    the next chunk of DER-encoded bytes.  The user must concatenate the
 *    output of each successive call to the callback in order to get the
 *    entire DER-encoded CMMFCertRepContent structure.
 *    The DER will be an encoding of the type POPODecKeyChallContents, which
 *    is just a sequence of challenges.
 *
 * RETURN:
 *    SECSuccess if encoding was successful.  Any other return value indicates
 *    an error in trying to encode the Challenges.
 */
extern SECStatus
CMMF_EncodePOPODecKeyChallContent(CMMFPOPODecKeyChallContent *inDecKeyChall,
                                  CRMFEncoderOutputCallback inCallback,
                                  void *inArg);

/*
 * FUNCTION: CMMF_EncodePOPODecKeyRespContent
 * INPUTS:
 *    inDecodedRand
 *        An array of integers to encode as the responses to
 *        CMMFPOPODecKeyChallContent.  The integers must be in the same order
 *        as the challenges extracted from CMMFPOPODecKeyChallContent.
 *    inNumRand
 *        The number of random integers contained in the array 'inDecodedRand'
 *    inCallback
 *        A callback function that the ASN1 encoder will call whenever it
 *        wants to write out DER-encoded bytes.  Look at the defintion of
 *        CRMFEncoderOutputCallback in crmft.h for a description of the
 *        parameters to the function.
 *    inArg
 *        An opaque pointer to a user-supplied argument that will be passed
 *        to the callback funtion whenever the function is called.
 * NOTES:
 *    The CMMF library will use the same DER-encoding scheme as the CRMF
 *    library.  In other words, when reading CRMF comments that pertain to
 *    encoding, those comments apply to the CMMF libray as well.
 *    The callback function will be called multiple times, each time supplying
 *    the next chunk of DER-encoded bytes.  The user must concatenate the
 *    output of each successive call to the callback in order to get the
 *    entire DER-encoded  POPODecKeyRespContent.
 *
 * RETURN:
 *    SECSuccess if encoding was successful.  Any other return value indicates
 *    an error in trying to encode the Challenges.
 */
extern SECStatus
CMMF_EncodePOPODecKeyRespContent(long *inDecodedRand,
                                 int inNumRand,
                                 CRMFEncoderOutputCallback inCallback,
                                 void *inArg);

/***************  Accessor function  ***********************************/

/*
 * FUNCTION: CMMF_CertRepContentGetCAPubs
 * INPUTS:
 *    inCertRepContent
 *        The CMMFCertRepContent to extract the caPubs from.
 * NOTES:
 *    This function will return a copy of the list of certificates that
 *    make up the chain of CA's required to make the cert issued valid.
 *    The user must call CERT_DestroyCertList on the return value when
 *    done using the return value.
 *
 *    Only call this function on a CertRepContent that has been decoded.
 *    The client must call CERT_DestroyCertList when the certificate list
 *    is no longer needed.
 *
 *    The certs in the list will not be in the temporary database.  In order
 *    to make these certificates a part of the permanent CA internal database,
 *    the user must collect the der for all of these certs and call
 *    CERT_ImportCAChain.  Afterwards the certs will be part of the permanent
 *    database.
 *
 * RETURN:
 *    A pointer to the CERTCertList representing the CA chain associated
 *    with the issued cert.  A NULL return value indicates  that no CA Pubs
 *    were available in the CMMFCertRepContent structure.
 */
extern CERTCertList *
CMMF_CertRepContentGetCAPubs(CMMFCertRepContent *inCertRepContent);

/*
 * FUNCTION: CMMF_CertRepContentGetNumResponses
 * INPUTS:
 *    inCertRepContent
 *        The CMMFCertRepContent to operate on.
 * NOTES:
 *    This function will return the number of CertResponses that are contained
 *    by the CMMFCertRepContent passed in.
 *
 * RETURN:
 *    The number of CMMFCertResponses contained in the structure passed in.
 */
extern int
CMMF_CertRepContentGetNumResponses(CMMFCertRepContent *inCertRepContent);

/*
 * FUNCTION: CMMF_CertRepContentGetResponseAtIndex
 * INPUTS:
 *    inCertRepContent
 *        The CMMFCertRepContent to operate on.
 *    inIndex
 *        The index of the CMMFCertResponse the user wants a copy of.
 * NOTES:
 *    This function creates a copy of the CMMFCertResponse at the index
 *    corresponding to the parameter 'inIndex'.  Indexing is done like a
 *    traditional C array, ie the valid indexes are (0...numResponses-1).
 *    The user must call CMMF_DestroyCertResponse after the return value is
 *    no longer needed.
 *
 * RETURN:
 *    A pointer to the CMMFCertResponse at the index corresponding to
 *    'inIndex'.  A return value of NULL indicates an error in copying
 *    the CMMFCertResponse.
 */
extern CMMFCertResponse *
CMMF_CertRepContentGetResponseAtIndex(CMMFCertRepContent *inCertRepContent,
                                      int inIndex);

/*
 * FUNCTION: CMMF_CertResponseGetCertReqId
 * INPUTS:
 *    inCertResp
 *        The CMMFCertResponse to operate on.
 * NOTES:
 *    This function returns the CertResponse.certReqId from the
 *    CMMFCertResponse structure passed in.  If the return value is -1, that
 *    means there is no associated certificate request with the CertResponse.
 * RETURN:
 *    A long representing the id of the certificate request this
 *    CMMFCertResponse corresponds to.  A return value of -1 indicates an
 *    error in extracting the value of the integer.
 */
extern long CMMF_CertResponseGetCertReqId(CMMFCertResponse *inCertResp);

/*
 * FUNCTION: CMMF_CertResponseGetPKIStatusInfoStatus
 * INPUTS:
 *    inCertResp
 *        The CMMFCertResponse to operate on.
 * NOTES:
 *    This function returns the CertResponse.status.status field of the
 *    CMMFCertResponse structure.
 *
 * RETURN:
 *    The enumerated value corresponding to the PKIStatus defined in the CMMF
 *    draft.  See the CMMF draft for the definition of PKIStatus.  See crmft.h
 *    for the definition of CMMFPKIStatus.
 */
extern CMMFPKIStatus
CMMF_CertResponseGetPKIStatusInfoStatus(CMMFCertResponse *inCertResp);

/*
 * FUNCTION: CMMF_CertResponseGetCertificate
 * INPUTS:
 *    inCertResp
 *        The Certificate Response to operate on.
 *    inCertdb
 *        This is the certificate database where the function will place the
 *        newly issued certificate.
 * NOTES:
 *    This function retrieves the CertResponse.certifiedKeyPair.certificate
 *    from the CMMFCertResponse.  The user will get a copy of that certificate
 *    so  the user must call CERT_DestroyCertificate when the return value is
 *    no longer needed.  The certificate returned will be in the temporary
 *    certificate database.
 *
 * RETURN:
 *    A pointer to a copy of the certificate contained within the
 *    CMMFCertResponse.  A return value of NULL indicates an error while trying
 *    to make a copy of the certificate.
 */
extern CERTCertificate *
CMMF_CertResponseGetCertificate(CMMFCertResponse *inCertResp,
                                CERTCertDBHandle *inCertdb);

/*
 * FUNCTION: CMMF_KeyRecRepContentGetPKIStatusInfoStatus
 * INPUTS:
 *    inKeyRecRep
 *        The CMMFKeyRecRepContent structure to operate on.
 * NOTES:
 *    This function retrieves the KeyRecRepContent.status.status field of
 *    the CMMFKeyRecRepContent structure.
 * RETURN:
 *    The CMMFPKIStatus corresponding to the value held in the
 *    CMMFKeyRecRepContent structure.
 */
extern CMMFPKIStatus
CMMF_KeyRecRepContentGetPKIStatusInfoStatus(CMMFKeyRecRepContent *inKeyRecRep);

/*
 * FUNCTION: CMMF_KeyRecRepContentGetNewSignCert
 * INPUTS:
 *    inKeyRecRep
 *        The CMMFKeyRecRepContent to operate on.
 * NOTES:
 *    This function retrieves the KeyRecRepContent.newSignCert field of the
 *    CMMFKeyRecRepContent structure.  The user must call
 *    CERT_DestroyCertificate when the return value is no longer needed. The
 *    returned certificate will be in the temporary database.  The user
 *    must then place the certificate permanently in whatever token the
 *    user determines is the proper destination.  A return value of NULL
 *    indicates the newSigCert field was not present.
 */
extern CERTCertificate *
CMMF_KeyRecRepContentGetNewSignCert(CMMFKeyRecRepContent *inKeyRecRep);

/*
 * FUNCTION: CMMF_KeyRecRepContentGetCACerts
 * INPUTS:
 *    inKeyRecRep
 *        The CMMFKeyRecRepContent to operate on.
 * NOTES:
 *    This function returns a CERTCertList which contains all of the
 *    certficates that are in the sequence KeyRecRepContent.caCerts
 *    User must call CERT_DestroyCertList when the return value is no longer
 *    needed.  All of these certificates will be placed in the tempoaray
 *    database.
 *
 * RETURN:
 *    A pointer to the list of caCerts contained in the CMMFKeyRecRepContent
 *    structure.  A return value of NULL indicates the library was not able to
 *    make a copy of the certifcates.  This may be because there are no caCerts
 *    included in the CMMFKeyRecRepContent strucure or an internal error.  Call
 *    CMMF_KeyRecRepContentHasCACerts to find out if there are any caCerts
 *    included in 'inKeyRecRep'.
 */
extern CERTCertList *
CMMF_KeyRecRepContentGetCACerts(CMMFKeyRecRepContent *inKeyRecRep);

/*
 * FUNCTION: CMMF_KeyRecRepContentGetNumKeyPairs
 * INPUTS:
 *    inKeyRecRep
 *        The CMMFKeyRecRepContent to operate on.
 * RETURN:
 *    This function returns the number of CMMFCertifiedKeyPair structures that
 *    that are stored in the KeyRecRepContent structure.
 */
extern int
CMMF_KeyRecRepContentGetNumKeyPairs(CMMFKeyRecRepContent *inKeyRecRep);

/*
 * FUNCTION: CMMF_KeyRecRepContentGetCertKeyAtIndex
 * INPUTS:
 *    inKeyRecRepContent
 *        The CMMFKeyRecRepContent to operate on.
 *    inIndex
 *        The index of the desired CMMFCertifiedKeyPair
 * NOTES:
 *    This function retrieves the CMMFCertifiedKeyPair structure at the index
 *    'inIndex'.  Valid indexes are 0...(numKeyPairs-1)  The user must call
 *    CMMF_DestroyCertifiedKeyPair when the return value is no longer needed.
 *
 * RETURN:
 *    A pointer to the Certified Key Pair at the desired index.  A return value
 *    of NULL indicates an error in extracting the Certified Key Pair at the
 *    desired index.
 */
extern CMMFCertifiedKeyPair *
CMMF_KeyRecRepContentGetCertKeyAtIndex(CMMFKeyRecRepContent *inKeyRecRep,
                                       int inIndex);

/*
 * FUNCTION: CMMF_CertifiedKeyPairGetCertificate
 * INPUTS:
 *    inCertKeyPair
 *        The CMMFCertifiedKeyPair to operate on.
 *    inCertdb
 *        The database handle for the database you want this certificate
 *        to wind up in.
 * NOTES:
 *    This function retrieves the certificate at
 *    CertifiedKeyPair.certOrEncCert.certificate
 *    The user must call CERT_DestroyCertificate when the return value is no
 *    longer needed.  The user must import this certificate as a token object
 *    onto PKCS#11 slot in order to make it a permanent object.  The returned
 *    certificate will be in the temporary database.
 *
 * RETURN:
 *    A pointer to the certificate contained within the certified key pair.
 *    A return value of NULL indicates an error in creating the copy of the
 *    certificate.
 */
extern CERTCertificate *
CMMF_CertifiedKeyPairGetCertificate(CMMFCertifiedKeyPair *inCertKeyPair,
                                    CERTCertDBHandle *inCertdb);

/*
 * FUNCTION: CMMF_POPODecKeyChallContentGetNumChallenges
 * INPUTS:
 *    inKeyChallCont
 *        The CMMFPOPODecKeyChallContent to operate on.
 * RETURN:
 *    This function returns the number of CMMFChallenges are contained in
 *    the CMMFPOPODecKeyChallContent structure.
 */
extern int CMMF_POPODecKeyChallContentGetNumChallenges(CMMFPOPODecKeyChallContent *inKeyChallCont);

/*
 * FUNCTION: CMMF_POPODecKeyChallContentGetPublicValue
 * ---------------------------------------------------
 * INPUTS:
 *    inKeyChallCont
 *        The CMMFPOPODecKeyChallContent to operate on.
 *    inIndex
 *        The index of the Challenge within inKeyChallCont to operate on.
 *        Indexes start from 0, ie the Nth Challenge corresponds to index
 *        N-1.
 * NOTES:
 * This function retrieves the public value stored away in the Challenge at
 * index inIndex of inKeyChallCont.
 * RETURN:
 * A pointer to a SECItem containing the public value.  User must call
 * SECITEM_FreeItem on the return value when the value is no longer necessary.
 * A return value of NULL indicates an error while retrieving the public value.
 */
extern SECItem *CMMF_POPODecKeyChallContentGetPublicValue(CMMFPOPODecKeyChallContent *inKeyChallCont,
                                                          int inIndex);

/*
 * FUNCTION: CMMF_POPODecKeyChallContentGetRandomNumber
 * INPUTS:
 *    inChallContent
 *        The CMMFPOPODecKeyChallContent to operate on.
 *    inIndex
 *        The index of the challenge to look at.  Valid indexes are 0 through
 *        (CMMF_POPODecKeyChallContentGetNumChallenges(inChallContent) - 1).
 *    inDest
 *        A pointer to a user supplied buffer where the library
 *        can place a copy of the random integer contatained in the
 *        challenge.
 * NOTES:
 *    This function returns the value held in the decrypted Rand structure
 *    corresponding to the random integer.  The user must call
 *    CMMF_POPODecKeyChallContentDecryptChallenge before calling this function.  Call
 *    CMMF_ChallengeIsDecrypted to find out if the challenge has been
 *    decrypted.
 *
 * RETURN:
 *    SECSuccess indicates the witness field has been previously decrypted
 *    and the value for the random integer was successfully placed at *inDest.
 *    Any other return value indicates an error and that the value at *inDest
 *    is not a valid value.
 */
extern SECStatus CMMF_POPODecKeyChallContentGetRandomNumber(CMMFPOPODecKeyChallContent *inKeyChallCont,
                                                            int inIndex,
                                                            long *inDest);

/*
 * FUNCTION: CMMF_POPODecKeyRespContentGetNumResponses
 * INPUTS:
 *    inRespCont
 *        The POPODecKeyRespContent to operate on.
 * RETURN:
 * This function returns the number of responses contained in inRespContent.
 */
extern int
CMMF_POPODecKeyRespContentGetNumResponses(CMMFPOPODecKeyRespContent *inRespCont);

/*
 * FUNCTION: CMMF_POPODecKeyRespContentGetResponse
 * INPUTS:
 *    inRespCont
 *        The POPODecKeyRespContent to operate on.
 *    inIndex
 *        The index of the response to retrieve.
 *        The Nth response is at index N-1, ie the 1st response is at index 0,
 *        the 2nd response is at index 1, and so on.
 *    inDest
 *        A pointer to a pre-allocated buffer where the library can put the
 *        value of the response located at inIndex.
 * NOTES:
 * The function returns the response contained at index inIndex.
 * CMMFPOPODecKeyRespContent is a structure that the server will generally
 * get in response to a CMMFPOPODecKeyChallContent.  The server will expect
 * to see the responses in the same order as it constructed them in
 * the CMMFPOPODecKeyChallContent structure.
 * RETURN:
 * SECSuccess if getting the response at the desired index was successful.  Any
 * other return value indicates an errror.
 */
extern SECStatus
CMMF_POPODecKeyRespContentGetResponse(CMMFPOPODecKeyRespContent *inRespCont,
                                      int inIndex,
                                      long *inDest);

/************************* Destructor Functions ******************************/

/*
 * FUNCTION: CMMF_DestroyCertResponse
 * INPUTS:
 *    inCertResp
 *        The CMMFCertResponse to destroy.
 * NOTES:
 *    This function frees all the memory associated with the CMMFCertResponse
 *    passed in.
 * RETURN:
 *    SECSuccess if freeing the memory was successful.  Any other return value
 *    indicates an error while freeing the memory.
 */
extern SECStatus CMMF_DestroyCertResponse(CMMFCertResponse *inCertResp);

/*
 * FUNCTION: CMMF_DestroyCertRepContent
 * INPUTS:
 *    inCertRepContent
 *        The CMMFCertRepContent to destroy
 * NOTES:
 *    This function frees the memory associated with the CMMFCertRepContent
 *    passed in.
 * RETURN:
 *    SECSuccess if freeing all the memory associated with the
 *    CMMFCertRepContent passed in is successful.  Any other return value
 *    indicates an error while freeing the memory.
 */
extern SECStatus
CMMF_DestroyCertRepContent(CMMFCertRepContent *inCertRepContent);

/*
 * FUNCTION: CMMF_DestroyKeyRecRepContent
 * INPUTS:
 *    inKeyRecRep
 *        The CMMFKeyRecRepContent to destroy.
 * NOTES:
 *    This function destroys all the memory associated with the
 *    CMMFKeyRecRepContent passed in.
 *
 * RETURN:
 *    SECSuccess if freeing all the memory is successful.  Any other return
 *    value indicates an error in freeing the memory.
 */
extern SECStatus
CMMF_DestroyKeyRecRepContent(CMMFKeyRecRepContent *inKeyRecRep);

/*
 * FUNCTION: CMMF_DestroyCertifiedKeyPair
 * INPUTS:
 *    inCertKeyPair
 *        The CMMFCertifiedKeyPair to operate on.
 * NOTES:
 *    This function frees up all the memory associated with 'inCertKeyPair'
 *
 * RETURN:
 *    SECSuccess if freeing all the memory associated with 'inCertKeyPair'
 *    is successful.  Any other return value indicates an error while trying
 *    to free the memory.
 */
extern SECStatus
CMMF_DestroyCertifiedKeyPair(CMMFCertifiedKeyPair *inCertKeyPair);

/*
 * FUNCTION: CMMF_DestroyPOPODecKeyRespContent
 * INPUTS:
 *    inDecKeyResp
 *        The CMMFPOPODecKeyRespContent structure to free.
 * NOTES:
 *    This function frees up all the memory associate with the
 *    CMMFPOPODecKeyRespContent.
 *
 * RETURN:
 *    SECSuccess if freeing up all the memory associated with the
 *    CMMFPOPODecKeyRespContent structure is successful.  Any other
 *    return value indicates an error while freeing the memory.
 */
extern SECStatus
CMMF_DestroyPOPODecKeyRespContent(CMMFPOPODecKeyRespContent *inDecKeyResp);

/************************** Miscellaneous Functions *************************/

/*
 * FUNCTION: CMMF_CertifiedKeyPairUnwrapPrivKey
 * INPUTS:
 *    inCertKeyPair
 *        The CMMFCertifiedKeyPair to operate on.
 *    inPrivKey
 *        The private key to use to un-wrap the private key
 *    inNickName
 *        This is the nickname that will be associated with the private key
 *        to be unwrapped.
 *    inSlot
 *        The PKCS11 slot where the unwrapped private key should end up.
 *    inCertdb
 *        The Certificate database with which the new key will be associated.
 *    destPrivKey
 *        A pointer to memory where the library can place a pointer to the
 *        private key after importing the key onto the specified slot.
 *    wincx
 *        An opaque pointer that the library will use in a callback function
 *        to get the password if necessary.
 *
 * NOTES:
 *    This function uses the private key passed in to unwrap the private key
 *    contained within the CMMFCertifiedKeyPair structure. After this
 *    function successfully returns, the private key has been unwrapped and
 *    placed in the specified slot.
 *
 * RETURN:
 *    SECSuccess if unwrapping the private key was successful.  Any other
 *    return value indicates an error while trying to un-wrap the private key.
 */
extern SECStatus
CMMF_CertifiedKeyPairUnwrapPrivKey(CMMFCertifiedKeyPair *inKeyPair,
                                   SECKEYPrivateKey *inPrivKey,
                                   SECItem *inNickName,
                                   PK11SlotInfo *inSlot,
                                   CERTCertDBHandle *inCertdb,
                                   SECKEYPrivateKey **destPrivKey,
                                   void *wincx);

/*
 * FUNCTION: CMMF_KeyRecRepContentHasCACerts
 * INPUTS:
 *    inKeyRecRecp
 *        The CMMFKeyRecRepContent to operate on.
 * RETURN:
 *    This function returns PR_TRUE if there are one or more certificates in
 *    the sequence KeyRecRepContent.caCerts within the CMMFKeyRecRepContent
 *    structure.  The function will return PR_FALSE if there are 0 certificate
 *    in the above mentioned sequence.
 */
extern PRBool
CMMF_KeyRecRepContentHasCACerts(CMMFKeyRecRepContent *inKeyRecRep);

/*
 * FUNCTION: CMMF_POPODecKeyChallContDecryptChallenge
 * INPUTS:
 *    inChalCont
 *        The CMMFPOPODecKeyChallContent to operate on.
 *    inIndex
 *        The index of the Challenge to operate on.  The 1st Challenge is
 *        at index 0, the second at index 1 and so forth.
 *    inPrivKey
 *        The private key to use to decrypt the witness field.
 * NOTES:
 *    This function uses the private key to decrypt the challenge field
 *    contained in the appropriate challenge.  Make sure the private key matches
 *    the public key that was used to encrypt the witness.  Use
 *    CMMF_POPODecKeyChallContentGetPublicValue to get the public value of
 *    the key used to encrypt the witness and then use that to determine the
 *    appropriate private key.  This can be done by calling PK11_MakeIDFromPubKey
 *    and then passing that return value to PK11_FindKeyByKeyID.  The creator of
 *    the challenge will most likely be an RA that has the public key
 *    from a Cert request.  So the private key should be the private key
 *    associated with public key in that request.  This function will also
 *    verify the witness field of the challenge.  This function also verifies
 *    that the sender and witness hashes match within the challenge.
 *
 * RETURN:
 *    SECSuccess if decrypting the witness field was successful.  This does
 *    not indicate that the decrypted data is valid, since the private key
 *    passed in may not be the actual key needed to properly decrypt the
 *    witness field.  Meaning that there is a decrypted structure now, but
 *    may be garbage because the private key was incorrect.
 *    Any other return value indicates the function could not complete the
 *    decryption process.
 */
extern SECStatus
CMMF_POPODecKeyChallContDecryptChallenge(CMMFPOPODecKeyChallContent *inChalCont,
                                         int inIndex,
                                         SECKEYPrivateKey *inPrivKey);

/*
 * FUNCTION: CMMF_DestroyPOPODecKeyChallContent
 * INPUTS:
 *    inDecKeyCont
 *        The CMMFPOPODecKeyChallContent to free
 * NOTES:
 *    This function frees up all the memory associated with the
 *    CMMFPOPODecKeyChallContent
 * RETURN:
 *    SECSuccess if freeing up all the memory associatd with the
 *    CMMFPOPODecKeyChallContent is successful.  Any other return value
 *    indicates an error while freeing the memory.
 *
 */
extern SECStatus
CMMF_DestroyPOPODecKeyChallContent(CMMFPOPODecKeyChallContent *inDecKeyCont);

SEC_END_PROTOS
#endif /* _CMMF_H_ */