PageRenderTime 267ms CodeModel.GetById 134ms app.highlight 96ms RepoModel.GetById 25ms app.codeStats 1ms

/gecko_api/include/nssckmdt.h

http://firefox-mac-pdf.googlecode.com/
C++ Header | 1981 lines | 954 code | 146 blank | 881 comment | 0 complexity | a3414c36f2039c601927cb0ae598264d MD5 | raw file

Large files files are truncated, but you can click here to view the full file

   1/* ***** BEGIN LICENSE BLOCK *****
   2 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   3 *
   4 * The contents of this file are subject to the Mozilla Public License Version
   5 * 1.1 (the "License"); you may not use this file except in compliance with
   6 * the License. You may obtain a copy of the License at
   7 * http://www.mozilla.org/MPL/
   8 *
   9 * Software distributed under the License is distributed on an "AS IS" basis,
  10 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  11 * for the specific language governing rights and limitations under the
  12 * License.
  13 *
  14 * The Original Code is the Netscape security libraries.
  15 *
  16 * The Initial Developer of the Original Code is
  17 * Netscape Communications Corporation.
  18 * Portions created by the Initial Developer are Copyright (C) 1994-2000
  19 * the Initial Developer. All Rights Reserved.
  20 *
  21 * Contributor(s):
  22 *
  23 * Alternatively, the contents of this file may be used under the terms of
  24 * either the GNU General Public License Version 2 or later (the "GPL"), or
  25 * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  26 * in which case the provisions of the GPL or the LGPL are applicable instead
  27 * of those above. If you wish to allow use of your version of this file only
  28 * under the terms of either the GPL or the LGPL, and not to allow others to
  29 * use your version of this file under the terms of the MPL, indicate your
  30 * decision by deleting the provisions above and replace them with the notice
  31 * and other provisions required by the GPL or the LGPL. If you do not delete
  32 * the provisions above, a recipient may use your version of this file under
  33 * the terms of any one of the MPL, the GPL or the LGPL.
  34 *
  35 * ***** END LICENSE BLOCK ***** */
  36
  37#ifndef NSSCKMDT_H
  38#define NSSCKMDT_H
  39
  40#ifdef DEBUG
  41static const char NSSCKMDT_CVS_ID[] = "@(#) $RCSfile: nssckmdt.h,v $ $Revision: 1.6 $ $Date: 2005/12/16 00:48:01 $";
  42#endif /* DEBUG */
  43
  44/*
  45 * nssckmdt.h
  46 *
  47 * This file specifies the basic types that must be implemented by
  48 * any Module using the NSS Cryptoki Framework.
  49 */
  50
  51#ifndef NSSBASET_H
  52#include "nssbaset.h"
  53#endif /* NSSBASET_H */
  54
  55#ifndef NSSCKT_H
  56#include "nssckt.h"
  57#endif /* NSSCKT_H */
  58
  59#ifndef NSSCKFWT_H
  60#include "nssckfwt.h"
  61#endif /* NSSCKFWT_H */
  62
  63typedef struct NSSCKMDInstanceStr NSSCKMDInstance;
  64typedef struct NSSCKMDSlotStr NSSCKMDSlot;
  65typedef struct NSSCKMDTokenStr NSSCKMDToken;
  66typedef struct NSSCKMDSessionStr NSSCKMDSession;
  67typedef struct NSSCKMDCryptoOperationStr NSSCKMDCryptoOperation;
  68typedef struct NSSCKMDFindObjectsStr NSSCKMDFindObjects;
  69typedef struct NSSCKMDMechanismStr NSSCKMDMechanism;
  70typedef struct NSSCKMDObjectStr NSSCKMDObject;
  71
  72/*
  73 * NSSCKFWItem
  74 *
  75 * This is a structure used by modules to return object attributes.
  76 * The needsFreeing bit indicates whether the object needs to be freed.
  77 * If so, the framework will call the FreeAttribute function on the item
  78 * after it is done using it.
  79 *
  80 */
  81
  82typedef struct {
  83  PRBool needsFreeing;
  84  NSSItem* item;
  85} NSSCKFWItem ;
  86
  87/*
  88 * NSSCKMDInstance
  89 *
  90 * This is the basic handle for an instance of a PKCS#11 Module.
  91 * It is returned by the Module's CreateInstance routine, and
  92 * may be obtained from the corresponding NSSCKFWInstance object.
  93 * It contains a pointer for use by the Module, to store any
  94 * instance-related data, and it contains the EPV for a set of
  95 * routines which the Module may implement for use by the Framework.
  96 * Some of these routines are optional; others are mandatory.
  97 */
  98
  99struct NSSCKMDInstanceStr {
 100  /*
 101   * The Module may use this pointer for its own purposes.
 102   */
 103  void *etc;
 104
 105  /*
 106   * This routine is called by the Framework to initialize
 107   * the Module.  This routine is optional; if unimplemented,
 108   * it won't be called.  If this routine returns an error,
 109   * then the initialization will fail.
 110   */
 111  CK_RV (PR_CALLBACK *Initialize)(
 112    NSSCKMDInstance *mdInstance,                                    
 113    NSSCKFWInstance *fwInstance,
 114    NSSUTF8 *configurationData
 115  );
 116
 117  /*
 118   * This routine is called when the Framework is finalizing
 119   * the PKCS#11 Module.  It is the last thing called before
 120   * the NSSCKFWInstance's NSSArena is destroyed.  This routine
 121   * is optional; if unimplemented, it merely won't be called.
 122   */
 123  void (PR_CALLBACK *Finalize)(
 124    NSSCKMDInstance *mdInstance,                                    
 125    NSSCKFWInstance *fwInstance
 126  );
 127
 128  /*
 129   * This routine gets the number of slots.  This value must
 130   * never change, once the instance is initialized.  This 
 131   * routine must be implemented.  It may return zero on error.
 132   */
 133  CK_ULONG (PR_CALLBACK *GetNSlots)(
 134    NSSCKMDInstance *mdInstance,                                    
 135    NSSCKFWInstance *fwInstance,
 136    CK_RV *pError
 137  );
 138
 139  /*
 140   * This routine returns the version of the Cryptoki standard
 141   * to which this Module conforms.  This routine is optional;
 142   * if unimplemented, the Framework uses the version to which
 143   * ~it~ was implemented.
 144   */
 145  CK_VERSION (PR_CALLBACK *GetCryptokiVersion)(
 146    NSSCKMDInstance *mdInstance,                                    
 147    NSSCKFWInstance *fwInstance
 148  );
 149
 150  /*
 151   * This routine returns a pointer to a UTF8-encoded string
 152   * containing the manufacturer ID for this Module.  Only
 153   * the characters completely encoded in the first thirty-
 154   * two bytes are significant.  This routine is optional.
 155   * The string returned is never freed; if dynamically generated,
 156   * the space for it should be allocated from the NSSArena
 157   * that may be obtained from the NSSCKFWInstance.  This
 158   * routine may return NULL upon error; however if *pError
 159   * is CKR_OK, the NULL will be considered the valid response.
 160   */
 161  NSSUTF8 *(PR_CALLBACK *GetManufacturerID)(
 162    NSSCKMDInstance *mdInstance,                                    
 163    NSSCKFWInstance *fwInstance,
 164    CK_RV *pError
 165  );
 166
 167  /*
 168   * This routine returns a pointer to a UTF8-encoded string
 169   * containing a description of this Module library.  Only
 170   * the characters completely encoded in the first thirty-
 171   * two bytes are significant.  This routine is optional.
 172   * The string returned is never freed; if dynamically generated,
 173   * the space for it should be allocated from the NSSArena
 174   * that may be obtained from the NSSCKFWInstance.  This
 175   * routine may return NULL upon error; however if *pError
 176   * is CKR_OK, the NULL will be considered the valid response.
 177   */
 178  NSSUTF8 *(PR_CALLBACK *GetLibraryDescription)(
 179    NSSCKMDInstance *mdInstance,                                    
 180    NSSCKFWInstance *fwInstance,
 181    CK_RV *pError
 182  );
 183
 184  /*
 185   * This routine returns the version of this Module library.
 186   * This routine is optional; if unimplemented, the Framework
 187   * will assume a Module library version of 0.1.
 188   */
 189  CK_VERSION (PR_CALLBACK *GetLibraryVersion)(
 190    NSSCKMDInstance *mdInstance,                                    
 191    NSSCKFWInstance *fwInstance
 192  );
 193
 194  /*
 195   * This routine returns CK_TRUE if the Module wishes to
 196   * handle session objects.  This routine is optional.
 197   * If this routine is NULL, or if it exists but returns
 198   * CK_FALSE, the Framework will assume responsibility
 199   * for managing session objects.
 200   */
 201  CK_BBOOL (PR_CALLBACK *ModuleHandlesSessionObjects)(
 202    NSSCKMDInstance *mdInstance,                                    
 203    NSSCKFWInstance *fwInstance
 204  );
 205
 206  /*
 207   * This routine stuffs pointers to NSSCKMDSlot objects into
 208   * the specified array; one for each slot supported by this
 209   * instance.  The Framework will determine the size needed
 210   * for the array by calling GetNSlots.  This routine is
 211   * required.
 212   */
 213  CK_RV (PR_CALLBACK *GetSlots)(
 214    NSSCKMDInstance *mdInstance,                                    
 215    NSSCKFWInstance *fwInstance,
 216    NSSCKMDSlot *slots[]
 217  );
 218
 219  /*
 220   * This call returns a pointer to the slot in which an event
 221   * has occurred.  If the block argument is CK_TRUE, the call 
 222   * should block until a slot event occurs; if CK_FALSE, it 
 223   * should check to see if an event has occurred, occurred, 
 224   * but return NULL (and set *pError to CK_NO_EVENT) if one 
 225   * hasn't.  This routine is optional; if unimplemented, the
 226   * Framework will assume that no event has happened.  This
 227   * routine may return NULL upon error.
 228   */
 229  NSSCKMDSlot *(PR_CALLBACK *WaitForSlotEvent)(
 230    NSSCKMDInstance *mdInstance,                                    
 231    NSSCKFWInstance *fwInstance,
 232    CK_BBOOL block,
 233    CK_RV *pError
 234  );
 235
 236  /*
 237   * This object may be extended in future versions of the
 238   * NSS Cryptoki Framework.  To allow for some flexibility
 239   * in the area of binary compatibility, this field should
 240   * be NULL.
 241   */
 242  void *null;
 243};
 244
 245
 246/*
 247 * NSSCKMDSlot
 248 *
 249 * This is the basic handle for a PKCS#11 Module Slot.  It is
 250 * created by the NSSCKMDInstance->GetSlots call, and may be
 251 * obtained from the Framework's corresponding NSSCKFWSlot
 252 * object.  It contains a pointer for use by the Module, to
 253 * store any slot-related data, and it contains the EPV for
 254 * a set of routines which the Module may implement for use
 255 * by the Framework.  Some of these routines are optional.
 256 */
 257
 258struct NSSCKMDSlotStr {
 259  /*
 260   * The Module may use this pointer for its own purposes.
 261   */
 262  void *etc;
 263
 264  /*
 265   * This routine is called during the Framework initialization
 266   * step, after the Framework Instance has obtained the list
 267   * of slots (by calling NSSCKMDInstance->GetSlots).  Any slot-
 268   * specific initialization can be done here.  This routine is
 269   * optional; if unimplemented, it won't be called.  Note that
 270   * if this routine returns an error, the entire Framework
 271   * initialization for this Module will fail.
 272   */
 273  CK_RV (PR_CALLBACK *Initialize)(
 274    NSSCKMDSlot *mdSlot,
 275    NSSCKFWSlot *fwSlot,
 276    NSSCKMDInstance *mdInstance,                                    
 277    NSSCKFWInstance *fwInstance
 278  );
 279
 280  /*
 281   * This routine is called when the Framework is finalizing
 282   * the PKCS#11 Module.  This call (for each of the slots)
 283   * is the last thing called before NSSCKMDInstance->Finalize.
 284   * This routine is optional; if unimplemented, it merely 
 285   * won't be called.  Note: In the rare circumstance that
 286   * the Framework initialization cannot complete (due to,
 287   * for example, memory limitations), this can be called with
 288   * a NULL value for fwSlot.
 289   */
 290  void (PR_CALLBACK *Destroy)(
 291    NSSCKMDSlot *mdSlot,
 292    NSSCKFWSlot *fwSlot,
 293    NSSCKMDInstance *mdInstance,                                    
 294    NSSCKFWInstance *fwInstance
 295  );
 296
 297  /*
 298   * This routine returns a pointer to a UTF8-encoded string
 299   * containing a description of this slot.  Only the characters
 300   * completely encoded in the first sixty-four bytes are
 301   * significant.  This routine is optional.  The string 
 302   * returned is never freed; if dynamically generated,
 303   * the space for it should be allocated from the NSSArena
 304   * that may be obtained from the NSSCKFWInstance.  This
 305   * routine may return NULL upon error; however if *pError
 306   * is CKR_OK, the NULL will be considered the valid response.
 307   */
 308  NSSUTF8 *(PR_CALLBACK *GetSlotDescription)(
 309    NSSCKMDSlot *mdSlot,
 310    NSSCKFWSlot *fwSlot,
 311    NSSCKMDInstance *mdInstance,                                    
 312    NSSCKFWInstance *fwInstance,
 313    CK_RV *pError
 314  );
 315
 316  /*
 317   * This routine returns a pointer to a UTF8-encoded string
 318   * containing a description of the manufacturer of this slot.
 319   * Only the characters completely encoded in the first thirty-
 320   * two bytes are significant.  This routine is optional.  
 321   * The string  returned is never freed; if dynamically generated,
 322   * the space for it should be allocated from the NSSArena
 323   * that may be obtained from the NSSCKFWInstance.  This
 324   * routine may return NULL upon error; however if *pError
 325   * is CKR_OK, the NULL will be considered the valid response.
 326   */
 327  NSSUTF8 *(PR_CALLBACK *GetManufacturerID)(
 328    NSSCKMDSlot *mdSlot,
 329    NSSCKFWSlot *fwSlot,
 330    NSSCKMDInstance *mdInstance,                                    
 331    NSSCKFWInstance *fwInstance,
 332    CK_RV *pError
 333  );
 334
 335  /*
 336   * This routine returns CK_TRUE if a token is present in this
 337   * slot.  This routine is optional; if unimplemented, CK_TRUE
 338   * is assumed.
 339   */
 340  CK_BBOOL (PR_CALLBACK *GetTokenPresent)(
 341    NSSCKMDSlot *mdSlot,
 342    NSSCKFWSlot *fwSlot,
 343    NSSCKMDInstance *mdInstance,                                    
 344    NSSCKFWInstance *fwInstance
 345  );
 346
 347  /*
 348   * This routine returns CK_TRUE if the slot supports removable
 349   * tokens.  This routine is optional; if unimplemented, CK_FALSE
 350   * is assumed.
 351   */
 352  CK_BBOOL (PR_CALLBACK *GetRemovableDevice)(
 353    NSSCKMDSlot *mdSlot,
 354    NSSCKFWSlot *fwSlot,
 355    NSSCKMDInstance *mdInstance,                                    
 356    NSSCKFWInstance *fwInstance
 357  );
 358
 359  /*
 360   * This routine returns CK_TRUE if this slot is a hardware
 361   * device, or CK_FALSE if this slot is a software device.  This
 362   * routine is optional; if unimplemented, CK_FALSE is assumed.
 363   */
 364  CK_BBOOL (PR_CALLBACK *GetHardwareSlot)(
 365    NSSCKMDSlot *mdSlot,
 366    NSSCKFWSlot *fwSlot,
 367    NSSCKMDInstance *mdInstance,                                    
 368    NSSCKFWInstance *fwInstance
 369  );
 370
 371  /*
 372   * This routine returns the version of this slot's hardware.
 373   * This routine is optional; if unimplemented, the Framework
 374   * will assume a hardware version of 0.1.
 375   */
 376  CK_VERSION (PR_CALLBACK *GetHardwareVersion)(
 377    NSSCKMDSlot *mdSlot,
 378    NSSCKFWSlot *fwSlot,
 379    NSSCKMDInstance *mdInstance,                                    
 380    NSSCKFWInstance *fwInstance
 381  );
 382
 383  /*
 384   * This routine returns the version of this slot's firmware.
 385   * This routine is optional; if unimplemented, the Framework
 386   * will assume a hardware version of 0.1.
 387   */
 388  CK_VERSION (PR_CALLBACK *GetFirmwareVersion)(
 389    NSSCKMDSlot *mdSlot,
 390    NSSCKFWSlot *fwSlot,
 391    NSSCKMDInstance *mdInstance,                                    
 392    NSSCKFWInstance *fwInstance
 393  );
 394
 395  /*
 396   * This routine should return a pointer to an NSSCKMDToken
 397   * object corresponding to the token in the specified slot.
 398   * The NSSCKFWToken object passed in has an NSSArena
 399   * available which is dedicated for this token.  This routine
 400   * must be implemented.  This routine may return NULL upon
 401   * error.
 402   */
 403  NSSCKMDToken *(PR_CALLBACK *GetToken)(
 404    NSSCKMDSlot *mdSlot,
 405    NSSCKFWSlot *fwSlot,
 406    NSSCKMDInstance *mdInstance,                                    
 407    NSSCKFWInstance *fwInstance,
 408    CK_RV *pError
 409  );
 410
 411  /*
 412   * This object may be extended in future versions of the
 413   * NSS Cryptoki Framework.  To allow for some flexibility
 414   * in the area of binary compatibility, this field should
 415   * be NULL.
 416   */
 417  void *null;
 418};
 419
 420/*
 421 * NSSCKMDToken
 422 *
 423 * This is the basic handle for a PKCS#11 Token.  It is created by
 424 * the NSSCKMDSlot->GetToken call, and may be obtained from the
 425 * Framework's corresponding NSSCKFWToken object.  It contains a
 426 * pointer for use by the Module, to store any token-related
 427 * data, and it contains the EPV for a set of routines which the
 428 * Module may implement for use by the Framework.  Some of these
 429 * routines are optional.
 430 */
 431
 432struct NSSCKMDTokenStr {
 433  /*
 434   * The Module may use this pointer for its own purposes.
 435   */
 436  void *etc;
 437
 438  /*
 439   * This routine is used to prepare a Module token object for
 440   * use.  It is called after the NSSCKMDToken object is obtained
 441   * from NSSCKMDSlot->GetToken.  It is named "Setup" here because
 442   * Cryptoki already defines "InitToken" to do the process of
 443   * wiping out any existing state on a token and preparing it for
 444   * a new use.  This routine is optional; if unimplemented, it
 445   * merely won't be called.
 446   */
 447  CK_RV (PR_CALLBACK *Setup)(
 448    NSSCKMDToken *mdToken,
 449    NSSCKFWToken *fwToken,
 450    NSSCKMDInstance *mdInstance,
 451    NSSCKFWInstance *fwInstance
 452  );
 453
 454  /*
 455   * This routine is called by the Framework whenever it notices
 456   * that the token object is invalid.  (Typically this is when a 
 457   * routine indicates an error such as CKR_DEVICE_REMOVED).  This
 458   * call is the last thing called before the NSSArena in the
 459   * corresponding NSSCKFWToken is destroyed.  This routine is
 460   * optional; if unimplemented, it merely won't be called.
 461   */
 462  void (PR_CALLBACK *Invalidate)(
 463    NSSCKMDToken *mdToken,
 464    NSSCKFWToken *fwToken,
 465    NSSCKMDInstance *mdInstance,
 466    NSSCKFWInstance *fwInstance
 467  );
 468
 469  /*
 470   * This routine initialises the token in the specified slot.
 471   * This routine is optional; if unimplemented, the Framework
 472   * will fail this operation with an error of CKR_DEVICE_ERROR.
 473   */
 474
 475  CK_RV (PR_CALLBACK *InitToken)(
 476    NSSCKMDToken *mdToken,
 477    NSSCKFWToken *fwToken,
 478    NSSCKMDInstance *mdInstance,
 479    NSSCKFWInstance *fwInstance,
 480    NSSItem *pin,
 481    NSSUTF8 *label
 482  );
 483
 484  /*
 485   * This routine returns a pointer to a UTF8-encoded string
 486   * containing this token's label.  Only the characters
 487   * completely encoded in the first thirty-two bytes are
 488   * significant.  This routine is optional.  The string 
 489   * returned is never freed; if dynamically generated,
 490   * the space for it should be allocated from the NSSArena
 491   * that may be obtained from the NSSCKFWInstance.  This
 492   * routine may return NULL upon error; however if *pError
 493   * is CKR_OK, the NULL will be considered the valid response.
 494   */
 495  NSSUTF8 *(PR_CALLBACK *GetLabel)(
 496    NSSCKMDToken *mdToken,
 497    NSSCKFWToken *fwToken,
 498    NSSCKMDInstance *mdInstance,
 499    NSSCKFWInstance *fwInstance,
 500    CK_RV *pError
 501  );
 502
 503  /*
 504   * This routine returns a pointer to a UTF8-encoded string
 505   * containing this token's manufacturer ID.  Only the characters
 506   * completely encoded in the first thirty-two bytes are
 507   * significant.  This routine is optional.  The string 
 508   * returned is never freed; if dynamically generated,
 509   * the space for it should be allocated from the NSSArena
 510   * that may be obtained from the NSSCKFWInstance.  This
 511   * routine may return NULL upon error; however if *pError
 512   * is CKR_OK, the NULL will be considered the valid response.
 513   */
 514  NSSUTF8 *(PR_CALLBACK *GetManufacturerID)(
 515    NSSCKMDToken *mdToken,
 516    NSSCKFWToken *fwToken,
 517    NSSCKMDInstance *mdInstance,
 518    NSSCKFWInstance *fwInstance,
 519    CK_RV *pError
 520  );
 521
 522  /*
 523   * This routine returns a pointer to a UTF8-encoded string
 524   * containing this token's model name.  Only the characters
 525   * completely encoded in the first thirty-two bytes are
 526   * significant.  This routine is optional.  The string 
 527   * returned is never freed; if dynamically generated,
 528   * the space for it should be allocated from the NSSArena
 529   * that may be obtained from the NSSCKFWInstance.  This
 530   * routine may return NULL upon error; however if *pError
 531   * is CKR_OK, the NULL will be considered the valid response.
 532   */
 533  NSSUTF8 *(PR_CALLBACK *GetModel)(
 534    NSSCKMDToken *mdToken,
 535    NSSCKFWToken *fwToken,
 536    NSSCKMDInstance *mdInstance,
 537    NSSCKFWInstance *fwInstance,
 538    CK_RV *pError
 539  );
 540
 541  /*
 542   * This routine returns a pointer to a UTF8-encoded string
 543   * containing this token's serial number.  Only the characters
 544   * completely encoded in the first thirty-two bytes are
 545   * significant.  This routine is optional.  The string 
 546   * returned is never freed; if dynamically generated,
 547   * the space for it should be allocated from the NSSArena
 548   * that may be obtained from the NSSCKFWInstance.  This
 549   * routine may return NULL upon error; however if *pError
 550   * is CKR_OK, the NULL will be considered the valid response.
 551   */
 552  NSSUTF8 *(PR_CALLBACK *GetSerialNumber)(
 553    NSSCKMDToken *mdToken,
 554    NSSCKFWToken *fwToken,
 555    NSSCKMDInstance *mdInstance,
 556    NSSCKFWInstance *fwInstance,
 557    CK_RV *pError
 558  );
 559
 560  /*
 561   * This routine returns CK_TRUE if the token has its own
 562   * random number generator.  This routine is optional; if
 563   * unimplemented, CK_FALSE is assumed.
 564   */
 565  CK_BBOOL (PR_CALLBACK *GetHasRNG)(
 566    NSSCKMDToken *mdToken,
 567    NSSCKFWToken *fwToken,
 568    NSSCKMDInstance *mdInstance,
 569    NSSCKFWInstance *fwInstance
 570  );
 571
 572  /*
 573   * This routine returns CK_TRUE if this token is write-protected.
 574   * This routine is optional; if unimplemented, CK_FALSE is
 575   * assumed.
 576   */
 577  CK_BBOOL (PR_CALLBACK *GetIsWriteProtected)(
 578    NSSCKMDToken *mdToken,
 579    NSSCKFWToken *fwToken,
 580    NSSCKMDInstance *mdInstance,
 581    NSSCKFWInstance *fwInstance
 582  );
 583
 584  /*
 585   * This routine returns CK_TRUE if this token requires a login.
 586   * This routine is optional; if unimplemented, CK_FALSE is
 587   * assumed.
 588   */
 589  CK_BBOOL (PR_CALLBACK *GetLoginRequired)(
 590    NSSCKMDToken *mdToken,
 591    NSSCKFWToken *fwToken,
 592    NSSCKMDInstance *mdInstance,
 593    NSSCKFWInstance *fwInstance
 594  );
 595
 596  /*
 597   * This routine returns CK_TRUE if the normal user's PIN on this
 598   * token has been initialised.  This routine is optional; if
 599   * unimplemented, CK_FALSE is assumed.
 600   */
 601  CK_BBOOL (PR_CALLBACK *GetUserPinInitialized)(
 602    NSSCKMDToken *mdToken,
 603    NSSCKFWToken *fwToken,
 604    NSSCKMDInstance *mdInstance,
 605    NSSCKFWInstance *fwInstance
 606  );
 607
 608  /*
 609   * This routine returns CK_TRUE if a successful save of a
 610   * session's cryptographic operations state ~always~ contains
 611   * all keys needed to restore the state of the session.  This
 612   * routine is optional; if unimplemented, CK_FALSE is assumed.
 613   */
 614  CK_BBOOL (PR_CALLBACK *GetRestoreKeyNotNeeded)(
 615    NSSCKMDToken *mdToken,
 616    NSSCKFWToken *fwToken,
 617    NSSCKMDInstance *mdInstance,
 618    NSSCKFWInstance *fwInstance
 619  );
 620
 621  /*
 622   * This routine returns CK_TRUE if the token has its own
 623   * hardware clock.  This routine is optional; if unimplemented,
 624   * CK_FALSE is assumed.
 625   */
 626  CK_BBOOL (PR_CALLBACK *GetHasClockOnToken)(
 627    NSSCKMDToken *mdToken,
 628    NSSCKFWToken *fwToken,
 629    NSSCKMDInstance *mdInstance,
 630    NSSCKFWInstance *fwInstance
 631  );
 632
 633  /*
 634   * This routine returns CK_TRUE if the token has a protected
 635   * authentication path.  This routine is optional; if
 636   * unimplemented, CK_FALSE is assumed.
 637   */
 638  CK_BBOOL (PR_CALLBACK *GetHasProtectedAuthenticationPath)(
 639    NSSCKMDToken *mdToken,
 640    NSSCKFWToken *fwToken,
 641    NSSCKMDInstance *mdInstance,
 642    NSSCKFWInstance *fwInstance
 643  );
 644
 645  /*
 646   * This routine returns CK_TRUE if the token supports dual
 647   * cryptographic operations within a single session.  This
 648   * routine is optional; if unimplemented, CK_FALSE is assumed.
 649   */
 650  CK_BBOOL (PR_CALLBACK *GetSupportsDualCryptoOperations)(
 651    NSSCKMDToken *mdToken,
 652    NSSCKFWToken *fwToken,
 653    NSSCKMDInstance *mdInstance,
 654    NSSCKFWInstance *fwInstance
 655  );
 656
 657  /*
 658   * XXX fgmr-- should we have a call to return all the flags
 659   * at once, for folks who already know about Cryptoki?
 660   */
 661
 662  /*
 663   * This routine returns the maximum number of sessions that
 664   * may be opened on this token.  This routine is optional;
 665   * if unimplemented, the special value CK_UNAVAILABLE_INFORMATION
 666   * is assumed.  XXX fgmr-- or CK_EFFECTIVELY_INFINITE?
 667   */
 668  CK_ULONG (PR_CALLBACK *GetMaxSessionCount)(
 669    NSSCKMDToken *mdToken,
 670    NSSCKFWToken *fwToken,
 671    NSSCKMDInstance *mdInstance,
 672    NSSCKFWInstance *fwInstance
 673  );
 674
 675  /*
 676   * This routine returns the maximum number of read/write
 677   * sesisons that may be opened on this token.  This routine
 678   * is optional; if unimplemented, the special value
 679   * CK_UNAVAILABLE_INFORMATION is assumed.  XXX fgmr-- or 
 680   * CK_EFFECTIVELY_INFINITE?
 681   */
 682  CK_ULONG (PR_CALLBACK *GetMaxRwSessionCount)(
 683    NSSCKMDToken *mdToken,
 684    NSSCKFWToken *fwToken,
 685    NSSCKMDInstance *mdInstance,
 686    NSSCKFWInstance *fwInstance
 687  );
 688
 689  /*
 690   * This routine returns the maximum PIN code length that is
 691   * supported on this token.  This routine is optional;
 692   * if unimplemented, the special value CK_UNAVAILABLE_INFORMATION
 693   * is assumed.
 694   */
 695  CK_ULONG (PR_CALLBACK *GetMaxPinLen)(
 696    NSSCKMDToken *mdToken,
 697    NSSCKFWToken *fwToken,
 698    NSSCKMDInstance *mdInstance,
 699    NSSCKFWInstance *fwInstance
 700  );
 701
 702  /*
 703   * This routine returns the minimum PIN code length that is
 704   * supported on this token.  This routine is optional; if
 705   * unimplemented, the special value CK_UNAVAILABLE_INFORMATION
 706   *  is assumed.  XXX fgmr-- or 0?
 707   */
 708  CK_ULONG (PR_CALLBACK *GetMinPinLen)(
 709    NSSCKMDToken *mdToken,
 710    NSSCKFWToken *fwToken,
 711    NSSCKMDInstance *mdInstance,
 712    NSSCKFWInstance *fwInstance
 713  );
 714
 715  /*
 716   * This routine returns the total amount of memory on the token
 717   * in which public objects may be stored.  This routine is
 718   * optional; if unimplemented, the special value
 719   * CK_UNAVAILABLE_INFORMATION is assumed.
 720   */
 721  CK_ULONG (PR_CALLBACK *GetTotalPublicMemory)(
 722    NSSCKMDToken *mdToken,
 723    NSSCKFWToken *fwToken,
 724    NSSCKMDInstance *mdInstance,
 725    NSSCKFWInstance *fwInstance
 726  );
 727
 728  /*
 729   * This routine returns the amount of unused memory on the
 730   * token in which public objects may be stored.  This routine
 731   * is optional; if unimplemented, the special value
 732   * CK_UNAVAILABLE_INFORMATION is assumed.
 733   */
 734  CK_ULONG (PR_CALLBACK *GetFreePublicMemory)(
 735    NSSCKMDToken *mdToken,
 736    NSSCKFWToken *fwToken,
 737    NSSCKMDInstance *mdInstance,
 738    NSSCKFWInstance *fwInstance
 739  );
 740
 741  /*
 742   * This routine returns the total amount of memory on the token
 743   * in which private objects may be stored.  This routine is
 744   * optional; if unimplemented, the special value
 745   * CK_UNAVAILABLE_INFORMATION is assumed.
 746   */
 747  CK_ULONG (PR_CALLBACK *GetTotalPrivateMemory)(
 748    NSSCKMDToken *mdToken,
 749    NSSCKFWToken *fwToken,
 750    NSSCKMDInstance *mdInstance,
 751    NSSCKFWInstance *fwInstance
 752  );
 753
 754  /*
 755   * This routine returns the amount of unused memory on the
 756   * token in which private objects may be stored.  This routine
 757   * is optional; if unimplemented, the special value
 758   * CK_UNAVAILABLE_INFORMATION is assumed.
 759   */
 760  CK_ULONG (PR_CALLBACK *GetFreePrivateMemory)(
 761    NSSCKMDToken *mdToken,
 762    NSSCKFWToken *fwToken,
 763    NSSCKMDInstance *mdInstance,
 764    NSSCKFWInstance *fwInstance
 765  );
 766
 767  /*
 768   * This routine returns the version number of this token's
 769   * hardware.  This routine is optional; if unimplemented,
 770   * the value 0.1 is assumed.
 771   */
 772  CK_VERSION (PR_CALLBACK *GetHardwareVersion)(
 773    NSSCKMDToken *mdToken,
 774    NSSCKFWToken *fwToken,
 775    NSSCKMDInstance *mdInstance,
 776    NSSCKFWInstance *fwInstance
 777  );
 778
 779  /*
 780   * This routine returns the version number of this token's
 781   * firmware.  This routine is optional; if unimplemented,
 782   * the value 0.1 is assumed.
 783   */
 784  CK_VERSION (PR_CALLBACK *GetFirmwareVersion)(
 785    NSSCKMDToken *mdToken,
 786    NSSCKFWToken *fwToken,
 787    NSSCKMDInstance *mdInstance,
 788    NSSCKFWInstance *fwInstance
 789  );
 790
 791  /*
 792   * This routine stuffs the current UTC time, as obtained from
 793   * the token, into the sixteen-byte buffer in the form
 794   * YYYYMMDDhhmmss00.  This routine need only be implemented
 795   * by token which indicate that they have a real-time clock.
 796   * XXX fgmr-- think about time formats.
 797   */
 798  CK_RV (PR_CALLBACK *GetUTCTime)(
 799    NSSCKMDToken *mdToken,
 800    NSSCKFWToken *fwToken,
 801    NSSCKMDInstance *mdInstance,
 802    NSSCKFWInstance *fwInstance,
 803    CK_CHAR utcTime[16]
 804  );
 805
 806  /*
 807   * This routine creates a session on the token, and returns
 808   * the corresponding NSSCKMDSession object.  The value of
 809   * rw will be CK_TRUE if the session is to be a read/write 
 810   * session, or CK_FALSE otherwise.  An NSSArena dedicated to
 811   * the new session is available from the specified NSSCKFWSession.
 812   * This routine may return NULL upon error.
 813   */
 814  NSSCKMDSession *(PR_CALLBACK *OpenSession)(
 815    NSSCKMDToken *mdToken,
 816    NSSCKFWToken *fwToken,
 817    NSSCKMDInstance *mdInstance,
 818    NSSCKFWInstance *fwInstance,
 819    NSSCKFWSession *fwSession,
 820    CK_BBOOL rw,
 821    CK_RV *pError
 822  );
 823
 824  /*
 825   * This routine returns the number of PKCS#11 Mechanisms
 826   * supported by this token.  This routine is optional; if
 827   * unimplemented, zero is assumed.
 828   */
 829  CK_ULONG (PR_CALLBACK *GetMechanismCount)(
 830    NSSCKMDToken *mdToken,
 831    NSSCKFWToken *fwToken,
 832    NSSCKMDInstance *mdInstance,
 833    NSSCKFWInstance *fwInstance
 834  );
 835
 836  /*
 837   * This routine stuffs into the specified array the types
 838   * of the mechanisms supported by this token.  The Framework
 839   * determines the size of the array by calling GetMechanismCount.
 840   */
 841  CK_RV (PR_CALLBACK *GetMechanismTypes)(
 842    NSSCKMDToken *mdToken,
 843    NSSCKFWToken *fwToken,
 844    NSSCKMDInstance *mdInstance,
 845    NSSCKFWInstance *fwInstance,
 846    CK_MECHANISM_TYPE types[]
 847  );
 848
 849  /*
 850   * This routine returns a pointer to a Module mechanism
 851   * object corresponding to a specified type.  This routine
 852   * need only exist for tokens implementing at least one
 853   * mechanism.
 854   */
 855  NSSCKMDMechanism *(PR_CALLBACK *GetMechanism)(
 856    NSSCKMDToken *mdToken,
 857    NSSCKFWToken *fwToken,
 858    NSSCKMDInstance *mdInstance,
 859    NSSCKFWInstance *fwInstance,
 860    CK_MECHANISM_TYPE which,
 861    CK_RV *pError
 862  );
 863
 864  /*
 865   * This object may be extended in future versions of the
 866   * NSS Cryptoki Framework.  To allow for some flexibility
 867   * in the area of binary compatibility, this field should
 868   * be NULL.
 869   */
 870  void *null;
 871};
 872
 873/*
 874 * NSSCKMDSession
 875 *
 876 * This is the basic handle for a session on a PKCS#11 Token.  It
 877 * is created by NSSCKMDToken->OpenSession, and may be obtained
 878 * from the Framework's corresponding NSSCKFWSession object.  It
 879 * contains a pointer for use by the Module, to store any session-
 880 * realted data, and it contains the EPV for a set of routines
 881 * which the Module may implement for use by the Framework.  Some
 882 * of these routines are optional.
 883 */
 884
 885struct NSSCKMDSessionStr {
 886  /*
 887   * The Module may use this pointer for its own purposes.
 888   */
 889  void *etc;
 890
 891  /*
 892   * This routine is called by the Framework when a session is
 893   * closed.  This call is the last thing called before the
 894   * NSSArena in the correspoinding NSSCKFWSession is destroyed.
 895   * This routine is optional; if unimplemented, it merely won't
 896   * be called.
 897   */
 898  void (PR_CALLBACK *Close)(
 899    NSSCKMDSession *mdSession,
 900    NSSCKFWSession *fwSession,
 901    NSSCKMDToken *mdToken,
 902    NSSCKFWToken *fwToken,
 903    NSSCKMDInstance *mdInstance,
 904    NSSCKFWInstance *fwInstance
 905  );
 906
 907  /*
 908   * This routine is used to get any device-specific error.
 909   * This routine is optional.
 910   */
 911  CK_ULONG (PR_CALLBACK *GetDeviceError)(
 912    NSSCKMDSession *mdSession,
 913    NSSCKFWSession *fwSession,
 914    NSSCKMDToken *mdToken,
 915    NSSCKFWToken *fwToken,
 916    NSSCKMDInstance *mdInstance,
 917    NSSCKFWInstance *fwInstance
 918  );
 919
 920  /*
 921   * This routine is used to log in a user to the token.  This
 922   * routine is optional, since the Framework's NSSCKFWSession
 923   * object keeps track of the login state.
 924   */
 925  CK_RV (PR_CALLBACK *Login)(
 926    NSSCKMDSession *mdSession,
 927    NSSCKFWSession *fwSession,
 928    NSSCKMDToken *mdToken,
 929    NSSCKFWToken *fwToken,
 930    NSSCKMDInstance *mdInstance,
 931    NSSCKFWInstance *fwInstance,
 932    CK_USER_TYPE userType,
 933    NSSItem *pin,
 934    CK_STATE oldState,
 935    CK_STATE newState
 936  );
 937
 938  /*
 939   * This routine is used to log out a user from the token.  This
 940   * routine is optional, since the Framework's NSSCKFWSession
 941   * object keeps track of the login state.
 942   */
 943  CK_RV (PR_CALLBACK *Logout)(
 944    NSSCKMDSession *mdSession,
 945    NSSCKFWSession *fwSession,
 946    NSSCKMDToken *mdToken,
 947    NSSCKFWToken *fwToken,
 948    NSSCKMDInstance *mdInstance,
 949    NSSCKFWInstance *fwInstance,
 950    CK_STATE oldState,
 951    CK_STATE newState
 952  );
 953
 954  /*
 955   * This routine is used to initialize the normal user's PIN or
 956   * password.  This will only be called in the "read/write
 957   * security officer functions" state.  If this token has a
 958   * protected authentication path, then the pin argument will
 959   * be NULL.  This routine is optional; if unimplemented, the
 960   * Framework will return the error CKR_TOKEN_WRITE_PROTECTED.
 961   */
 962  CK_RV (PR_CALLBACK *InitPIN)(
 963    NSSCKMDSession *mdSession,
 964    NSSCKFWSession *fwSession,
 965    NSSCKMDToken *mdToken,
 966    NSSCKFWToken *fwToken,
 967    NSSCKMDInstance *mdInstance,
 968    NSSCKFWInstance *fwInstance,
 969    NSSItem *pin
 970  );
 971
 972  /*
 973   * This routine is used to modify a user's PIN or password.  This
 974   * routine will only be called in the "read/write security officer
 975   * functions" or "read/write user functions" state.  If this token
 976   * has a protected authentication path, then the pin arguments
 977   * will be NULL.  This routine is optional; if unimplemented, the
 978   * Framework will return the error CKR_TOKEN_WRITE_PROTECTED.
 979   */
 980  CK_RV (PR_CALLBACK *SetPIN)(
 981    NSSCKMDSession *mdSession,
 982    NSSCKFWSession *fwSession,
 983    NSSCKMDToken *mdToken,
 984    NSSCKFWToken *fwToken,
 985    NSSCKMDInstance *mdInstance,
 986    NSSCKFWInstance *fwInstance,
 987    NSSItem *oldPin,
 988    NSSItem *newPin
 989  );
 990
 991  /*
 992   * This routine is used to find out how much space would be required
 993   * to save the current operational state.  This routine is optional;
 994   * if unimplemented, the Framework will reject any attempts to save
 995   * the operational state with the error CKR_STATE_UNSAVEABLE.  This
 996   * routine may return zero on error.
 997   */
 998  CK_ULONG (PR_CALLBACK *GetOperationStateLen)(
 999    NSSCKMDSession *mdSession,
1000    NSSCKFWSession *fwSession,
1001    NSSCKMDToken *mdToken,
1002    NSSCKFWToken *fwToken,
1003    NSSCKMDInstance *mdInstance,
1004    NSSCKFWInstance *fwInstance,
1005    CK_RV *pError
1006  );
1007
1008  /*
1009   * This routine is used to store the current operational state.  This
1010   * routine is only required if GetOperationStateLen is implemented 
1011   * and can return a nonzero value.  The buffer in the specified item
1012   * will be pre-allocated, and the length will specify the amount of
1013   * space available (which may be more than GetOperationStateLen
1014   * asked for, but which will not be smaller).
1015   */
1016  CK_RV (PR_CALLBACK *GetOperationState)(
1017    NSSCKMDSession *mdSession,
1018    NSSCKFWSession *fwSession,
1019    NSSCKMDToken *mdToken,
1020    NSSCKFWToken *fwToken,
1021    NSSCKMDInstance *mdInstance,
1022    NSSCKFWInstance *fwInstance,
1023    NSSItem *buffer
1024  );
1025
1026  /*
1027   * This routine is used to restore an operational state previously
1028   * obtained with GetOperationState.  The Framework will take pains
1029   * to be sure that the state is (or was at one point) valid; if the
1030   * Module notices that the state is invalid, it should return an
1031   * error, but it is not required to be paranoid about the issue.
1032   * [XXX fgmr-- should (can?) the framework verify the keys match up?]
1033   * This routine is required only if GetOperationState is implemented.
1034   */
1035  CK_RV (PR_CALLBACK *SetOperationState)(
1036    NSSCKMDSession *mdSession,
1037    NSSCKFWSession *fwSession,
1038    NSSCKMDToken *mdToken,
1039    NSSCKFWToken *fwToken,
1040    NSSCKMDInstance *mdInstance,
1041    NSSCKFWInstance *fwInstance,
1042    NSSItem *state,
1043    NSSCKMDObject *mdEncryptionKey,
1044    NSSCKFWObject *fwEncryptionKey,
1045    NSSCKMDObject *mdAuthenticationKey,
1046    NSSCKFWObject *fwAuthenticationKey
1047  );
1048
1049  /*
1050   * This routine is used to create an object.  The specified template
1051   * will only specify a session object if the Module has indicated 
1052   * that it wishes to handle its own session objects.  This routine
1053   * is optional; if unimplemented, the Framework will reject the
1054   * operation with the error CKR_TOKEN_WRITE_PROTECTED.  Space for
1055   * token objects should come from the NSSArena available from the
1056   * NSSCKFWToken object; space for session objects (if supported)
1057   * should come from the NSSArena available from the NSSCKFWSession
1058   * object.  The appropriate NSSArena pointer will, as a convenience,
1059   * be passed as the handyArenaPointer argument.  This routine may
1060   * return NULL upon error.
1061   */
1062  NSSCKMDObject *(PR_CALLBACK *CreateObject)(
1063    NSSCKMDSession *mdSession,
1064    NSSCKFWSession *fwSession,
1065    NSSCKMDToken *mdToken,
1066    NSSCKFWToken *fwToken,
1067    NSSCKMDInstance *mdInstance,
1068    NSSCKFWInstance *fwInstance,
1069    NSSArena *handyArenaPointer,
1070    CK_ATTRIBUTE_PTR pTemplate,
1071    CK_ULONG ulAttributeCount,
1072    CK_RV *pError
1073  );
1074
1075  /*
1076   * This routine is used to make a copy of an object.  It is entirely
1077   * optional; if unimplemented, the Framework will try to use
1078   * CreateObject instead.  If the Module has indicated that it does
1079   * not wish to handle session objects, then this routine will only
1080   * be called to copy a token object to another token object.
1081   * Otherwise, either the original object or the new may be of
1082   * either the token or session variety.  As with CreateObject, the
1083   * handyArenaPointer will point to the appropriate arena for the
1084   * new object.  This routine may return NULL upon error.
1085   */
1086  NSSCKMDObject *(PR_CALLBACK *CopyObject)(
1087    NSSCKMDSession *mdSession,
1088    NSSCKFWSession *fwSession,
1089    NSSCKMDToken *mdToken,
1090    NSSCKFWToken *fwToken,
1091    NSSCKMDInstance *mdInstance,
1092    NSSCKFWInstance *fwInstance,
1093    NSSCKMDObject *mdOldObject,
1094    NSSCKFWObject *fwOldObject,
1095    NSSArena *handyArenaPointer,
1096    CK_ATTRIBUTE_PTR pTemplate,
1097    CK_ULONG ulAttributeCount,
1098    CK_RV *pError
1099  );
1100
1101  /*
1102   * This routine is used to begin an object search.  This routine may
1103   * be unimplemented only if the Module does not handle session 
1104   * objects, and if none of its tokens have token objects.  The
1105   * NSSCKFWFindObjects pointer has an NSSArena that may be used for
1106   * storage for the life of this "find" operation.  This routine may
1107   * return NULL upon error.  If the Module can determine immediately
1108   * that the search will not find any matching objects, it may return
1109   * NULL, and specify CKR_OK as the error.
1110   */
1111  NSSCKMDFindObjects *(PR_CALLBACK *FindObjectsInit)(
1112    NSSCKMDSession *mdSession,
1113    NSSCKFWSession *fwSession,
1114    NSSCKMDToken *mdToken,
1115    NSSCKFWToken *fwToken,
1116    NSSCKMDInstance *mdInstance,
1117    NSSCKFWInstance *fwInstance,
1118    CK_ATTRIBUTE_PTR pTemplate,
1119    CK_ULONG ulAttributeCount,
1120    CK_RV *pError
1121  );
1122
1123  /*
1124   * This routine seeds the random-number generator.  It is
1125   * optional, even if GetRandom is implemented.  If unimplemented,
1126   * the Framework will issue the error CKR_RANDOM_SEED_NOT_SUPPORTED.
1127   */
1128  CK_RV (PR_CALLBACK *SeedRandom)(
1129    NSSCKMDSession *mdSession,
1130    NSSCKFWSession *fwSession,
1131    NSSCKMDToken *mdToken,
1132    NSSCKFWToken *fwToken,
1133    NSSCKMDInstance *mdInstance,
1134    NSSCKFWInstance *fwInstance,
1135    NSSItem *seed
1136  );
1137
1138  /*
1139   * This routine gets random data.  It is optional.  If unimplemented,
1140   * the Framework will issue the error CKR_RANDOM_NO_RNG.
1141   */
1142  CK_RV (PR_CALLBACK *GetRandom)(
1143    NSSCKMDSession *mdSession,
1144    NSSCKFWSession *fwSession,
1145    NSSCKMDToken *mdToken,
1146    NSSCKFWToken *fwToken,
1147    NSSCKMDInstance *mdInstance,
1148    NSSCKFWInstance *fwInstance,
1149    NSSItem *buffer
1150  );
1151
1152  /*
1153   * This object may be extended in future versions of the
1154   * NSS Cryptoki Framework.  To allow for some flexibility
1155   * in the area of binary compatibility, this field should
1156   * be NULL.
1157   */
1158  void *null;
1159};
1160
1161/*
1162 * NSSCKMDFindObjects
1163 *
1164 * This is the basic handle for an object search.  It is
1165 * created by NSSCKMDSession->FindObjectsInit, and may be
1166 * obtained from the Framework's corresponding object.
1167 * It contains a pointer for use by the Module, to store
1168 * any search-related data, and it contains the EPV for a
1169 * set of routines which the Module may implement for use
1170 * by the Framework.  Some of these routines are optional.
1171 */
1172
1173struct NSSCKMDFindObjectsStr {
1174  /*
1175   * The Module may use this pointer for its own purposes.
1176   */
1177  void *etc;
1178
1179  /*
1180   * This routine is called by the Framework to finish a
1181   * search operation.  Note that the Framework may finish
1182   * a search before it has completed.  This routine is
1183   * optional; if unimplemented, it merely won't be called.
1184   */
1185  void (PR_CALLBACK *Final)(
1186    NSSCKMDFindObjects *mdFindObjects,
1187    NSSCKFWFindObjects *fwFindObjects,
1188    NSSCKMDSession *mdSession,
1189    NSSCKFWSession *fwSession,
1190    NSSCKMDToken *mdToken,
1191    NSSCKFWToken *fwToken,
1192    NSSCKMDInstance *mdInstance,
1193    NSSCKFWInstance *fwInstance
1194  );
1195
1196  /*
1197   * This routine is used to obtain another pointer to an
1198   * object matching the search criteria.  This routine is
1199   * required.  If no (more) objects match the search, it
1200   * should return NULL and set the error to CKR_OK.
1201   */
1202  NSSCKMDObject *(PR_CALLBACK *Next)(
1203    NSSCKMDFindObjects *mdFindObjects,
1204    NSSCKFWFindObjects *fwFindObjects,
1205    NSSCKMDSession *mdSession,
1206    NSSCKFWSession *fwSession,
1207    NSSCKMDToken *mdToken,
1208    NSSCKFWToken *fwToken,
1209    NSSCKMDInstance *mdInstance,
1210    NSSCKFWInstance *fwInstance,
1211    NSSArena *arena,
1212    CK_RV *pError
1213  );
1214
1215  /*
1216   * This object may be extended in future versions of the
1217   * NSS Cryptoki Framework.  To allow for some flexibility
1218   * in the area of binary compatibility, this field should
1219   * be NULL.
1220   */
1221  void *null;
1222};
1223
1224/*
1225 * NSSCKMDCryptoOperaion
1226 *
1227 * This is the basic handle for an encryption, decryption,
1228 * sign, verify, or hash opertion.
1229 * created by NSSCKMDMechanism->XXXXInit, and may be
1230 * obtained from the Framework's corresponding object.
1231 * It contains a pointer for use by the Module, to store
1232 * any intermediate data, and it contains the EPV for a
1233 * set of routines which the Module may implement for use
1234 * by the Framework.  Some of these routines are optional.
1235 */
1236
1237struct NSSCKMDCryptoOperationStr {
1238  /*
1239   * The Module may use this pointer for its own purposes.
1240   */
1241  void *etc;
1242
1243  /*
1244   * This routine is called by the Framework clean up the mdCryptoOperation
1245   * structure.
1246   * This routine is optional; if unimplemented, it will be ignored.
1247   */
1248  void (PR_CALLBACK *Destroy)(
1249    NSSCKMDCryptoOperation *mdCryptoOperation,
1250    NSSCKFWCryptoOperation *fwCryptoOperation,
1251    NSSCKMDInstance *mdInstance,
1252    NSSCKFWInstance *fwInstance
1253  );
1254
1255
1256  /*
1257   * how many bytes do we need to finish this buffer?
1258   * must be implemented if Final is implemented.
1259   */
1260  CK_ULONG (PR_CALLBACK *GetFinalLength)(
1261    NSSCKMDCryptoOperation *mdCryptoOperation,
1262    NSSCKFWCryptoOperation *fwCryptoOperation,
1263    NSSCKMDSession *mdSession,
1264    NSSCKFWSession *fwSession,
1265    NSSCKMDToken *mdToken,
1266    NSSCKFWToken *fwToken,
1267    NSSCKMDInstance *mdInstance,
1268    NSSCKFWInstance *fwInstance,
1269    CK_RV *pError
1270  );
1271
1272  /*
1273   * how many bytes do we need to complete the next operation.
1274   * used in both Update and UpdateFinal.
1275   */
1276  CK_ULONG (PR_CALLBACK *GetOperationLength)(
1277    NSSCKMDCryptoOperation *mdCryptoOperation,
1278    NSSCKFWCryptoOperation *fwCryptoOperation,
1279    NSSCKMDSession *mdSession,
1280    NSSCKFWSession *fwSession,
1281    NSSCKMDToken *mdToken,
1282    NSSCKFWToken *fwToken,
1283    NSSCKMDInstance *mdInstance,
1284    NSSCKFWInstance *fwInstance,
1285    const NSSItem   *inputBuffer,
1286    CK_RV *pError
1287  );
1288
1289  /*
1290   * This routine is called by the Framework to finish a
1291   * search operation.  Note that the Framework may finish
1292   * a search before it has completed.  This routine is
1293   * optional; if unimplemented, it merely won't be called.
1294   * The respective final call with fail with CKR_FUNCTION_FAILED
1295   * Final should not free the mdCryptoOperation.
1296   */
1297  CK_RV(PR_CALLBACK *Final)(
1298    NSSCKMDCryptoOperation *mdCryptoOperation,
1299    NSSCKFWCryptoOperation *fwCryptoOperation,
1300    NSSCKMDSession *mdSession,
1301    NSSCKFWSession *fwSession,
1302    NSSCKMDToken *mdToken,
1303    NSSCKFWToken *fwToken,
1304    NSSCKMDInstance *mdInstance,
1305    NSSCKFWInstance *fwInstance,
1306    NSSItem       *outputBuffer
1307  );
1308
1309
1310  /*
1311   * This routine is called by the Framework to complete the
1312   * next step in an encryption/decryption operation.
1313   * This routine is optional; if unimplemented, the respective
1314   * update call with fail with CKR_FUNCTION_FAILED.
1315   * Update should not be implemented for signing/verification/digest
1316   * mechanisms.
1317   */
1318  CK_RV(PR_CALLBACK *Update)(
1319    NSSCKMDCryptoOperation *mdCryptoOperation,
1320    NSSCKFWCryptoOperation *fwCryptoOperation,
1321    NSSCKMDSession *mdSession,
1322    NSSCKFWSession *fwSession,
1323    NSSCKMDToken *mdToken,
1324    NSSCKFWToken *fwToken,
1325    NSSCKMDInstance *mdInstance,
1326    NSSCKFWInstance *fwInstance,
1327    const NSSItem   *inputBuffer,
1328    NSSItem   *outputBuffer
1329  );
1330
1331  /*
1332   * This routine is called by the Framework to complete the
1333   * next step in a signing/verification/digest operation.
1334   * This routine is optional; if unimplemented, the respective
1335   * update call with fail with CKR_FUNCTION_FAILED
1336   * Update should not be implemented for encryption/decryption
1337   * mechanisms.
1338   */
1339  CK_RV(PR_CALLBACK *DigestUpdate)(
1340    NSSCKMDCryptoOperation *mdCryptoOperation,
1341    NSSCKFWCryptoOperation *fwCryptoOperation,
1342    NSSCKMDSession *mdSession,
1343    NSSCKFWSession *fwSession,
1344    NSSCKMDToken *mdToken,
1345    NSSCKFWToken *fwToken,
1346    NSSCKMDInstance *mdInstance,
1347    NSSCKFWInstance *fwInstance,
1348    const NSSItem   *inputBuffer
1349  );
1350
1351  /*
1352   * This routine is called by the Framework to complete a
1353   * single step operation. This routine is optional; if unimplemented, 
1354   * the framework will use the Update and Final functions to complete
1355   * the operation.
1356   */
1357  CK_RV(PR_CALLBACK *UpdateFinal)(
1358    NSSCKMDCryptoOperation *mdCryptoOperation,
1359    NSSCKFWCryptoOperation *fwCryptoOperation,
1360    NSSCKMDSession *mdSession,
1361    NSSCKFWSession *fwSession,
1362    NSSCKMDToken *mdToken,
1363    NSSCKFWToken *fwToken,
1364    NSSCKMDInstance *mdInstance,
1365    NSSCKFWInstance *fwInstance,
1366    const NSSItem   *inputBuffer,
1367    NSSItem   *outputBuffer
1368  );
1369
1370  /*
1371   * This routine is called by the Framework to complete next
1372   * step in a combined operation. The Decrypt/Encrypt mechanism
1373   * should define and drive the combo step.
1374   * This routine is optional; if unimplemented, 
1375   * the framework will use the appropriate Update functions to complete
1376   * the operation.
1377   */
1378  CK_RV(PR_CALLBACK *UpdateCombo)(
1379    NSSCKMDCryptoOperation *mdCryptoOperation,
1380    NSSCKFWCryptoOperation *fwCryptoOperation,
1381    NSSCKMDCryptoOperation *mdPeerCryptoOperation,
1382    NSSCKFWCryptoOperation *fwPeerCryptoOperation,
1383    NSSCKMDSession *mdSession,
1384    NSSCKFWSession *fwSession,
1385    NSSCKMDToken *mdToken,
1386    NSSCKFWToken *fwToken,
1387    NSSCKMDInstance *mdInstance,
1388    NSSCKFWInstance *fwInstance,
1389    const NSSItem   *inputBuffer,
1390    NSSItem   *outputBuffer
1391  );
1392
1393  /*
1394   * Hash a key directly into the digest
1395   */
1396  CK_RV(PR_CALLBACK *DigestKey)(
1397    NSSCKMDCryptoOperation *mdCryptoOperation,
1398    NSSCKFWCryptoOperation *fwCryptoOperation,
1399    NSSCKMDToken *mdToken,
1400    NSSCKFWToken *fwToken,
1401    NSSCKMDInstance *mdInstance,
1402    NSSCKFWInstance *fwInstance,
1403    NSSCKMDObject *mdKey,
1404    NSSCKFWObject *fwKey
1405  );
1406
1407  /*
1408   * This object may be extended in future versions of the
1409   * NSS Cryptoki Framework.  To allow for some flexibility
1410   * in the area of binary compatibility, this field should
1411   * be NULL.
1412   */
1413  void *null;
1414};
1415
1416/*
1417 * NSSCKMDMechanism
1418 *
1419 */
1420
1421struct NSSCKMDMechanismStr {
1422  /*
1423   * The Module may use this pointer for its own purposes.
1424   */
1425  void *etc;
1426
1427  /*
1428   * This also frees the fwMechanism if appropriate.
1429   * If it is not supplied, the Framework will assume that the Token
1430   * Manages a static list of mechanisms and the function will not be called.
1431   */
1432  void (PR_CALLBACK *Destroy)(
1433    NSSCKMDMechanism *mdMechanism,
1434    NSSCKFWMechanism *fwMechanism,
1435    NSSCKMDInstance *mdInstance,
1436    NSSCKFWInstance *fwInstance
1437  );
1438
1439
1440  /*
1441   * This routine returns the minimum key size allowed for
1442   * this mechanism.  This routine is optional; if unimplemented,
1443   * zero will be assumed.  This routine may return zero on
1444   * error; if the error is CKR_OK, zero will be accepted as
1445   * a valid response.
1446   */
1447  CK_ULONG (PR_CALLBACK *GetMinKeySize)(
1448    NSSCKMDMechanism *mdMechanism,
1449    NSSCKFWMechanism *fwMechanism,
1450    NSSCKMDToken *mdToken,
1451    NSSCKFWToken *fwToken,
1452    NSSCKMDInstance *mdInstance,
1453    NSSCKFWInstance *fwInstance,
1454    CK_RV *pError
1455  );
1456
1457  /*
1458   * This routine returns the maximum key size allowed for
1459   * this mechanism.  This routine is optional; if unimplemented,
1460   * zero will be assumed.  This routine may return zero on
1461   * error; if the error is CKR_OK, zero will be accepted as
1462   * a valid response.
1463   */
1464  CK_ULONG (PR_CALLBACK *GetMaxKeySize)(
1465    NSSCKMDMechanism *mdMechanism,
1466    NSSCKFWMechanism *fwMechanism,
1467    NSSCKMDToken *mdToken,
1468    NSSCKFWToken *fwToken,
1469    NSSCKMDInstance *mdInstance,
1470    NSSCKFWInstance *fwInstance,
1471    CK_RV *pError
1472  );
1473
1474  /*
1475   * This routine is called to determine if the mechanism is
1476   * implemented in hardware or software.  It returns CK_TRUE
1477   * if it is done in hardware.
1478   */
1479  CK_BBOOL (PR_CALLBACK *GetInHardware)(
1480    NSSCKMDMechanism *mdMechanism,
1481    NSSCKFWMechanism *fwMechanism,
1482    NSSCKMDToken *mdToken,
1483    NSSCKFWToken *fwToken,
1484    NSSCKMDInstance *mdInstance,
1485    NSSCKFWInstance *fwInstance,
1486    CK_RV *pError
1487  );
1488
1489  /*
1490   * The crypto routines themselves.  Most crypto operations may
1491   * be performed in two ways, streaming and single-part.  The
1492   * streaming operations involve the use of (typically) three
1493   * calls-- an Init method to set up the operation, an Update
1494   * method to feed data to the operation, and a Final method to
1495   * obtain the final result.  Single-part operations involve
1496   * one method, to perform the crypto operation all at once.
1497   *
1498   * The NSS Cryptoki Framework can implement the single-part
1499   * operations in terms of the streaming operations on behalf
1500   * of the Module.  There are a few variances.
1501   *
1502   * Only the Init Functions are defined by the mechanism. Each
1503   * init function will return a NSSCKFWCryptoOperation which
1504   * can supply update, final, the single part updateFinal, and
1505   * the combo updateCombo functions.
1506   * 
1507   * For simplicity, the routines are listed in summary here:
1508   *
1509   *  EncryptInit,
1510   *  DecryptInit,
1511   *  DigestInit,
1512   *  SignInit, 
1513   *  SignRecoverInit;
1514   *  VerifyInit,
1515   *  VerifyRecoverInit;
1516   *
1517   * The key-management routineā€¦

Large files files are truncated, but you can click here to view the full file