|
|
| (47 intermediate revisions by 8 users not shown) |
| Line 5: |
Line 5: |
| NSS is available under the Mozilla Public License, the GNU General Public License, and the GNU Lesser General Public License. For information on downloading NSS releases as tar files, see Download PKI Source. | | NSS is available under the Mozilla Public License, the GNU General Public License, and the GNU Lesser General Public License. For information on downloading NSS releases as tar files, see Download PKI Source. |
|
| |
|
| Mozilla NSS documentation can be found at [http://www.mozilla.org/projects/security/pki/nss/].
| | NSS documentation can be found at [https://developer.mozilla.org/en/docs/NSS]. |
| NSS is undergoing it's third round of [[FIPS Validation]]. | |
|
| |
|
| == PKCS #11 Module Specs == | | == Supported Architectures == |
|
| |
|
| The following is a proposal to the PKCS #11 working group made in August 2001 for configuring PKCS #11 modules. NSS currently implements this proposal internally.
| | Platforms officially supported by NSS are those tested by our [[NSS:TryServer|Continuous Integration environment]]: |
| | * Linux on x86-32, x86-64, aarch64 |
| | * Windows 2012+ on x86-32, and x86-64 |
| | * MacOS 10.9+ on x86-64 |
|
| |
|
| The file format consists of name/value pairs of the form ''name''=''value''.
| | Other platforms are utilize community support, primarily via the [https://groups.google.com/forum/#!forum/mozilla.dev.tech.crypto mozilla.dev.tech.crypto mailing list]. |
| Each name/value pair is separated by a blank value. A single line,
| |
| terminated by a '\n', '\r\n', or '\r' represents a single pkcs #11 library.
| |
|
| |
|
| Names can be any alpha/numeric combination, and are parsed case-insensitive.
| | Building and Testing NSS for Android can be found [[NSS:Android| here]] |
|
| |
|
| Values can contain any printable ascii value, including UTF8 characters.
| | == Internal Documentation == |
| Values can contain imbedded blanks either through quoting the entire
| | NSS internal documentation is here, including: |
| value, or by escaping the imbedded blanks with '\'. The value is
| | * The fourth round of [[FIPS Validation]], which finished in August 2007. A new round is underway in 2019. |
| considered quoted if the first character after the '=' is ', ", {, [,
| | * [[PSM:CertPrompt|PSM Certificate Prompting Scenarios]] |
| (, or <. If the value is quoted, then the value is terminated with and
| | <!-- *Please visit our [[NSS:Roadmap|NSS Roadmap page here]] --> |
| ending quote of the form ', ", ), ], }, or > matching the respective
| | <!-- *[[NSS:Branch_Status|NSS trunk and branch status]] --> |
| starting quote. Ending quotes can be escaped. Imbedded '\' charaters are
| | <!-- *[[NSS:Tags|NSS tags and branches history]] --> |
| considered escape characters for the next character in the stream. Note
| | * [[NSS:Root certs|NSS root certificates and policies]] |
| that case must be preserved in the values.
| | * [[NSS:Development|NSS Development]] |
| | * [[NSS:Tracing|Tracing]] |
| | * [[NSS/Bug_Triage|Bug Triage]] |
| | * [[NSS/Release Management|Release Management]] |
| | * [[NSS:Release_Versions|Release Versions]] |
| | * [[NSS:Versions|Versions]] |
| | * [[NSS:TryServer|NSS Try Server]] |
| | * [[NSS/Build System|Gyp Build System]] |
| | * [[NSS/BoGo_Tests|BoGo Tests]] |
| | * [[NSS/C++|C++]] |
|
| |
|
| === Recognized Names: ===
| | [[Category:NSS]] |
| | |
| All applications/libraries must be able recognize the following name values:
| |
| | |
| '''library''' - This specifies the path to the pkcs #11 library.
| |
| '''name''' - This specifies the name of the pkcs #11 library.
| |
| '''parameter''' - This specifies a pkcs #11 library parameter with the application must pass to the pkcs #11 library at C_Initialize() time (see below).
| |
| | |
| In additions applications/libraries should be able to ignore additional
| |
| name value pairs which are used to specify configuration for other applications.
| |
| Of course these application/libraries should be able to parse their own
| |
| name/value pairs.
| |
| | |
| Each of these name/value pairs are optional.
| |
| | |
| If the library is not specified, the line represents some application
| |
| specific meta configuration data. Other applications and libraries can
| |
| safely ignore this line.
| |
| | |
| If the name is not specified, the application can use the library path
| |
| to describe the PKCS #11 library in any UI it may have.
| |
| | |
| If the parameter is not specified, no parameters are passed to the PKCS #11 module.
| |
| | |
| If the application/library does not find its application/library
| |
| specific data, it should use it's defaults for this pkcs #11 library.
| |
| | |
| === Parameter Passing: ===
| |
| | |
| If the parameter is specified, the application/library will strip the
| |
| value out, processing any outter quotes and escapes appropriately, and
| |
| pass the parameter to the pkcs #11 library when it calls C_Initialize().
| |
| | |
| A new CK_C_INITIALIZE_ARGS structure is defined as
| |
| | |
| <pre>
| |
| typedef struct CK_C_INITIALIZE_ARGS {
| |
| CK_CREATEMUTEX CreateMutex;
| |
| CK_DESTROYMUTEX DestroyMutex;
| |
| CK_LOCKMUTEX LockMutex;
| |
| CK_UNLOCKMUTEX UnlockMutex;
| |
| CK_FLAGS flags;
| |
| CK_VOID_PTR LibraryParameters;
| |
| CK_VOID_PTR pReserved;
| |
| } CK_C_INITIALIZE_ARGS;
| |
| </pre>
| |
| | |
| Applications/libraries must set LibraryParameters to NULL if no
| |
| parameter value is specified. PKCS #11 libraries which accept parameters
| |
| must check if the 'new' pReserved field is NULL if and only if
| |
| LibraryParameters field is not NULL.
| |
| | |
| == NSS Specific Parameters in Module Specs ==
| |
| | |
| Here are the NSS Application specific parameters in use.
| |
| This data is currently store in secmod.db. This isn't part of the
| |
| generic spec (that is other applications need not parse it, nor pkcs #11
| |
| modules need supply them.
| |
| | |
| '''NSS'''="''nss_params''"
| |
| ''nss_params'' are themselves name/value pairs, parsed with the same rules described above. Valid names inside nss_params are:
| |
| '''flags''' - comma separated list of flag values, parsed case-insensitive.
| |
| Valid flag values are:
| |
| '''internal''' - this library is actually the Netscape internal library
| |
| '''fips''' - this library is the Netscape internal fips library.
| |
| '''critical''' - if this library cannot be loaded, completely fail initialization
| |
| '''moduleDB''' - this library includes NSS specific functions to supply additional module specs for loading.
| |
| '''moduleDBOnly''' - this library has no PKCS #11 functions and is only used for loading additional modules.
| |
| '''trustOrder''' - integer value specifying the order in which the trust information for certificates specified by tokens on this PKCS #11 library should be rolled up. '0' means that tokens on this library should not supply trust information (default). The relative order of two pkcs#11 libraries which have the same trustOrder value is undefined.
| |
| '''cipherOrder''' - integer value specifiying the order in which tokens are searched when looking for a token to do a generic operation (DES/Hashing, etc).
| |
| '''ciphers''' - comma separated list of ciphers this token will enable that isn't already enabled by the library (currently only '''FORTEZZA''' is defined) (case-insensitive)..
| |
| '''slotParams''' - space separated list of name/value pairs where the name is a slotID and the value is a space sparated list of parameters related to that slotID.
| |
| Valid slotParams values are:
| |
| '''slotFlags''' - comma separated list of cipher groups which this slot is expected to be the default implementation for (case-insensitive).
| |
| Valid flags are:
| |
| '''RSA''' - This token should be used for all RSA operations (other than Private key operations where the key lives in another token).
| |
| '''DSA''' - This token should be used for all DSA operations (other than Private key operations where the key lives in another token).
| |
| '''RC4''' - This token should be used for all RC4 operations which are not constrained by an existing key in another token.
| |
| '''RC2''' - This token should be used for all RC2 operations which are not constrained by an existing key in another token.
| |
| '''DES''' - This token should be used for all DES, DES2, and DES3 operations which are not constrained by an existing key in another token.
| |
| '''DH''' - This token should be used for all DH operations (other than Private key operations where the key lives in another token).
| |
| '''FORTEZZA'''- This token should be used for all KEA operations (other than Private key operations where the key lives in another token), as well as SKIPJACK operations which are not constrained by an existing key in another token.
| |
| '''RC5''' - This token should be used for all RC5 operations which are not constrained by an existing key in another token.
| |
| '''SHA1''' - - This token should be used for all basic SHA1 hashing.
| |
| '''MD5''' - This token should be used for all basic MD5 hashing.
| |
| '''MD2''' - This token should be used for all basic MD2 hashing.
| |
| '''SSL''' - This token should be used for SSL key derivation which are not constrained by an existing key in another token.
| |
| '''TLS''' - This token should be used for TLS key derivation which are not constrained by an existing key in another token.
| |
| '''AES''' - This token should be used for all AES operations which are not constrained by an existing key in another token.
| |
| '''RANDOM''' - This token should be used to generate random numbers when the application call 'PK11_GenerateRandom'.
| |
| '''PublicCerts''' - The certificates on this token can be read without authenticating to this token, and any user certs on this token have a patching public key which is also readable without authenticating.
| |
|
| |
| '''rootFlags''' - comma separated of flags describing any root certs that may be stored (case-insensitive).
| |
| Valid flags are:
| |
| '''hasRootCerts'''
| |
| '''hasRootTrust'''
| |
| '''timeout''' - time in minutes before the current authentication should be rechecked.
| |
| '''askpwd''' - case-insensitive flag describing how password prompts should be manages:
| |
| '''every'''
| |
| '''timeout'''
| |
| '''only'''
| |
| | |
| | |
| Sample file:
| |
| <pre>
| |
| 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' timeout=50 askpw=only]}"
| |
| library=dkck32.dll name="DataKey SignaSURE 3600" NSS="TrustOrder=50 ciphers= "
| |
| library=swft32.dll name="Netscape Software Fortezza" parameters="keyfile=/u/relyea/keyfile" NSS="TrustOrder=50 ciphers=FORTEZZA slotParams=0x1=[slotFlags='FORTEZZA']"
| |
| library=core32.dll name="Litronic Netsign"
| |
| </pre>
| |
| | |
| == Softoken Specific Parameters ==
| |
| | |
| The internal NSS PKCS #11 implementation (softoken) requires Applications parameters. It will not initialize if the '''parameters'''= is not specified.
| |
| If another application wishes to load the softoken, that application must supply a non-NULL libraryParameters value in the CK_C_INITIALIZE_ARGS structure passed at C_INITIALIZE time. The parameter passed to softoken is a space separated list of name/value pairs exactly like those specified in the PKCS #11 module spec. Valid values are:
| |