crmf.h

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

 * 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 funciton 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