Back to index

lightning-sunbird  0.9+nobinonly
nssckmdt.h
Go to the documentation of this file.
00001 /* ***** BEGIN LICENSE BLOCK *****
00002  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
00003  *
00004  * The contents of this file are subject to the Mozilla Public License Version
00005  * 1.1 (the "License"); you may not use this file except in compliance with
00006  * the License. You may obtain a copy of the License at
00007  * http://www.mozilla.org/MPL/
00008  *
00009  * Software distributed under the License is distributed on an "AS IS" basis,
00010  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
00011  * for the specific language governing rights and limitations under the
00012  * License.
00013  *
00014  * The Original Code is the Netscape security libraries.
00015  *
00016  * The Initial Developer of the Original Code is
00017  * Netscape Communications Corporation.
00018  * Portions created by the Initial Developer are Copyright (C) 1994-2000
00019  * the Initial Developer. All Rights Reserved.
00020  *
00021  * Contributor(s):
00022  *
00023  * Alternatively, the contents of this file may be used under the terms of
00024  * either the GNU General Public License Version 2 or later (the "GPL"), or
00025  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
00026  * in which case the provisions of the GPL or the LGPL are applicable instead
00027  * of those above. If you wish to allow use of your version of this file only
00028  * under the terms of either the GPL or the LGPL, and not to allow others to
00029  * use your version of this file under the terms of the MPL, indicate your
00030  * decision by deleting the provisions above and replace them with the notice
00031  * and other provisions required by the GPL or the LGPL. If you do not delete
00032  * the provisions above, a recipient may use your version of this file under
00033  * the terms of any one of the MPL, the GPL or the LGPL.
00034  *
00035  * ***** END LICENSE BLOCK ***** */
00036 
00037 #ifndef NSSCKMDT_H
00038 #define NSSCKMDT_H
00039 
00040 #ifdef DEBUG
00041 static const char NSSCKMDT_CVS_ID[] = "@(#) $RCSfile: nssckmdt.h,v $ $Revision: 1.5 $ $Date: 2005/01/20 02:25:45 $";
00042 #endif /* DEBUG */
00043 
00044 /*
00045  * nssckmdt.h
00046  *
00047  * This file specifies the basic types that must be implemented by
00048  * any Module using the NSS Cryptoki Framework.
00049  */
00050 
00051 #ifndef NSSBASET_H
00052 #include "nssbaset.h"
00053 #endif /* NSSBASET_H */
00054 
00055 #ifndef NSSCKT_H
00056 #include "nssckt.h"
00057 #endif /* NSSCKT_H */
00058 
00059 #ifndef NSSCKFWT_H
00060 #include "nssckfwt.h"
00061 #endif /* NSSCKFWT_H */
00062 
00063 typedef struct NSSCKMDInstanceStr NSSCKMDInstance;
00064 typedef struct NSSCKMDSlotStr NSSCKMDSlot;
00065 typedef struct NSSCKMDTokenStr NSSCKMDToken;
00066 typedef struct NSSCKMDSessionStr NSSCKMDSession;
00067 typedef struct NSSCKMDFindObjectsStr NSSCKMDFindObjects;
00068 typedef struct NSSCKMDMechanismStr NSSCKMDMechanism;
00069 typedef struct NSSCKMDObjectStr NSSCKMDObject;
00070 
00071 /*
00072  * NSSCKFWItem
00073  *
00074  * This is a structure used by modules to return object attributes.
00075  * The needsFreeing bit indicates whether the object needs to be freed.
00076  * If so, the framework will call the FreeAttribute function on the item
00077  * after it is done using it.
00078  *
00079  */
00080 
00081 typedef struct {
00082   PRBool needsFreeing;
00083   NSSItem* item;
00084 } NSSCKFWItem ;
00085 
00086 /*
00087  * NSSCKMDInstance
00088  *
00089  * This is the basic handle for an instance of a PKCS#11 Module.
00090  * It is returned by the Module's CreateInstance routine, and
00091  * may be obtained from the corresponding NSSCKFWInstance object.
00092  * It contains a pointer for use by the Module, to store any
00093  * instance-related data, and it contains the EPV for a set of
00094  * routines which the Module may implement for use by the Framework.
00095  * Some of these routines are optional; others are mandatory.
00096  */
00097 
00098 struct NSSCKMDInstanceStr {
00099   /*
00100    * The Module may use this pointer for its own purposes.
00101    */
00102   void *etc;
00103 
00104   /*
00105    * This routine is called by the Framework to initialize
00106    * the Module.  This routine is optional; if unimplemented,
00107    * it won't be called.  If this routine returns an error,
00108    * then the initialization will fail.
00109    */
00110   CK_RV (PR_CALLBACK *Initialize)(
00111     NSSCKMDInstance *mdInstance,                                    
00112     NSSCKFWInstance *fwInstance,
00113     NSSUTF8 *configurationData
00114   );
00115 
00116   /*
00117    * This routine is called when the Framework is finalizing
00118    * the PKCS#11 Module.  It is the last thing called before
00119    * the NSSCKFWInstance's NSSArena is destroyed.  This routine
00120    * is optional; if unimplemented, it merely won't be called.
00121    */
00122   void (PR_CALLBACK *Finalize)(
00123     NSSCKMDInstance *mdInstance,                                    
00124     NSSCKFWInstance *fwInstance
00125   );
00126 
00127   /*
00128    * This routine gets the number of slots.  This value must
00129    * never change, once the instance is initialized.  This 
00130    * routine must be implemented.  It may return zero on error.
00131    */
00132   CK_ULONG (PR_CALLBACK *GetNSlots)(
00133     NSSCKMDInstance *mdInstance,                                    
00134     NSSCKFWInstance *fwInstance,
00135     CK_RV *pError
00136   );
00137 
00138   /*
00139    * This routine returns the version of the Cryptoki standard
00140    * to which this Module conforms.  This routine is optional;
00141    * if unimplemented, the Framework uses the version to which
00142    * ~it~ was implemented.
00143    */
00144   CK_VERSION (PR_CALLBACK *GetCryptokiVersion)(
00145     NSSCKMDInstance *mdInstance,                                    
00146     NSSCKFWInstance *fwInstance
00147   );
00148 
00149   /*
00150    * This routine returns a pointer to a UTF8-encoded string
00151    * containing the manufacturer ID for this Module.  Only
00152    * the characters completely encoded in the first thirty-
00153    * two bytes are significant.  This routine is optional.
00154    * The string returned is never freed; if dynamically generated,
00155    * the space for it should be allocated from the NSSArena
00156    * that may be obtained from the NSSCKFWInstance.  This
00157    * routine may return NULL upon error; however if *pError
00158    * is CKR_OK, the NULL will be considered the valid response.
00159    */
00160   NSSUTF8 *(PR_CALLBACK *GetManufacturerID)(
00161     NSSCKMDInstance *mdInstance,                                    
00162     NSSCKFWInstance *fwInstance,
00163     CK_RV *pError
00164   );
00165 
00166   /*
00167    * This routine returns a pointer to a UTF8-encoded string
00168    * containing a description of this Module library.  Only
00169    * the characters completely encoded in the first thirty-
00170    * two bytes are significant.  This routine is optional.
00171    * The string returned is never freed; if dynamically generated,
00172    * the space for it should be allocated from the NSSArena
00173    * that may be obtained from the NSSCKFWInstance.  This
00174    * routine may return NULL upon error; however if *pError
00175    * is CKR_OK, the NULL will be considered the valid response.
00176    */
00177   NSSUTF8 *(PR_CALLBACK *GetLibraryDescription)(
00178     NSSCKMDInstance *mdInstance,                                    
00179     NSSCKFWInstance *fwInstance,
00180     CK_RV *pError
00181   );
00182 
00183   /*
00184    * This routine returns the version of this Module library.
00185    * This routine is optional; if unimplemented, the Framework
00186    * will assume a Module library version of 0.1.
00187    */
00188   CK_VERSION (PR_CALLBACK *GetLibraryVersion)(
00189     NSSCKMDInstance *mdInstance,                                    
00190     NSSCKFWInstance *fwInstance
00191   );
00192 
00193   /*
00194    * This routine returns CK_TRUE if the Module wishes to
00195    * handle session objects.  This routine is optional.
00196    * If this routine is NULL, or if it exists but returns
00197    * CK_FALSE, the Framework will assume responsibility
00198    * for managing session objects.
00199    */
00200   CK_BBOOL (PR_CALLBACK *ModuleHandlesSessionObjects)(
00201     NSSCKMDInstance *mdInstance,                                    
00202     NSSCKFWInstance *fwInstance
00203   );
00204 
00205   /*
00206    * This routine stuffs pointers to NSSCKMDSlot objects into
00207    * the specified array; one for each slot supported by this
00208    * instance.  The Framework will determine the size needed
00209    * for the array by calling GetNSlots.  This routine is
00210    * required.
00211    */
00212   CK_RV (PR_CALLBACK *GetSlots)(
00213     NSSCKMDInstance *mdInstance,                                    
00214     NSSCKFWInstance *fwInstance,
00215     NSSCKMDSlot *slots[]
00216   );
00217 
00218   /*
00219    * This call returns a pointer to the slot in which an event
00220    * has occurred.  If the block argument is CK_TRUE, the call 
00221    * should block until a slot event occurs; if CK_FALSE, it 
00222    * should check to see if an event has occurred, occurred, 
00223    * but return NULL (and set *pError to CK_NO_EVENT) if one 
00224    * hasn't.  This routine is optional; if unimplemented, the
00225    * Framework will assume that no event has happened.  This
00226    * routine may return NULL upon error.
00227    */
00228   NSSCKMDSlot *(PR_CALLBACK *WaitForSlotEvent)(
00229     NSSCKMDInstance *mdInstance,                                    
00230     NSSCKFWInstance *fwInstance,
00231     CK_BBOOL block,
00232     CK_RV *pError
00233   );
00234 
00235   /*
00236    * This object may be extended in future versions of the
00237    * NSS Cryptoki Framework.  To allow for some flexibility
00238    * in the area of binary compatibility, this field should
00239    * be NULL.
00240    */
00241   void *null;
00242 };
00243 
00244 
00245 /*
00246  * NSSCKMDSlot
00247  *
00248  * This is the basic handle for a PKCS#11 Module Slot.  It is
00249  * created by the NSSCKMDInstance->GetSlots call, and may be
00250  * obtained from the Framework's corresponding NSSCKFWSlot
00251  * object.  It contains a pointer for use by the Module, to
00252  * store any slot-related data, and it contains the EPV for
00253  * a set of routines which the Module may implement for use
00254  * by the Framework.  Some of these routines are optional.
00255  */
00256 
00257 struct NSSCKMDSlotStr {
00258   /*
00259    * The Module may use this pointer for its own purposes.
00260    */
00261   void *etc;
00262 
00263   /*
00264    * This routine is called during the Framework initialization
00265    * step, after the Framework Instance has obtained the list
00266    * of slots (by calling NSSCKMDInstance->GetSlots).  Any slot-
00267    * specific initialization can be done here.  This routine is
00268    * optional; if unimplemented, it won't be called.  Note that
00269    * if this routine returns an error, the entire Framework
00270    * initialization for this Module will fail.
00271    */
00272   CK_RV (PR_CALLBACK *Initialize)(
00273     NSSCKMDSlot *mdSlot,
00274     NSSCKFWSlot *fwSlot,
00275     NSSCKMDInstance *mdInstance,                                    
00276     NSSCKFWInstance *fwInstance
00277   );
00278 
00279   /*
00280    * This routine is called when the Framework is finalizing
00281    * the PKCS#11 Module.  This call (for each of the slots)
00282    * is the last thing called before NSSCKMDInstance->Finalize.
00283    * This routine is optional; if unimplemented, it merely 
00284    * won't be called.  Note: In the rare circumstance that
00285    * the Framework initialization cannot complete (due to,
00286    * for example, memory limitations), this can be called with
00287    * a NULL value for fwSlot.
00288    */
00289   void (PR_CALLBACK *Destroy)(
00290     NSSCKMDSlot *mdSlot,
00291     NSSCKFWSlot *fwSlot,
00292     NSSCKMDInstance *mdInstance,                                    
00293     NSSCKFWInstance *fwInstance
00294   );
00295 
00296   /*
00297    * This routine returns a pointer to a UTF8-encoded string
00298    * containing a description of this slot.  Only the characters
00299    * completely encoded in the first sixty-four bytes are
00300    * significant.  This routine is optional.  The string 
00301    * returned is never freed; if dynamically generated,
00302    * the space for it should be allocated from the NSSArena
00303    * that may be obtained from the NSSCKFWInstance.  This
00304    * routine may return NULL upon error; however if *pError
00305    * is CKR_OK, the NULL will be considered the valid response.
00306    */
00307   NSSUTF8 *(PR_CALLBACK *GetSlotDescription)(
00308     NSSCKMDSlot *mdSlot,
00309     NSSCKFWSlot *fwSlot,
00310     NSSCKMDInstance *mdInstance,                                    
00311     NSSCKFWInstance *fwInstance,
00312     CK_RV *pError
00313   );
00314 
00315   /*
00316    * This routine returns a pointer to a UTF8-encoded string
00317    * containing a description of the manufacturer of this slot.
00318    * Only the characters completely encoded in the first thirty-
00319    * two bytes are significant.  This routine is optional.  
00320    * The string  returned is never freed; if dynamically generated,
00321    * the space for it should be allocated from the NSSArena
00322    * that may be obtained from the NSSCKFWInstance.  This
00323    * routine may return NULL upon error; however if *pError
00324    * is CKR_OK, the NULL will be considered the valid response.
00325    */
00326   NSSUTF8 *(PR_CALLBACK *GetManufacturerID)(
00327     NSSCKMDSlot *mdSlot,
00328     NSSCKFWSlot *fwSlot,
00329     NSSCKMDInstance *mdInstance,                                    
00330     NSSCKFWInstance *fwInstance,
00331     CK_RV *pError
00332   );
00333 
00334   /*
00335    * This routine returns CK_TRUE if a token is present in this
00336    * slot.  This routine is optional; if unimplemented, CK_TRUE
00337    * is assumed.
00338    */
00339   CK_BBOOL (PR_CALLBACK *GetTokenPresent)(
00340     NSSCKMDSlot *mdSlot,
00341     NSSCKFWSlot *fwSlot,
00342     NSSCKMDInstance *mdInstance,                                    
00343     NSSCKFWInstance *fwInstance
00344   );
00345 
00346   /*
00347    * This routine returns CK_TRUE if the slot supports removable
00348    * tokens.  This routine is optional; if unimplemented, CK_FALSE
00349    * is assumed.
00350    */
00351   CK_BBOOL (PR_CALLBACK *GetRemovableDevice)(
00352     NSSCKMDSlot *mdSlot,
00353     NSSCKFWSlot *fwSlot,
00354     NSSCKMDInstance *mdInstance,                                    
00355     NSSCKFWInstance *fwInstance
00356   );
00357 
00358   /*
00359    * This routine returns CK_TRUE if this slot is a hardware
00360    * device, or CK_FALSE if this slot is a software device.  This
00361    * routine is optional; if unimplemented, CK_FALSE is assumed.
00362    */
00363   CK_BBOOL (PR_CALLBACK *GetHardwareSlot)(
00364     NSSCKMDSlot *mdSlot,
00365     NSSCKFWSlot *fwSlot,
00366     NSSCKMDInstance *mdInstance,                                    
00367     NSSCKFWInstance *fwInstance
00368   );
00369 
00370   /*
00371    * This routine returns the version of this slot's hardware.
00372    * This routine is optional; if unimplemented, the Framework
00373    * will assume a hardware version of 0.1.
00374    */
00375   CK_VERSION (PR_CALLBACK *GetHardwareVersion)(
00376     NSSCKMDSlot *mdSlot,
00377     NSSCKFWSlot *fwSlot,
00378     NSSCKMDInstance *mdInstance,                                    
00379     NSSCKFWInstance *fwInstance
00380   );
00381 
00382   /*
00383    * This routine returns the version of this slot's firmware.
00384    * This routine is optional; if unimplemented, the Framework
00385    * will assume a hardware version of 0.1.
00386    */
00387   CK_VERSION (PR_CALLBACK *GetFirmwareVersion)(
00388     NSSCKMDSlot *mdSlot,
00389     NSSCKFWSlot *fwSlot,
00390     NSSCKMDInstance *mdInstance,                                    
00391     NSSCKFWInstance *fwInstance
00392   );
00393 
00394   /*
00395    * This routine should return a pointer to an NSSCKMDToken
00396    * object corresponding to the token in the specified slot.
00397    * The NSSCKFWToken object passed in has an NSSArena
00398    * available which is dedicated for this token.  This routine
00399    * must be implemented.  This routine may return NULL upon
00400    * error.
00401    */
00402   NSSCKMDToken *(PR_CALLBACK *GetToken)(
00403     NSSCKMDSlot *mdSlot,
00404     NSSCKFWSlot *fwSlot,
00405     NSSCKMDInstance *mdInstance,                                    
00406     NSSCKFWInstance *fwInstance,
00407     CK_RV *pError
00408   );
00409 
00410   /*
00411    * This object may be extended in future versions of the
00412    * NSS Cryptoki Framework.  To allow for some flexibility
00413    * in the area of binary compatibility, this field should
00414    * be NULL.
00415    */
00416   void *null;
00417 };
00418 
00419 /*
00420  * NSSCKMDToken
00421  *
00422  * This is the basic handle for a PKCS#11 Token.  It is created by
00423  * the NSSCKMDSlot->GetToken call, and may be obtained from the
00424  * Framework's corresponding NSSCKFWToken object.  It contains a
00425  * pointer for use by the Module, to store any token-related
00426  * data, and it contains the EPV for a set of routines which the
00427  * Module may implement for use by the Framework.  Some of these
00428  * routines are optional.
00429  */
00430 
00431 struct NSSCKMDTokenStr {
00432   /*
00433    * The Module may use this pointer for its own purposes.
00434    */
00435   void *etc;
00436 
00437   /*
00438    * This routine is used to prepare a Module token object for
00439    * use.  It is called after the NSSCKMDToken object is obtained
00440    * from NSSCKMDSlot->GetToken.  It is named "Setup" here because
00441    * Cryptoki already defines "InitToken" to do the process of
00442    * wiping out any existing state on a token and preparing it for
00443    * a new use.  This routine is optional; if unimplemented, it
00444    * merely won't be called.
00445    */
00446   CK_RV (PR_CALLBACK *Setup)(
00447     NSSCKMDToken *mdToken,
00448     NSSCKFWToken *fwToken,
00449     NSSCKMDInstance *mdInstance,
00450     NSSCKFWInstance *fwInstance
00451   );
00452 
00453   /*
00454    * This routine is called by the Framework whenever it notices
00455    * that the token object is invalid.  (Typically this is when a 
00456    * routine indicates an error such as CKR_DEVICE_REMOVED).  This
00457    * call is the last thing called before the NSSArena in the
00458    * corresponding NSSCKFWToken is destroyed.  This routine is
00459    * optional; if unimplemented, it merely won't be called.
00460    */
00461   void (PR_CALLBACK *Invalidate)(
00462     NSSCKMDToken *mdToken,
00463     NSSCKFWToken *fwToken,
00464     NSSCKMDInstance *mdInstance,
00465     NSSCKFWInstance *fwInstance
00466   );
00467 
00468   /*
00469    * This routine initialises the token in the specified slot.
00470    * This routine is optional; if unimplemented, the Framework
00471    * will fail this operation with an error of CKR_DEVICE_ERROR.
00472    */
00473 
00474   CK_RV (PR_CALLBACK *InitToken)(
00475     NSSCKMDToken *mdToken,
00476     NSSCKFWToken *fwToken,
00477     NSSCKMDInstance *mdInstance,
00478     NSSCKFWInstance *fwInstance,
00479     NSSItem *pin,
00480     NSSUTF8 *label
00481   );
00482 
00483   /*
00484    * This routine returns a pointer to a UTF8-encoded string
00485    * containing this token's label.  Only the characters
00486    * completely encoded in the first thirty-two bytes are
00487    * significant.  This routine is optional.  The string 
00488    * returned is never freed; if dynamically generated,
00489    * the space for it should be allocated from the NSSArena
00490    * that may be obtained from the NSSCKFWInstance.  This
00491    * routine may return NULL upon error; however if *pError
00492    * is CKR_OK, the NULL will be considered the valid response.
00493    */
00494   NSSUTF8 *(PR_CALLBACK *GetLabel)(
00495     NSSCKMDToken *mdToken,
00496     NSSCKFWToken *fwToken,
00497     NSSCKMDInstance *mdInstance,
00498     NSSCKFWInstance *fwInstance,
00499     CK_RV *pError
00500   );
00501 
00502   /*
00503    * This routine returns a pointer to a UTF8-encoded string
00504    * containing this token's manufacturer ID.  Only the characters
00505    * completely encoded in the first thirty-two bytes are
00506    * significant.  This routine is optional.  The string 
00507    * returned is never freed; if dynamically generated,
00508    * the space for it should be allocated from the NSSArena
00509    * that may be obtained from the NSSCKFWInstance.  This
00510    * routine may return NULL upon error; however if *pError
00511    * is CKR_OK, the NULL will be considered the valid response.
00512    */
00513   NSSUTF8 *(PR_CALLBACK *GetManufacturerID)(
00514     NSSCKMDToken *mdToken,
00515     NSSCKFWToken *fwToken,
00516     NSSCKMDInstance *mdInstance,
00517     NSSCKFWInstance *fwInstance,
00518     CK_RV *pError
00519   );
00520 
00521   /*
00522    * This routine returns a pointer to a UTF8-encoded string
00523    * containing this token's model name.  Only the characters
00524    * completely encoded in the first thirty-two bytes are
00525    * significant.  This routine is optional.  The string 
00526    * returned is never freed; if dynamically generated,
00527    * the space for it should be allocated from the NSSArena
00528    * that may be obtained from the NSSCKFWInstance.  This
00529    * routine may return NULL upon error; however if *pError
00530    * is CKR_OK, the NULL will be considered the valid response.
00531    */
00532   NSSUTF8 *(PR_CALLBACK *GetModel)(
00533     NSSCKMDToken *mdToken,
00534     NSSCKFWToken *fwToken,
00535     NSSCKMDInstance *mdInstance,
00536     NSSCKFWInstance *fwInstance,
00537     CK_RV *pError
00538   );
00539 
00540   /*
00541    * This routine returns a pointer to a UTF8-encoded string
00542    * containing this token's serial number.  Only the characters
00543    * completely encoded in the first thirty-two bytes are
00544    * significant.  This routine is optional.  The string 
00545    * returned is never freed; if dynamically generated,
00546    * the space for it should be allocated from the NSSArena
00547    * that may be obtained from the NSSCKFWInstance.  This
00548    * routine may return NULL upon error; however if *pError
00549    * is CKR_OK, the NULL will be considered the valid response.
00550    */
00551   NSSUTF8 *(PR_CALLBACK *GetSerialNumber)(
00552     NSSCKMDToken *mdToken,
00553     NSSCKFWToken *fwToken,
00554     NSSCKMDInstance *mdInstance,
00555     NSSCKFWInstance *fwInstance,
00556     CK_RV *pError
00557   );
00558 
00559   /*
00560    * This routine returns CK_TRUE if the token has its own
00561    * random number generator.  This routine is optional; if
00562    * unimplemented, CK_FALSE is assumed.
00563    */
00564   CK_BBOOL (PR_CALLBACK *GetHasRNG)(
00565     NSSCKMDToken *mdToken,
00566     NSSCKFWToken *fwToken,
00567     NSSCKMDInstance *mdInstance,
00568     NSSCKFWInstance *fwInstance
00569   );
00570 
00571   /*
00572    * This routine returns CK_TRUE if this token is write-protected.
00573    * This routine is optional; if unimplemented, CK_FALSE is
00574    * assumed.
00575    */
00576   CK_BBOOL (PR_CALLBACK *GetIsWriteProtected)(
00577     NSSCKMDToken *mdToken,
00578     NSSCKFWToken *fwToken,
00579     NSSCKMDInstance *mdInstance,
00580     NSSCKFWInstance *fwInstance
00581   );
00582 
00583   /*
00584    * This routine returns CK_TRUE if this token requires a login.
00585    * This routine is optional; if unimplemented, CK_FALSE is
00586    * assumed.
00587    */
00588   CK_BBOOL (PR_CALLBACK *GetLoginRequired)(
00589     NSSCKMDToken *mdToken,
00590     NSSCKFWToken *fwToken,
00591     NSSCKMDInstance *mdInstance,
00592     NSSCKFWInstance *fwInstance
00593   );
00594 
00595   /*
00596    * This routine returns CK_TRUE if the normal user's PIN on this
00597    * token has been initialised.  This routine is optional; if
00598    * unimplemented, CK_FALSE is assumed.
00599    */
00600   CK_BBOOL (PR_CALLBACK *GetUserPinInitialized)(
00601     NSSCKMDToken *mdToken,
00602     NSSCKFWToken *fwToken,
00603     NSSCKMDInstance *mdInstance,
00604     NSSCKFWInstance *fwInstance
00605   );
00606 
00607   /*
00608    * This routine returns CK_TRUE if a successful save of a
00609    * session's cryptographic operations state ~always~ contains
00610    * all keys needed to restore the state of the session.  This
00611    * routine is optional; if unimplemented, CK_FALSE is assumed.
00612    */
00613   CK_BBOOL (PR_CALLBACK *GetRestoreKeyNotNeeded)(
00614     NSSCKMDToken *mdToken,
00615     NSSCKFWToken *fwToken,
00616     NSSCKMDInstance *mdInstance,
00617     NSSCKFWInstance *fwInstance
00618   );
00619 
00620   /*
00621    * This routine returns CK_TRUE if the token has its own
00622    * hardware clock.  This routine is optional; if unimplemented,
00623    * CK_FALSE is assumed.
00624    */
00625   CK_BBOOL (PR_CALLBACK *GetHasClockOnToken)(
00626     NSSCKMDToken *mdToken,
00627     NSSCKFWToken *fwToken,
00628     NSSCKMDInstance *mdInstance,
00629     NSSCKFWInstance *fwInstance
00630   );
00631 
00632   /*
00633    * This routine returns CK_TRUE if the token has a protected
00634    * authentication path.  This routine is optional; if
00635    * unimplemented, CK_FALSE is assumed.
00636    */
00637   CK_BBOOL (PR_CALLBACK *GetHasProtectedAuthenticationPath)(
00638     NSSCKMDToken *mdToken,
00639     NSSCKFWToken *fwToken,
00640     NSSCKMDInstance *mdInstance,
00641     NSSCKFWInstance *fwInstance
00642   );
00643 
00644   /*
00645    * This routine returns CK_TRUE if the token supports dual
00646    * cryptographic operations within a single session.  This
00647    * routine is optional; if unimplemented, CK_FALSE is assumed.
00648    */
00649   CK_BBOOL (PR_CALLBACK *GetSupportsDualCryptoOperations)(
00650     NSSCKMDToken *mdToken,
00651     NSSCKFWToken *fwToken,
00652     NSSCKMDInstance *mdInstance,
00653     NSSCKFWInstance *fwInstance
00654   );
00655 
00656   /*
00657    * XXX fgmr-- should we have a call to return all the flags
00658    * at once, for folks who already know about Cryptoki?
00659    */
00660 
00661   /*
00662    * This routine returns the maximum number of sessions that
00663    * may be opened on this token.  This routine is optional;
00664    * if unimplemented, the special value CK_UNAVAILABLE_INFORMATION
00665    * is assumed.  XXX fgmr-- or CK_EFFECTIVELY_INFINITE?
00666    */
00667   CK_ULONG (PR_CALLBACK *GetMaxSessionCount)(
00668     NSSCKMDToken *mdToken,
00669     NSSCKFWToken *fwToken,
00670     NSSCKMDInstance *mdInstance,
00671     NSSCKFWInstance *fwInstance
00672   );
00673 
00674   /*
00675    * This routine returns the maximum number of read/write
00676    * sesisons that may be opened on this token.  This routine
00677    * is optional; if unimplemented, the special value
00678    * CK_UNAVAILABLE_INFORMATION is assumed.  XXX fgmr-- or 
00679    * CK_EFFECTIVELY_INFINITE?
00680    */
00681   CK_ULONG (PR_CALLBACK *GetMaxRwSessionCount)(
00682     NSSCKMDToken *mdToken,
00683     NSSCKFWToken *fwToken,
00684     NSSCKMDInstance *mdInstance,
00685     NSSCKFWInstance *fwInstance
00686   );
00687 
00688   /*
00689    * This routine returns the maximum PIN code length that is
00690    * supported on this token.  This routine is optional;
00691    * if unimplemented, the special value CK_UNAVAILABLE_INFORMATION
00692    * is assumed.
00693    */
00694   CK_ULONG (PR_CALLBACK *GetMaxPinLen)(
00695     NSSCKMDToken *mdToken,
00696     NSSCKFWToken *fwToken,
00697     NSSCKMDInstance *mdInstance,
00698     NSSCKFWInstance *fwInstance
00699   );
00700 
00701   /*
00702    * This routine returns the minimum PIN code length that is
00703    * supported on this token.  This routine is optional; if
00704    * unimplemented, the special value CK_UNAVAILABLE_INFORMATION
00705    *  is assumed.  XXX fgmr-- or 0?
00706    */
00707   CK_ULONG (PR_CALLBACK *GetMinPinLen)(
00708     NSSCKMDToken *mdToken,
00709     NSSCKFWToken *fwToken,
00710     NSSCKMDInstance *mdInstance,
00711     NSSCKFWInstance *fwInstance
00712   );
00713 
00714   /*
00715    * This routine returns the total amount of memory on the token
00716    * in which public objects may be stored.  This routine is
00717    * optional; if unimplemented, the special value
00718    * CK_UNAVAILABLE_INFORMATION is assumed.
00719    */
00720   CK_ULONG (PR_CALLBACK *GetTotalPublicMemory)(
00721     NSSCKMDToken *mdToken,
00722     NSSCKFWToken *fwToken,
00723     NSSCKMDInstance *mdInstance,
00724     NSSCKFWInstance *fwInstance
00725   );
00726 
00727   /*
00728    * This routine returns the amount of unused memory on the
00729    * token in which public objects may be stored.  This routine
00730    * is optional; if unimplemented, the special value
00731    * CK_UNAVAILABLE_INFORMATION is assumed.
00732    */
00733   CK_ULONG (PR_CALLBACK *GetFreePublicMemory)(
00734     NSSCKMDToken *mdToken,
00735     NSSCKFWToken *fwToken,
00736     NSSCKMDInstance *mdInstance,
00737     NSSCKFWInstance *fwInstance
00738   );
00739 
00740   /*
00741    * This routine returns the total amount of memory on the token
00742    * in which private objects may be stored.  This routine is
00743    * optional; if unimplemented, the special value
00744    * CK_UNAVAILABLE_INFORMATION is assumed.
00745    */
00746   CK_ULONG (PR_CALLBACK *GetTotalPrivateMemory)(
00747     NSSCKMDToken *mdToken,
00748     NSSCKFWToken *fwToken,
00749     NSSCKMDInstance *mdInstance,
00750     NSSCKFWInstance *fwInstance
00751   );
00752 
00753   /*
00754    * This routine returns the amount of unused memory on the
00755    * token in which private objects may be stored.  This routine
00756    * is optional; if unimplemented, the special value
00757    * CK_UNAVAILABLE_INFORMATION is assumed.
00758    */
00759   CK_ULONG (PR_CALLBACK *GetFreePrivateMemory)(
00760     NSSCKMDToken *mdToken,
00761     NSSCKFWToken *fwToken,
00762     NSSCKMDInstance *mdInstance,
00763     NSSCKFWInstance *fwInstance
00764   );
00765 
00766   /*
00767    * This routine returns the version number of this token's
00768    * hardware.  This routine is optional; if unimplemented,
00769    * the value 0.1 is assumed.
00770    */
00771   CK_VERSION (PR_CALLBACK *GetHardwareVersion)(
00772     NSSCKMDToken *mdToken,
00773     NSSCKFWToken *fwToken,
00774     NSSCKMDInstance *mdInstance,
00775     NSSCKFWInstance *fwInstance
00776   );
00777 
00778   /*
00779    * This routine returns the version number of this token's
00780    * firmware.  This routine is optional; if unimplemented,
00781    * the value 0.1 is assumed.
00782    */
00783   CK_VERSION (PR_CALLBACK *GetFirmwareVersion)(
00784     NSSCKMDToken *mdToken,
00785     NSSCKFWToken *fwToken,
00786     NSSCKMDInstance *mdInstance,
00787     NSSCKFWInstance *fwInstance
00788   );
00789 
00790   /*
00791    * This routine stuffs the current UTC time, as obtained from
00792    * the token, into the sixteen-byte buffer in the form
00793    * YYYYMMDDhhmmss00.  This routine need only be implemented
00794    * by token which indicate that they have a real-time clock.
00795    * XXX fgmr-- think about time formats.
00796    */
00797   CK_RV (PR_CALLBACK *GetUTCTime)(
00798     NSSCKMDToken *mdToken,
00799     NSSCKFWToken *fwToken,
00800     NSSCKMDInstance *mdInstance,
00801     NSSCKFWInstance *fwInstance,
00802     CK_CHAR utcTime[16]
00803   );
00804 
00805   /*
00806    * This routine creates a session on the token, and returns
00807    * the corresponding NSSCKMDSession object.  The value of
00808    * rw will be CK_TRUE if the session is to be a read/write 
00809    * session, or CK_FALSE otherwise.  An NSSArena dedicated to
00810    * the new session is available from the specified NSSCKFWSession.
00811    * This routine may return NULL upon error.
00812    */
00813   NSSCKMDSession *(PR_CALLBACK *OpenSession)(
00814     NSSCKMDToken *mdToken,
00815     NSSCKFWToken *fwToken,
00816     NSSCKMDInstance *mdInstance,
00817     NSSCKFWInstance *fwInstance,
00818     NSSCKFWSession *fwSession,
00819     CK_BBOOL rw,
00820     CK_RV *pError
00821   );
00822 
00823   /*
00824    * This routine returns the number of PKCS#11 Mechanisms
00825    * supported by this token.  This routine is optional; if
00826    * unimplemented, zero is assumed.
00827    */
00828   CK_ULONG (PR_CALLBACK *GetMechanismCount)(
00829     NSSCKMDToken *mdToken,
00830     NSSCKFWToken *fwToken,
00831     NSSCKMDInstance *mdInstance,
00832     NSSCKFWInstance *fwInstance
00833   );
00834 
00835   /*
00836    * This routine stuffs into the specified array the types
00837    * of the mechanisms supported by this token.  The Framework
00838    * determines the size of the array by calling GetMechanismCount.
00839    */
00840   CK_RV (PR_CALLBACK *GetMechanismTypes)(
00841     NSSCKMDToken *mdToken,
00842     NSSCKFWToken *fwToken,
00843     NSSCKMDInstance *mdInstance,
00844     NSSCKFWInstance *fwInstance,
00845     CK_MECHANISM_TYPE types[]
00846   );
00847 
00848   /*
00849    * This routine returns a pointer to a Module mechanism
00850    * object corresponding to a specified type.  This routine
00851    * need only exist for tokens implementing at least one
00852    * mechanism.
00853    */
00854   NSSCKMDMechanism *(PR_CALLBACK *GetMechanism)(
00855     NSSCKMDToken *mdToken,
00856     NSSCKFWToken *fwToken,
00857     NSSCKMDInstance *mdInstance,
00858     NSSCKFWInstance *fwInstance,
00859     NSSCKFWMechanism *fwMechanism,
00860     CK_MECHANISM_TYPE which
00861   );
00862 
00863   /*
00864    * This object may be extended in future versions of the
00865    * NSS Cryptoki Framework.  To allow for some flexibility
00866    * in the area of binary compatibility, this field should
00867    * be NULL.
00868    */
00869   void *null;
00870 };
00871 
00872 /*
00873  * NSSCKMDSession
00874  *
00875  * This is the basic handle for a session on a PKCS#11 Token.  It
00876  * is created by NSSCKMDToken->OpenSession, and may be obtained
00877  * from the Framework's corresponding NSSCKFWSession object.  It
00878  * contains a pointer for use by the Module, to store any session-
00879  * realted data, and it contains the EPV for a set of routines
00880  * which the Module may implement for use by the Framework.  Some
00881  * of these routines are optional.
00882  */
00883 
00884 struct NSSCKMDSessionStr {
00885   /*
00886    * The Module may use this pointer for its own purposes.
00887    */
00888   void *etc;
00889 
00890   /*
00891    * This routine is called by the Framework when a session is
00892    * closed.  This call is the last thing called before the
00893    * NSSArena in the correspoinding NSSCKFWSession is destroyed.
00894    * This routine is optional; if unimplemented, it merely won't
00895    * be called.
00896    */
00897   void (PR_CALLBACK *Close)(
00898     NSSCKMDSession *mdSession,
00899     NSSCKFWSession *fwSession,
00900     NSSCKMDToken *mdToken,
00901     NSSCKFWToken *fwToken,
00902     NSSCKMDInstance *mdInstance,
00903     NSSCKFWInstance *fwInstance
00904   );
00905 
00906   /*
00907    * This routine is used to get any device-specific error.
00908    * This routine is optional.
00909    */
00910   CK_ULONG (PR_CALLBACK *GetDeviceError)(
00911     NSSCKMDSession *mdSession,
00912     NSSCKFWSession *fwSession,
00913     NSSCKMDToken *mdToken,
00914     NSSCKFWToken *fwToken,
00915     NSSCKMDInstance *mdInstance,
00916     NSSCKFWInstance *fwInstance
00917   );
00918 
00919   /*
00920    * This routine is used to log in a user to the token.  This
00921    * routine is optional, since the Framework's NSSCKFWSession
00922    * object keeps track of the login state.
00923    */
00924   CK_RV (PR_CALLBACK *Login)(
00925     NSSCKMDSession *mdSession,
00926     NSSCKFWSession *fwSession,
00927     NSSCKMDToken *mdToken,
00928     NSSCKFWToken *fwToken,
00929     NSSCKMDInstance *mdInstance,
00930     NSSCKFWInstance *fwInstance,
00931     CK_USER_TYPE userType,
00932     NSSItem *pin,
00933     CK_STATE oldState,
00934     CK_STATE newState
00935   );
00936 
00937   /*
00938    * This routine is used to log out a user from the token.  This
00939    * routine is optional, since the Framework's NSSCKFWSession
00940    * object keeps track of the login state.
00941    */
00942   CK_RV (PR_CALLBACK *Logout)(
00943     NSSCKMDSession *mdSession,
00944     NSSCKFWSession *fwSession,
00945     NSSCKMDToken *mdToken,
00946     NSSCKFWToken *fwToken,
00947     NSSCKMDInstance *mdInstance,
00948     NSSCKFWInstance *fwInstance,
00949     CK_STATE oldState,
00950     CK_STATE newState
00951   );
00952 
00953   /*
00954    * This routine is used to initialize the normal user's PIN or
00955    * password.  This will only be called in the "read/write
00956    * security officer functions" state.  If this token has a
00957    * protected authentication path, then the pin argument will
00958    * be NULL.  This routine is optional; if unimplemented, the
00959    * Framework will return the error CKR_TOKEN_WRITE_PROTECTED.
00960    */
00961   CK_RV (PR_CALLBACK *InitPIN)(
00962     NSSCKMDSession *mdSession,
00963     NSSCKFWSession *fwSession,
00964     NSSCKMDToken *mdToken,
00965     NSSCKFWToken *fwToken,
00966     NSSCKMDInstance *mdInstance,
00967     NSSCKFWInstance *fwInstance,
00968     NSSItem *pin
00969   );
00970 
00971   /*
00972    * This routine is used to modify a user's PIN or password.  This
00973    * routine will only be called in the "read/write security officer
00974    * functions" or "read/write user functions" state.  If this token
00975    * has a protected authentication path, then the pin arguments
00976    * will be NULL.  This routine is optional; if unimplemented, the
00977    * Framework will return the error CKR_TOKEN_WRITE_PROTECTED.
00978    */
00979   CK_RV (PR_CALLBACK *SetPIN)(
00980     NSSCKMDSession *mdSession,
00981     NSSCKFWSession *fwSession,
00982     NSSCKMDToken *mdToken,
00983     NSSCKFWToken *fwToken,
00984     NSSCKMDInstance *mdInstance,
00985     NSSCKFWInstance *fwInstance,
00986     NSSItem *oldPin,
00987     NSSItem *newPin
00988   );
00989 
00990   /*
00991    * This routine is used to find out how much space would be required
00992    * to save the current operational state.  This routine is optional;
00993    * if unimplemented, the Framework will reject any attempts to save
00994    * the operational state with the error CKR_STATE_UNSAVEABLE.  This
00995    * routine may return zero on error.
00996    */
00997   CK_ULONG (PR_CALLBACK *GetOperationStateLen)(
00998     NSSCKMDSession *mdSession,
00999     NSSCKFWSession *fwSession,
01000     NSSCKMDToken *mdToken,
01001     NSSCKFWToken *fwToken,
01002     NSSCKMDInstance *mdInstance,
01003     NSSCKFWInstance *fwInstance,
01004     CK_RV *pError
01005   );
01006 
01007   /*
01008    * This routine is used to store the current operational state.  This
01009    * routine is only required if GetOperationStateLen is implemented 
01010    * and can return a nonzero value.  The buffer in the specified item
01011    * will be pre-allocated, and the length will specify the amount of
01012    * space available (which may be more than GetOperationStateLen
01013    * asked for, but which will not be smaller).
01014    */
01015   CK_RV (PR_CALLBACK *GetOperationState)(
01016     NSSCKMDSession *mdSession,
01017     NSSCKFWSession *fwSession,
01018     NSSCKMDToken *mdToken,
01019     NSSCKFWToken *fwToken,
01020     NSSCKMDInstance *mdInstance,
01021     NSSCKFWInstance *fwInstance,
01022     NSSItem *buffer
01023   );
01024 
01025   /*
01026    * This routine is used to restore an operational state previously
01027    * obtained with GetOperationState.  The Framework will take pains
01028    * to be sure that the state is (or was at one point) valid; if the
01029    * Module notices that the state is invalid, it should return an
01030    * error, but it is not required to be paranoid about the issue.
01031    * [XXX fgmr-- should (can?) the framework verify the keys match up?]
01032    * This routine is required only if GetOperationState is implemented.
01033    */
01034   CK_RV (PR_CALLBACK *SetOperationState)(
01035     NSSCKMDSession *mdSession,
01036     NSSCKFWSession *fwSession,
01037     NSSCKMDToken *mdToken,
01038     NSSCKFWToken *fwToken,
01039     NSSCKMDInstance *mdInstance,
01040     NSSCKFWInstance *fwInstance,
01041     NSSItem *state,
01042     NSSCKMDObject *mdEncryptionKey,
01043     NSSCKFWObject *fwEncryptionKey,
01044     NSSCKMDObject *mdAuthenticationKey,
01045     NSSCKFWObject *fwAuthenticationKey
01046   );
01047 
01048   /*
01049    * This routine is used to create an object.  The specified template
01050    * will only specify a session object if the Module has indicated 
01051    * that it wishes to handle its own session objects.  This routine
01052    * is optional; if unimplemented, the Framework will reject the
01053    * operation with the error CKR_TOKEN_WRITE_PROTECTED.  Space for
01054    * token objects should come from the NSSArena available from the
01055    * NSSCKFWToken object; space for session objects (if supported)
01056    * should come from the NSSArena available from the NSSCKFWSession
01057    * object.  The appropriate NSSArena pointer will, as a convenience,
01058    * be passed as the handyArenaPointer argument.  This routine may
01059    * return NULL upon error.
01060    */
01061   NSSCKMDObject *(PR_CALLBACK *CreateObject)(
01062     NSSCKMDSession *mdSession,
01063     NSSCKFWSession *fwSession,
01064     NSSCKMDToken *mdToken,
01065     NSSCKFWToken *fwToken,
01066     NSSCKMDInstance *mdInstance,
01067     NSSCKFWInstance *fwInstance,
01068     NSSArena *handyArenaPointer,
01069     CK_ATTRIBUTE_PTR pTemplate,
01070     CK_ULONG ulAttributeCount,
01071     CK_RV *pError
01072   );
01073 
01074   /*
01075    * This routine is used to make a copy of an object.  It is entirely
01076    * optional; if unimplemented, the Framework will try to use
01077    * CreateObject instead.  If the Module has indicated that it does
01078    * not wish to handle session objects, then this routine will only
01079    * be called to copy a token object to another token object.
01080    * Otherwise, either the original object or the new may be of
01081    * either the token or session variety.  As with CreateObject, the
01082    * handyArenaPointer will point to the appropriate arena for the
01083    * new object.  This routine may return NULL upon error.
01084    */
01085   NSSCKMDObject *(PR_CALLBACK *CopyObject)(
01086     NSSCKMDSession *mdSession,
01087     NSSCKFWSession *fwSession,
01088     NSSCKMDToken *mdToken,
01089     NSSCKFWToken *fwToken,
01090     NSSCKMDInstance *mdInstance,
01091     NSSCKFWInstance *fwInstance,
01092     NSSCKMDObject *mdOldObject,
01093     NSSCKFWObject *fwOldObject,
01094     NSSArena *handyArenaPointer,
01095     CK_ATTRIBUTE_PTR pTemplate,
01096     CK_ULONG ulAttributeCount,
01097     CK_RV *pError
01098   );
01099 
01100   /*
01101    * This routine is used to begin an object search.  This routine may
01102    * be unimplemented only if the Module does not handle session 
01103    * objects, and if none of its tokens have token objects.  The
01104    * NSSCKFWFindObjects pointer has an NSSArena that may be used for
01105    * storage for the life of this "find" operation.  This routine may
01106    * return NULL upon error.  If the Module can determine immediately
01107    * that the search will not find any matching objects, it may return
01108    * NULL, and specify CKR_OK as the error.
01109    */
01110   NSSCKMDFindObjects *(PR_CALLBACK *FindObjectsInit)(
01111     NSSCKMDSession *mdSession,
01112     NSSCKFWSession *fwSession,
01113     NSSCKMDToken *mdToken,
01114     NSSCKFWToken *fwToken,
01115     NSSCKMDInstance *mdInstance,
01116     NSSCKFWInstance *fwInstance,
01117     CK_ATTRIBUTE_PTR pTemplate,
01118     CK_ULONG ulAttributeCount,
01119     CK_RV *pError
01120   );
01121 
01122   /*
01123    * This routine seeds the random-number generator.  It is
01124    * optional, even if GetRandom is implemented.  If unimplemented,
01125    * the Framework will issue the error CKR_RANDOM_SEED_NOT_SUPPORTED.
01126    */
01127   CK_RV (PR_CALLBACK *SeedRandom)(
01128     NSSCKMDSession *mdSession,
01129     NSSCKFWSession *fwSession,
01130     NSSCKMDToken *mdToken,
01131     NSSCKFWToken *fwToken,
01132     NSSCKMDInstance *mdInstance,
01133     NSSCKFWInstance *fwInstance,
01134     NSSItem *seed
01135   );
01136 
01137   /*
01138    * This routine gets random data.  It is optional.  If unimplemented,
01139    * the Framework will issue the error CKR_RANDOM_NO_RNG.
01140    */
01141   CK_RV (PR_CALLBACK *GetRandom)(
01142     NSSCKMDSession *mdSession,
01143     NSSCKFWSession *fwSession,
01144     NSSCKMDToken *mdToken,
01145     NSSCKFWToken *fwToken,
01146     NSSCKMDInstance *mdInstance,
01147     NSSCKFWInstance *fwInstance,
01148     NSSItem *buffer
01149   );
01150 
01151   /*
01152    * This object may be extended in future versions of the
01153    * NSS Cryptoki Framework.  To allow for some flexibility
01154    * in the area of binary compatibility, this field should
01155    * be NULL.
01156    */
01157   void *null;
01158 };
01159 
01160 /*
01161  * NSSCKMDFindObjects
01162  *
01163  * This is the basic handle for an object search.  It is
01164  * created by NSSCKMDSession->FindObjectsInit, and may be
01165  * obtained from the Framework's corresponding object.
01166  * It contains a pointer for use by the Module, to store
01167  * any search-related data, and it contains the EPV for a
01168  * set of routines which the Module may implement for use
01169  * by the Framework.  Some of these routines are optional.
01170  */
01171 
01172 struct NSSCKMDFindObjectsStr {
01173   /*
01174    * The Module may use this pointer for its own purposes.
01175    */
01176   void *etc;
01177 
01178   /*
01179    * This routine is called by the Framework to finish a
01180    * search operation.  Note that the Framework may finish
01181    * a search before it has completed.  This routine is
01182    * optional; if unimplemented, it merely won't be called.
01183    */
01184   void (PR_CALLBACK *Final)(
01185     NSSCKMDFindObjects *mdFindObjects,
01186     NSSCKFWFindObjects *fwFindObjects,
01187     NSSCKMDSession *mdSession,
01188     NSSCKFWSession *fwSession,
01189     NSSCKMDToken *mdToken,
01190     NSSCKFWToken *fwToken,
01191     NSSCKMDInstance *mdInstance,
01192     NSSCKFWInstance *fwInstance
01193   );
01194 
01195   /*
01196    * This routine is used to obtain another pointer to an
01197    * object matching the search criteria.  This routine is
01198    * required.  If no (more) objects match the search, it
01199    * should return NULL and set the error to CKR_OK.
01200    */
01201   NSSCKMDObject *(PR_CALLBACK *Next)(
01202     NSSCKMDFindObjects *mdFindObjects,
01203     NSSCKFWFindObjects *fwFindObjects,
01204     NSSCKMDSession *mdSession,
01205     NSSCKFWSession *fwSession,
01206     NSSCKMDToken *mdToken,
01207     NSSCKFWToken *fwToken,
01208     NSSCKMDInstance *mdInstance,
01209     NSSCKFWInstance *fwInstance,
01210     NSSArena *arena,
01211     CK_RV *pError
01212   );
01213 
01214   /*
01215    * This object may be extended in future versions of the
01216    * NSS Cryptoki Framework.  To allow for some flexibility
01217    * in the area of binary compatibility, this field should
01218    * be NULL.
01219    */
01220   void *null;
01221 };
01222 
01223 /*
01224  * NSSCKMDMechanism
01225  *
01226  */
01227 
01228 struct NSSCKMDMechanismStr {
01229   /*
01230    * The Module may use this pointer for its own purposes.
01231    */
01232   void *etc;
01233 
01234   /*
01235    * This routine returns the minimum key size allowed for
01236    * this mechanism.  This routine is optional; if unimplemented,
01237    * zero will be assumed.  This routine may return zero on
01238    * error; if the error is CKR_OK, zero will be accepted as
01239    * a valid response.
01240    */
01241   CK_ULONG (PR_CALLBACK *GetMinKeySize)(
01242     NSSCKMDMechanism *mdMechanism,
01243     NSSCKFWMechanism *fwMechanism,
01244     NSSCKMDToken *mdToken,
01245     NSSCKFWToken *fwToken,
01246     NSSCKMDInstance *mdInstance,
01247     NSSCKFWInstance *fwInstance,
01248     CK_RV *pError
01249   );
01250 
01251   /*
01252    * This routine returns the maximum key size allowed for
01253    * this mechanism.  This routine is optional; if unimplemented,
01254    * zero will be assumed.  This routine may return zero on
01255    * error; if the error is CKR_OK, zero will be accepted as
01256    * a valid response.
01257    */
01258   CK_ULONG (PR_CALLBACK *GetMaxKeySize)(
01259     NSSCKMDMechanism *mdMechanism,
01260     NSSCKFWMechanism *fwMechanism,
01261     NSSCKMDToken *mdToken,
01262     NSSCKFWToken *fwToken,
01263     NSSCKMDInstance *mdInstance,
01264     NSSCKFWInstance *fwInstance,
01265     CK_RV *pError
01266   );
01267 
01268   /*
01269    * This routine is called to determine if the mechanism is
01270    * implemented in hardware or software.  It returns CK_TRUE
01271    * if it is done in hardware.
01272    */
01273   CK_BBOOL (PR_CALLBACK *GetInHardware)(
01274     NSSCKMDMechanism *mdMechanism,
01275     NSSCKFWMechanism *fwMechanism,
01276     NSSCKMDToken *mdToken,
01277     NSSCKFWToken *fwToken,
01278     NSSCKMDInstance *mdInstance,
01279     NSSCKFWInstance *fwInstance,
01280     CK_RV *pError
01281   );
01282 
01283   /*
01284    * The crypto routines themselves.  Most crypto operations may
01285    * be performed in two ways, streaming and single-part.  The
01286    * streaming operations involve the use of (typically) three
01287    * calls-- an Init method to set up the operation, an Update
01288    * method to feed data to the operation, and a Final method to
01289    * obtain the final result.  Single-part operations involve
01290    * one method, to perform the crypto operation all at once.
01291    * The NSS Cryptoki Framework can implement the single-part
01292    * operations in terms of the streaming operations on behalf
01293    * of the Module.  There are a few variances.
01294    * 
01295    * For simplicity, the routines are listed in summary here:
01296    *
01297    *  EncryptInit, EncryptUpdate, EncryptFinal; Encrypt
01298    *  DecryptInit, DecryptUpdate, DecryptFinal; Decrypt
01299    *  DigestInit, DigestUpdate, DigestKey, DigestFinal; Digest
01300    *  SignInit, SignUpdate, SignFinal; Sign
01301    *  SignRecoverInit; SignRecover
01302    *  VerifyInit, VerifyUpdate, VerifyFinal; Verify
01303    *  VerifyRecoverInit; VerifyRecover
01304    * 
01305    * Also, there are some combined-operation calls:
01306    * 
01307    *  DigestEncryptUpdate
01308    *  DecryptDigestUpdate
01309    *  SignEncryptUpdate
01310    *  DecryptVerifyUpdate
01311    *
01312    * The key-management routines are
01313    *
01314    *  GenerateKey
01315    *  GenerateKeyPair
01316    *  WrapKey
01317    *  UnwrapKey
01318    *  DeriveKey
01319    *
01320    * All of these routines based directly on the Cryptoki API; 
01321    * see PKCS#11 for further information.
01322    */
01323 
01324   /*
01325    */
01326   CK_RV (PR_CALLBACK *EncryptInit)(
01327     NSSCKMDMechanism *mdMechanism,
01328     NSSCKFWMechanism *fwMechanism,
01329     NSSCKMDSession *mdSession,
01330     NSSCKFWSession *fwSession,
01331     NSSCKMDToken *mdToken,
01332     NSSCKFWToken *fwToken,
01333     NSSCKMDInstance *mdInstance,
01334     NSSCKFWInstance *fwInstance,
01335     NSSCKMDObject *mdKey,
01336     NSSCKFWObject *fwKey
01337   );
01338 
01339   /*
01340    */
01341   CK_RV (PR_CALLBACK *EncryptUpdate)(
01342     NSSCKMDMechanism *mdMechanism,
01343     NSSCKFWMechanism *fwMechanism,
01344     NSSCKMDSession *mdSession,
01345     NSSCKFWSession *fwSession,
01346     NSSCKMDToken *mdToken,
01347     NSSCKFWToken *fwToken,
01348     NSSCKMDInstance *mdInstance,
01349     NSSCKFWInstance *fwInstance,
01350     NSSItem *data, 
01351     NSSItem *buffer
01352   );
01353 
01354   /*
01355    */
01356   CK_RV (PR_CALLBACK *EncryptFinal)(
01357     NSSCKMDMechanism *mdMechanism,
01358     NSSCKFWMechanism *fwMechanism,
01359     NSSCKMDSession *mdSession,
01360     NSSCKFWSession *fwSession,
01361     NSSCKMDToken *mdToken,
01362     NSSCKFWToken *fwToken,
01363     NSSCKMDInstance *mdInstance,
01364     NSSCKFWInstance *fwInstance,
01365     NSSItem *buffer
01366   );
01367 
01368   /*
01369    */
01370   CK_RV (PR_CALLBACK *Encrypt)(
01371     NSSCKMDMechanism *mdMechanism,
01372     NSSCKFWMechanism *fwMechanism,
01373     NSSCKMDSession *mdSession,
01374     NSSCKFWSession *fwSession,
01375     NSSCKMDToken *mdToken,
01376     NSSCKFWToken *fwToken,
01377     NSSCKMDInstance *mdInstance,
01378     NSSCKFWInstance *fwInstance,
01379     NSSCKMDObject *mdKey,
01380     NSSCKFWObject *fwKey,
01381     NSSItem *data, 
01382     NSSItem *buffer
01383   );
01384 
01385   /*
01386    */
01387   CK_RV (PR_CALLBACK *DecryptInit)(
01388     NSSCKMDMechanism *mdMechanism,
01389     NSSCKFWMechanism *fwMechanism,
01390     NSSCKMDSession *mdSession,
01391     NSSCKFWSession *fwSession,
01392     NSSCKMDToken *mdToken,
01393     NSSCKFWToken *fwToken,
01394     NSSCKMDInstance *mdInstance,
01395     NSSCKFWInstance *fwInstance,
01396     NSSCKMDObject *mdKey,
01397     NSSCKFWObject *fwKey
01398   );
01399 
01400   /*
01401    */
01402   CK_RV (PR_CALLBACK *DecryptUpdate)(
01403     NSSCKMDMechanism *mdMechanism,
01404     NSSCKFWMechanism *fwMechanism,
01405     NSSCKMDSession *mdSession,
01406     NSSCKFWSession *fwSession,
01407     NSSCKMDToken *mdToken,
01408     NSSCKFWToken *fwToken,
01409     NSSCKMDInstance *mdInstance,
01410     NSSCKFWInstance *fwInstance,
01411     NSSItem *data, 
01412     NSSItem *buffer
01413   );
01414 
01415   /*
01416    */
01417   CK_RV (PR_CALLBACK *DecryptFinal)(
01418     NSSCKMDMechanism *mdMechanism,
01419     NSSCKFWMechanism *fwMechanism,
01420     NSSCKMDSession *mdSession,
01421     NSSCKFWSession *fwSession,
01422     NSSCKMDToken *mdToken,
01423     NSSCKFWToken *fwToken,
01424     NSSCKMDInstance *mdInstance,
01425     NSSCKFWInstance *fwInstance,
01426     NSSItem *buffer
01427   );
01428 
01429   /*
01430    */
01431   CK_RV (PR_CALLBACK *Decrypt)(
01432     NSSCKMDMechanism *mdMechanism,
01433     NSSCKFWMechanism *fwMechanism,
01434     NSSCKMDSession *mdSession,
01435     NSSCKFWSession *fwSession,
01436     NSSCKMDToken *mdToken,
01437     NSSCKFWToken *fwToken,
01438     NSSCKMDInstance *mdInstance,
01439     NSSCKFWInstance *fwInstance,
01440     NSSCKMDObject *mdKey,
01441     NSSCKFWObject *fwKey,
01442     NSSItem *data, 
01443     NSSItem *buffer
01444   );
01445 
01446   /*
01447    */
01448   CK_RV (PR_CALLBACK *DigestInit)(
01449     NSSCKMDMechanism *mdMechanism,
01450     NSSCKFWMechanism *fwMechanism,
01451     NSSCKMDSession *mdSession,
01452     NSSCKFWSession *fwSession,
01453     NSSCKMDToken *mdToken,
01454     NSSCKFWToken *fwToken,
01455     NSSCKMDInstance *mdInstance,
01456     NSSCKFWInstance *fwInstance
01457   );
01458 
01459   /*
01460    */
01461   CK_RV (PR_CALLBACK *DigestUpdate)(
01462     NSSCKMDMechanism *mdMechanism,
01463     NSSCKFWMechanism *fwMechanism,
01464     NSSCKMDSession *mdSession,
01465     NSSCKFWSession *fwSession,
01466     NSSCKMDToken *mdToken,
01467     NSSCKFWToken *fwToken,
01468     NSSCKMDInstance *mdInstance,
01469     NSSCKFWInstance *fwInstance,
01470     NSSItem *data
01471   );
01472 
01473   /*
01474    */
01475   CK_RV (PR_CALLBACK *DigestKey)(
01476     NSSCKMDMechanism *mdMechanism,
01477     NSSCKFWMechanism *fwMechanism,
01478     NSSCKMDSession *mdSession,
01479     NSSCKFWSession *fwSession,
01480     NSSCKMDToken *mdToken,
01481     NSSCKFWToken *fwToken,
01482     NSSCKMDInstance *mdInstance,
01483     NSSCKFWInstance *fwInstance,
01484     NSSCKMDObject *mdKey,
01485     NSSCKFWObject *fwKey
01486   );
01487 
01488   /*
01489    */
01490   CK_RV (PR_CALLBACK *DigestFinal)(
01491     NSSCKMDMechanism *mdMechanism,
01492     NSSCKFWMechanism *fwMechanism,
01493     NSSCKMDSession *mdSession,
01494     NSSCKFWSession *fwSession,
01495     NSSCKMDToken *mdToken,
01496     NSSCKFWToken *fwToken,
01497     NSSCKMDInstance *mdInstance,
01498     NSSCKFWInstance *fwInstance,
01499     NSSItem *buffer
01500   );
01501 
01502   /*
01503    */
01504   CK_RV (PR_CALLBACK *Digest)(
01505     NSSCKMDMechanism *mdMechanism,
01506     NSSCKFWMechanism *fwMechanism,
01507     NSSCKMDSession *mdSession,
01508     NSSCKFWSession *fwSession,
01509     NSSCKMDToken *mdToken,
01510     NSSCKFWToken *fwToken,
01511     NSSCKMDInstance *mdInstance,
01512     NSSCKFWInstance *fwInstance,
01513     NSSItem *data, 
01514     NSSItem *buffer
01515   );
01516 
01517   /*
01518    */
01519   CK_RV (PR_CALLBACK *SignInit)(
01520     NSSCKMDMechanism *mdMechanism,
01521     NSSCKFWMechanism *fwMechanism,
01522     NSSCKMDSession *mdSession,
01523     NSSCKFWSession *fwSession,
01524     NSSCKMDToken *mdToken,
01525     NSSCKFWToken *fwToken,
01526     NSSCKMDInstance *mdInstance,
01527     NSSCKFWInstance *fwInstance,
01528     NSSCKMDObject *mdKey,
01529     NSSCKFWObject *fwKey
01530   );
01531 
01532   /*
01533    */
01534   CK_RV (PR_CALLBACK *SignUpdate)(
01535     NSSCKMDMechanism *mdMechanism,
01536     NSSCKFWMechanism *fwMechanism,
01537     NSSCKMDSession *mdSession,
01538     NSSCKFWSession *fwSession,
01539     NSSCKMDToken *mdToken,
01540     NSSCKFWToken *fwToken,
01541     NSSCKMDInstance *mdInstance,
01542     NSSCKFWInstance *fwInstance,
01543     NSSItem *data,
01544     NSSItem *buffer
01545   );
01546 
01547   /*
01548    */
01549   CK_RV (PR_CALLBACK *SignFinal)(
01550     NSSCKMDMechanism *mdMechanism,
01551     NSSCKFWMechanism *fwMechanism,
01552     NSSCKMDSession *mdSession,
01553     NSSCKFWSession *fwSession,
01554     NSSCKMDToken *mdToken,
01555     NSSCKFWToken *fwToken,
01556     NSSCKMDInstance *mdInstance,
01557     NSSCKFWInstance *fwInstance,
01558     NSSItem *buffer
01559   );
01560 
01561   /*
01562    */
01563   CK_RV (PR_CALLBACK *Sign)(
01564     NSSCKMDMechanism *mdMechanism,
01565     NSSCKFWMechanism *fwMechanism,
01566     NSSCKMDSession *mdSession,
01567     NSSCKFWSession *fwSession,
01568     NSSCKMDToken *mdToken,
01569     NSSCKFWToken *fwToken,
01570     NSSCKMDInstance *mdInstance,
01571     NSSCKFWInstance *fwInstance,
01572     NSSCKMDObject *mdKey,
01573     NSSCKFWObject *fwKey,
01574     NSSItem *data,
01575     NSSItem *buffer
01576   );
01577 
01578   /*
01579    */
01580   CK_RV (PR_CALLBACK *VerifyInit)(
01581     NSSCKMDMechanism *mdMechanism,
01582     NSSCKFWMechanism *fwMechanism,
01583     NSSCKMDSession *mdSession,
01584     NSSCKFWSession *fwSession,
01585     NSSCKMDToken *mdToken,
01586     NSSCKFWToken *fwToken,
01587     NSSCKMDInstance *mdInstance,
01588     NSSCKFWInstance *fwInstance,
01589     NSSCKFWObject *key
01590   );
01591 
01592   /*
01593    */
01594   CK_RV (PR_CALLBACK *VerifyUpdate)(
01595     NSSCKMDMechanism *mdMechanism,
01596     NSSCKFWMechanism *fwMechanism,
01597     NSSCKMDSession *mdSession,
01598     NSSCKFWSession *fwSession,
01599     NSSCKMDToken *mdToken,
01600     NSSCKFWToken *fwToken,
01601     NSSCKMDInstance *mdInstance,
01602     NSSCKFWInstance *fwInstance,
01603     NSSItem *data
01604   );
01605 
01606   /*
01607    */
01608   CK_RV (PR_CALLBACK *VerifyFinish)(
01609     NSSCKMDMechanism *mdMechanism,
01610     NSSCKFWMechanism *fwMechanism,
01611     NSSCKMDSession *mdSession,
01612     NSSCKFWSession *fwSession,
01613     NSSCKMDToken *mdToken,
01614     NSSCKFWToken *fwToken,
01615     NSSCKMDInstance *mdInstance,
01616     NSSCKFWInstance *fwInstance,
01617     NSSItem *buffer
01618   );
01619 
01620   /*
01621    */
01622   CK_RV (PR_CALLBACK *Verify)(
01623     NSSCKMDMechanism *mdMechanism,
01624     NSSCKFWMechanism *fwMechanism,
01625     NSSCKMDSession *mdSession,
01626     NSSCKFWSession *fwSession,
01627     NSSCKMDToken *mdToken,
01628     NSSCKFWToken *fwToken,
01629     NSSCKMDInstance *mdInstance,
01630     NSSCKFWInstance *fwInstance,
01631     NSSCKFWObject *key,
01632     NSSItem *data,
01633     NSSItem *buffer
01634   );
01635 
01636   /*
01637    */
01638   CK_RV (PR_CALLBACK *SignRecover)(
01639     NSSCKMDMechanism *mdMechanism,
01640     NSSCKFWMechanism *fwMechanism,
01641     NSSCKMDSession *mdSession,
01642     NSSCKFWSession *fwSession,
01643     NSSCKMDToken *mdToken,
01644     NSSCKFWToken *fwToken,
01645     NSSCKMDInstance *mdInstance,
01646     NSSCKFWInstance *fwInstance,
01647     NSSCKMDObject *mdKey,
01648     NSSCKFWObject *fwKey,
01649     NSSItem *data,
01650     NSSItem *buffer
01651   );
01652 
01653   /*
01654    */
01655   CK_RV (PR_CALLBACK *VerifyRecover)(
01656     NSSCKMDMechanism *mdMechanism,
01657     NSSCKFWMechanism *fwMechanism,
01658     NSSCKMDSession *mdSession,
01659     NSSCKFWSession *fwSession,
01660     NSSCKMDToken *mdToken,
01661     NSSCKFWToken *fwToken,
01662     NSSCKMDInstance *mdInstance,
01663     NSSCKFWInstance *fwInstance,
01664     NSSCKMDObject *mdKey,
01665     NSSCKFWObject *fwKey,
01666     NSSItem *data,
01667     NSSItem *buffer
01668   );
01669 
01670   /*
01671    */
01672   CK_RV (PR_CALLBACK *DigestEncryptUpdate)(
01673     NSSCKMDMechanism *mdMechanism,
01674     NSSCKFWMechanism *fwMechanism,
01675     NSSCKMDSession *mdSession,
01676     NSSCKFWSession *fwSession,
01677     NSSCKMDToken *mdToken,
01678     NSSCKFWToken *fwToken,
01679     NSSCKMDInstance *mdInstance,
01680     NSSCKFWInstance *fwInstance,
01681     NSSItem *data,
01682     NSSItem *buffer
01683   );
01684 
01685   /*
01686    */
01687   CK_RV (PR_CALLBACK *DecryptDigestUpdate)(
01688     NSSCKMDMechanism *mdMechanism,
01689     NSSCKFWMechanism *fwMechanism,
01690     NSSCKMDSession *mdSession,
01691     NSSCKFWSession *fwSession,
01692     NSSCKMDToken *mdToken,
01693     NSSCKFWToken *fwToken,
01694     NSSCKMDInstance *mdInstance,
01695     NSSCKFWInstance *fwInstance,
01696     NSSItem *data,
01697     NSSItem *buffer
01698   );
01699 
01700   /*
01701    */
01702   CK_RV (PR_CALLBACK *SignEncryptUpdate)(
01703     NSSCKMDMechanism *mdMechanism,
01704     NSSCKFWMechanism *fwMechanism,
01705     NSSCKMDSession *mdSession,
01706     NSSCKFWSession *fwSession,
01707     NSSCKMDToken *mdToken,
01708     NSSCKFWToken *fwToken,
01709     NSSCKMDInstance *mdInstance,
01710     NSSCKFWInstance *fwInstance,
01711     NSSItem *data,
01712     NSSItem *buffer
01713   );
01714 
01715   /*
01716    */
01717   CK_RV (PR_CALLBACK *DecryptVerifyUpdate)(
01718     NSSCKMDMechanism *mdMechanism,
01719     NSSCKFWMechanism *fwMechanism,
01720     NSSCKMDSession *mdSession,
01721     NSSCKFWSession *fwSession,
01722     NSSCKMDToken *mdToken,
01723     NSSCKFWToken *fwToken,
01724     NSSCKMDInstance *mdInstance,
01725     NSSCKFWInstance *fwInstance,
01726     NSSItem *data,
01727     NSSItem *buffer
01728   );
01729 
01730   /*
01731    * Key management operations.
01732    */
01733 
01734   /*
01735    * This routine generates a key.  This routine may return NULL
01736    * upon error.
01737    */
01738   NSSCKMDObject *(PR_CALLBACK *GenerateKey)(
01739     NSSCKMDMechanism *mdMechanism,
01740     NSSCKFWMechanism *fwMechanism,
01741     NSSCKMDSession *mdSession,
01742     NSSCKFWSession *fwSession,
01743     NSSCKMDToken *mdToken,
01744     NSSCKFWToken *fwToken,
01745     NSSCKMDInstance *mdInstance,
01746     NSSCKFWInstance *fwInstance,
01747     CK_ATTRIBUTE_PTR pTemplate,
01748     CK_ULONG ulAttributeCount,
01749     CK_RV *pError
01750   );
01751 
01752   /*
01753    * This routine generates a key pair.
01754    */
01755   CK_RV (PR_CALLBACK *GenerateKeyPair)(
01756     NSSCKMDMechanism *mdMechanism,
01757     NSSCKFWMechanism *fwMechanism,
01758     NSSCKMDSession *mdSession,
01759     NSSCKFWSession *fwSession,
01760     NSSCKMDToken *mdToken,
01761     NSSCKFWToken *fwToken,
01762     NSSCKMDInstance *mdInstance,
01763     NSSCKFWInstance *fwInstance,
01764     CK_ATTRIBUTE_PTR pPublicKeyTemplate,
01765     CK_ULONG ulPublicKeyAttributeCount,
01766     CK_ATTRIBUTE_PTR pPrivateKeyTemplate,
01767     CK_ULONG ulPrivateKeyAttributeCount,
01768     NSSCKMDObject **pPublicKey,
01769     NSSCKMDObject **pPrivateKey
01770   );
01771 
01772   /*
01773    * This routine wraps a key.
01774    */
01775   CK_RV (PR_CALLBACK *WrapKey)(
01776     NSSCKMDMechanism *mdMechanism,
01777     NSSCKFWMechanism *fwMechanism,
01778     NSSCKMDSession *mdSession,
01779     NSSCKFWSession *fwSession,
01780     NSSCKMDToken *mdToken,
01781     NSSCKFWToken *fwToken,
01782     NSSCKMDInstance *mdInstance,
01783     NSSCKFWInstance *fwInstance,
01784     NSSCKMDObject *mdWrappingKey,
01785     NSSCKFWObject *fwWrappingKey,
01786     NSSCKMDObject *mdWrappedKey,
01787     NSSCKFWObject *fwWrappedKey,
01788     NSSItem *buffer
01789   );
01790 
01791   /*
01792    * This routine unwraps a key.  This routine may return NULL
01793    * upon error.
01794    */
01795   NSSCKMDObject *(PR_CALLBACK *UnwrapKey)(
01796     NSSCKMDMechanism *mdMechanism,
01797     NSSCKFWMechanism *fwMechanism,
01798     NSSCKMDSession *mdSession,
01799     NSSCKFWSession *fwSession,
01800     NSSCKMDToken *mdToken,
01801     NSSCKFWToken *fwToken,
01802     NSSCKMDInstance *mdInstance,
01803     NSSCKFWInstance *fwInstance,
01804     NSSCKMDObject *mdWrappingKey,
01805     NSSCKFWObject *fwWrappingKey,
01806     NSSItem *wrappedKey,
01807     CK_ATTRIBUTE_PTR pTemplate,
01808     CK_ULONG ulAttributeCount,
01809     CK_RV *pError
01810   );    
01811     
01812   /*
01813    * This routine derives a key.  This routine may return NULL
01814    * upon error.
01815    */
01816   NSSCKMDObject *(PR_CALLBACK *DeriveKey)(
01817     NSSCKMDMechanism *mdMechanism,
01818     NSSCKFWMechanism *fwMechanism,
01819     NSSCKMDSession *mdSession,
01820     NSSCKFWSession *fwSession,
01821     NSSCKMDToken *mdToken,
01822     NSSCKFWToken *fwToken,
01823     NSSCKMDInstance *mdInstance,
01824     NSSCKFWInstance *fwInstance,
01825     NSSCKMDObject *mdBaseKey,
01826     NSSCKFWObject *fwBaseKey,
01827     CK_ATTRIBUTE_PTR pTemplate,
01828     CK_ULONG ulAttributeCount,
01829     CK_RV *pError
01830   );    
01831 
01832   /*
01833    * This object may be extended in future versions of the
01834    * NSS Cryptoki Framework.  To allow for some flexibility
01835    * in the area of binary compatibility, this field should
01836    * be NULL.
01837    */
01838   void *null;
01839 };
01840 
01841 /*
01842  * NSSCKMDObject
01843  *
01844  * This is the basic handle for any object used by a PKCS#11 Module.
01845  * Modules must implement it if they support their own objects, and
01846  * the Framework supports it for Modules that do not handle session
01847  * objects.  This type contains a pointer for use by the implementor,
01848  * to store any object-specific data, and it contains an EPV for a
01849  * set of routines used to access the object.
01850  */
01851 
01852 struct NSSCKMDObjectStr {
01853   /*
01854    * The implementation my use this pointer for its own purposes.
01855    */
01856   void *etc;
01857 
01858   /*
01859    * This routine is called by the Framework when it is letting
01860    * go of an object handle.  It can be used by the Module to
01861    * free any resources tied up by an object "in use."  It is
01862    * optional.
01863    */
01864   void (PR_CALLBACK *Finalize)(
01865     NSSCKMDObject *mdObject,
01866     NSSCKFWObject *fwObject,
01867     NSSCKMDSession *mdSession,
01868     NSSCKFWSession *fwSession,
01869     NSSCKMDToken *mdToken,
01870     NSSCKFWToken *fwToken,
01871     NSSCKMDInstance *mdInstance,
01872     NSSCKFWInstance *fwInstance
01873   );
01874 
01875   /*
01876    * This routine is used to completely destroy an object.
01877    * It is optional.  The parameter fwObject might be NULL
01878    * if the framework runs out of memory at the wrong moment.
01879    */
01880   CK_RV (PR_CALLBACK *Destroy)(
01881     NSSCKMDObject *mdObject,
01882     NSSCKFWObject *fwObject,
01883     NSSCKMDSession *mdSession,
01884     NSSCKFWSession *fwSession,
01885     NSSCKMDToken *mdToken,
01886     NSSCKFWToken *fwToken,
01887     NSSCKMDInstance *mdInstance,
01888     NSSCKFWInstance *fwInstance
01889   );
01890 
01891   /*
01892    * This helper routine is used by the Framework, and is especially
01893    * useful when it is managing session objects on behalf of the
01894    * Module.  This routine is optional; if unimplemented, the
01895    * Framework will actually look up the CKA_TOKEN attribute.  In the
01896    * event of an error, just make something up-- the Framework will
01897    * find out soon enough anyway.
01898    */
01899   CK_BBOOL (PR_CALLBACK *IsTokenObject)(
01900     NSSCKMDObject *mdObject,
01901     NSSCKFWObject *fwObject,
01902     NSSCKMDSession *mdSession,
01903     NSSCKFWSession *fwSession,
01904     NSSCKMDToken *mdToken,
01905     NSSCKFWToken *fwToken,
01906     NSSCKMDInstance *mdInstance,
01907     NSSCKFWInstance *fwInstance
01908   );
01909 
01910   /*
01911    * This routine returns the number of attributes of which this
01912    * object consists.  It is mandatory.  It can return zero on
01913    * error.
01914    */
01915   CK_ULONG (PR_CALLBACK *GetAttributeCount)(
01916     NSSCKMDObject *mdObject,
01917     NSSCKFWObject *fwObject,
01918     NSSCKMDSession *mdSession,
01919     NSSCKFWSession *fwSession,
01920     NSSCKMDToken *mdToken,
01921     NSSCKFWToken *fwToken,
01922     NSSCKMDInstance *mdInstance,
01923     NSSCKFWInstance *fwInstance,
01924     CK_RV *pError
01925   );
01926 
01927   /*
01928    * This routine stuffs the attribute types into the provided array.
01929    * The array size (as obtained from GetAttributeCount) is passed in
01930    * as a check; return CKR_BUFFER_TOO_SMALL if the count is wrong
01931    * (either too big or too small).
01932    */
01933   CK_RV (PR_CALLBACK *GetAttributeTypes)(
01934     NSSCKMDObject *mdObject,
01935     NSSCKFWObject *fwObject,
01936     NSSCKMDSession *mdSession,
01937     NSSCKFWSession *fwSession,
01938     NSSCKMDToken *mdToken,
01939     NSSCKFWToken *fwToken,
01940     NSSCKMDInstance *mdInstance,
01941     NSSCKFWInstance *fwInstance,
01942     CK_ATTRIBUTE_TYPE_PTR typeArray,
01943     CK_ULONG ulCount
01944   );
01945 
01946   /*
01947    * This routine returns the size (in bytes) of the specified
01948    * attribute.  It can return zero on error.
01949    */
01950   CK_ULONG (PR_CALLBACK *GetAttributeSize)(
01951     NSSCKMDObject *mdObject,
01952     NSSCKFWObject *fwObject,
01953     NSSCKMDSession *mdSession,
01954     NSSCKFWSession *fwSession,
01955     NSSCKMDToken *mdToken,
01956     NSSCKFWToken *fwToken,
01957     NSSCKMDInstance *mdInstance,
01958     NSSCKFWInstance *fwInstance,
01959     CK_ATTRIBUTE_TYPE attribute,
01960     CK_RV *pError
01961   );
01962 
01963   /*
01964    * This routine returns an NSSCKFWItem structure.
01965    * The item pointer points to an NSSItem containing the attribute value.
01966    * The needsFreeing bit tells the framework whether to call the
01967    * FreeAttribute function . Upon error, an NSSCKFWItem structure
01968    * with a NULL NSSItem item pointer will be returned
01969    */
01970   NSSCKFWItem (PR_CALLBACK *GetAttribute)(
01971     NSSCKMDObject *mdObject,
01972     NSSCKFWObject *fwObject,
01973     NSSCKMDSession *mdSession,
01974     NSSCKFWSession *fwSession,
01975     NSSCKMDToken *mdToken,
01976     NSSCKFWToken *fwToken,
01977     NSSCKMDInstance *mdInstance,
01978     NSSCKFWInstance *fwInstance,
01979     CK_ATTRIBUTE_TYPE attribute,
01980     CK_RV *pError
01981   );
01982 
01983   /*
01984    * This routine returns CKR_OK if the attribute could be freed.
01985    */
01986   CK_RV (PR_CALLBACK *FreeAttribute)(
01987     NSSCKFWItem * item
01988   );
01989 
01990   /*
01991    * This routine changes the specified attribute.  If unimplemented,
01992    * the object will be considered read-only.
01993    */
01994   CK_RV (PR_CALLBACK *SetAttribute)(
01995     NSSCKMDObject *mdObject,
01996     NSSCKFWObject *fwObject,
01997     NSSCKMDSession *mdSession,
01998     NSSCKFWSession *fwSession,
01999     NSSCKMDToken *mdToken,
02000     NSSCKFWToken *fwToken,
02001     NSSCKMDInstance *mdInstance,
02002     NSSCKFWInstance *fwInstance,
02003     CK_ATTRIBUTE_TYPE attribute,
02004     NSSItem *value
02005   );
02006 
02007   /*
02008    * This routine returns the storage requirements of this object,
02009    * in bytes.  Cryptoki doesn't strictly define the definition,
02010    * but it should relate to the values returned by the "Get Memory"
02011    * routines of the NSSCKMDToken.  This routine is optional; if
02012    * unimplemented, the Framework will consider this information
02013    * sensitive.  This routine may return zero on error.  If the
02014    * specified error is CKR_OK, zero will be accepted as a valid
02015    * response.
02016    */
02017   CK_ULONG (PR_CALLBACK *GetObjectSize)(
02018     NSSCKMDObject *mdObject,
02019     NSSCKFWObject *fwObject,
02020     NSSCKMDSession *mdSession,
02021     NSSCKFWSession *fwSession,
02022     NSSCKMDToken *mdToken,
02023     NSSCKFWToken *fwToken,
02024     NSSCKMDInstance *mdInstance,
02025     NSSCKFWInstance *fwInstance,
02026     CK_RV *pError
02027   );
02028 
02029   /*
02030    * This object may be extended in future versions of the
02031    * NSS Cryptoki Framework.  To allow for some flexibility
02032    * in the area of binary compatibility, this field should
02033    * be NULL.
02034    */
02035   void *null;
02036 };
02037 
02038 
02039 #endif /* NSSCKMDT_H */