/* This Source Code Form is subject to the terms of the Mozilla Public

 * License, v. 2.0. If a copy of the MPL was not distributed with this

 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#ifndef NSSCKMDT_H

#define NSSCKMDT_H

/*

 * 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 NSSCKMDCryptoOperationStr NSSCKMDCryptoOperation;

typedef struct NSSCKMDFindObjectsStr NSSCKMDFindObjects;

typedef struct NSSCKMDMechanismStr NSSCKMDMechanism;

typedef struct NSSCKMDObjectStr NSSCKMDObject;

/*

 * NSSCKFWItem

 *

 * This is a structure used by modules to return object attributes.

 * The needsFreeing bit indicates whether the object needs to be freed.

 * If so, the framework will call the FreeAttribute function on the item

 * after it is done using it.

 *

 */

typedef struct {

  PRBool needsFreeing;

  NSSItem* item;

} NSSCKFWItem ;

/*

 * 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

 *

 * This is the basic handle for a PKCS#11 Token.  It is created by

 * the NSSCKMDSlot->GetToken call, and may be obtained from the

 * Framework's corresponding NSSCKFWToken object.  It contains a

 * pointer for use by the Module, to store any token-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 NSSCKMDTokenStr {

  /*

   * The Module may use this pointer for its own purposes.

   */

  void *etc;

  /*

   * This routine is used to prepare a Module token object for

   * use.  It is called after the NSSCKMDToken object is obtained

   * from NSSCKMDSlot->GetToken.  It is named "Setup" here because

   * Cryptoki already defines "InitToken" to do the process of

   * wiping out any existing state on a token and preparing it for

   * a new use.  This routine is optional; if unimplemented, it

   * merely won't be called.

   */

  CK_RV (PR_CALLBACK *Setup)(

    NSSCKMDToken *mdToken,

    NSSCKFWToken *fwToken,

    NSSCKMDInstance *mdInstance,

    NSSCKFWInstance *fwInstance

  );

  /*

   * This routine is called by the Framework whenever it notices

   * that the token object is invalid.  (Typically this is when a 

   * routine indicates an error such as CKR_DEVICE_REMOVED).  This

   * call is the last thing called before the NSSArena in the

   * corresponding NSSCKFWToken is destroyed.  This routine is

   * optional; if unimplemented, it merely won't be called.

   */

  void (PR_CALLBACK *Invalidate)(

    NSSCKMDToken *mdToken,

    NSSCKFWToken *fwToken,

    NSSCKMDInstance *mdInstance,

    NSSCKFWInstance *fwInstance

  );

  /*

   * This routine initialises the token in the specified slot.

   * This routine is optional; if unimplemented, the Framework

   * will fail this operation with an error of CKR_DEVICE_ERROR.

   */

  CK_RV (PR_CALLBACK *InitToken)(

    NSSCKMDToken *mdToken,

    NSSCKFWToken *fwToken,

    NSSCKMDInstance *mdInstance,

    NSSCKFWInstance *fwInstance,

    NSSItem *pin,

    NSSUTF8 *label

  );

  /*

   * This routine returns a pointer to a UTF8-encoded string

   * containing this token's label.  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 *GetLabel)(

    NSSCKMDToken *mdToken,

    NSSCKFWToken *fwToken,

    NSSCKMDInstance *mdInstance,

    NSSCKFWInstance *fwInstance,

    CK_RV *pError

  );

  /*

   * This routine returns a pointer to a UTF8-encoded string

   * containing this token's manufacturer ID.  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)(

    NSSCKMDToken *mdToken,

    NSSCKFWToken *fwToken,

    NSSCKMDInstance *mdInstance,

    NSSCKFWInstance *fwInstance,

    CK_RV *pError

  );

  /*

   * This routine returns a pointer to a UTF8-encoded string

   * containing this token's model name.  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 *GetModel)(

    NSSCKMDToken *mdToken,

    NSSCKFWToken *fwToken,

    NSSCKMDInstance *mdInstance,

    NSSCKFWInstance *fwInstance,

    CK_RV *pError

  );

  /*

   * This routine returns a pointer to a UTF8-encoded string

   * containing this token's serial number.  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 *GetSerialNumber)(

    NSSCKMDToken *mdToken,

    NSSCKFWToken *fwToken,

    NSSCKMDInstance *mdInstance,

    NSSCKFWInstance *fwInstance,

    CK_RV *pError

  );

  /*

   * This routine returns CK_TRUE if the token has its own

   * random number generator.  This routine is optional; if

   * unimplemented, CK_FALSE is assumed.

   */

  CK_BBOOL (PR_CALLBACK *GetHasRNG)(

    NSSCKMDToken *mdToken,

    NSSCKFWToken *fwToken,

    NSSCKMDInstance *mdInstance,

    NSSCKFWInstance *fwInstance

  );

  /*

   * This routine returns CK_TRUE if this token is write-protected.

   * This routine is optional; if unimplemented, CK_FALSE is

   * assumed.

   */

  CK_BBOOL (PR_CALLBACK *GetIsWriteProtected)(

    NSSCKMDToken *mdToken,

    NSSCKFWToken *fwToken,

    NSSCKMDInstance *mdInstance,

    NSSCKFWInstance *fwInstance

  );

  /*

   * This routine returns CK_TRUE if this token requires a login.

   * This routine is optional; if unimplemented, CK_FALSE is

   * assumed.

   */

  CK_BBOOL (PR_CALLBACK *GetLoginRequired)(

    NSSCKMDToken *mdToken,

    NSSCKFWToken *fwToken,

    NSSCKMDInstance *mdInstance,

    NSSCKFWInstance *fwInstance

  );

  /*

   * This routine returns CK_TRUE if the normal user's PIN on this

   * token has been initialised.  This routine is optional; if

   * unimplemented, CK_FALSE is assumed.

   */

  CK_BBOOL (PR_CALLBACK *GetUserPinInitialized)(

    NSSCKMDToken *mdToken,

    NSSCKFWToken *fwToken,

    NSSCKMDInstance *mdInstance,

    NSSCKFWInstance *fwInstance

  );

  /*

   * This routine returns CK_TRUE if a successful save of a

   * session's cryptographic operations state ~always~ contains

   * all keys needed to restore the state of the session.  This

   * routine is optional; if unimplemented, CK_FALSE is assumed.

   */

  CK_BBOOL (PR_CALLBACK *GetRestoreKeyNotNeeded)(

    NSSCKMDToken *mdToken,

    NSSCKFWToken *fwToken,

    NSSCKMDInstance *mdInstance,

    NSSCKFWInstance *fwInstance

  );

  /*

   * This routine returns CK_TRUE if the token has its own

   * hardware clock.  This routine is optional; if unimplemented,

   * CK_FALSE is assumed.

   */

  CK_BBOOL (PR_CALLBACK *GetHasClockOnToken)(

    NSSCKMDToken *mdToken,

    NSSCKFWToken *fwToken,

    NSSCKMDInstance *mdInstance,

    NSSCKFWInstance *fwInstance

  );

  /*

   * This routine returns CK_TRUE if the token has a protected

   * authentication path.  This routine is optional; if

   * unimplemented, CK_FALSE is assumed.

   */

  CK_BBOOL (PR_CALLBACK *GetHasProtectedAuthenticationPath)(

    NSSCKMDToken *mdToken,

    NSSCKFWToken *fwToken,

    NSSCKMDInstance *mdInstance,

    NSSCKFWInstance *fwInstance

  );

  /*

   * This routine returns CK_TRUE if the token supports dual

   * cryptographic operations within a single session.  This

   * routine is optional; if unimplemented, CK_FALSE is assumed.

   */

  CK_BBOOL (PR_CALLBACK *GetSupportsDualCryptoOperations)(

    NSSCKMDToken *mdToken,

    NSSCKFWToken *fwToken,

    NSSCKMDInstance *mdInstance,

    NSSCKFWInstance *fwInstance

  );

  /*

   * XXX fgmr-- should we have a call to return all the flags

   * at once, for folks who already know about Cryptoki?

   */

  /*

   * This routine returns the maximum number of sessions that

   * may be opened on this token.  This routine is optional;

   * if unimplemented, the special value CK_UNAVAILABLE_INFORMATION

   * is assumed.  XXX fgmr-- or CK_EFFECTIVELY_INFINITE?

   */

  CK_ULONG (PR_CALLBACK *GetMaxSessionCount)(

    NSSCKMDToken *mdToken,

    NSSCKFWToken *fwToken,

    NSSCKMDInstance *mdInstance,

    NSSCKFWInstance *fwInstance

  );

  /*

   * This routine returns the maximum number of read/write

   * sesisons that may be opened on this token.  This routine

   * is optional; if unimplemented, the special value

   * CK_UNAVAILABLE_INFORMATION is assumed.  XXX fgmr-- or 

   * CK_EFFECTIVELY_INFINITE?

   */

  CK_ULONG (PR_CALLBACK *GetMaxRwSessionCount)(

    NSSCKMDToken *mdToken,

    NSSCKFWToken *fwToken,

    NSSCKMDInstance *mdInstance,

    NSSCKFWInstance *fwInstance

  );

  /*

   * This routine returns the maximum PIN code length that is

   * supported on this token.  This routine is optional;

   * if unimplemented, the special value CK_UNAVAILABLE_INFORMATION

   * is assumed.

   */

  CK_ULONG (PR_CALLBACK *GetMaxPinLen)(

    NSSCKMDToken *mdToken,

    NSSCKFWToken *fwToken,

    NSSCKMDInstance *mdInstance,

    NSSCKFWInstance *fwInstance

  );

  /*

   * This routine returns the minimum PIN code length that is

   * supported on this token.  This routine is optional; if

   * unimplemented, the special value CK_UNAVAILABLE_INFORMATION

   *  is assumed.  XXX fgmr-- or 0?

   */

  CK_ULONG (PR_CALLBACK *GetMinPinLen)(

    NSSCKMDToken *mdToken,

    NSSCKFWToken *fwToken,

    NSSCKMDInstance *mdInstance,

    NSSCKFWInstance *fwInstance

  );

  /*

   * This routine returns the total amount of memory on the token

   * in which public objects may be stored.  This routine is

   * optional; if unimplemented, the special value

   * CK_UNAVAILABLE_INFORMATION is assumed.

   */

  CK_ULONG (PR_CALLBACK *GetTotalPublicMemory)(

    NSSCKMDToken *mdToken,

    NSSCKFWToken *fwToken,

    NSSCKMDInstance *mdInstance,

    NSSCKFWInstance *fwInstance

  );

  /*

   * This routine returns the amount of unused memory on the

   * token in which public objects may be stored.  This routine

   * is optional; if unimplemented, the special value

   * CK_UNAVAILABLE_INFORMATION is assumed.

   */

  CK_ULONG (PR_CALLBACK *GetFreePublicMemory)(

    NSSCKMDToken *mdToken,

    NSSCKFWToken *fwToken,

    NSSCKMDInstance *mdInstance,

    NSSCKFWInstance *fwInstance

  );

  /*

   * This routine returns the total amount of memory on the token

   * in which private objects may be stored.  This routine is

   * optional; if unimplemented, the special value

   * CK_UNAVAILABLE_INFORMATION is assumed.

   */

  CK_ULONG (PR_CALLBACK *GetTotalPrivateMemory)(

    NSSCKMDToken *mdToken,

    NSSCKFWToken *fwToken,

    NSSCKMDInstance *mdInstance,

    NSSCKFWInstance *fwInstance

  );

  /*

   * This routine returns the amount of unused memory on the

   * token in which private objects may be stored.  This routine

   * is optional; if unimplemented, the special value

   * CK_UNAVAILABLE_INFORMATION is assumed.

   */

  CK_ULONG (PR_CALLBACK *GetFreePrivateMemory)(

    NSSCKMDToken *mdToken,

    NSSCKFWToken *fwToken,

    NSSCKMDInstance *mdInstance,

    NSSCKFWInstance *fwInstance

  );

  /*

   * This routine returns the version number of this token's

   * hardware.  This routine is optional; if unimplemented,

   * the value 0.1 is assumed.

   */

  CK_VERSION (PR_CALLBACK *GetHardwareVersion)(

    NSSCKMDToken *mdToken,

    NSSCKFWToken *fwToken,

    NSSCKMDInstance *mdInstance,

    NSSCKFWInstance *fwInstance

  );

  /*

   * This routine returns the version number of this token's

   * firmware.  This routine is optional; if unimplemented,

   * the value 0.1 is assumed.

   */

  CK_VERSION (PR_CALLBACK *GetFirmwareVersion)(

    NSSCKMDToken *mdToken,

    NSSCKFWToken *fwToken,

    NSSCKMDInstance *mdInstance,

    NSSCKFWInstance *fwInstance

  );

  /*

   * This routine stuffs the current UTC time, as obtained from

   * the token, into the sixteen-byte buffer in the form

   * YYYYMMDDhhmmss00.  This routine need only be implemented

   * by token which indicate that they have a real-time clock.

   * XXX fgmr-- think about time formats.

   */

  CK_RV (PR_CALLBACK *GetUTCTime)(

    NSSCKMDToken *mdToken,

    NSSCKFWToken *fwToken,

    NSSCKMDInstance *mdInstance,

    NSSCKFWInstance *fwInstance,

    CK_CHAR utcTime[16]

  );

  /*

   * This routine creates a session on the token, and returns

   * the corresponding NSSCKMDSession object.  The value of

   * rw will be CK_TRUE if the session is to be a read/write 

   * session, or CK_FALSE otherwise.  An NSSArena dedicated to

   * the new session is available from the specified NSSCKFWSession.

   * This routine may return NULL upon error.

   */

  NSSCKMDSession *(PR_CALLBACK *OpenSession)(

    NSSCKMDToken *mdToken,

    NSSCKFWToken *fwToken,

    NSSCKMDInstance *mdInstance,

    NSSCKFWInstance *fwInstance,

    NSSCKFWSession *fwSession,

    CK_BBOOL rw,

    CK_RV *pError

  );

  /*

   * This routine returns the number of PKCS#11 Mechanisms

   * supported by this token.  This routine is optional; if

   * unimplemented, zero is assumed.

   */

  CK_ULONG (PR_CALLBACK *GetMechanismCount)(

    NSSCKMDToken *mdToken,

    NSSCKFWToken *fwToken,

    NSSCKMDInstance *mdInstance,

    NSSCKFWInstance *fwInstance

  );

  /*

   * This routine stuffs into the specified array the types

   * of the mechanisms supported by this token.  The Framework

   * determines the size of the array by calling GetMechanismCount.

   */

  CK_RV (PR_CALLBACK *GetMechanismTypes)(

    NSSCKMDToken *mdToken,

    NSSCKFWToken *fwToken,

    NSSCKMDInstance *mdInstance,

    NSSCKFWInstance *fwInstance,

    CK_MECHANISM_TYPE types[]

  );

  /*

   * This routine returns a pointer to a Module mechanism

   * object corresponding to a specified type.  This routine

   * need only exist for tokens implementing at least one

   * mechanism.

   */

  NSSCKMDMechanism *(PR_CALLBACK *GetMechanism)(

    NSSCKMDToken *mdToken,

    NSSCKFWToken *fwToken,

    NSSCKMDInstance *mdInstance,

    NSSCKFWInstance *fwInstance,

    CK_MECHANISM_TYPE which,

    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;

};

/*

 * NSSCKMDSession

 *

 * This is the basic handle for a session on a PKCS#11 Token.  It

 * is created by NSSCKMDToken->OpenSession, and may be obtained

 * from the Framework's corresponding NSSCKFWSession object.  It

 * contains a pointer for use by the Module, to store any session-

 * realted 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 NSSCKMDSessionStr {

  /*

   * The Module may use this pointer for its own purposes.

   */

  void *etc;

  /*

   * This routine is called by the Framework when a session is

   * closed.  This call is the last thing called before the

   * NSSArena in the correspoinding NSSCKFWSession is destroyed.

   * This routine is optional; if unimplemented, it merely won't

   * be called.

   */

  void (PR_CALLBACK *Close)(

    NSSCKMDSession *mdSession,

    NSSCKFWSession *fwSession,

    NSSCKMDToken *mdToken,

    NSSCKFWToken *fwToken,

    NSSCKMDInstance *mdInstance,

    NSSCKFWInstance *fwInstance

  );

  /*

   * This routine is used to get any device-specific error.

   * This routine is optional.

   */

  CK_ULONG (PR_CALLBACK *GetDeviceError)(

    NSSCKMDSession *mdSession,

    NSSCKFWSession *fwSession,

    NSSCKMDToken *mdToken,

    NSSCKFWToken *fwToken,