cmmf.h

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

/* -*- Mode: C; tab-width: 8 -*-*/
/*
 * The contents of this file are subject to the Mozilla Public
 * License Version 1.1 (the "License"); you may not use this file
 * except in compliance with the License. You may obtain a copy of
 * the License at http://www.mozilla.org/MPL/
 * 
 * Software distributed under the License is distributed on an "AS
 * IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
 * implied. See the License for the specific language governing
 * rights and limitations under the License.
 * 
 * The Original Code is the Netscape security libraries.
 * 
 * The Initial Developer of the Original Code is Netscape
 * Communications Corporation.  Portions created by Netscape are 
 * Copyright (C) 1994-2000 Netscape Communications Corporation.  All
 * Rights Reserved.
 * 
 * Contributor(s):
 * 
 * Alternatively, the contents of this file may be used under the
 * terms of the GNU General Public License Version 2 or later (the
 * "GPL"), in which case the provisions of the GPL are applicable 
 * instead of those above.  If you wish to allow use of your 
 * version of this file only under the terms of the GPL and not to
 * allow others to use your version of this file under the MPL,
 * indicate your decision by deleting the provisions above and
 * replace them with the notice and other provisions required by
 * the GPL.  If you do not delete the provisions above, a recipient
 * may use your version of this file under either the MPL or the
 * GPL.
 */

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

SEC_BEGIN_PROTOS

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

/*
 * FUNCTION: CMMF_KeyRecRepContentSetCACerts
 * INPUTS:
 *    inKeyRecRep
 *        The CMMFKeyRecRepContent to operate on.
 *    inCACerts
 *        The list of CA certificates required to construct a valid 
 *        certificate chain with the certificates that will be returned
 *        to the end user via this KeyRecRepContent.
 * NOTES:
 *    This function sets the caCerts that are required to form a chain with the
 *    end entity certificates that are being re-issued in this 
 *    CMMFKeyRecRepContent structure.
 *
 * RETURN: