nssckmdt.h

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

 * 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