crmf.h

来自「支持SSL v2/v3, TLS, PKCS #5, PKCS #7, PKCS」· C头文件 代码 · 共 1,780 行 · 第 1/5 页

 *        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 funciton 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 funciton looks at the the inKeyChoice parameter and interprets it in
 * in the following manner.
 *
 * If a parameter is not mentioned under interpretation, the funciton 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 funciton looks at the the inKeyChoice parameter and interprets it in
 * in the following manner.
 *
 * If a parameter is not mentioned under interpretation, the funciton will not