index.rst (17657B)
1 .. _mozilla_projects_nss_pkcs11_module_specs: 2 3 PKCS #11 Module Specs 4 ===================== 5 6 .. _pkcs_.2311_module_specs: 7 8 `PKCS #11 Module Specs <#pkcs_.2311_module_specs>`__ 9 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 10 11 .. container:: 12 13 The following is a proposal to the `PKCS <https://en.wikipedia.org/wiki/PKCS>`__ #11 working 14 group made in August 2001 for configuring PKCS #11 modules. NSS currently implements this 15 proposal internally. 16 17 The file format consists of name/value pairs of the form ``name=value``. Each name/value pair is 18 separated by a blank value. A single line, terminated by a '\n', '\r\n', or '\r' represents a 19 single pkcs #11 library. 20 21 Names can be any alpha/numeric combination, and are parsed case-insensitive. 22 23 Values can contain any printable ASCII value, including UTF8 characters. Values can contain 24 embedded blanks either through quoting the entire value, or by escaping the embedded blanks with 25 '\'. The value is considered quoted if the first character after the '=' is ', ", {, [, or <. If 26 the value is quoted, then the value is terminated with and ending quote of the form ', ", ), ], 27 }, or > matching the respective starting quote. Ending quotes can be escaped. Embedded '\' 28 characters are considered escape characters for the next character in the stream. Note that case 29 must be preserved in the values. 30 31 These modules specs can be passed by the application directly to NSS via the 32 ``SECMOD_LoadUserModule()`` call. To initialize a PKCS #11 module 'on-the-fly'. 33 34 .. rubric:: Recognized Names 35 :name: recognized_names 36 37 All applications/libraries must be able recognize the following name values: 38 39 library 40 This specifies the path to the pkcs #11 library. 41 name 42 This specifies the name of the pkcs #11 library. 43 parameter 44 This specifies a pkcs #11 library parameter with the application must pass to the pkcs #11 45 library at ``C_Initialize()`` time (see below). 46 47 In additions applications/libraries should be able to ignore additional name value pairs which 48 are used to specify configuration for other applications. Of course these application/libraries 49 should be able to parse their own name/value pairs. 50 51 Each of these name/value pairs are optional. 52 53 If the library is not specified, the line represents some application specific meta configuration 54 data. Other applications and libraries can safely ignore this line. 55 56 If the name is not specified, the application can use the library path to describe the PKCS #11 57 library in any UI it may have. 58 59 If the parameter is not specified, no parameters are passed to the PKCS #11 module. 60 61 If the application/library does not find its application/library specific data, it should use 62 it's defaults for this pkcs #11 library. 63 64 .. rubric:: Parameter Passing 65 :name: parameter_passing 66 67 If the parameter is specified, the application/library will strip the value out, processing any 68 outter quotes and escapes appropriately, and pass the parameter to the pkcs #11 library when it 69 calls ``C_Initialize()``. 70 71 A new ``CK_C_INITIALIZE_ARGS`` structure is defined as 72 73 .. code:: 74 75 typedef struct CK_C_INITIALIZE_ARGS { 76 CK_CREATEMUTEX CreateMutex; 77 CK_DESTROYMUTEX DestroyMutex; 78 CK_LOCKMUTEX LockMutex; 79 CK_UNLOCKMUTEX UnlockMutex; 80 CK_FLAGS flags; 81 CK_VOID_PTR LibraryParameters; 82 CK_VOID_PTR pReserved; 83 } CK_C_INITIALIZE_ARGS; 84 85 Applications/libraries must set LibraryParameters to ``NULL`` if no parameter value is specified. 86 PKCS #11 libraries which accept parameters must check if the 'new' ``pReserved`` field is 87 ``NULL`` if and only if ``LibraryParameters`` field is not ``NULL``. 88 89 .. _nss_specific_parameters_in_module_specs: 90 91 `NSS Specific Parameters in Module Specs <#nss_specific_parameters_in_module_specs>`__ 92 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 93 94 .. container:: 95 96 Here are the NSS Application specific parameters in use. This data is currently stored in 97 ``secmod.db`` or pkcs11.txt. This isn't part of the generic spec (that is other applications need 98 not parse it, nor pkcs #11 modules need supply them or use them). 99 100 .. code:: 101 102 NSS="nss_params" 103 104 ``nss_params`` are themselves name/value pairs, parsed with the same rules described above. Valid 105 names inside ``nss_params`` are: 106 107 flags 108 comma separated list of flag values, parsed case-insensitive. 109 Valid flag values are: 110 111 internal 112 this library is actually the Netscape internal library 113 fips 114 this library is the Netscape internal fips library. 115 critical 116 if this library cannot be loaded, completely fail initialization. 117 moduleDB 118 this library includes NSS specific functions to supply additional module specs for loading. 119 **moduleDBOnly** - this library has no PKCS #11 functions and is only used for loading 120 additional modules. 121 trustOrder 122 integer value specifying the order in which the trust information for certificates specified 123 by tokens on this PKCS #11 library should be rolled up. A value of 0 means that tokens on this 124 library should not supply trust information. The default trust order value is 50. The relative 125 order of two pkcs#11 libraries which have the same trustOrder value is undefined. 126 cipherOrder 127 integer value specifiying the order in which tokens are searched when looking for a token to 128 do a generic operation (DES/Hashing, etc). 129 ciphers 130 comma separated list of ciphers this token will enable that isn't already enabled by the 131 library (currently only **FORTEZZA** is defined) (case-insensitive). 132 slotParams 133 space separated list of name/value pairs where the name is a slotID and the value is a space 134 separated list of parameters related to that slotID. Valid slotParams values are: 135 136 slotFlags 137 comma separated list of cipher groups which this slot is expected to be the default 138 implementation for (case-insensitive). 139 Valid flags are: 140 141 RSA 142 This token should be used for all RSA operations (other than Private key operations 143 where the key lives in another token). 144 DSA 145 This token should be used for all DSA operations (other than Private key operations 146 where the key lives in another token). 147 RC4 148 This token should be used for all RC4 operations which are not constrained by an 149 existing key in another token. 150 RC2 151 This token should be used for all RC2 operations which are not constrained by an 152 existing key in another token. 153 DES 154 This token should be used for all DES, DES2, and DES3 operations which are not 155 constrained by an existing key in another token. 156 DH 157 This token should be used for all DH operations (other than Private key operations where 158 the key lives in another token). 159 FORTEZZA 160 This token should be used for all KEA operations (other than Private key operations 161 where the key lives in another token), as well as SKIPJACK operations which are not 162 constrained by an existing key in another token. 163 RC5 164 This token should be used for all RC5 operations which are not constrained by an 165 existing key in another token. 166 SHA1 167 This token should be used for all basic SHA1 hashing. 168 MD5 169 This token should be used for all basic MD5 hashing. 170 MD2 171 This token should be used for all basic MD2 hashing. 172 SSL 173 This token should be used for SSL key derivation which are not constrained by an 174 existing key in another token. 175 TLS 176 This token should be used for TLS key derivation which are not constrained by an 177 existing key in another token. 178 AES 179 This token should be used for all AES operations which are not constrained by an 180 existing key in another token. 181 RANDOM 182 This token should be used to generate random numbers when the application call 183 'PK11_GenerateRandom'. 184 PublicCerts 185 The certificates on this token can be read without authenticating to this token, and any 186 user certs on this token have a matching public key which is also readable without 187 authenticating. Setting this flags means NSS will not try to authenticate to the token 188 when searching for Certificates. This removes spurious password prompts, but if 189 incorrectly set it can also cause NSS to miss certificates in a token until that token 190 is explicitly logged in. 191 rootFlags 192 comma separated of flags describing any root certs that may be stored (case-insensitive). 193 Valid flags are: 194 195 hasRootCerts 196 claims that this token has the default root certs and trust values. At init time NSS, 197 will try to look for a default root cert device if one has not already been loaded. 198 hasRootTrust 199 parsed but ignored. 200 timeout 201 time in minutes before the current authentication should be rechecked. This value is only 202 used if askpwd is set to 'timeout'. (default = 0). 203 askpwd 204 case-insensitive flag describing how password prompts should be manages. Only one of the 205 following can be specified. 206 207 every 208 prompt whenever the a private key on this token needs to be access (this is on the 209 entire token, not on a key-by-key basis. 210 timeout 211 whenever the last explicit login was longer than 'timeout' minutes ago. 212 only 213 authenticate to the token only when necessary (default). 214 215 Sample file: 216 217 .. code:: 218 219 library= name="Netscape Internal Crypto Module" parameters="configdir=/u/relyea/.netscape certprefix= secmod=secmod.db" NSS="Flags=internal,pkcs11module TrustOrder=1 CipherOrder=-1 ciphers= slotParams={0x1=[slotFlags='RSA,DSA,DH,RC4,RC2,DES,MD2,MD5,SHA1,SSL,TLS,PublicCerts,Random'] 0x2=[slotFlags='RSA' askpw=only]}" 220 library=dkck32.dll name="DataKey SignaSURE 3600" NSS="TrustOrder=50 ciphers= " 221 library=swft32.dll name="Netscape Software Fortezza" parameters="keyfile=/u/relyea/keyfile" NSS="TrustOrder=50 ciphers=FORTEZZA slotParams=0x1=[slotFlags='FORTEZZA']" 222 library=core32.dll name="Litronic Netsign" 223 224 .. _softoken_specific_parameters: 225 226 `Softoken Specific Parameters <#softoken_specific_parameters>`__ 227 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 228 229 .. container:: 230 231 The internal NSS PKCS #11 implementation (softoken) requires Applications parameters. It will not 232 initialize if the **parameters**\ = is not specified. If another application wishes to load the 233 softoken, that application must supply a non-``NULL`` ``libraryParameters`` value in the 234 ``CK_C_INITIALIZE_ARGS`` structure passed at ``C_INITIALIZE`` time. The parameter passed to 235 softoken is a space separated list of name/value pairs exactly like those specified in the PKCS 236 #11 module spec. 237 238 Valid values are: 239 240 configDir 241 Configuration Directory where NSS can store persistant state information (typically 242 databases). 243 secmod 244 Name of the secmod database (default = secmod.db). 245 certPrefix 246 Prefix for the cert database. 247 keyPrefix 248 Prefix for the key database. 249 minPWLen 250 Minimum password length in bytes. 251 manufacturerID 252 Override the default ``manufactureID`` value for the module returned in the ``CK_INFO``, 253 ``CK_SLOT_INFO``, and ``CK_TOKEN_INFO`` structures with an internationalize string (UTF8). 254 This value will be truncated at 32 bytes (no NULL, partial UTF8 characters dropped). 255 libraryDescription 256 Override the default ``libraryDescription`` value for the module returned in the ``CK_INFO`` 257 structure with an internationalize string (UTF8). This value will be truncated at 32 bytes (no 258 ``NULL``, partial UTF8 characters dropped). 259 cryptoTokenDescription 260 Override the default label value for the internal crypto token returned in the 261 ``CK_TOKEN_INFO`` structure with an internationalize string (UTF8). This value will be 262 truncated at 32 bytes (no NULL, partial UTF8 characters dropped). 263 dbTokenDescription 264 Override the default label value for the internal DB token returned in the ``CK_TOKEN_INFO`` 265 structure with an internationalize string (UTF8). This value will be truncated at 32 bytes (no 266 NULL, partial UTF8 characters dropped). 267 FIPSTokenDescription 268 Override the default label value for the internal FIPS token returned in the ``CK_TOKEN_INFO`` 269 structure with an internationalize string (UTF8). This value will be truncated at 32 bytes (no 270 NULL, partial UTF8 characters dropped). 271 cryptoSlotDescription 272 Override the default ``slotDescription`` value for the internal crypto token returned in the 273 ``CK_SLOT_INFO`` structure with an internationalize string (UTF8). This value will be 274 truncated at 64 bytes (no NULL, partial UTF8 characters dropped). 275 dbSlotDescription 276 Override the default ``slotDescription`` value for the internal DB token returned in the 277 ``CK_SLOT_INFO`` structure with an internationalize string (UTF8). This value will be 278 truncated at 64 bytes (no NULL, partial UTF8 characters dropped). 279 FIPSSlotDescription 280 Override the default ``slotDescription`` value for the internal FIPS token returned in the 281 ``CK_SLOT_INFO`` structure with an internationalize string (UTF8). This value will be 282 truncated at 64 bytes (no NULL, partial UTF8 characters dropped). 283 flags 284 comma separated list of flag values, parsed case-insensitive. 285 286 .. rubric:: Flags 287 :name: flags 288 289 Valid flags are: 290 291 noModDB 292 Don't open ``secmod.db`` and try to supply the strings. The MOD DB function is not through 293 standard PKCS #11 interfaces. 294 readOnly 295 Databases should be opened read only. 296 noCertDB 297 Don't try to open a certificate database. 298 noKeyDB 299 Don't try to open a key database. 300 forceOpen 301 Don't fail to initialize the token if the databases could not be opened. 302 passwordRequired 303 Zero length passwords are not acceptable (valid only if there is a keyDB). 304 optimizeSpace 305 allocate smaller hash tables and lock tables. When this flag is not specified, Softoken will 306 allocate large tables to prevent lock contention. 307 tokens 308 configure 'tokens' by hand. The tokens parameter specifies a space separated list of slotIDS, 309 each of which specify their own set of parameters affecting that token. Typically 'tokens' 310 would not be specified unless additional databases are to be opened as additional tokens. If 311 tokens is specified, then all tokens (including the default tokens) need to be specified. If 312 tokens is not specified, then softoken would default to the following specs: 313 314 In non-FIPS mode: 315 316 .. code:: 317 318 tokens=<0x01=[configDir=configDir tokenDescription=cryptoTokenDescription slotDescription=cryptoSlotDescription flags=noCertDB,noKeyDB,optimizeSpace] 0x02=[configDir=configDir tokenDescription=dbTokenDescription slotDescription=dbSlotDescription certPrefix=certPrefix keyPrefix=keyPrefix flags=flags minPWLen=minPWLen]> 319 320 In FIPS mode: 321 322 .. code:: 323 324 tokens=<0x03=[configDir=configDir tokenDescription=FIPSTokenDescription slotDescription=FIPSSlotDescription certPrefix=certPrefix keyPrefix=keyPrefix flags=flags minPWLen=minPWLen]> 325 326 where *configDir*, *cryptoTokenDescription*, *cryptoSlotDescription*, *dbTokenDescription*, 327 *dbSlotDescription*, *FIPSTokenDescription*, *FIPSSlotDescription*, *optimizeSpace*, 328 *certPrefix*, *keyPrefix*, *flags*, and *minPWLen* are copied from the parameters above. 329 330 Parameters: 331 332 configDir 333 The location of the databases for this token. If ``configDir`` is not specified, the default 334 ``configDir`` specified earlier will be used. 335 certPrefix 336 Cert prefix for this token. 337 keyPrefix 338 Prefix for the key database for this token. 339 tokenDescription 340 The label value for this token returned in the ``CK_TOKEN_INFO`` structure with an 341 internationalize string (UTF8). This value will be truncated at 32 bytes (no NULL, partial 342 UTF8 characters dropped). 343 slotDescription 344 The ``slotDescription`` value for this token returned in the ``CK_SLOT_INFO`` structure with 345 an internationalize string (UTF8). This value will be truncated at 64 bytes (no NULL, partial 346 UTF8 characters dropped). 347 minPWLen 348 minimum password length for this token. 349 flags 350 comma separated list of flag values, parsed case-insensitive. 351 Valid flags are: 352 353 readOnly 354 Databases should be opened read only. 355 noCertDB 356 Don't try to open a certificate database. 357 noKeyDB 358 Don't try to open a key database. 359 forceOpen 360 Don't fail to initialize the token if the databases could not be opened. 361 passwordRequired 362 Zero length passwords are not acceptable (valid only if there is a ``keyDB``). 363 optimizeSpace 364 allocate smaller hash tables and lock tables. When this flag is not specified, Softoken 365 will allocate large tables to prevent lock contention.