cmtjs.h

安全开发库。含客户端建立ssl连接、签名、证书验证、证书发布和撤销等。编译用到nss

/* 
 * 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 _CMTJS_H_
#define _CMTJS_H_
#include "cmtcmn.h"
#include "ssmdefs.h"
#include "rsrcids.h"
/*
 * Define some constants.
 */

/*
 * These defines are used in conjuction with the function
 * CMT_AddNewModule.
 */
#define PUBLIC_MECH_RSA_FLAG         0x00000001ul
#define PUBLIC_MECH_DSA_FLAG         0x00000002ul
#define PUBLIC_MECH_RC2_FLAG         0x00000004ul
#define PUBLIC_MECH_RC4_FLAG         0x00000008ul
#define PUBLIC_MECH_DES_FLAG         0x00000010ul
#define PUBLIC_MECH_DH_FLAG          0x00000020ul
#define PUBLIC_MECH_FORTEZZA_FLAG    0x00000040ul
#define PUBLIC_MECH_RC5_FLAG         0x00000080ul
#define PUBLIC_MECH_SHA1_FLAG        0x00000100ul
#define PUBLIC_MECH_MD5_FLAG         0x00000200ul
#define PUBLIC_MECH_MD2_FLAG         0x00000400ul
 
#define PUBLIC_MECH_RANDOM_FLAG      0x08000000ul
#define PUBLIC_MECH_FRIENDLY_FLAG    0x10000000ul
#define PUBLIC_OWN_PW_DEFAULTS       0X20000000ul
#define PUBLIC_DISABLE_FLAG          0x40000000ul


/*
 * This is the lone supported constant for the Cipher flag
 * for CMT_AddNewModule
 */
#define PUBLIC_CIPHER_FORTEZZA_FLAG  0x00000001ul

CMT_BEGIN_EXTERN_C

/*
 * FUNCTION: CMT_GenerateKeyPair
 * -----------------------------
 * INPUTS:
 *    control
 *        The Control Connection that has already established a connection
 *        with the psm server.
 *    keyGenContext
 *        The Resource ID of a key gen context to use for creating the
 *        key pair.
 *    mechType
 *        A PKCS11 mechanism used to generate the key pair. Valid values are:
 *          CKM_RSA_PKCS_KEY_PAIR_GEN    0x00000000
 *          CKM_DSA_KEY_PAIR_GEN         0x00000010
 *        The definition of these values can be found at 
 *        http://www.rsa.com/rsalabs/pubs/pkcs11.html
 *        The psm module currently supports v2.01 of PKCS11
 *    params
 *        This parameter will be used to pass parameters to the Key Pair
 *        generation process.  Currently this feature is not supported, so 
 *        pass in NULL for this parameter.
 *    keySize
 *        The size (in bits) of the key to generate.
 *    keyPairId
 *        A pointer to pre-allocated memory where the function can place
 *        the value of the resource ID of the key pair that gets created.
 *
 * NOTES:
 * This function will send a message to the psm server requesting that 
 * a public/private key pair be generated. The key gen context will queue
 * the request. You can send as many key gen requests as you want with a
 * given key gen context. After sending all the key gen requests, the user
 * must call CMT_FinishGeneratingKeys so that the key gen context actually
 * generates the keys.
 *
 * RETURN:
 * A return value of CMTSuccess indicates the request for key generation
 * was queued successfully and the corresponding resource ID can be found
 * at *keyPairId.  Any other return value indicates an error and the value
 * at *keyPairId should be ignored.
 */
CMTStatus
CMT_GenerateKeyPair(PCMT_CONTROL control, CMUint32 keyGenContext, 
		    CMUint32 mechType, CMTItem *params, CMUint32 keySize, 
		    CMUint32 *keyPairId);

/*
 * FUNCTION: CMT_FinishGeneratingKeys
 * ----------------------------------
 * INPUTS
 *    control
 *        The Control Connection that has already established a connection
 *        with the psm server.
 *    keyGenContext
 *        The resource ID of the key gen context which should finish 
 *        generating its key pairs.
 * NOTES
 * This function will send a message to the psm server notifying the key 
 * gen context with the resource ID of keyGenContext to finish generating
 * all of the key gen requests it has queued up. After each key gen has 
 * finished, the psm server will send a SSM_TASK_COMPLETED_EVENT. So in order
 * to detect when all of the key gens are done, the user should register 
 * an event handler.  See comments for CMT_RegisterEventHandler for information
 * on how to successfully register event handler callbacks. You must register
 * the event handler with keyGenContext as the target resource ID for this
 * to work correctly.
 *
 * RETURN:
 * A return value of CMTSuccess indicates the key gen context has started to
 * generate the key pairs in its queue. Any other return value indicates an
 * error and the key pairs will not be generated.
 */
CMTStatus
CMT_FinishGeneratingKeys(PCMT_CONTROL control, CMUint32 keyGenContext);

/*
 * FUNCTION: CMT_CreateNewCRMFRequest
 * ----------------------------------
 * INPUTS:
 *    control
 *        The Control Connection that has already established a connection
 *        with the psm server.
 *    keyPairID
 *        The resource ID of the key pair that should be associated with
 *        the CRMF request created. At the time this function is called,
 *        key pair should have already been created. 
 *    keyGenType
 *        An enumeration that explains how the key pair will be used.
 *        Look at the definition of SSMKeyGenType in ssmdefs.h for valid
 *        values and their affects on the request.
 *    reqID
 *        A pointer to a pre-allocatd chunk of memory where the library 
 *        can place the resource ID of the new CRMF request.
 * NOTES:
 * This function sends a message to the psm server requesting that a new 
 * CRMF resource object be created. Each CRMF request must be associated with 
 * a public/private key pair, that is why the keyPairID parameter exists.
 * The keyGenType parameter is used to initialize the request, eg set the
 * correct keyUsage extension.
 * 
 * Before encoding a CRMF request, the user will want to set the appropriate
 * attributes to build up the request. The supported attributes are:
 *
 * Attribute Enumeration          Attribute Type       What value means
 * ---------------------          --------------       ----------------
 * SSM_FID_CRMFREQ_REGTOKEN       String               The value to encode as 
 *                                                     the registration token
 *                                                     value for the request.
 *
 * SSM_FID_CRMFREQ_AUTHENTICATOR String                The value to encode as
 *                                                     authenticator control
 *                                                     in the request.
 * 
 * SSM_FID_DN                    String                The RFC1485 formatted
 *                                                     DN to include in the
 *                                                     CRMF request.
 *
 * For information on how to properly set the attribute of a resource, refer
 * to the comments for the functions CMT_SetNumericAttribute and 
 * CMT_SetStringAttribute.
 *
 * RETURN:
 * A return value of CMTSuccess indicates a new CRMF resource was created by
 * the psm server and has the resource ID placed at *reqID. Any other return
 * value indicates an error and the value at *reqID should be ignored.
 */
CMTStatus
CMT_CreateNewCRMFRequest(PCMT_CONTROL control, CMUint32 keyPairID, 
			 SSMKeyGenType keyGenType, CMUint32 *reqID);

/*
 * FUNCTION: CMT_EncodeCRMFRequest
 * ------------------------------
 * INPUTS:
 *    control
 *        The Control Connection that has already established a connection
 *        with the psm server.
 *    crmfReqID
 *        An array of resource ID's for CRMF objects to be encoded.
 *    numRequests
 *        The length of the array crmfReqID that is passed in.
 *    der
 *        A pointer to a pre-allocated pointer for a char* where the library
 *        can place the final DER-encoding of the requests.
 * NOTES
 * This function will send a message to the psm server requesting that 
 * a number of CRMF requests be encoded into their appropriate DER 
 * representation. The DER that is sent back will be of the type 
 * CertReqMessages as define in the internet draft for CRMF. To look at the
 * draft, visit the following URL: 
 * http://search.ietf.org/internet-drafts/internet-draft-ietf-pkix-crmf-01.txt
 *
 * RETURN:
 * A return value of CMTSuccess indicates psm successfully encoded the requests
 * and placed the base64 DER encoded request at *der. Any other return value
 * indicates an error and the value at *der should be ignored.
 */
CMTStatus
CMT_EncodeCRMFRequest(PCMT_CONTROL control, CMUint32 *crmfReqID, 
		      CMUint32 numRequests, char ** der);

/*
 * FUNCTION: CMT_ProcessCMMFResponse
 * ---------------------------------
 * INPUTS:
 *    control
 *        The Control Connection that has already established a connection
 *        with the psm server.
 *    nickname
 *        The nickname that should be associated with the certificate 
 *        contained in the CMMF Response.
 *    certRepString
 *        This is the base 64 encoded CertRepContent that issues a certificate.
 *        The psm server will decode the base 64 data and then parse the
 *        CertRepContent.
 *    doBackup
 *        A boolean value indicating whether or not psm should initiate the
 *        process of backing up the newly issued certificate into a PKCS-12
 *        file.
 *    clientContext
 *         Client supplied data pointer that is returned to the client during
 *         a UI event.
 * NOTES:
 * This function takes a CertRepContent as defined in the CMMF internet draft
 * (http://search.ietf.org/internet-drafts/draft-ietf-pkix-cmmf-02.txt) and
 * imports the certificate into the user's database. The certificate will have
 * the string value of nickanme as it's nickname when added to the database
 * unless another certificate with that same Distinguished Name (DN) already
 * exists in the database, in which case the nickname of the certificate that
 * already exists will be used. If the value passed in for doBackup is 
 * non-zero, then the psm server will initiate the process of backing up the
 * certificate(s) that were just imported.
 *
 * RETURN:
 * A return value of CMTSuccess indicates the certificate(s) were successfully
 * added to the database. Any other return value means the certificate(s) could
 * not be successfully added to the database.
 */
CMTStatus
CMT_ProcessCMMFResponse(PCMT_CONTROL control, char *nickname, 
			char *certRepString, CMBool doBackup,
			void *clientContext);

/*
 * FUNCTION: CMT_CreateResource
 * ----------------------------
 * INPUTS: