The Tor Browser: security/nss/lib/crmf/crmf.h@6474c204b198 (annotated)

security/nss/lib/crmf/crmf.h@6474c204b198 (annotated)

security/nss/lib/crmf/crmf.h

Wed, 31 Dec 2014 06:09:35 +0100

author: Michael Schloh von Bennewitz <michael@schloh.com>
date: Wed, 31 Dec 2014 06:09:35 +0100
changeset 0: 6474c204b198
permissions: -rw-r--r--

Cloned upstream origin tor-browser at tor-browser-31.3.0esr-4.5-1-build1
revision ID fc1c9ff7c1b2defdbc039f12214767608f46423f for hacking purpose.

 /* -*- 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_*/

The Tor Browser / annotate

security/nss/lib/crmf/crmf.h@6474c204b198 (annotated)

security/nss/lib/crmf/crmf.h