path: root/security/nss/lib/crmf/crmf.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 _CRMF_H_
#define _CRMF_H_

#include "seccomon.h"
#include "cert.h"
#include "crmft.h"
#include "secoid.h"
#include "secpkcs7.h"

SEC_BEGIN_PROTOS

/*
 * FUNCTION: CRMF_EncodeCertReqMsg
 * INPUTS:
 *    inCertReqMsg
 *        The Certificate Request Message to be encoded.
 *    fn
 *        A Callback function that the ASN1 encoder calls whenever
 *        the encoder wants to write out some DER encoded bytes.
 *    arg
 *        An opaque pointer that gets passed to the function fn
 * OUTPUT:
 *    The function fn will be called multiple times.  Look at the
 *    comments in crmft.h where the CRMFEncoderOutputCallback type is
 *    defined for information on proper behavior of the function fn.
 * RETURN:
 *    SECSuccess if encoding was successful.  Any other return value
 *    indicates an error occurred during encoding.
 */
extern SECStatus
CRMF_EncodeCertReqMsg(CRMFCertReqMsg *inCertReqMsg,
                      CRMFEncoderOutputCallback fn,
                      void *arg);

/*
 * FUNCTION: CRMF_EncoderCertRequest
 * INPUTS:
 *    inCertReq
 *        The Certificate Request to be encoded.
 *    fn
 *        A Callback function that the ASN1 encoder calls whenever
 *        the encoder wants to write out some DER encoded bytes.
 *    arg
 *        An opaque pointer that gets passed to the function fn.
 * OUTPUT:
 *    The function fn will be called, probably multiple times whenever
 *    the ASN1 encoder wants to write out DER-encoded bytes.  Look at the
 *    comments in crmft.h where the CRMFEncoderOutputCallback type is
 *    defined for information on proper behavior of the function fn.
 * RETURN:
 *    SECSuccess if encoding was successful.  Any other return value
 *    indicates an error occurred during encoding.
 */
extern SECStatus CRMF_EncodeCertRequest(CRMFCertRequest *inCertReq,
                                        CRMFEncoderOutputCallback fn,
                                        void *arg);
/*
 * FUNCTION: CRMF_EncodeCertReqMessages
 * INPUTS:
 *    inCertReqMsgs
 *        An array of pointers to the Certificate Request Messages
 *        to encode.  The user must place a NULL pointer in the index
 *        after the last message to be encoded.  When the library runs
 *        into the NULL pointer, the library assumes there are no more
 *        messages to encode.
 *    fn
 *        A Callback function that the ASN1 encoder calls whenever
 *        the encoder wants to write out some DER encoded byts.
 *    arg
 *        An opaque pointer that gets passed to the function fn.
 *
 * NOTES:
 *    The parameter inCertReqMsgs needs to be an array with a NULL pointer
 *    to signal the end of messages.  An array in the form of
 *    {m1, m2, m3, NULL, m4, ...} will only encode the messages m1, m2, and
 *    m3.  All messages from m4 on will not be looked at by the library.
 *
 * OUTPUT:
 *    The function fn will be called, probably multiple times.  Look at the
 *    comments in crmft.h where the CRMFEncoderOutputCallback type is
 *    defined for information on proper behavior of the function fn.
 *
 * RETURN:
 * SECSuccess if encoding the Certificate Request Messages was successful.
 * Any other return value indicates an error occurred while encoding the
 * certificate request messages.
 */
extern SECStatus
CRMF_EncodeCertReqMessages(CRMFCertReqMsg **inCertReqMsgs,
                           CRMFEncoderOutputCallback fn,
                           void *arg);

/*
 * FUNCTION: CRMF_CreateCertReqMsg
 * INPUTS:
 *    NONE
 * OUTPUT:
 *    An empty CRMF Certificate Request Message.
 *    Before encoding this message, the user must set
 *    the ProofOfPossession field and the certificate
 *    request which are necessary for the full message.
 *    After the user no longer needs this CertReqMsg,
 *    the user must call CRMF_DestroyCertReqMsg to free
 *    all memory associated with the Certificate Request
 *    Message.
 * RETURN:
 *    A pointer to a Certificate Request Message.  The user
 *    must pass the return value of this function to
 *    CRMF_DestroyCertReqMsg after the Certificate Request
 *    Message is no longer necessary.
 */
extern CRMFCertReqMsg *CRMF_CreateCertReqMsg(void);

/*
 * FUNCTION: CRMF_DestroyCertReqMsg
 * INPUTS:
 *    inCertReqMsg
 *        The Certificate Request Message to destroy.
 *  NOTES:
 *    This function frees all the memory used for the Certificate
 *    Request Message and all the memory used in making copies of
 *    fields of elelments of the message, eg. the Proof Of Possession
 *    filed and the Cetificate Request.
 * RETURN:
 *    SECSuccess if destruction was successful.  Any other return value
 *    indicates an error while trying to free the memory associated
 *    with inCertReqMsg.
 *
 */
extern SECStatus CRMF_DestroyCertReqMsg(CRMFCertReqMsg *inCertReqMsg);

/*
 * FUNCTION: CRMF_CertReqMsgSetCertRequest
 * INPUTS:
 *    inCertReqMsg
 *        The Certificate Request Message that the function will set
 *        the certificate request for.
 *    inCertReq
 *        The Certificate Request that will be added to the Certificate
 *        Request Message.
 * NOTES:
 *    This function will make a copy of the Certificate Request passed in
 *    and store it as part of the Certificate Request Message.  Therefore,
 *    the user must not call this function until the Certificate Request
 *    has been fully built and is ready to be encoded.
 * RETURN:
 *    SECSuccess
 *        If copying the Certificate as a member of the Certificate
 *        request message was successful.
 *    Any other return value indicates a failure to copy the Certificate
 *    Request and make it a part of the Certificate Request Message.
 */
extern SECStatus CRMF_CertReqMsgSetCertRequest(CRMFCertReqMsg *inCertReqMsg,
                                               CRMFCertRequest *inCertReq);

/*
 * FUNCTION: CRMF_CreateCertRequest
 * INPUTS:
 *    inRequestID
 *        The ID that will be associated with this certificate request.
 * OUTPUTS:
 *    A certificate request which only has the requestID set.
 * NOTES:
 *    The user must call the function CRMF_DestroyCertRequest when
 *    the returned value is no longer needed.  This is usually the
 *    case after fully constructing the Certificate Request and then
 *    calling the function CRMF_CertReqMsgSetCertRequest.
 * RETURN:
 *    A pointer to the new Certificate Request.  A NULL return value
 *    indicates an error in creating the Certificate Request.
 */
extern CRMFCertRequest *CRMF_CreateCertRequest(PRUint32 inRequestID);

/*
 * FUNCTION: CRMF_DestroyCertRequest
 * INPUTS:
 *    inCertReq
 *        The Certificate Request that will be destroyed.
 * RETURN:
 *    SECSuccess
 *        If freeing the memory associated with the certificate request
 *        was successful.
 *    Any other return value indicates an error while trying to free the
 *    memory.
 */
extern SECStatus CRMF_DestroyCertRequest(CRMFCertRequest *inCertReq);

/*
 * FUNCTION: CRMF_CreateCertExtension
 * INPUTS:
 *    id
 *        The SECOidTag to associate with this CertExtension.  This must
 *        correspond to a valid Certificate Extension, if not the function
 *        will fail.
 *    isCritical
 *        A boolean value stating if the extension value is crtical.  PR_TRUE
 *        means the value is crtical.  PR_FALSE indicates the value is not
 *        critical.
 *    data
 *        This is the data associated with the extension.  The user of the
 *        library is responsible for making sure the value passed in is a
 *        valid interpretation of the certificate extension.
 * NOTES:
 * Use this function to create CRMFCertExtension Structures which will
 * then be passed to CRMF_AddFieldToCertTemplate as part of the
 * CRMFCertCreationInfo.extensions  The user must call
 * CRMF_DestroyCertExtension after the extension has been added to a certifcate
 * and the extension is no longer needed.
 *
 * RETURN:
 * A pointer to a newly created CertExtension.  A return value of NULL
 * indicates the id passed in was an invalid certificate extension.
 */
extern CRMFCertExtension *CRMF_CreateCertExtension(SECOidTag id,
                                                   PRBool isCritical,
                                                   SECItem *data);

/*
 * FUNCTION: CMRF_DestroyCertExtension
 * INPUTS:
 *    inExtension
 *        The Cert Extension to destroy
 * NOTES:
 * Destroy a structure allocated by CRMF_CreateCertExtension.
 *
 * RETURN:
 * SECSuccess if freeing the memory associated with the certificate extension
 * was successful.  Any other error indicates an error while freeing the
 * memory.
 */
extern SECStatus CRMF_DestroyCertExtension(CRMFCertExtension *inExtension);

/*
 * FUNCTION: CRMF_CertRequestSetTemplateField
 * INPUTS:
 *    inCertReq
 *        The Certificate Request to operate on.
 *    inTemplateField
 *        An enumeration that indicates which field of the Certificate
 *        template to add.
 *    data
 *        A generic pointer that will be type cast according to the
 *        table under NOTES and used as the key for adding to the
 *        certificate template;
 * NOTES:
 *
 * Below is a table that tells what type to pass in as data
 * depending on the template field one wants to set.
 *
 * Look in crmft.h for the definition of CRMFCertTemplateField.
 *
 * In all cases, the library makes copies of the data passed in.
 *
 *   CRMFCertTemplateField    Type of data    What data means
 *   ---------------------    ------------    ---------------
 *   crmfVersion              long *          The version of
 *                                            the certificate
 *                                            to be created.
 *
 *   crmfSerialNumber         long *          The serial number
 *                                            for the cert to be
 *                                            created.
 *
 *   crmfSigningAlg           SECAlgorithm *  The ASN.1 object ID for
 *                                            the algorithm used in encoding
 *                                            the certificate.
 *
 *   crmfIssuer               CERTName *      Certificate Library
 *                                            representation of the ASN1 type
 *                                            Name from X.509
 *
 *   crmfValidity     CRMFValidityCreationInfo *  At least one of the two
 *                                                fields in the structure must
 *                                                be present.  A NULL pointer
 *                                                in the structure indicates
 *                                                that member should not be
 *                                                added.
 *
 *   crmfSubject              CERTName *      Certificate Library
 *                                            representation of the ASN1 type
 *                                            Name from X.509
 *
 *   crmfPublicKey    CERTSubjectPublicKeyInfo *  The public key info for the
 *                                                certificate being requested.
 *
 *   crmfIssuerUID            SECItem *           A bit string representation
 *                                                of the issuer UID. NOTE: The
 *                                                length is the number of bits
 *                                                and not the number of bytes.
 *
 *   crmfSubjectUID           SECItem*            A bit string representation
 *                                                of the subject UID. NOTE: The
 *                                                length is the number of bits
 *                                                and not the number of bytes.
 *
 *   crmfExtension   CRMFCertExtCreationInfo *     A pointer to the structure
 *                                                 populated with an array of
 *                                                 of certificate extensions
 *                                                 and an integer that tells
 *                                                 how many elements are in the
 *                                                 array. Look in crmft.h for
 *                                                 the definition of
 *                                                 CRMFCertExtCreationInfo
 * RETURN:
 *    SECSuccess if adding the desired field to the template was successful.
 *    Any other return value indicates failure when trying to add the field
 *    to the template.
 *
 */
extern SECStatus
CRMF_CertRequestSetTemplateField(CRMFCertRequest *inCertReq,
                                 CRMFCertTemplateField inTemplateField,
                                 void *data);

/*
 * FUNCTION: CRMF_CertRequestIsFieldPresent
 * INPUTS:
 *    inCertReq
 *        The certificate request to operate on.
 *    inTemplateField
 *        The enumeration for the template field the user wants to query
 *        about.
 * NOTES:
 * This function checks to see if the the field associated with inTemplateField
 * enumeration is already present in the certificate request passed in.
 *
 * RETURN:
 * The function returns PR_TRUE if the field associated with inTemplateField
 * is already present in the certificate request.  If the field is not present
 * the function returns PR_FALSE.
 */
extern PRBool
CRMF_CertRequestIsFieldPresent(CRMFCertRequest *inCertReq,
                               CRMFCertTemplateField inTemplateField);

/*
 * FUNCTION: CRMF_CertRequestIsControlPresent
 * INPUTS:
 *    inCertReq
 *        The certificate request to operate on.
 *    inControlType
 *        The type of control to look for.
 * NOTES:
 * This function looks at the control present in the certificate request
 * and returns PR_TRUE iff a control of type inControlType already exists.
 * The CRMF draft does not explicitly state that two controls of the same
 * type can not exist within the same request.  So the library will not
 * cause an error if you try to add a control and one of the same type
 * already exists.  It is up to the application to ensure that multiple
 * controls of the same type do not exist, if that is the desired behavior
 * by the application.
 *
 * RETURN:
 * The function returns PR_TRUE if a control of type inControlType already
 * exists in the certificate request.  If a control of type inControlType
 * does not exist, the function will return PR_FALSE.
 */
extern PRBool
CRMF_CertRequestIsControlPresent(CRMFCertRequest *inCertReq,
                                 CRMFControlType inControlType);

/*
 * FUNCTION: CRMF_CertRequestSetRegTokenControl
 * INPUTS:
 *    inCertReq
 *        The Certificate Request to operate on.
 *    value
 *        The UTF8 value which will be the Registration Token Control
 *        for this Certificate Request.
 * NOTES:
 *    The library does no verification that the value passed in is
 *    a valid UTF8 value.  The caller must make sure of this in order
 *    to get an encoding that is valid.  The library will ultimately
 *    encode this value as it was passed in.
 * RETURN:
 *    SECSucces on successful addition of the Registration Token Control.
 *    Any other return value indicates an unsuccessful attempt to add the
 *    control.
 *
 */
extern SECStatus CRMF_CertRequestSetRegTokenControl(CRMFCertRequest *inCertReq,
                                                    SECItem *value);

/*
 * FUNCTION: CRMF_CertRequestSetAuthenticatorControl
 * INPUTS:
 *    inCertReq
 *        The Certificate Request to operate on.
 *    value
 *        The UTF8 value that will become the Authenticator Control
 *        for the passed in Certificate Request.
 * NOTES:
 *    The library does no verification that the value passed in is
 *    a valid UTF8 value.  The caller must make sure of this in order
 *    to get an encoding that is valid.  The library will ultimately
 *    encode this value as it was passed in.
 * RETURN:
 *    SECSucces on successful addition of the Authenticator Control.
 *    Any other return value indicates an unsuccessful attempt to add the
 *    control.
 */
extern SECStatus
CRMF_CertRequestSetAuthenticatorControl(CRMFCertRequest *inCertReq,
                                        SECItem *value);

/*
 * FUNCTION: CRMF_CreateEncryptedKeyWithencryptedValue
 * INPUTS:
 *    inPrivKey
 *        This is the private key associated with a certificate that is
 *        being requested.  This structure will eventually wind up as
 *        a part of the PKIArchiveOptions Control.
 *    inCACert
 *        This is the certificate for the CA that will be receiving the
 *        certificate request for the private key passed in.
 * OUTPUT:
 *    A CRMFEncryptedKey that can ultimately be used as part of the
 *    PKIArchiveOptions Control.
 *
 * RETURN:
 *    A pointer to a CRMFEncyptedKey.  A NULL return value indicates an erro
 *    during the creation of the encrypted key.
 */
extern CRMFEncryptedKey *
CRMF_CreateEncryptedKeyWithEncryptedValue(SECKEYPrivateKey *inPrivKey,
                                          CERTCertificate *inCACert);

/*
 * FUNCTION: CRMF_DestroyEncryptedKey
 * INPUTS:
 *    inEncrKey
 *        The CRMFEncryptedKey to be destroyed.
 * NOTES:
 *    Frees all memory associated with the CRMFEncryptedKey passed in.
 * RETURN:
 *    SECSuccess if freeing the memory was successful.  Any other return
 *    value indicates an error while freeig the memroy.
 */
extern SECStatus CRMF_DestroyEncryptedKey(CRMFEncryptedKey *inEncrKey);

/*
 * FUNCTION: CRMF_CreatePKIArchiveOptions
 * INPUTS:
 *    inType
 *        An enumeration value indicating which option for
 *        PKIArchiveOptions to use.
 *    data
 *        A pointer that will be type-cast and de-referenced according
 *        to the table under NOTES.
 * NOTES:
 * A table listing what should be passed in as data
 * ------------------------------------------------
 *
 * inType                            data
 * ------                            ----
 * crmfEncryptedPrivateKey           CRMFEncryptedKey*
 * crmfKeyGenParameters              SECItem*(This needs to be an octet string)
 * crmfArchiveRemGenPrivKey          PRBool*
 *
 * RETURN:
 *    A pointer the a CRMFPKIArchiveOptions that can be added to a Certificate
 *    Request.  A NULL pointer indicates an error occurred while creating
 *    the CRMFPKIArchiveOptions Structure.
 */
extern CRMFPKIArchiveOptions *
CRMF_CreatePKIArchiveOptions(CRMFPKIArchiveOptionsType inType,
                             void *data);
/*
 * FUNCTION: CRMF_DestroyPKIArchiveOptions
 * INPUTS:
 *    inArchOpt
 *        A pointer to the CRMFPKIArchiveOptions structure to free.
 * NOTES:
 *    Will free all memory associated with 'inArchOpt'.
 * RETURN:
 *    SECSuccess if successful in freeing the memory used by 'inArchOpt'
 *    Any other return value indicates an error while freeing the memory.
 */
extern SECStatus
CRMF_DestroyPKIArchiveOptions(CRMFPKIArchiveOptions *inArchOpt);

/*
 * FUNCTION: CRMF_CertRequestSetPKIArchiveOptions
 * INPUTS:
 *    inCertReq
 *        The Certificate Request to add the the options to.
 *    inOptions
 *        The Archive Options to add to the Certificate Request.
 * NOTES:
 *    Adds the PKIArchiveOption to the Certificate Request.  This is what
 *    enables Key Escrow to take place through CRMF.  The library makes
 *    its own copy of the information.
 * RETURN:
 *    SECSuccess if successful in adding the ArchiveOptions to the Certificate
 *    request.  Any other return value indicates an error when trying to add
 *    the Archive Options  to the Certificate Request.
 */
extern SECStatus
CRMF_CertRequestSetPKIArchiveOptions(CRMFCertRequest *inCertReq,
                                     CRMFPKIArchiveOptions *inOptions);

/*
 * FUNCTION: CRMF_CertReqMsgGetPOPType
 * INPUTS:
 *    inCertReqMsg
 *        The Certificate Request Message to operate on.
 * NOTES:
 *    Returns an enumeration value indicating the method of Proof
 *    of Possession that was used for the passed in Certificate Request
 *    Message.
 * RETURN:
 *    An enumeration indicating what method for Proof Of Possession is
 *    being used in this Certificate Request Message.  Look in the file
 *    crmft.h for the definition of CRMFPOPChoice for the possible return
 *    values.
 */
extern CRMFPOPChoice CRMF_CertReqMsgGetPOPType(CRMFCertReqMsg *inCertReqMsg);

/*
 * FUNCTION: CRMF_CertReqMsgSetRAVerifiedPOP
 * INPUT:
 *    InCertReqMsg
 *        The Certificate Request Message to operate on.
 * NOTES:
 *    This function will set the method of Proof Of Possession to
 *    crmfRAVerified which means the RA has already verified the
 *    requester does possess the private key.
 * RETURN:
 *    SECSuccess if adding RAVerified to the message is successful.
 *    Any other message indicates an error while trying to add RAVerified
 *    as the Proof of Possession.
 */
extern SECStatus CRMF_CertReqMsgSetRAVerifiedPOP(CRMFCertReqMsg *inCertReqMsg);

/*
 * FUNCTION: CRMF_CertReqMsgSetSignaturePOP
 * INPUT:
 *    inCertReqMsg
 *        The Certificate Request Message to add the SignaturePOP to.
 *    inPrivKey
 *        The Private Key which corresponds to the the Certificate Request
 *        Message.
 *    inPubKey
 *        The Public Key which corresponds to the Private Key passed in.
 *    inCertForInput
 *        A Certificate that in the future may be used to create
 *        POPOSigningKeyInput.
 *    fn
 *        A callback for retrieving a password which may be used in the
 *       future to generate POPOSigningKeyInput.
 *    arg
 *        An opaque pointer that would be passed to fn whenever it is
 *        called.
 * NOTES:
 * Adds Proof Of Possession to the CertRequest using the signature field
 * of the ProofOfPossession field.  NOTE: In order to use this option,
 * the certificate template must contain the publicKey at the very minimum.
 *
 * If you don't want the function to generate POPOSigningKeyInput, then
 * make sure the cert template already contains the subject and public key
 * values.  Currently creating POPOSigningKeyInput is not supported, so
 * a Message passed to this function must have the publicKey and the subject
 * as part of the template
 *
 * This will take care of creating the entire POPOSigningKey structure
 * that will become part of the message.
 *
 * inPrivKey is the key to be used in the signing operation when creating
 * POPOSigningKey structure.  This should be the key corresponding to
 * the certificate being requested.
 *
 * inCertForInput will be used if POPOSigningKeyInput needs to be generated.
 * It will be used in generating the authInfo.sender field.  If the parameter
 * is not passed in then authInfo.publicKeyMAC will be generated instead.
 * If passed in, this certificate needs to be a valid certificate.
 *
 * The last 3 arguments are for future compatibility in case we ever want to
 * support generating POPOSigningKeyInput.  Pass in NULL for all 3 if you
 * definitely don't want the function to even try to generate
 * POPOSigningKeyInput.  If you try to use POPOSigningKeyInput, the function
 * will fail.
 *
 * RETURN:
 *    SECSuccess if adding the Signature Proof Of Possession worked.
 *    Any other return value indicates an error in trying to add
 *    the Signature Proof Of Possession.
 */
extern SECStatus
CRMF_CertReqMsgSetSignaturePOP(CRMFCertReqMsg *inCertReqMsg,
                               SECKEYPrivateKey *inPrivKey,
                               SECKEYPublicKey *inPubKey,
                               CERTCertificate *inCertForInput,
                               CRMFMACPasswordCallback fn,
                               void *arg);

/*
 * FUNCTION: CRMF_CertReqMsgSetKeyEnciphermentPOP
 * INPUTS:
 *    inCertReqMsg
 *        The Certificate Request Message to operate on.
 *    inKeyChoice
 *        An enumeration indicating which POPOPrivKey Choice to use
 *        in constructing the KeyEnciphermentPOP.
 *    subseqMess
 *        This parameter must be provided iff inKeyChoice is
 *        crmfSubsequentMessage.  This details how the RA is to respond
 *        in order to perform Proof Of Possession.  Look in crmft.h under
 *        the definition of CRMFSubseqMessOptions for possible values.
 *    encPrivKey
 *        This parameter only needs to be provided if inKeyChoice is
 *        crmfThisMessage.  The item should contain the encrypted private
 *        key.
 *
 * NOTES:
 * Adds Proof Of Possession using the keyEncipherment field of
 * ProofOfPossession.
 *
 * The function looks at the the inKeyChoice parameter and interprets it in
 * in the following manner.
 *
 * If a parameter is not mentioned under interpretation, the function will not
 * look at its value when implementing that case.
 *
 * inKeyChoice          Interpretation
 * -----------          --------------
 * crmfThisMessage      This options requires that the encrypted private key
 *                      be included in the thisMessage field of POPOPrivKey.
 *                      We don't support this yet, so any clients who want
 *                      to use this feature have to implement a wrapping
 *                      function and agree with the server on how to properly
 *                      wrap the key.  That encrypted key must be passed in
 *                      as the encPrivKey parameter.
 *
 * crmfSubequentMessage Must pass in a value for subseqMess.  The value must
 *                      be either CRMFEncrCert or CRMFChallengeResp.  The
 *                      parameter encPrivKey will not be looked at in this
 *                      case.
 *
 * crmfDHMAC            This is not a valid option for this function.  Passing
 *                      in this value will result in the function returning
 *                      SECFailure.
 * RETURN:
 *    SECSuccess if adding KeyEnciphermentPOP was successful.  Any other return
 *    value indicates an error in adding KeyEnciphermentPOP.
 */
extern SECStatus
CRMF_CertReqMsgSetKeyEnciphermentPOP(CRMFCertReqMsg *inCertReqMsg,
                                     CRMFPOPOPrivKeyChoice inKeyChoice,
                                     CRMFSubseqMessOptions subseqMess,
                                     SECItem *encPrivKey);

/*
 * FUNCTION: CRMF_CertReqMsgSetKeyAgreementPOP
 * INPUTS:
 *    inCertReqMsg
 *        The Certificate Request Message to operate on.
 *    inKeyChoice
 *        An enumeration indicating which POPOPrivKey Choice to use
 *        in constructing the KeyAgreementPOP.
 *    subseqMess
 *        This parameter must be provided iff inKeyChoice is
 *        crmfSubsequentMessage.  This details how the RA is to respond
 *        in order to perform Proof Of Possession.  Look in crmft.h under
 *        the definition of CRMFSubseqMessOptions for possible values.
 *    encPrivKey
 *        This parameter only needs to be provided if inKeyChoice is
 *        crmfThisMessage.  The item should contain the encrypted private
 *        key.
 * Adds Proof Of Possession using the keyAgreement field of
 * ProofOfPossession.
 *
 * The function looks at the the inKeyChoice parameter and interprets it in
 * in the following manner.
 *
 * If a parameter is not mentioned under interpretation, the function will not
 * look at its value when implementing that case.
 *
 * inKeyChoice          Interpretation
 * -----------          --------------
 * crmfThisMessage      This options requires that the encrypted private key
 *                      be included in the thisMessage field of POPOPrivKey.
 *                      We don't support this yet, so any clients who want
 *                      to use this feature have to implement a wrapping
 *                      function and agree with the server on how to properly
 *                      wrap the key.  That encrypted key must be passed in
 *                      as the encPrivKey parameter.
 *
 * crmfSubequentMessage Must pass in a value for subseqMess.  The value must
 *                      be either crmfEncrCert or crmfChallengeResp.  The
 *                      parameter encPrivKey will not be looked at in this
 *                      case.
 *
 * crmfDHMAC            This option is not supported.
 */
extern SECStatus
CRMF_CertReqMsgSetKeyAgreementPOP(CRMFCertReqMsg *inCertReqMsg,
                                  CRMFPOPOPrivKeyChoice inKeyChoice,
                                  CRMFSubseqMessOptions subseqMess,
                                  SECItem *encPrivKey);

/*
 * FUNCTION: CRMF_CreateCertReqMsgFromDER
 * INPUTS:
 *    buf
 *        A buffer to the DER-encoded Certificate Request Message.
 *    len
 *        The length in bytes of the buffer 'buf'
 * NOTES:
 * This function passes the buffer to the ASN1 decoder and creates a
 * CRMFCertReqMsg structure.  Do not try adding any fields to a message
 * returned from this function.  Specifically adding more Controls or
 * Extensions may cause your program to crash.
 *
 * RETURN:
 *    A pointer to the Certificate Request Message structure.  A NULL return
 *    value indicates the library was unable to parse the DER.
 */
extern CRMFCertReqMsg *CRMF_CreateCertReqMsgFromDER(const char *buf, long len);

/*
 * FUNCTION: CRMF_CreateCertReqMessagesFromDER
 * INPUTS:
 *    buf
 *        A buffer to the DER-encoded Certificate Request Messages.
 *    len
 *        The length in bytes of buf
 * NOTES:
 * This function passes the buffer to the ASN1 decoder and creates a
 * CRMFCertReqMessages structure.  Do not try adding any fields to a message
 * derived from this function.  Specifically adding more Controls or
 * Extensions may cause your program to crash.
 * The user must call CRMF_DestroyCertReqMessages after the return value is
 * no longer needed, ie when all individual messages have been extracted.
 *
 * RETURN:
 *    A pointer to the Certificate Request Messages structure.  A NULL return
 *    value indicates the library was unable to parse the DER.
 */
extern CRMFCertReqMessages *
CRMF_CreateCertReqMessagesFromDER(const char *buf, long len);

/*
 * FUNCTION: CRMF_DestroyCertReqMessages
 * INPUTS
 *    inCertReqMsgs
 *        The Messages to destroy.
 * RETURN:
 *    SECSuccess if freeing the memory was done successfully.  Any other
 *    return value indicates an error in freeing up memory.
 */
extern SECStatus
CRMF_DestroyCertReqMessages(CRMFCertReqMessages *inCertReqMsgs);

/*
 * FUNCTION: CRMF_CertReqMessagesGetNumMessages
 * INPUTS:
 *    inCertReqMsgs
 *        The Request Messages to operate on.
 * RETURN:
 *    The number of messages contained in the in the Request Messages
 *    strucure.
 */
extern int
CRMF_CertReqMessagesGetNumMessages(CRMFCertReqMessages *inCertReqMsgs);

/*
 * FUNCTION: CRMF_CertReqMessagesGetCertReqMsgAtIndex
 * INPUTS:
 *    inReqMsgs
 *        The Certificate Request Messages to operate on.
 *    index
 *        The index of the single message the user wants a copy of.
 * NOTES:
 * This function returns a copy of the request messages stored at the
 * index corresponding to the parameter 'index'.  Indexing of the messages
 * is done in the same manner as a C array.  Meaning the valid index are
 * 0...numMessages-1.  User must call CRMF_DestroyCertReqMsg when done using
 * the return value of this function.
 *
 * RETURN:
 * SECSuccess if copying the message at the requested index was successful.
 * Any other return value indicates an invalid index or error while copying
 * the single request message.
 */
extern CRMFCertReqMsg *
CRMF_CertReqMessagesGetCertReqMsgAtIndex(CRMFCertReqMessages *inReqMsgs,
                                         int index);

/*
 * FUNCTION: CRMF_CertReqMsgGetID
 * INPUTS:
 *    inCertReqMsg
 *        The Certificate Request Message to get the ID from.
 *    destID
 *        A pointer to where the library can place the ID of the Message.
 * RETURN:
 *    SECSuccess if the function was able to retrieve the ID and place it
 *    at *destID.  Any other return value indicates an error meaning the value
 *    in *destId is un-reliable and should not be used by the caller of this
 *    function.
 *
 */
extern SECStatus CRMF_CertReqMsgGetID(CRMFCertReqMsg *inCertReqMsg,
                                      long *destID);

/*
 * FUNCTION: CRMF_DoesRequestHaveField
 * INPUTS:
 *    inCertReq
 *        The Certificate Request to operate on.
 *    inField
 *        An enumeration indicating which filed of the certificate template
 *        to look for.
 * NOTES:
 * All the fields in a certificate template are optional.  This function
 * checks to see if the requested field is present.  Look in crmft.h at the
 * definition of CRMFCertTemplateField for possible values for possible
 * querying.
 *
 * RETURN:
 * PR_TRUE iff the field corresponding to 'inField' has been specified as part
 *         of 'inCertReq'
 * PR_FALSE iff the field corresponding to 'inField' has not been speicified
 *          as part of 'inCertReq'
 *
 */
extern PRBool CRMF_DoesRequestHaveField(CRMFCertRequest *inCertReq,
                                        CRMFCertTemplateField inField);

/*
 * FUNCTION: CRMF_CertReqMsgGetCertRequest
 * INPUTS:
 *    inCertReqMsg
 *        The Certificate Request Message to operate on.
 * NOTES:
 *    This function returns a copy of the Certificate Request to the user.
 *    The user can keep adding to this request and then making it a part
 *    of another message.  After the user no longer wants to use the
 *    returned request, the user must call CRMF_DestroyCertRequest and
 *    pass it the request returned by this function.
 * RETURN:
 *    A pointer to a copy of the certificate request contained by the message.
 *    A NULL return value indicates an error occurred while copying the
 *   certificate request.
 */
extern CRMFCertRequest *
CRMF_CertReqMsgGetCertRequest(CRMFCertReqMsg *inCertReqMsg);

/*
 * FUNCTION: CRMF_CertRequestGetCertTemplateVersion
 * INPUTS:
 *    inCertReq
 *        The Certificate Request to operate on.
 *    version
 *        A pointer to where the library can store the version contatined
 *        in the certificate template within the certifcate request.
 * RETURN:
 *    SECSuccess if the Certificate template contains the version field.  In
 *    this case, *version will hold the value of the certificate template
 *    version.
 *    SECFailure indicates that version field was not present as part of
 *    of the certificate template.
 */
extern SECStatus
CRMF_CertRequestGetCertTemplateVersion(CRMFCertRequest *inCertReq,
                                       long *version);

/*
 * FUNCTION: CRMF_CertRequestGetCertTemplateSerialNumber
 * INPUTS:
 *    inCertReq
 *        The certificate request to operate on.
 *    serialNumber
 *        A pointer where the library can put the serial number contained
 *        in the certificate request's certificate template.
 * RETURN:
 * If a serial number exists in the CertTemplate of the request, the function
 * returns SECSuccess and the value at *serialNumber contains the serial
 * number.
 * If no serial number is present, then the function returns SECFailure and
 * the value at *serialNumber is un-changed.
 */
extern SECStatus
CRMF_CertRequestGetCertTemplateSerialNumber(CRMFCertRequest *inCertReq,
                                            long *serialNumber);

/*
 * FUNCTION: CRMF_CertRequestGetCertTemplateSigningAlg
 * INPUT:
 *    inCertReq
 *        The Certificate Request to operate on.
 *    destAlg
 *        A Pointer to where the library can place a copy of the signing alg
 *        used in the cert request's cert template.
 * RETURN:
 * If the signingAlg is present in the CertRequest's CertTemplate, then
 * the function returns SECSuccess and places a copy of sigingAlg in
 * *destAlg.
 * If no signingAlg is present, then the function returns SECFailure and
 * the value at *destAlg is un-changed
 */
extern SECStatus
CRMF_CertRequestGetCertTemplateSigningAlg(CRMFCertRequest *inCertReq,
                                          SECAlgorithmID *destAlg);
/*
 * FUNCTION: CRMF_CertRequestGetCertTemplateIssuer
 * INPUTS:
 *    inCertReq
 *        The Certificate Request to operate on.
 *    destIssuer
 *        A pointer to where the library can place a copy of the cert
 *        request's cert template issuer field.
 * RETURN:
 * If the issuer is present in the cert request cert template, the function
 * returns SECSuccess and places a  copy of the issuer in *destIssuer.
 * If there is no issuer present, the function returns SECFailure and the
 * value at *destIssuer is unchanged.
 */
extern SECStatus
CRMF_CertRequestGetCertTemplateIssuer(CRMFCertRequest *inCertReq,
                                      CERTName *destIssuer);

/*
 * FUNCTION: CRMF_CertRequestGetCertTemplateValidity
 * INPUTS:
 *    inCertReq
 *        The Certificate Request to operate on.
 *    destValdity
 *        A pointer to where the library can place a copy of the validity
 *        info in the cert request cert template.
 * NOTES:
 * Pass the pointer to
 * RETURN:
 * If there is an OptionalValidity field, the function will return SECSuccess
 * and place the appropriate values in *destValidity->notBefore and
 * *destValidity->notAfter. (Each field is optional, but at least one will
 * be present if the function returns SECSuccess)
 *
 * If there is no OptionalValidity field, the function will return SECFailure
 * and the values at *destValidity will be un-changed.
 */
extern SECStatus
CRMF_CertRequestGetCertTemplateValidity(CRMFCertRequest *inCertReq,
                                        CRMFGetValidity *destValidity);
/*
 * FUNCTION: CRMF_DestroyGetValidity
 * INPUTS:
 *    inValidity
 *        A pointer to the memroy to be freed.
 * NOTES:
 * The function will free the memory allocated by the function
 * CRMF_CertRequestGetCertTemplateValidity.  That means only memory pointed
 * to within the CRMFGetValidity structure.  Since
 * CRMF_CertRequestGetCertTemplateValidity does not allocate memory for the
 * structure passed into it, it will not free it.  Meaning this function will
 * free the memory at inValidity->notBefore and inValidity->notAfter, but not
 * the memory directly at inValdity.
 *
 * RETURN:
 * SECSuccess if freeing the memory was successful.  Any other return value
 * indicates an error while freeing the memory.
 */
extern SECStatus
CRMF_DestroyGetValidity(CRMFGetValidity *inValidity);

/*
 * FUNCTION: CRMF_CertRequestGetCertTemplateSubject
 * INPUTS:
 *    inCertReq
 *        The Certificate Request to operate on.
 *    destSubject
 *        A pointer to where the library can place a copy of the subject
 *        contained in the request's cert template.
 * RETURN:
 * If there is a subject in the CertTemplate, then the function returns
 * SECSuccess and a copy of the subject is placed in *destSubject.
 *
 * If there is no subject, the function returns SECFailure and the values at
 * *destSubject is unchanged.
 */
extern SECStatus
CRMF_CertRequestGetCertTemplateSubject(CRMFCertRequest *inCertReq,
                                       CERTName *destSubject);

/*
 * FUNCTION: CRMF_CertRequestGetCertTemplatePublicKey
 * INPUTS:
 *    inCertReq
 *        The Cert request to operate on.
 *    destPublicKey
 *        A pointer to where the library can place a copy of the request's
 *        cert template public key.
 * RETURN:
 * If there is a publicKey parameter in the CertRequest, the function returns
 * SECSuccess, and places a copy of the publicKey in *destPublicKey.
 *
 * If there is no publicKey, the function returns SECFailure and the value
 * at *destPublicKey is un-changed.
 */
extern SECStatus
CRMF_CertRequestGetCertTemplatePublicKey(CRMFCertRequest *inCertReq,
                                         CERTSubjectPublicKeyInfo *destPublicKey);

/*
 * FUNCTION: CRMF_CertRequestGetCertTemplateIssuerUID
 * INPUTS:
 *    inCertReq
 *        The Cert request to operate on.
 *    destIssuerUID
 *        A pointer to where the library can store a copy of the request's
 *        cert template destIssuerUID.
 *
 * NOTES:
 * destIssuerUID is a bit string and will be returned in a SECItem as
 * a bit string.  Meaning the len field contains the number of valid bits as
 * opposed to the number of bytes allocated.
 *
 * RETURN:
 * If the CertTemplate has an issuerUID, the function returns SECSuccess and
 * places a copy of the issuerUID in *destIssuerUID.
 *
 * If there is no issuerUID, the function returns SECFailure and the value
 * *destIssuerUID is unchanged.
 */
extern SECStatus
CRMF_CertRequestGetCertTemplateIssuerUID(CRMFCertRequest *inCertReq,
                                         SECItem *destIssuerUID);

/*
 * FUNCTION: CRMF_CertRequestGetCertTemplateSubjectUID
 *    inCertReq
 *        The Cert request to operate on.
 *    destSubjectUID
 *        A pointer to where the library can store a copy of the request's
 *        cert template destIssuerUID.
 *
 * NOTES:
 * destSubjectUID is a bit string and will be returned in a SECItem as
 * a bit string.  Meaning the len field contains the number of valid bits as
 * opposed to the number of bytes allocated.
 *
 * RETURN:
 * If the CertTemplate has an issuerUID, the function returns SECSuccess and
 * places a copy of the issuerUID in *destIssuerUID.
 *
 * If there is no issuerUID, the function returns SECSuccess and the value
 * *destIssuerUID is unchanged.
 */
extern SECStatus CRMF_GetCertTemplateSubjectUID(CRMFCertRequest *inCertReq,
                                                SECItem *destSubjectUID);

/*
 * FUNCTION: CRMF_CertRequestGetNumberOfExtensions
 * INPUTS:
 *    inCertReq
 *        The cert request to operate on.
 * RETURN:
 *    Returns the number of extensions contained by the Cert Request.
 */
extern int CRMF_CertRequestGetNumberOfExtensions(CRMFCertRequest *inCertReq);

/*
 * FUNCTION: CRMF_CertRequestGetExtensionAtIndex
 * INPUTS:
 *    inCertReq
 *        The Certificate request to operate on.
 *    index
 *        The index of the extension array whihc the user wants to access.
 * NOTES:
 * This function retrieves the extension at the index corresponding to the
 * parameter "index" indicates.  Indexing is done like a C array.
 * (0 ... numElements-1)
 *
 * Call CRMF_DestroyCertExtension when done using the return value.
 *
 * RETURN:
 *    A pointer to a copy of the extension at the desired index.  A NULL
 *    return value indicates an invalid index or an error while copying
 *    the extension.
 */
extern CRMFCertExtension *
CRMF_CertRequestGetExtensionAtIndex(CRMFCertRequest *inCertReq,
                                    int index);
/*
 * FUNCTION: CRMF_CertExtensionGetOidTag
 * INPUTS:
 *    inExtension

 *        The extension to operate on.
 * RETURN:
 *    Returns the SECOidTag associated with the cert extension passed in.
 */
extern SECOidTag CRMF_CertExtensionGetOidTag(CRMFCertExtension *inExtension);

/*
 * FUNCTION: CRMF_CertExtensionGetIsCritical
 * INPUT:
 *    inExt
 *        The cert extension to operate on.
 *
 * RETURN:
 * PR_TRUE if the extension is critical.
 * PR_FALSE if the extension is not critical.
 */
extern PRBool CRMF_CertExtensionGetIsCritical(CRMFCertExtension *inExt);

/*
 * FUNCTION: CRMF_CertExtensionGetValue
 * INPUT:
 *    inExtension
 *        The extension to operate on.
 * NOTES:
 * Caller is responsible for freeing the memory associated with the return
 * value.  Call SECITEM_FreeItem(retVal, PR_TRUE) when done using the return
 * value.
 *
 * RETURN:
 * A pointer to an item containig the value for the certificate extension.
 * A NULL return value indicates an error in copying the information.
 */
extern SECItem *CRMF_CertExtensionGetValue(CRMFCertExtension *inExtension);

/*
 * FUNCTION: CRMF_CertReqMsgGetPOPOSigningKey
 * INPUTS:
 *    inCertReqMsg
 *        The certificate request message to operate on.
 *    destKey
 *        A pointer to where the library can place a pointer to
 *        a copy of the Proof Of Possession Signing Key used
 *        by the message.
 *
 * RETURN:
 * Get the POPOSigningKey associated with this CRMFCertReqMsg.
 * If the CertReqMsg does not have a pop, the function returns
 * SECFailure and the value at *destKey is un-changed..
 *
 * If the CertReqMsg does have a pop, then the CertReqMsg's
 * POPOSigningKey will be placed at *destKey.
 */
extern SECStatus
CRMF_CertReqMsgGetPOPOSigningKey(CRMFCertReqMsg *inCertReqMsg,
                                 CRMFPOPOSigningKey **destKey);

/*
 * FUNCTION: CRMF_DestroyPOPOSigningKey
 * INPUTS:
 *    inKey
 *        The signing key to free.
 *
 * RETURN:
 * SECSuccess if freeing the memory was successful.  Any other return value
 * indicates an error while freeing memory.
 */
extern SECStatus CRMF_DestroyPOPOSigningKey(CRMFPOPOSigningKey *inKey);

/*
 * FUNCTION: CRMF_POPOSigningKeyGetAlgID
 * INPUTS:
 *    inSignKey
 *        The Signing Key to operate on.
 * RETURN:
 * Return the algorithmID used by the CRMFPOPOSigningKey.  User must
 * call SECOID_DestroyAlgorithmID(destID, PR_TRUE) when done using the
 * return value.
 */
extern SECAlgorithmID *
CRMF_POPOSigningKeyGetAlgID(CRMFPOPOSigningKey *inSignKey);

/*
 * FUNCTION: CRMF_POPOSigningKeyGetSignature
 * INPUTS:
 *    inSignKey
 *        The Signing Key to operate on.
 *
 * RETURN:
 * Get the actual signature stored away in the CRMFPOPOSigningKey.  SECItem
 * returned is a BIT STRING, so the len field is the number of bits as opposed
 * to the total number of bytes allocatd.  User must call
 * SECITEM_FreeItem(retVal,PR_TRUE) when done using the return value.
 */
extern SECItem *CRMF_POPOSigningKeyGetSignature(CRMFPOPOSigningKey *inSignKey);

/*
 * FUNCTION: CRMF_POPOSigningKeyGetInput
 * INPUTS:
 *    inSignKey
 *        The Signing Key to operate on.
 * NOTES:
 * This function will return the der encoded input that was read in while
 * decoding.  The API does not support this option when creating, so you
 * cannot add this field.
 *
 * RETURN:
 * Get the poposkInput that is part of the of the POPOSigningKey. If the
 * optional field is not part of the POPOSigningKey, the function returns
 * NULL.
 *
 * If the optional field is part of the POPOSingingKey, the function will
 * return a copy of the der encoded poposkInput.
 */
extern SECItem *CRMF_POPOSigningKeyGetInput(CRMFPOPOSigningKey *inSignKey);

/*
 * FUNCTION: CRMF_CertReqMsgGetPOPKeyEncipherment
 * INPUTS:
 *    inCertReqMsg
 *        The certificate request message to operate on.
 *    destKey
 *        A pointer to where the library can place a pointer to a
 *        copy of the POPOPrivKey representing Key Encipherment
 *        Proof of Possession.
 *NOTES:
 * This function gets the POPOPrivKey associated with this CRMFCertReqMsg
 * for Key Encipherment.
 *
 * RETURN:
 * If the CertReqMsg did not use Key Encipherment for Proof Of Possession, the
 * function returns SECFailure and the value at *destKey is un-changed.
 *
 * If the CertReqMsg did use Key Encipherment for ProofOfPossession, the
 * function returns SECSuccess and places the POPOPrivKey representing the
 * Key Encipherment Proof Of Possessin at *destKey.
 */
extern SECStatus
CRMF_CertReqMsgGetPOPKeyEncipherment(CRMFCertReqMsg *inCertReqMsg,
                                     CRMFPOPOPrivKey **destKey);

/*
 * FUNCTION: CRMF_CertReqMsgGetPOPKeyAgreement
 * INPUTS:
 *    inCertReqMsg
 *        The certificate request message to operate on.
 *    destKey
 *        A pointer to where the library can place a pointer to a
 *        copy of the POPOPrivKey representing Key Agreement
 *        Proof of Possession.
 * NOTES:
 * This function gets the POPOPrivKey associated with this CRMFCertReqMsg for
 * Key Agreement.
 *
 * RETURN:
 * If the CertReqMsg used Key Agreement for Proof Of Possession, the
 * function returns SECSuccess and the POPOPrivKey for Key Agreement
 * is placed at *destKey.
 *
 * If the CertReqMsg did not use Key Agreement for Proof Of Possession, the
 * function return SECFailure and the value at *destKey is unchanged.
 */
extern SECStatus
CRMF_CertReqMsgGetPOPKeyAgreement(CRMFCertReqMsg *inCertReqMsg,
                                  CRMFPOPOPrivKey **destKey);

/*
 * FUNCTION: CRMF_DestroyPOPOPrivKey
 * INPUTS:
 *    inPrivKey
 *        The POPOPrivKey to destroy.
 * NOTES:
 * Destroy a structure allocated by CRMF_GetPOPKeyEncipherment or
 * CRMF_GetPOPKeyAgreement.
 *
 * RETURN:
 * SECSuccess on successful destruction of the POPOPrivKey.
 * Any other return value indicates an error in freeing the
 * memory.
 */
extern SECStatus CRMF_DestroyPOPOPrivKey(CRMFPOPOPrivKey *inPrivKey);

/*
 * FUNCTION: CRMF_POPOPrivKeyGetChoice
 * INPUT:
 *    inKey
 *        The POPOPrivKey to operate on.
 * RETURN:
 * Returns which choice was used in constructing the POPPOPrivKey. Look at
 * the definition of CRMFPOPOPrivKeyChoice in crmft.h for the possible return
 * values.
 */
extern CRMFPOPOPrivKeyChoice CRMF_POPOPrivKeyGetChoice(CRMFPOPOPrivKey *inKey);

/*
 * FUNCTION: CRMF_POPOPrivKeyGetThisMessage
 * INPUTS:
 *    inKey
 *        The POPOPrivKey to operate on.
 *    destString
 *        A pointer to where the library can place a copy of the This Message
 *        field stored in the POPOPrivKey
 *
 * RETURN:
 * Returns the field thisMessage from the POPOPrivKey.
 * If the POPOPrivKey did not use the field thisMessage, the function
 * returns SECFailure and the value at *destString is unchanged.
 *
 * If the POPOPrivKey did use the field thisMessage, the function returns
 * SECSuccess and the BIT STRING representing thisMessage is placed
 * at *destString. BIT STRING representation means the len field is the
 * number of valid bits as opposed to the total number of bytes.
 */
extern SECStatus CRMF_POPOPrivKeyGetThisMessage(CRMFPOPOPrivKey *inKey,
                                                SECItem *destString);

/*
 * FUNCTION: CRMF_POPOPrivKeyGetSubseqMess
 * INPUTS:
 *    inKey
 *        The POPOPrivKey to operate on.
 *    destOpt
 *        A pointer to where the library can place the value of the
 *        Subsequent Message option used by POPOPrivKey.
 *
 * RETURN:
 * Retrieves the field subsequentMessage from the POPOPrivKey.
 * If the POPOPrivKey used the subsequentMessage option, the function
 * returns SECSuccess and places the appropriate enumerated value at
 * *destMessageOption.
 *
 * If the POPOPrivKey did not use the subsequenMessage option, the function
 * returns SECFailure and the value at *destOpt is un-changed.
 */
extern SECStatus CRMF_POPOPrivKeyGetSubseqMess(CRMFPOPOPrivKey *inKey,
                                               CRMFSubseqMessOptions *destOpt);

/*
 * FUNCTION: CRMF_POPOPrivKeyGetDHMAC
 * INPUTS:
 *    inKey
 *        The POPOPrivKey to operate on.
 *    destMAC
 *        A pointer to where the library can place a copy of the dhMAC
 *        field of the POPOPrivKey.
 *
 * NOTES:
 * Returns the field dhMAC from the POPOPrivKey.  The populated SECItem
 * is in BIT STRING format.
 *
 * RETURN:
 * If the POPOPrivKey used the dhMAC option, the function returns SECSuccess
 * and the BIT STRING for dhMAC will be placed at *destMAC.  The len field in
 * destMAC (ie destMAC->len) will be the valid number of bits as opposed to
 * the number of allocated bytes.
 *
 * If the POPOPrivKey did not use the dhMAC option, the function returns
 * SECFailure and the value at *destMAC is unchanged.
 *
 */
extern SECStatus CRMF_POPOPrivKeyGetDHMAC(CRMFPOPOPrivKey *inKey,
                                          SECItem *destMAC);

/*
 * FUNCTION: CRMF_CertRequestGetNumControls
 * INPUTS:
 *    inCertReq
 *        The Certificate Request to operate on.
 * RETURN:
 * Returns the number of Controls registered with this CertRequest.
 */
extern int CRMF_CertRequestGetNumControls(CRMFCertRequest *inCertReq);

/*
 * FUNCTION: CRMF_CertRequestGetControlAtIndex
 * INPUTS:
 *    inCertReq
 *        The certificate request to operate on.
 *    index
 *        The index of the control the user wants a copy of.
 * NOTES:
 * Function retrieves the Control at located at index.  The Controls
 * are numbered like a traditional C array (0 ... numElements-1)
 *
 * RETURN:
 * Returns a copy of the control at the index specified.  This is a copy
 * so the user must call CRMF_DestroyControl after the return value is no
 * longer needed.  A return value of NULL indicates an error while copying
 * the control or that the index was invalid.
 */
extern CRMFControl *
CRMF_CertRequestGetControlAtIndex(CRMFCertRequest *inCertReq,
                                  int index);

/*
 * FUNCTION: CRMF_DestroyControl
 * INPUTS:
 *    inControl
 *        The Control to destroy.
 * NOTES:
 * Destroy a CRMFControl allocated by CRMF_GetControlAtIndex.
 *
 * RETURN:
 * SECSuccess if freeing the memory was successful.  Any other return
 * value indicates an error while freeing the memory.
 */
extern SECStatus CRMF_DestroyControl(CRMFControl *inControl);

/*
 * FUNCTION: CRMF_ControlGetControlType
 * INPUTS:
 *    inControl
 *        The control to operate on.
 * NOTES:
 * The function returns an enumertion which indicates the type of control
 * 'inControl'.
 *
 * RETURN:
 * Look in crmft.h at the definition of the enumerated type CRMFControlType
 * for the possible return values.
 */
extern CRMFControlType CRMF_ControlGetControlType(CRMFControl *inControl);

/*
 * FUNCTION: CRMF_ControlGetRegTokenControlValue
 * INPUTS:
 *    inControl
 *        The Control to operate on.
 * NOTES:
 * The user must call SECITEM_FreeItem passing in the return value
 * after the returnvalue is no longer needed.

 * RETURN:
 * Return the value for a Registration Token Control.
 * The SECItem returned should be in UTF8 format.  A NULL
 * return value indicates there was no Registration Control associated
 * with the Control.
 * (This library will not verify format.  It assumes the client properly
 * formatted the strings when adding it or the message decoded was properly
 * formatted.  The library will just give back the bytes it was given.)
 */
extern SECItem *CRMF_ControlGetRegTokenControlValue(CRMFControl *inControl);

/*
 * FUNCTION: CRMF_ControlGetAuthenticatorControlValue
 * INPUTS:
 *    inControl
 *        The Control to operate on.
 * NOTES:
 * The user must call SECITEM_FreeItem passing in the return value
 * after the returnvalue is no longer needed.
 *
 * RETURN:
 * Return the value for the Authenticator Control.
 * The SECItem returned should be in UTF8 format.  A NULL
 * return value indicates there was no Authenticator Control associated
 * with the CRMFControl..
 * (This library will not verify format.  It assumes the client properly
 * formatted the strings when adding it or the message decoded was properly
 * formatted.  The library will just give back the bytes it was given.)
 */
extern SECItem *CRMF_ControlGetAuthicatorControlValue(CRMFControl *inControl);

/*
 * FUNCTION: CRMF_ControlGetPKIArchiveOptions
 * INPUTS:inControl
 *    The Control tooperate on.
 * NOTES:
 * This function returns a copy of the PKIArchiveOptions.  The user must call
 * the function CRMF_DestroyPKIArchiveOptions when the return value is no
 * longer needed.
 *
 * RETURN:
 * Get the PKIArchiveOptions associated with the Control.  A return
 * value of NULL indicates the Control was not a PKIArchiveOptions
 * Control.
 */
extern CRMFPKIArchiveOptions *
CRMF_ControlGetPKIArchiveOptions(CRMFControl *inControl);

/*
 * FUNCTION: CMRF_DestroyPKIArchiveOptions
 * INPUTS:
 *    inOptions
 *        The ArchiveOptions to destroy.
 * NOTE:
 * Destroy the CRMFPKIArchiveOptions structure.
 *
 * RETURN:
 * SECSuccess if successful in freeing all the memory associated with
 * the PKIArchiveOptions.  Any other return value indicates an error while
 * freeing the PKIArchiveOptions.
 */
extern SECStatus
CRMF_DestroyPKIArchiveOptions(CRMFPKIArchiveOptions *inOptions);

/*
 * FUNCTION: CRMF_PKIArchiveOptionsGetOptionType
 * INPUTS:
 *    inOptions
 *        The PKIArchiveOptions to operate on.
 * RETURN:
 * Returns the choice used for the PKIArchiveOptions.  Look at the definition
 * of CRMFPKIArchiveOptionsType in crmft.h for possible return values.
 */
extern CRMFPKIArchiveOptionsType
CRMF_PKIArchiveOptionsGetOptionType(CRMFPKIArchiveOptions *inOptions);

/*
 * FUNCTION: CRMF_PKIArchiveOptionsGetEncryptedPrivKey
 * INPUTS:
 *    inOpts
 *        The PKIArchiveOptions to operate on.
 *
 * NOTES:
 * The user must call CRMF_DestroyEncryptedKey when done using this return
 * value.
 *
 * RETURN:
 * Get the encryptedPrivKey field of the PKIArchiveOptions structure.
 * A return value of NULL indicates that encryptedPrivKey was not used as
 * the choice for this PKIArchiveOptions.
 */
extern CRMFEncryptedKey *
CRMF_PKIArchiveOptionsGetEncryptedPrivKey(CRMFPKIArchiveOptions *inOpts);

/*
 * FUNCTION: CRMF_EncryptedKeyGetChoice
 * INPUTS:
 *    inEncrKey
 *        The EncryptedKey to operate on.
 *
 * NOTES:
 * Get the choice used for representing the EncryptedKey.
 *
 * RETURN:
 * Returns the Choice used in representing the EncryptedKey.  Look in
 * crmft.h at the definition of CRMFEncryptedKeyChoice for possible return
 * values.
 */
extern CRMFEncryptedKeyChoice
CRMF_EncryptedKeyGetChoice(CRMFEncryptedKey *inEncrKey);

/*
 * FUNCTION: CRMF_EncryptedKeyGetEncryptedValue
 * INPUTS:
 *    inKey
 *        The EncryptedKey to operate on.
 *
 * NOTES:
 * The user must call CRMF_DestroyEncryptedValue passing in
 * CRMF_GetEncryptedValue's return value.
 *
 * RETURN:
 * A pointer to a copy of the EncryptedValue contained as a member of
 * the EncryptedKey.
 */
extern CRMFEncryptedValue *
CRMF_EncryptedKeyGetEncryptedValue(CRMFEncryptedKey *inKey);

/*
 * FUNCTION: CRMF_DestroyEncryptedValue
 * INPUTS:
 *    inEncrValue
 *        The EncryptedValue to destroy.
 *
 * NOTES:
 * Free up all memory associated with 'inEncrValue'.
 *
 * RETURN:
 * SECSuccess if freeing up the memory associated with the EncryptedValue
 * is successful. Any other return value indicates an error while freeing the
 * memory.
 */
extern SECStatus CRMF_DestroyEncryptedValue(CRMFEncryptedValue *inEncrValue);

/*
 * FUNCTION: CRMF_EncryptedValueGetEncValue
 * INPUTS:
 *    inEncValue
 *        The EncryptedValue to operate on.
 * NOTES:
 * Function retrieves the encValue from an EncryptedValue structure.
 *
 * RETURN:
 * A poiner to a SECItem containing the encValue of the EncryptedValue
 * structure.  The return value is in BIT STRING format, meaning the
 * len field of the return structure represents the number of valid bits
 * as opposed to the allocated number of bytes.
 * ANULL return value indicates an error in copying the encValue field.
 */
extern SECItem *CRMF_EncryptedValueGetEncValue(CRMFEncryptedValue *inEncValue);

/*
 * FUNCTION: CRMF_EncryptedValueGetIntendedAlg
 * INPUTS
 *    inEncValue
 *        The EncryptedValue to operate on.
 * NOTES:
 * Retrieve the IntendedAlg field from the EncryptedValue structure.
 * Call SECOID_DestroyAlgorithmID (destAlgID, PR_TRUE) after done using
 * the return value.  When present, this alogorithm is the alogrithm for
 * which the private key will be used.
 *
 * RETURN:
 * A Copy of the intendedAlg field.  A NULL return value indicates the
 * optional field was not present in the structure.
 */
extern SECAlgorithmID *
CRMF_EncryptedValueGetIntendedAlg(CRMFEncryptedValue *inEncValue);

/*
 * FUNCTION: CRMF_EncryptedValueGetSymmAlg
 * INPUTS
 *    inEncValue
 *        The EncryptedValue to operate on.
 * NOTES:
 * Retrieve the symmAlg field from the EncryptedValue structure.
 * Call SECOID_DestroyAlgorithmID (destAlgID, PR_TRUE) after done using
 * the return value.  When present, this is algorithm used to
 * encrypt the encValue of the EncryptedValue.
 *
 * RETURN:
 * A Copy of the symmAlg field.  A NULL return value indicates the
 * optional field was not present in the structure.
 */
extern SECAlgorithmID *
CRMF_EncryptedValueGetSymmAlg(CRMFEncryptedValue *inEncValue);

/*
 * FUNCTION: CRMF_EncryptedValueGetKeyAlg
 * INPUTS
 *    inEncValue
 *        The EncryptedValue to operate on.
 * NOTES:
 * Retrieve the keyAlg field from the EncryptedValue structure.
 * Call SECOID_DestroyAlgorithmID (destAlgID, PR_TRUE) after done using
 * the return value.  When present, this is the algorithm used to encrypt
 * the symmetric key in the encSymmKey field of the EncryptedValue structure.
 *
 * RETURN:
 * A Copy of the keyAlg field.  A NULL return value indicates the
 * optional field was not present in the structure.
 */
extern SECAlgorithmID *
CRMF_EncryptedValueGetKeyAlg(CRMFEncryptedValue *inEncValue);

/*
 * FUNCTION: CRMF_EncryptedValueGetValueHint
 * INPUTS:
 *    inEncValue
 *        The EncryptedValue to operate on.
 *
 * NOTES:
 * Return a copy of the der-encoded value hint.
 * User must call SECITEM_FreeItem(retVal, PR_TRUE) when done using the
 * return value.  When, present, this is a value that the client which
 * originally issued a certificate request can use to reproduce any data
 * it wants.  The RA does not know how to interpret this data.
 *
 * RETURN:
 * A copy of the valueHint field of the EncryptedValue.  A NULL return
 * value indicates the optional valueHint field is not present in the
 * EncryptedValue.
 */
extern SECItem *
CRMF_EncryptedValueGetValueHint(CRMFEncryptedValue *inEncValue);

/*
 * FUNCTION: CRMF_EncrypteValueGetEncSymmKey
 * INPUTS:
 *    inEncValue
 *        The EncryptedValue to operate on.
 *
 * NOTES:
 * Return a copy of the encSymmKey field. This field is the encrypted
 * symmetric key that the client uses in doing Public Key wrap of a private
 * key.  When present, this is the symmetric key that was used to wrap the
 * private key.  (The encrypted private key will be stored in encValue
 * of the same EncryptedValue structure.)  The user must call
 * SECITEM_FreeItem(retVal, PR_TRUE) when the return value is no longer
 * needed.
 *
 * RETURN:
 * A copy of the optional encSymmKey field of the EncryptedValue structure.
 * The return value will be in BIT STRING format, meaning the len field will
 * be the number of valid bits as opposed to the number of bytes. A return
 * value of NULL means the optional encSymmKey field was not present in
 * the EncryptedValue structure.
 */
extern SECItem *
CRMF_EncryptedValueGetEncSymmKey(CRMFEncryptedValue *inEncValue);

/*
 * FUNCTION: CRMF_PKIArchiveOptionsGetKeyGenParameters
 * INPUTS:
 *    inOptions
 *        The PKiArchiveOptions to operate on.
 *
 * NOTES:
 * User must call SECITEM_FreeItem(retVal, PR_TRUE) after the return
 * value is no longer needed.
 *
 * RETURN:
 * Get the keyGenParameters field of the PKIArchiveOptions.
 * A NULL return value indicates that keyGenParameters was not
 * used as the choice for this PKIArchiveOptions.
 *
 * The SECItem returned is in BIT STRING format (ie, the len field indicates
 * number of valid bits as opposed to allocated number of bytes.)
 */
extern SECItem *
CRMF_PKIArchiveOptionsGetKeyGenParameters(CRMFPKIArchiveOptions *inOptions);

/*
 * FUNCTION: CRMF_PKIArchiveOptionsGetArchiveRemGenPrivKey
 * INPUTS:
 *    inOpt
 *        The PKIArchiveOptions to operate on.
 *    destVal
 *        A pointer to where the library can place the value for
 *        arciveRemGenPrivKey
 * RETURN:
 * If the PKIArchiveOptions used the archiveRemGenPrivKey field, the
 * function returns SECSuccess and fills the value at *destValue with either
 * PR_TRUE or PR_FALSE, depending on what the PKIArchiveOptions has as a
 * value.
 *
 * If the PKIArchiveOptions does not use the archiveRemGenPrivKey field, the
 * function returns SECFailure and the value at *destValue is unchanged.
 */
extern SECStatus
CRMF_PKIArchiveOptionsGetArchiveRemGenPrivKey(CRMFPKIArchiveOptions *inOpt,
                                              PRBool *destVal);

/* Helper functions that can be used by other libraries. */
/*
 * A quick helper function to get the best wrap mechanism.
 */
extern CK_MECHANISM_TYPE CRMF_GetBestWrapPadMechanism(PK11SlotInfo *slot);

/*
 * A helper function to get a randomly generated IV from a mechanism
 * type.
 */
extern SECItem *CRMF_GetIVFromMechanism(CK_MECHANISM_TYPE mechType);

SEC_END_PROTOS
#endif /*_CRMF_H_*/