security/nss/lib/ckfw/nssckmdt.h

   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
  41 static 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
  63 typedef struct NSSCKMDInstanceStr NSSCKMDInstance;
  64 typedef struct NSSCKMDSlotStr NSSCKMDSlot;
  65 typedef struct NSSCKMDTokenStr NSSCKMDToken;
  66 typedef struct NSSCKMDSessionStr NSSCKMDSession;
  67 typedef struct NSSCKMDCryptoOperationStr NSSCKMDCryptoOperation;
  68 typedef struct NSSCKMDFindObjectsStr NSSCKMDFindObjects;
  69 typedef struct NSSCKMDMechanismStr NSSCKMDMechanism;
  70 typedef 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
  82 typedef 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
  99 struct 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
 258 struct 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
 432 struct 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
 885 struct 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
1173 struct 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
1237 struct 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
1421 struct 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 routines are
1518    *
1519    *  GenerateKey
1520    *  GenerateKeyPair
1521    *  WrapKey
1522    *  UnwrapKey
1523    *  DeriveKey
1524    *
1525    * All of these routines based on the Cryptoki API;
1526    * see PKCS#11 for further information.
1527    */
1528
1529   /*
1530    */
1531   NSSCKMDCryptoOperation * (PR_CALLBACK *EncryptInit)(
1532     NSSCKMDMechanism *mdMechanism,
1533     NSSCKFWMechanism *fwMechanism,
1534     CK_MECHANISM_PTR  pMechanism,
1535     NSSCKMDSession *mdSession,
1536     NSSCKFWSession *fwSession,
1537     NSSCKMDToken *mdToken,
1538     NSSCKFWToken *fwToken,
1539     NSSCKMDInstance *mdInstance,
1540     NSSCKFWInstance *fwInstance,
1541     NSSCKMDObject *mdKey,
1542     NSSCKFWObject *fwKey,
1543     CK_RV *pError
1544   );
1545
1546   /*
1547    */
1548   NSSCKMDCryptoOperation * (PR_CALLBACK *DecryptInit)(
1549     NSSCKMDMechanism *mdMechanism,
1550     NSSCKFWMechanism *fwMechanism,
1551     CK_MECHANISM_PTR  pMechanism,
1552     NSSCKMDSession *mdSession,
1553     NSSCKFWSession *fwSession,
1554     NSSCKMDToken *mdToken,
1555     NSSCKFWToken *fwToken,
1556     NSSCKMDInstance *mdInstance,
1557     NSSCKFWInstance *fwInstance,
1558     NSSCKMDObject *mdKey,
1559     NSSCKFWObject *fwKey,
1560     CK_RV *pError
1561   );
1562
1563   /*
1564    */
1565   NSSCKMDCryptoOperation * (PR_CALLBACK *DigestInit)(
1566     NSSCKMDMechanism *mdMechanism,
1567     NSSCKFWMechanism *fwMechanism,
1568     CK_MECHANISM_PTR  pMechanism,
1569     NSSCKMDSession *mdSession,
1570     NSSCKFWSession *fwSession,
1571     NSSCKMDToken *mdToken,
1572     NSSCKFWToken *fwToken,
1573     NSSCKMDInstance *mdInstance,
1574     NSSCKFWInstance *fwInstance,
1575     CK_RV *pError
1576   );
1577
1578
1579   /*
1580    */
1581   NSSCKMDCryptoOperation * (PR_CALLBACK *SignInit)(
1582     NSSCKMDMechanism *mdMechanism,
1583     NSSCKFWMechanism *fwMechanism,
1584     CK_MECHANISM_PTR  pMechanism,
1585     NSSCKMDSession *mdSession,
1586     NSSCKFWSession *fwSession,
1587     NSSCKMDToken *mdToken,
1588     NSSCKFWToken *fwToken,
1589     NSSCKMDInstance *mdInstance,
1590     NSSCKFWInstance *fwInstance,
1591     NSSCKMDObject *mdKey,
1592     NSSCKFWObject *fwKey,
1593     CK_RV *pError
1594   );
1595
1596   /*
1597    */
1598   NSSCKMDCryptoOperation * (PR_CALLBACK *VerifyInit)(
1599     NSSCKMDMechanism *mdMechanism,
1600     NSSCKFWMechanism *fwMechanism,
1601     CK_MECHANISM_PTR  pMechanism,
1602     NSSCKMDSession *mdSession,
1603     NSSCKFWSession *fwSession,
1604     NSSCKMDToken *mdToken,
1605     NSSCKFWToken *fwToken,
1606     NSSCKMDInstance *mdInstance,
1607     NSSCKFWInstance *fwInstance,
1608     NSSCKMDObject *mdKey,
1609     NSSCKFWObject *fwKey,
1610     CK_RV *pError
1611   );
1612
1613   /*
1614    */
1615   NSSCKMDCryptoOperation * (PR_CALLBACK *SignRecoverInit)(
1616     NSSCKMDMechanism *mdMechanism,
1617     NSSCKFWMechanism *fwMechanism,
1618     CK_MECHANISM_PTR  pMechanism,
1619     NSSCKMDSession *mdSession,
1620     NSSCKFWSession *fwSession,
1621     NSSCKMDToken *mdToken,
1622     NSSCKFWToken *fwToken,
1623     NSSCKMDInstance *mdInstance,
1624     NSSCKFWInstance *fwInstance,
1625     NSSCKMDObject *mdKey,
1626     NSSCKFWObject *fwKey,
1627     CK_RV *pError
1628   );
1629
1630   /*
1631    */
1632   NSSCKMDCryptoOperation * (PR_CALLBACK *VerifyRecoverInit)(
1633     NSSCKMDMechanism *mdMechanism,
1634     NSSCKFWMechanism *fwMechanism,
1635     CK_MECHANISM_PTR  pMechanism,
1636     NSSCKMDSession *mdSession,
1637     NSSCKFWSession *fwSession,
1638     NSSCKMDToken *mdToken,
1639     NSSCKFWToken *fwToken,
1640     NSSCKMDInstance *mdInstance,
1641     NSSCKFWInstance *fwInstance,
1642     NSSCKMDObject *mdKey,
1643     NSSCKFWObject *fwKey,
1644     CK_RV *pError
1645   );
1646
1647   /*
1648    * Key management operations.
1649    */
1650
1651   /*
1652    * This routine generates a key.  This routine may return NULL
1653    * upon error.
1654    */
1655   NSSCKMDObject *(PR_CALLBACK *GenerateKey)(
1656     NSSCKMDMechanism *mdMechanism,
1657     NSSCKFWMechanism *fwMechanism,
1658     CK_MECHANISM_PTR  pMechanism,
1659     NSSCKMDSession *mdSession,
1660     NSSCKFWSession *fwSession,
1661     NSSCKMDToken *mdToken,
1662     NSSCKFWToken *fwToken,
1663     NSSCKMDInstance *mdInstance,
1664     NSSCKFWInstance *fwInstance,
1665     CK_ATTRIBUTE_PTR pTemplate,
1666     CK_ULONG ulAttributeCount,
1667     CK_RV *pError
1668   );
1669
1670   /*
1671    * This routine generates a key pair.
1672    */
1673   CK_RV (PR_CALLBACK *GenerateKeyPair)(
1674     NSSCKMDMechanism *mdMechanism,
1675     NSSCKFWMechanism *fwMechanism,
1676     CK_MECHANISM_PTR  pMechanism,
1677     NSSCKMDSession *mdSession,
1678     NSSCKFWSession *fwSession,
1679     NSSCKMDToken *mdToken,
1680     NSSCKFWToken *fwToken,
1681     NSSCKMDInstance *mdInstance,
1682     NSSCKFWInstance *fwInstance,
1683     CK_ATTRIBUTE_PTR pPublicKeyTemplate,
1684     CK_ULONG ulPublicKeyAttributeCount,
1685     CK_ATTRIBUTE_PTR pPrivateKeyTemplate,
1686     CK_ULONG ulPrivateKeyAttributeCount,
1687     NSSCKMDObject **pPublicKey,
1688     NSSCKMDObject **pPrivateKey
1689   );
1690
1691   /*
1692    * This routine wraps a key.
1693    */
1694   CK_ULONG (PR_CALLBACK *GetWrapKeyLength)(
1695     NSSCKMDMechanism *mdMechanism,
1696     NSSCKFWMechanism *fwMechanism,
1697     CK_MECHANISM_PTR  pMechanism,
1698     NSSCKMDSession *mdSession,
1699     NSSCKFWSession *fwSession,
1700     NSSCKMDToken *mdToken,
1701     NSSCKFWToken *fwToken,
1702     NSSCKMDInstance *mdInstance,
1703     NSSCKFWInstance *fwInstance,
1704     NSSCKMDObject *mdWrappingKey,
1705     NSSCKFWObject *fwWrappingKey,
1706     NSSCKMDObject *mdWrappedKey,
1707     NSSCKFWObject *fwWrappedKey,
1708     CK_RV *pError
1709   );
1710
1711   /*
1712    * This routine wraps a key.
1713    */
1714   CK_RV (PR_CALLBACK *WrapKey)(
1715     NSSCKMDMechanism *mdMechanism,
1716     NSSCKFWMechanism *fwMechanism,
1717     CK_MECHANISM_PTR  pMechanism,
1718     NSSCKMDSession *mdSession,
1719     NSSCKFWSession *fwSession,
1720     NSSCKMDToken *mdToken,
1721     NSSCKFWToken *fwToken,
1722     NSSCKMDInstance *mdInstance,
1723     NSSCKFWInstance *fwInstance,
1724     NSSCKMDObject *mdWrappingKey,
1725     NSSCKFWObject *fwWrappingKey,
1726     NSSCKMDObject *mdKeyObject,
1727     NSSCKFWObject *fwKeyObject,
1728     NSSItem *wrappedKey
1729   );
1730
1731   /*
1732    * This routine unwraps a key.  This routine may return NULL
1733    * upon error.
1734    */
1735   NSSCKMDObject *(PR_CALLBACK *UnwrapKey)(
1736     NSSCKMDMechanism *mdMechanism,
1737     NSSCKFWMechanism *fwMechanism,
1738     CK_MECHANISM_PTR  pMechanism,
1739     NSSCKMDSession *mdSession,
1740     NSSCKFWSession *fwSession,
1741     NSSCKMDToken *mdToken,
1742     NSSCKFWToken *fwToken,
1743     NSSCKMDInstance *mdInstance,
1744     NSSCKFWInstance *fwInstance,
1745     NSSCKMDObject *mdWrappingKey,
1746     NSSCKFWObject *fwWrappingKey,
1747     NSSItem *wrappedKey,
1748     CK_ATTRIBUTE_PTR pTemplate,
1749     CK_ULONG ulAttributeCount,
1750     CK_RV *pError
1751   );
1752
1753   /*
1754    * This routine derives a key.  This routine may return NULL
1755    * upon error.
1756    */
1757   NSSCKMDObject *(PR_CALLBACK *DeriveKey)(
1758     NSSCKMDMechanism *mdMechanism,
1759     NSSCKFWMechanism *fwMechanism,
1760     CK_MECHANISM_PTR  pMechanism,
1761     NSSCKMDSession *mdSession,
1762     NSSCKFWSession *fwSession,
1763     NSSCKMDToken *mdToken,
1764     NSSCKFWToken *fwToken,
1765     NSSCKMDInstance *mdInstance,
1766     NSSCKFWInstance *fwInstance,
1767     NSSCKMDObject *mdBaseKey,
1768     NSSCKFWObject *fwBaseKey,
1769     CK_ATTRIBUTE_PTR pTemplate,
1770     CK_ULONG ulAttributeCount,
1771     CK_RV *pError
1772   );
1773
1774   /*
1775    * This object may be extended in future versions of the
1776    * NSS Cryptoki Framework.  To allow for some flexibility
1777    * in the area of binary compatibility, this field should
1778    * be NULL.
1779    */
1780   void *null;
1781 };
1782
1783 /*
1784  * NSSCKMDObject
1785  *
1786  * This is the basic handle for any object used by a PKCS#11 Module.
1787  * Modules must implement it if they support their own objects, and
1788  * the Framework supports it for Modules that do not handle session
1789  * objects.  This type contains a pointer for use by the implementor,
1790  * to store any object-specific data, and it contains an EPV for a
1791  * set of routines used to access the object.
1792  */
1793
1794 struct NSSCKMDObjectStr {
1795   /*
1796    * The implementation my use this pointer for its own purposes.
1797    */
1798   void *etc;
1799
1800   /*
1801    * This routine is called by the Framework when it is letting
1802    * go of an object handle.  It can be used by the Module to
1803    * free any resources tied up by an object "in use."  It is
1804    * optional.
1805    */
1806   void (PR_CALLBACK *Finalize)(
1807     NSSCKMDObject *mdObject,
1808     NSSCKFWObject *fwObject,
1809     NSSCKMDSession *mdSession,
1810     NSSCKFWSession *fwSession,
1811     NSSCKMDToken *mdToken,
1812     NSSCKFWToken *fwToken,
1813     NSSCKMDInstance *mdInstance,
1814     NSSCKFWInstance *fwInstance
1815   );
1816
1817   /*
1818    * This routine is used to completely destroy an object.
1819    * It is optional.  The parameter fwObject might be NULL
1820    * if the framework runs out of memory at the wrong moment.
1821    */
1822   CK_RV (PR_CALLBACK *Destroy)(
1823     NSSCKMDObject *mdObject,
1824     NSSCKFWObject *fwObject,
1825     NSSCKMDSession *mdSession,
1826     NSSCKFWSession *fwSession,
1827     NSSCKMDToken *mdToken,
1828     NSSCKFWToken *fwToken,
1829     NSSCKMDInstance *mdInstance,
1830     NSSCKFWInstance *fwInstance
1831   );
1832
1833   /*
1834    * This helper routine is used by the Framework, and is especially
1835    * useful when it is managing session objects on behalf of the
1836    * Module.  This routine is optional; if unimplemented, the
1837    * Framework will actually look up the CKA_TOKEN attribute.  In the
1838    * event of an error, just make something up-- the Framework will
1839    * find out soon enough anyway.
1840    */
1841   CK_BBOOL (PR_CALLBACK *IsTokenObject)(
1842     NSSCKMDObject *mdObject,
1843     NSSCKFWObject *fwObject,
1844     NSSCKMDSession *mdSession,
1845     NSSCKFWSession *fwSession,
1846     NSSCKMDToken *mdToken,
1847     NSSCKFWToken *fwToken,
1848     NSSCKMDInstance *mdInstance,
1849     NSSCKFWInstance *fwInstance
1850   );
1851
1852   /*
1853    * This routine returns the number of attributes of which this
1854    * object consists.  It is mandatory.  It can return zero on
1855    * error.
1856    */
1857   CK_ULONG (PR_CALLBACK *GetAttributeCount)(
1858     NSSCKMDObject *mdObject,
1859     NSSCKFWObject *fwObject,
1860     NSSCKMDSession *mdSession,
1861     NSSCKFWSession *fwSession,
1862     NSSCKMDToken *mdToken,
1863     NSSCKFWToken *fwToken,
1864     NSSCKMDInstance *mdInstance,
1865     NSSCKFWInstance *fwInstance,
1866     CK_RV *pError
1867   );
1868
1869   /*
1870    * This routine stuffs the attribute types into the provided array.
1871    * The array size (as obtained from GetAttributeCount) is passed in
1872    * as a check; return CKR_BUFFER_TOO_SMALL if the count is wrong
1873    * (either too big or too small).
1874    */
1875   CK_RV (PR_CALLBACK *GetAttributeTypes)(
1876     NSSCKMDObject *mdObject,
1877     NSSCKFWObject *fwObject,
1878     NSSCKMDSession *mdSession,
1879     NSSCKFWSession *fwSession,
1880     NSSCKMDToken *mdToken,
1881     NSSCKFWToken *fwToken,
1882     NSSCKMDInstance *mdInstance,
1883     NSSCKFWInstance *fwInstance,
1884     CK_ATTRIBUTE_TYPE_PTR typeArray,
1885     CK_ULONG ulCount
1886   );
1887
1888   /*
1889    * This routine returns the size (in bytes) of the specified
1890    * attribute.  It can return zero on error.
1891    */
1892   CK_ULONG (PR_CALLBACK *GetAttributeSize)(
1893     NSSCKMDObject *mdObject,
1894     NSSCKFWObject *fwObject,
1895     NSSCKMDSession *mdSession,
1896     NSSCKFWSession *fwSession,
1897     NSSCKMDToken *mdToken,
1898     NSSCKFWToken *fwToken,
1899     NSSCKMDInstance *mdInstance,
1900     NSSCKFWInstance *fwInstance,
1901     CK_ATTRIBUTE_TYPE attribute,
1902     CK_RV *pError
1903   );
1904
1905   /*
1906    * This routine returns an NSSCKFWItem structure.
1907    * The item pointer points to an NSSItem containing the attribute value.
1908    * The needsFreeing bit tells the framework whether to call the
1909    * FreeAttribute function . Upon error, an NSSCKFWItem structure
1910    * with a NULL NSSItem item pointer will be returned
1911    */
1912   NSSCKFWItem (PR_CALLBACK *GetAttribute)(
1913     NSSCKMDObject *mdObject,
1914     NSSCKFWObject *fwObject,
1915     NSSCKMDSession *mdSession,
1916     NSSCKFWSession *fwSession,
1917     NSSCKMDToken *mdToken,
1918     NSSCKFWToken *fwToken,
1919     NSSCKMDInstance *mdInstance,
1920     NSSCKFWInstance *fwInstance,
1921     CK_ATTRIBUTE_TYPE attribute,
1922     CK_RV *pError
1923   );
1924
1925   /*
1926    * This routine returns CKR_OK if the attribute could be freed.
1927    */
1928   CK_RV (PR_CALLBACK *FreeAttribute)(
1929     NSSCKFWItem * item
1930   );
1931
1932   /*
1933    * This routine changes the specified attribute.  If unimplemented,
1934    * the object will be considered read-only.
1935    */
1936   CK_RV (PR_CALLBACK *SetAttribute)(
1937     NSSCKMDObject *mdObject,
1938     NSSCKFWObject *fwObject,
1939     NSSCKMDSession *mdSession,
1940     NSSCKFWSession *fwSession,
1941     NSSCKMDToken *mdToken,
1942     NSSCKFWToken *fwToken,
1943     NSSCKMDInstance *mdInstance,
1944     NSSCKFWInstance *fwInstance,
1945     CK_ATTRIBUTE_TYPE attribute,
1946     NSSItem *value
1947   );
1948
1949   /*
1950    * This routine returns the storage requirements of this object,
1951    * in bytes.  Cryptoki doesn't strictly define the definition,
1952    * but it should relate to the values returned by the "Get Memory"
1953    * routines of the NSSCKMDToken.  This routine is optional; if
1954    * unimplemented, the Framework will consider this information
1955    * sensitive.  This routine may return zero on error.  If the
1956    * specified error is CKR_OK, zero will be accepted as a valid
1957    * response.
1958    */
1959   CK_ULONG (PR_CALLBACK *GetObjectSize)(
1960     NSSCKMDObject *mdObject,
1961     NSSCKFWObject *fwObject,
1962     NSSCKMDSession *mdSession,
1963     NSSCKFWSession *fwSession,
1964     NSSCKMDToken *mdToken,
1965     NSSCKFWToken *fwToken,
1966     NSSCKMDInstance *mdInstance,
1967     NSSCKFWInstance *fwInstance,
1968     CK_RV *pError
1969   );
1970
1971   /*
1972    * This object may be extended in future versions of the
1973    * NSS Cryptoki Framework.  To allow for some flexibility
1974    * in the area of binary compatibility, this field should
1975    * be NULL.
1976    */
1977   void *null;
1978 };
1979
1980
1981 #endif /* NSSCKMDT_H */