CA认证

开发平台：
WINDOWS

crmfres.h：源码内容
							/* -*- Mode: C; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/*
 * 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 _CRMFRES_H_
#define _CRMFRES_H_
#include "cmmf.h"
#include "keyres.h"
#include "ssmdefs.h"
#include "ctrlconn.h"
/*
 * FILE: crmfres.h
 * ---------------
 * This file defines the public interface for the class SSMCRMFRequest
 * which is to be used in Cartman to implement all necessary CRMF 
 * functionality.
 */
/*
 * STRUCTURE: SSMCRMFRequest
 * -------------------------
 * This is the structure used to implement the SSMCRMFRequest
 * class.  This class will be used to create CRMF Requests within
 * Cartman.  SSMCRMFRequest sub-classess off of SSMResource so it 
 * must always follow any guidelines for naming and defining presented
 * by the SSMResource class.
 *
 * The fields:
 *
 * super           The mandatory first member for any class sub-classing
 *                 from SSMResource.
 *
 * m_KeyGenType     An enumerated type indicating what type of key pair 
 *                  we are creating a request for.  This value is used 
 *                  to set the appropriate keyUsage extensions and also 
 *                  determining the proper method to set for 
 *                  Proof-Of-Possession.  Look at the file
 *                  ns/security/ssm/lib/protocol/ssmders.h for valid values.
 *                  This value is set by the client.
 *
 * m_KeyPair        A pointer to a key pair associated with the instantiation
 *                  of the CRMF request.  The members mPrivKey and mPubKey
 *                  must be non-NULL values when a new request is created.
 *
 * m_CRMFRequest    This is the member that holds all of the state information
 *                  about the CRMF request.
 *
 * m_Connection     This is the control connection associated with the 
 *                  request.
 */
typedef struct SSMCRMFRequest {
  SSMResource super; /* This must always be the first member of the
                      * structure.  Don't even think of adding another
                      * field before it or removing it.
                      */
  SSMKeyGenType         m_KeyGenType;
  SSMKeyPair           *m_KeyPair;
  CRMFCertRequest      *m_CRMFRequest;
  SSMControlConnection *m_Connection;
} SSMCRMFRequest;
/*
 * STRUCTURE: SSMCRMFRequestArg
 * ----------------------------
 * This structure will be used to pass the initialization information
 * to the SSMCRMFRequest_Init function.
 *
 * keyPair          The key pair that will be associated with the 
 *                  new CRMF request.
 *
 * connection       The control connection to be associated with the
 *                  new CRMF request.  The SSMCRMFRequest object will
 *                  use to get to the certificate and key databases.
 */
typedef struct SSMCRMFRequestArgStr {
  SSMKeyPair           *keyPair;
  SSMControlConnection *connection;
} SSMCRMFRequestArg;
/*
 * FUNCTION:SSM_CreateNewCRMFRequest
 * ---------------------------------
 * INPUTS:
 *    msg
 *        The message from the client requesting a new CRMF request.
 *    connection
 *        The control connection to be associated with the new request.
 *    destID
 *        Pointer to a pre-allocated chunk of memory where the function
 *        will place the ID of the newly created SSMCRMFRequest Object.
 *
 * NOTES:
 * This function takes the message received by the client, interprets
 * the message, creates a new SSMCRMFObject, adds it to the Global Resource
 * table, and places the resource id of the new object at *destID.  To free
 * the returned object, call SSM_FreeResource and pass in the object object 
 * ID placed at *destID by this function.
 *
 * RETURN:
 * The function returns PR_SUCCESS when successful.  Any other return value
 * should be interpreted as an error.
 */
SSMStatus SSM_CreateNewCRMFRequest(SECItem *msg, 
                                  SSMControlConnection *connection,
                                  SSMResourceID *destID);
/*
 * FUNCTION: SSMCRMFRequest_Create
 * -------------------------------
 * INPUTS:
 *    arg
 *        The creation argument for the SSMCRMFRequest class.  This should
 *        be a pointer to SSMKeyPair resource.
 *    res
 *        Pointer to a pre-allocated chunk of memory where the function can
 *        place the value of the pointer to the newly created SSMCRMFRequest
 *        object
 *
 * NOTES:
 * This function serves as the constructor for the SSMCRMFRequest class.  This 
 * function over-rides the function SSMResource_Create which is the super
 * class for SSMCRMFRequest.
 *
 * RETURN:
 * Returns PR_SUCCESS upon successful creation.  Any other error indicates an
 * error.
 */
SSMStatus SSMCRMFRequest_Create(void *arg, SSMControlConnection * conn, 
                               SSMResource **res);
/*
 * FUNCTION: SSMCRMFRequest_Init
 * -----------------------------
 * INPUTS:
 *    inCRMFReq
 *        A pointer to a newly allocated SSMCRMFRequest which needs to be
 *        initialized.  
 *    type
 *        The type for the class that is being initialized.  This value should
 *        always be SSM_RESTYPE_CRMFREQ.  (Unless one day someone decides to
 *        sub-class off of SSMCRMFRequest.)
 *    inKeyPair
 *        The Key Pair to associate with the CRMF request being initialized.
 *    inConnection
 *        The control connection to be associated with the request being 
 *        initialized.
 *
 * NOTES:
 * This function intializes a new SSMCRMFRequest object.  This function will
 * initialize its super-class member and make sure the passed in key pair has
 * non-NULL values for mPrivKey and mPubKey before getting a reference to the
 * passed in key pair.  Finally, the function creates a
 * new NSS based CRMF request and sets the following fields in the request:
 *  1) version is set v3 Cert
 *  2) The Public Key value in the request
 *
 * RETURN:
 * The function returns PR_SUCCESS upon successful initialization.  Any other
 * return value should be interpreted as an error.
 */
SSMStatus SSMCRMFRequest_Init(SSMCRMFRequest       *inCRMFReq, 
			     SSMControlConnection * conn,
                             SSMResourceType       type,
                             SSMKeyPair           *inKeyPair,
                             SSMControlConnection *inConnection);
/*
 * FUNCTION: SSMCRMFRequest_Destroy
 * --------------------------------
 * INPUTS:
 *    inRequest
 *        A pointer to a SSMResource of type SSM_RESTYPE_CRMFREQ to be
 *        destroyed.
 *    doFree
 *        Until the day when someone creates a sub-class of SSMCRMFRequest,
 *        this value should always be PR_TRUE.
 * 
 * NOTES:
 * This function takes of freeing up all memory associated with the
 * SSMCRMFRequest.  First the funciton will release the reference obtained
 * for the member mKeyPair in the function SSMCRMFRequest_Init.  The function
 * then calls CRMF_DestroyCertRequest to free the memory used by mCRMFRequest.
 * Finally, the function calls SSMResource_Destroy to free up the SSMResource
 * member before calling free on the pointer passed in.
 *
 * RETURN:
 * Function returns PR_SUCCESS upon successful destruction of the object. Any
 * other return value should be interpreted as an error.
 */
SSMStatus SSMCRMFRequest_Destroy(SSMResource *inRequest, PRBool doFree);
/*
 * FUNCTION: SSMCRMFRequest_SetAttr
 * --------------------------------
 * INPUTS:
 *    res
 *        A pointer to a SSMResource of type SSM_RESTYPE_CRMFREQ
 *    attrID
 *        The attribute to set in the request.
 *    value
 *        The data to use when setting the desired attribute.
 *
 * NOTES:
 * This function over-rides SSMResource_SetAttr which all classes inherit
 * from the SSMResource class.  This function will set the following 
 * attributes (these attributes are defined in 
 * ns/security/ssm/lib/protocol/rsrcids.h):
 *
 *    SSMAttributeID                SSMResourceAttrType     Value(s)
 *    --------------                -------------------     --------
 *    SSM_FID_CRMFREQ_KEY_TYPE      SSM_NUMERIC_ATTRIBUTE   A pointer to any
 *                                                          enumerated value 
 *                                                          with type of
 *                                                          SSMKeyGenType.
 *
 *    SSM_FID_CRMFREQ_DN            SSM_STRING_ATTRIBUTE    An RFC1485 
 *                                                          formatted DN.
 *    
 *    SSM_FID_REGTOKEN              SSM_STRING_ATTRIBUTE    A string to place
 *                                                          as the Registration
 *                                                          token for the 
 *                                                          request.
 *
 *    SSM_FID_AUTHENTICATOR         SSM_STRING_ATTRIBUTE    A string to place
 *                                                          as the 
 *                                                          Authenticator token
 *                                                          in the request.
 *
 *    SSM_FID_CRMFREQ_ESCROW_AUTHORITY SSM_STRING_ATTRIBUTE A base64 encoded 
 *                                                          DER cert to use for
 *                                                          creating the 
 *                                                          PKIArchiveOptions
 *                                                          control.
 *
 * NOTES:
 * The function return PR_SUCCESS if setting the field with the given data
 * was successful.  Any other return value should be considered an error.
 *    
 */
SSMStatus SSMCRMFRequest_SetAttr(SSMResource         *res,
                                SSMAttributeID      attrID,
                                SSMAttributeValue   *value);
/*
 * FUNCTION: SSMCRMFRequest_SetEscrowAuthority
 * -------------------------------------------
 * INPUTS:
 *    crmfReq
 *        The CRMFRequest resource to add the escrow authority to.
 *    eaCert
 *        The Certificate that belongs to the CA that wants to 
 *        escrow the private key associated with the request.
 * NOTES:
 * This function will wrap the private key in an EncryptedKey type
 * defined by CRMF and include in the CRMF request that is generated.
 *
 * RETURN:
 * PR_SUCCESS indicates the private key associated with the requested
 * was successfully wrapped and made a part of the CRMF request.  Any
 * other return value indicates an error in trying to wrap the private
 * and include it in the CRMF request.
 */
SSMStatus SSMCRMFRequest_SetEscrowAuthority(SSMCRMFRequest  *crmfReq,
                                           CERTCertificate *eaCert);
/*
 * FUNCTION: SSM_EncodeCRMFRequests
 * --------------------------------
 * INPUTS:
 *    msg
 *        The message received from the client requesting CRMF messages to 
 *        be encoded.
 *    destDER
 *        Pointer to a pre-allocated chunk of memory where the function can 
 *        place a pointer to the base64 encoded CRMF CertReqMessages
 *    destLen
 *        Pointer to a pre-allocated piece of memory where the function can
 *        place the length of the string returned in *destDER.
 *
 * NOTES:
 * This function takes a message request from the client to encode CRMF 
 * requests.  The output will be base64 DER-formatted bytes of the type
 * CertReqMessages as defined by the CRMF Internet Draft.  The function 
 * will allocate a buffer in memory to store the DER using PORT_Alloc and
 * place a pointer to the buffer at *destDER.
 *
 * RETURN:
 * The function will return PR_SUCCESS if encoding the requests was successful.
 * Any other return value should be treated as an error and the values at 
 * *destDER and *destLen should be ignored.
 */
SSMStatus SSM_EncodeCRMFRequests(SSMControlConnection * ctrl, SECItem *msg, 
                                char **destDER, SSMPRUint32 *destLen);
/*
 * FUNCTION: SSM_ProcessCMMFCertResponse
 * -------------------------------------
 * INPUTS:
 *    msg
 *        The message received from the client requesting Cartman to 
 *        process a CMMF response.
 *    connection
 *        The control connection associated with the CMMF response.
 *        The connection is necessary so that the function can find
 *        the appropriate cetificate database for placing the decoded
 *        certificates.
 *
 * NOTES:
 * This function serves as the back-end for the JavaScript method
 * crypto.importUserCertificates.  It will decode the base64 DER blob passed
 * in and process it.  Eventually this function will also start the process
 * of backing up the certificate when Cartman supports that feature.  
 * View the document at http://warp/hardcore/library/arch/cert-issue.html
 * to see a detailed explanation for what this function doess.
 * 
 */
SSMStatus SSM_ProcessCMMFCertResponse(SECItem              *msg, 
                                     SSMControlConnection *connection);
/*
 * FUNCTION: SSM_RespondToPOPChallenge
 * -----------------------------------
 * INPUTS:
 *    msg
 *        The message received from the client requesting that Cartman
 *        respond to a challenge.
 *    ctrl
 *        The Control Connection associated with the message to process.
 *    challengeResponse
 *        A pointer to a pre-allocated pointer where the function can place
 *        a copy of the base64 encoded response to the challenge.  The 
 *        response will be a POPODecKeyRespContent defined in the CMMF 
 *        internet draft.
 *    responseLen
 *        A pointer to a pre-allocated PRUint32 where the function can place
 *        the length of the response returned via the challengeResponse input
 *        parameter.
 *
 * NOTES:
 * This function servers as the back-end for the JavaScript method
 * crypto.popChallengeRespone.  The function will decode the base64 DER blob
 * passed in and process it.  The function 
 */
SSMStatus SSM_RespondToPOPChallenge(SECItem                *msg, 
                                   SSMControlConnection   *ctrl,
                                   char                  **challengeResponse, 
                                   PRUint32               *responseLen);
typedef struct SSMCRMFThreadArgStr {
    SSMControlConnection *ctrl;
    SECItem              *msg;
} SSMCRMFThreadArg;
/*
 * FUNCTION: SSM_CRMFEncodeThread
 * ------------------------------
 * INPUTS:
 *    arg
 *        A pointer to a structure of type SSMCRMFThreadArg which the function
 *        will use to encode a CRMF request.
 * NOTES:
 * This function is intended to encode a CRMF request taking a message from
 * the client as its argument along with the associated control thread.  This
 * function will send the reply back to the client in case of success or 
 * failure so the client may proceed with its operations.
 * RETURN:
 * No return value.
 */
void SSM_CRMFEncodeThread(void *arg);
#endif /* _CRMFRES_H_ */

						