nssckmdt.h

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

/* 
 * 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 NSSCKMDT_H
#define NSSCKMDT_H

#ifdef DEBUG
static const char NSSCKMDT_CVS_ID[] = "@(#) $RCSfile: nssckmdt.h,v $ $Revision: 1.1 $ $Date: 2000/03/31 19:43:30 $ $Name: NSS_3_1_1_RTM $";
#endif /* DEBUG */

/*
 * nssckmdt.h
 *
 * This file specifies the basic types that must be implemented by
 * any Module using the NSS Cryptoki Framework.
 */

#ifndef NSSBASET_H
#include "nssbaset.h"
#endif /* NSSBASET_H */

#ifndef NSSCKT_H
#include "nssckt.h"
#endif /* NSSCKT_H */

#ifndef NSSCKFWT_H
#include "nssckfwt.h"
#endif /* NSSCKFWT_H */

typedef struct NSSCKMDInstanceStr NSSCKMDInstance;
typedef struct NSSCKMDSlotStr NSSCKMDSlot;
typedef struct NSSCKMDTokenStr NSSCKMDToken;
typedef struct NSSCKMDSessionStr NSSCKMDSession;
typedef struct NSSCKMDFindObjectsStr NSSCKMDFindObjects;
typedef struct NSSCKMDMechanismStr NSSCKMDMechanism;
typedef struct NSSCKMDObjectStr NSSCKMDObject;

/*
 * NSSCKMDInstance
 *
 * This is the basic handle for an instance of a PKCS#11 Module.
 * It is returned by the Module's CreateInstance routine, and
 * may be obtained from the corresponding NSSCKFWInstance object.
 * It contains a pointer for use by the Module, to store any
 * instance-related data, and it contains the EPV for a set of
 * routines which the Module may implement for use by the Framework.
 * Some of these routines are optional; others are mandatory.
 */

struct NSSCKMDInstanceStr {
  /*
   * The Module may use this pointer for its own purposes.
   */
  void *etc;

  /*
   * This routine is called by the Framework to initialize
   * the Module.  This routine is optional; if unimplemented,
   * it won't be called.  If this routine returns an error,
   * then the initialization will fail.
   */
  CK_RV (PR_CALLBACK *Initialize)(
    NSSCKMDInstance *mdInstance,                                    
    NSSCKFWInstance *fwInstance,
    NSSUTF8 *configurationData
  );

  /*
   * This routine is called when the Framework is finalizing
   * the PKCS#11 Module.  It is the last thing called before
   * the NSSCKFWInstance's NSSArena is destroyed.  This routine
   * is optional; if unimplemented, it merely won't be called.
   */
  void (PR_CALLBACK *Finalize)(
    NSSCKMDInstance *mdInstance,                                    
    NSSCKFWInstance *fwInstance
  );

  /*
   * This routine gets the number of slots.  This value must
   * never change, once the instance is initialized.  This 
   * routine must be implemented.  It may return zero on error.
   */
  CK_ULONG (PR_CALLBACK *GetNSlots)(
    NSSCKMDInstance *mdInstance,                                    
    NSSCKFWInstance *fwInstance,
    CK_RV *pError
  );

  /*
   * This routine returns the version of the Cryptoki standard
   * to which this Module conforms.  This routine is optional;
   * if unimplemented, the Framework uses the version to which
   * ~it~ was implemented.
   */
  CK_VERSION (PR_CALLBACK *GetCryptokiVersion)(
    NSSCKMDInstance *mdInstance,                                    
    NSSCKFWInstance *fwInstance
  );

  /*
   * This routine returns a pointer to a UTF8-encoded string
   * containing the manufacturer ID for this Module.  Only
   * the characters completely encoded in the first thirty-
   * two bytes are significant.  This routine is optional.
   * The string returned is never freed; if dynamically generated,
   * the space for it should be allocated from the NSSArena
   * that may be obtained from the NSSCKFWInstance.  This
   * routine may return NULL upon error; however if *pError
   * is CKR_OK, the NULL will be considered the valid response.
   */
  NSSUTF8 *(PR_CALLBACK *GetManufacturerID)(
    NSSCKMDInstance *mdInstance,                                    
    NSSCKFWInstance *fwInstance,
    CK_RV *pError
  );

  /*
   * This routine returns a pointer to a UTF8-encoded string
   * containing a description of this Module library.  Only
   * the characters completely encoded in the first thirty-
   * two bytes are significant.  This routine is optional.
   * The string returned is never freed; if dynamically generated,
   * the space for it should be allocated from the NSSArena
   * that may be obtained from the NSSCKFWInstance.  This
   * routine may return NULL upon error; however if *pError
   * is CKR_OK, the NULL will be considered the valid response.
   */
  NSSUTF8 *(PR_CALLBACK *GetLibraryDescription)(
    NSSCKMDInstance *mdInstance,                                    
    NSSCKFWInstance *fwInstance,
    CK_RV *pError
  );

  /*
   * This routine returns the version of this Module library.
   * This routine is optional; if unimplemented, the Framework
   * will assume a Module library version of 0.1.
   */
  CK_VERSION (PR_CALLBACK *GetLibraryVersion)(
    NSSCKMDInstance *mdInstance,                                    
    NSSCKFWInstance *fwInstance
  );

  /*
   * This routine returns CK_TRUE if the Module wishes to
   * handle session objects.  This routine is optional.
   * If this routine is NULL, or if it exists but returns
   * CK_FALSE, the Framework will assume responsibility
   * for managing session objects.
   */
  CK_BBOOL (PR_CALLBACK *ModuleHandlesSessionObjects)(
    NSSCKMDInstance *mdInstance,                                    
    NSSCKFWInstance *fwInstance
  );

  /*
   * This routine stuffs pointers to NSSCKMDSlot objects into
   * the specified array; one for each slot supported by this
   * instance.  The Framework will determine the size needed
   * for the array by calling GetNSlots.  This routine is
   * required.
   */
  CK_RV (PR_CALLBACK *GetSlots)(
    NSSCKMDInstance *mdInstance,                                    
    NSSCKFWInstance *fwInstance,
    NSSCKMDSlot *slots[]
  );

  /*
   * This call returns a pointer to the slot in which an event
   * has occurred.  If the block argument is CK_TRUE, the call 
   * should block until a slot event occurs; if CK_FALSE, it 
   * should check to see if an event has occurred, occurred, 
   * but return NULL (and set *pError to CK_NO_EVENT) if one 
   * hasn't.  This routine is optional; if unimplemented, the
   * Framework will assume that no event has happened.  This
   * routine may return NULL upon error.
   */
  NSSCKMDSlot *(PR_CALLBACK *WaitForSlotEvent)(
    NSSCKMDInstance *mdInstance,                                    
    NSSCKFWInstance *fwInstance,
    CK_BBOOL block,
    CK_RV *pError
  );

  /*
   * This object may be extended in future versions of the
   * NSS Cryptoki Framework.  To allow for some flexibility
   * in the area of binary compatibility, this field should
   * be NULL.
   */
  void *null;
};


/*
 * NSSCKMDSlot
 *
 * This is the basic handle for a PKCS#11 Module Slot.  It is
 * created by the NSSCKMDInstance->GetSlots call, and may be
 * obtained from the Framework's corresponding NSSCKFWSlot
 * object.  It contains a pointer for use by the Module, to
 * store any slot-related data, and it contains the EPV for
 * a set of routines which the Module may implement for use
 * by the Framework.  Some of these routines are optional.
 */

struct NSSCKMDSlotStr {
  /*
   * The Module may use this pointer for its own purposes.
   */
  void *etc;

  /*
   * This routine is called during the Framework initialization
   * step, after the Framework Instance has obtained the list
   * of slots (by calling NSSCKMDInstance->GetSlots).  Any slot-
   * specific initialization can be done here.  This routine is
   * optional; if unimplemented, it won't be called.  Note that
   * if this routine returns an error, the entire Framework
   * initialization for this Module will fail.
   */
  CK_RV (PR_CALLBACK *Initialize)(
    NSSCKMDSlot *mdSlot,
    NSSCKFWSlot *fwSlot,
    NSSCKMDInstance *mdInstance,                                    
    NSSCKFWInstance *fwInstance
  );

  /*
   * This routine is called when the Framework is finalizing
   * the PKCS#11 Module.  This call (for each of the slots)
   * is the last thing called before NSSCKMDInstance->Finalize.
   * This routine is optional; if unimplemented, it merely 
   * won't be called.  Note: In the rare circumstance that
   * the Framework initialization cannot complete (due to,
   * for example, memory limitations), this can be called with
   * a NULL value for fwSlot.
   */
  void (PR_CALLBACK *Destroy)(
    NSSCKMDSlot *mdSlot,
    NSSCKFWSlot *fwSlot,
    NSSCKMDInstance *mdInstance,                                    
    NSSCKFWInstance *fwInstance
  );

  /*
   * This routine returns a pointer to a UTF8-encoded string
   * containing a description of this slot.  Only the characters
   * completely encoded in the first sixty-four bytes are
   * significant.  This routine is optional.  The string 
   * returned is never freed; if dynamically generated,
   * the space for it should be allocated from the NSSArena
   * that may be obtained from the NSSCKFWInstance.  This
   * routine may return NULL upon error; however if *pError
   * is CKR_OK, the NULL will be considered the valid response.
   */
  NSSUTF8 *(PR_CALLBACK *GetSlotDescription)(
    NSSCKMDSlot *mdSlot,
    NSSCKFWSlot *fwSlot,
    NSSCKMDInstance *mdInstance,                                    
    NSSCKFWInstance *fwInstance,
    CK_RV *pError
  );

  /*
   * This routine returns a pointer to a UTF8-encoded string
   * containing a description of the manufacturer of this slot.
   * Only the characters completely encoded in the first thirty-
   * two bytes are significant.  This routine is optional.  
   * The string  returned is never freed; if dynamically generated,
   * the space for it should be allocated from the NSSArena
   * that may be obtained from the NSSCKFWInstance.  This
   * routine may return NULL upon error; however if *pError
   * is CKR_OK, the NULL will be considered the valid response.
   */
  NSSUTF8 *(PR_CALLBACK *GetManufacturerID)(
    NSSCKMDSlot *mdSlot,
    NSSCKFWSlot *fwSlot,
    NSSCKMDInstance *mdInstance,                                    
    NSSCKFWInstance *fwInstance,
    CK_RV *pError
  );

  /*
   * This routine returns CK_TRUE if a token is present in this
   * slot.  This routine is optional; if unimplemented, CK_TRUE
   * is assumed.
   */
  CK_BBOOL (PR_CALLBACK *GetTokenPresent)(
    NSSCKMDSlot *mdSlot,
    NSSCKFWSlot *fwSlot,
    NSSCKMDInstance *mdInstance,                                    
    NSSCKFWInstance *fwInstance
  );

  /*
   * This routine returns CK_TRUE if the slot supports removable
   * tokens.  This routine is optional; if unimplemented, CK_FALSE
   * is assumed.
   */
  CK_BBOOL (PR_CALLBACK *GetRemovableDevice)(
    NSSCKMDSlot *mdSlot,
    NSSCKFWSlot *fwSlot,
    NSSCKMDInstance *mdInstance,                                    
    NSSCKFWInstance *fwInstance
  );

  /*
   * This routine returns CK_TRUE if this slot is a hardware
   * device, or CK_FALSE if this slot is a software device.  This
   * routine is optional; if unimplemented, CK_FALSE is assumed.
   */
  CK_BBOOL (PR_CALLBACK *GetHardwareSlot)(
    NSSCKMDSlot *mdSlot,
    NSSCKFWSlot *fwSlot,
    NSSCKMDInstance *mdInstance,                                    
    NSSCKFWInstance *fwInstance
  );

  /*
   * This routine returns the version of this slot's hardware.
   * This routine is optional; if unimplemented, the Framework
   * will assume a hardware version of 0.1.
   */
  CK_VERSION (PR_CALLBACK *GetHardwareVersion)(
    NSSCKMDSlot *mdSlot,
    NSSCKFWSlot *fwSlot,
    NSSCKMDInstance *mdInstance,                                    
    NSSCKFWInstance *fwInstance
  );

  /*
   * This routine returns the version of this slot's firmware.
   * This routine is optional; if unimplemented, the Framework
   * will assume a hardware version of 0.1.
   */
  CK_VERSION (PR_CALLBACK *GetFirmwareVersion)(
    NSSCKMDSlot *mdSlot,
    NSSCKFWSlot *fwSlot,
    NSSCKMDInstance *mdInstance,                                    
    NSSCKFWInstance *fwInstance
  );

  /*
   * This routine should return a pointer to an NSSCKMDToken
   * object corresponding to the token in the specified slot.
   * The NSSCKFWToken object passed in has an NSSArena
   * available which is dedicated for this token.  This routine
   * must be implemented.  This routine may return NULL upon
   * error.
   */
  NSSCKMDToken *(PR_CALLBACK *GetToken)(
    NSSCKMDSlot *mdSlot,
    NSSCKFWSlot *fwSlot,
    NSSCKMDInstance *mdInstance,                                    
    NSSCKFWInstance *fwInstance,
    CK_RV *pError
  );

  /*
   * This object may be extended in future versions of the
   * NSS Cryptoki Framework.  To allow for some flexibility
   * in the area of binary compatibility, this field should
   * be NULL.
   */
  void *null;
};

/*
 * NSSCKMDToken
 *