Skip to content

Working with NSS keystores

Eric Devolder edited this page Dec 10, 2018 · 2 revisions

Introduction

NSS can be used as a PKCS#11 token; it does expose a PKCS#11-compatible API, excepting for the call to C_Initialize(). Hopefully, the pkcs11-toolkit can handle the specific case. This short How-to guide explains how to deal with these keystores.

NSS installation and build

Most distributions have NSS as part of their base packages. If not the case, you may have to build it: instructions about NSS can be found here.

Create the NSS token

Creating the NSS token takes the following steps:

  1. creating the keystore. To do this, use the command modutil. You will also need to specify the -dbdir [PATH] optional parameter, together with a location where the NSS database files are stored. Two options are possible:

    • either you are using the old format (BerkeleyDB), resulting in files entitled cert8.db, key3.db and secmod.db. To do so, just replace [PATH] with a valid directory.
    • To use the new format (SQLite3), resulting in files entitled cert9.db, key4.db and pkcs11.txt, you must prefix the path with sql:; alternatively, you can set the environment NSS_DEFAULT_DB_TYPE to SQL.

    In the following example, a newer-style NSS database is created in the current directory:

    $ modutil -dbdir sql:. -create
    
    WARNING: Performing this operation while the browser is running could cause
    corruption of your security databases. If the browser is currently running,
    you should exit browser before continuing this operation. Type
    'q <enter>' to abort, or <enter> to continue: y
    $

    An NSS database contains one or more PKCS#11 cryptographic tokens. For what concerns us, only one token is needed, and it is always named "NSS Certificate DB".

  2. changing the keystore password. Again, use modutil to perform the password change. You must obviouly use the same -dbdir parameter as in the previous command.

    $ modutil -dbdir sql:. -changepw "NSS Certificate DB"
    
    WARNING: Performing this operation while the browser is running could cause
    corruption of your security databases. If the browser is currently running,
    you should exit browser before continuing this operation. Type
    'q <enter>' to abort, or <enter> to continue:
    
    Enter new password: ********
    Re-enter new password: ********
    Token "NSS Certificate DB" password changed successfully.
  3. Using modutil, you can also list the tokens attached to the keystore, using the -list parameter. In the following example, the list of PKCS#11 "modules" (i.e. tokens) is obtained for the NSS database sitting in the current directory.

    $ modutil -dbdir sql:. -list
    
    Listing of PKCS #11 Modules
    -----------------------------------------------------------
    1. NSS Internal PKCS #11 Module
           uri: pkcs11:library-manufacturer=Mozilla%20Foundation;library-description=NSS%20Internal%20Crypto%20Services;library-version=3.40
         slots: 2 slots attached
        status: loaded
    
         slot: NSS Internal Cryptographic Services
        token: NSS Generic Crypto Services
          uri: pkcs11:token=NSS%20Generic%20Crypto%20Services;manufacturer=Mozilla%20Foundation;serial=0000000000000000;model=NSS%203
    
         slot: NSS User Private Key and Certificate Services
        token: NSS Certificate DB
          uri: pkcs11:token=NSS%20Certificate%20DB;manufacturer=Mozilla%20Foundation;serial=0000000000000000;model=NSS%203
    -----------------------------------------------------------

Using pkcs11-tools with NSS databases

When interfacing with an NSS library, you need to specify:

  • The PKCS#11 library, using the -l optional parameter. It is typically named libsoftokn3.so, libsoftokn3.dylib or softokn3.dll (depending on the platform)
  • A supplementary parameter to the PKCS#11 tools: where the db files are located. To do this, simply add the -m parameter and add the path to the directory, as you specified earlier with modutil -dbdir.

In the example below, the command p11slotinfo is executed on slot index 1 (with token label "NSS Certificate DB"), from a MacOS platform:

$ p11slotinfo -l /usr/local/opt/nss/lib/libsoftokn3.dylib -m sql:.
PKCS#11 module slot list:
Slot index: 0
----------------
Description : NSS Internal Cryptographic Services
Token Label : NSS Generic Crypto Services
Manufacturer: Mozilla Foundation

Slot index: 1
----------------
Description : NSS User Private Key and Certificate Services
Token Label : NSS Certificate DB
Manufacturer: Mozilla Foundation


Enter slot index: 1

Slot[1]
-------------
Slot Number : 2
Description : NSS User Private Key and Certificate Services
Manufacturer: Mozilla Foundation
Slot Flags  : [ CKF_TOKEN_PRESENT ]

Token
-------------
Label       : NSS Certificate DB
Manufacturer: Mozilla Foundation

Token Flags : [ CKF_RNG CKF_LOGIN_REQUIRED CKF_USER_PIN_INITIALIZED CKF_DUAL_CRYPTO_OPERATIONS CKF_TOKEN_INITIALIZED ]

Mechanisms:
-----------
CKM_RSA_PKCS_KEY_PAIR_GEN                 --- --- --- --- --- --- --- --- gkp --- --- --- SW (00000000)
CKM_RSA_PKCS                              enc dec --- sig sir vfy vre --- --- wra unw --- SW (00000001)
CKM_RSA_PKCS_PSS                          --- --- --- sig --- vfy --- --- --- --- --- --- SW (0000000d)
CKM_RSA_PKCS_OAEP                         enc dec --- --- --- --- --- --- --- wra unw --- SW (00000009)
CKM_RSA_X_509                             enc dec --- sig sir vfy vre --- --- wra unw --- SW (00000003)
CKM_MD2_RSA_PKCS                          --- --- --- sig --- vfy --- --- --- --- --- --- SW (00000004)
CKM_MD5_RSA_PKCS                          --- --- --- sig --- vfy --- --- --- --- --- --- SW (00000005)
CKM_SHA1_RSA_PKCS                         --- --- --- sig --- vfy --- --- --- --- --- --- SW (00000006)
CKM_SHA224_RSA_PKCS                       --- --- --- sig --- vfy --- --- --- --- --- --- SW (00000046)
CKM_SHA256_RSA_PKCS                       --- --- --- sig --- vfy --- --- --- --- --- --- SW (00000040)
CKM_SHA384_RSA_PKCS                       --- --- --- sig --- vfy --- --- --- --- --- --- SW (00000041)
CKM_SHA512_RSA_PKCS                       --- --- --- sig --- vfy --- --- --- --- --- --- SW (00000042)
CKM_DSA_KEY_PAIR_GEN                      --- --- --- --- --- --- --- --- gkp --- --- --- SW (00000010)
CKM_DSA                                   --- --- --- sig --- vfy --- --- --- --- --- --- SW (00000011)
CKM_DSA_PARAMETER_GEN                     --- --- --- --- --- --- --- gen --- --- --- --- SW (00002000)
CKM_DSA_SHA1                              --- --- --- sig --- vfy --- --- --- --- --- --- SW (00000012)
CKM_DH_PKCS_KEY_PAIR_GEN                  --- --- --- --- --- --- --- --- gkp --- --- --- SW (00000020)
CKM_DH_PKCS_DERIVE                        --- --- --- --- --- --- --- --- --- --- --- der SW (00000021)
CKM_ECDSA_KEY_PAIR_GEN                    --- --- --- --- --- --- --- --- gkp --- --- --- SW (00001040) ec: F^p F2m --- nam unc ---
CKM_ECDH1_DERIVE                          --- --- --- --- --- --- --- --- --- --- --- der SW (00001050) ec: F^p F2m --- nam unc ---
CKM_ECDSA                                 --- --- --- sig --- vfy --- --- --- --- --- --- SW (00001041) ec: F^p F2m --- nam unc ---
CKM_ECDSA_SHA1                            --- --- --- sig --- vfy --- --- --- --- --- --- SW (00001042) ec: F^p F2m --- nam unc ---
CKM_RC2_KEY_GEN                           --- --- --- --- --- --- --- gen --- --- --- --- SW (00000100)
CKM_RC2_ECB                               enc dec --- --- --- --- --- --- --- wra unw --- SW (00000101)
CKM_RC2_CBC                               enc dec --- --- --- --- --- --- --- wra unw --- SW (00000102)
CKM_RC2_MAC                               --- --- --- sig --- vfy --- --- --- --- --- --- SW (00000103)
CKM_RC2_MAC_GENERAL                       --- --- --- sig --- vfy --- --- --- --- --- --- SW (00000104)
CKM_RC2_CBC_PAD                           enc dec --- --- --- --- --- --- --- wra unw --- SW (00000105)
CKM_DES_KEY_GEN                           --- --- --- --- --- --- --- gen --- --- --- --- SW (00000120)
CKM_DES_ECB                               enc dec --- --- --- --- --- --- --- wra unw --- SW (00000121)
CKM_DES_CBC                               enc dec --- --- --- --- --- --- --- wra unw --- SW (00000122)
CKM_DES_MAC                               --- --- --- sig --- vfy --- --- --- --- --- --- SW (00000123)
CKM_DES_MAC_GENERAL                       --- --- --- sig --- vfy --- --- --- --- --- --- SW (00000124)
CKM_DES_CBC_PAD                           enc dec --- --- --- --- --- --- --- wra unw --- SW (00000125)
CKM_DES2_KEY_GEN                          --- --- --- --- --- --- --- gen --- --- --- --- SW (00000130)
CKM_DES3_KEY_GEN                          --- --- --- --- --- --- --- gen --- --- --- --- SW (00000131)
CKM_DES3_ECB                              enc dec --- --- --- --- --- --- --- wra unw --- SW (00000132)
CKM_DES3_CBC                              enc dec --- --- --- --- --- --- --- wra unw --- SW (00000133)
CKM_DES3_MAC                              --- --- --- sig --- vfy --- --- --- --- --- --- SW (00000134)
CKM_DES3_MAC_GENERAL                      --- --- --- sig --- vfy --- --- --- --- --- --- SW (00000135)
CKM_DES3_CBC_PAD                          enc dec --- --- --- --- --- --- --- wra unw --- SW (00000136)
CKM_CDMF_KEY_GEN                          --- --- --- --- --- --- --- gen --- --- --- --- SW (00000140)
CKM_CDMF_ECB                              enc dec --- --- --- --- --- --- --- wra unw --- SW (00000141)
CKM_CDMF_CBC                              enc dec --- --- --- --- --- --- --- wra unw --- SW (00000142)
CKM_CDMF_MAC                              --- --- --- sig --- vfy --- --- --- --- --- --- SW (00000143)
CKM_CDMF_MAC_GENERAL                      --- --- --- sig --- vfy --- --- --- --- --- --- SW (00000144)
CKM_CDMF_CBC_PAD                          enc dec --- --- --- --- --- --- --- wra unw --- SW (00000145)
CKM_AES_KEY_GEN                           --- --- --- --- --- --- --- gen --- --- --- --- SW (00001080)
CKM_AES_ECB                               enc dec --- --- --- --- --- --- --- wra unw --- SW (00001081)
CKM_AES_CBC                               enc dec --- --- --- --- --- --- --- wra unw --- SW (00001082)
CKM_AES_MAC                               --- --- --- sig --- vfy --- --- --- --- --- --- SW (00001083)
CKM_AES_MAC_GENERAL                       --- --- --- sig --- vfy --- --- --- --- --- --- SW (00001084)
CKM_AES_CBC_PAD                           enc dec --- --- --- --- --- --- --- wra unw --- SW (00001085)
CKM_AES_CTS                               enc dec --- --- --- --- --- --- --- --- --- --- SW (00001089)
CKM_AES_CTR                               enc dec --- --- --- --- --- --- --- --- --- --- SW (00001086)
CKM_AES_GCM                               enc dec --- --- --- --- --- --- --- --- --- --- SW (00001087)
CKM_CAMELLIA_KEY_GEN                      --- --- --- --- --- --- --- gen --- --- --- --- SW (00000550)
CKM_CAMELLIA_ECB                          enc dec --- --- --- --- --- --- --- wra unw --- SW (00000551)
CKM_CAMELLIA_CBC                          enc dec --- --- --- --- --- --- --- wra unw --- SW (00000552)
CKM_CAMELLIA_MAC                          --- --- --- sig --- vfy --- --- --- --- --- --- SW (00000553)
CKM_CAMELLIA_MAC_GENERAL                  --- --- --- sig --- vfy --- --- --- --- --- --- SW (00000554)
CKM_CAMELLIA_CBC_PAD                      enc dec --- --- --- --- --- --- --- wra unw --- SW (00000555)
CKM_SEED_KEY_GEN                          --- --- --- --- --- --- --- gen --- --- --- --- SW (00000650)
CKM_SEED_ECB                              enc dec --- --- --- --- --- --- --- wra unw --- SW (00000651)
CKM_SEED_CBC                              enc dec --- --- --- --- --- --- --- wra unw --- SW (00000652)
CKM_SEED_MAC                              --- --- --- sig --- vfy --- --- --- --- --- --- SW (00000653)
CKM_SEED_MAC_GENERAL                      --- --- --- sig --- vfy --- --- --- --- --- --- SW (00000654)
CKM_SEED_CBC_PAD                          enc dec --- --- --- --- --- --- --- wra unw --- SW (00000655)
CKM_VENDOR_DEFINED                       *--- --- --- --- --- --- --- gen --- --- --- --- SW (ce53436b)
CKM_VENDOR_DEFINED                       *enc dec --- --- --- --- --- --- --- --- --- --- SW (ce53436c)
CKM_MD2_HMAC                              --- --- --- sig --- vfy --- --- --- --- --- --- SW (00000201)
CKM_MD2_HMAC_GENERAL                      --- --- --- sig --- vfy --- --- --- --- --- --- SW (00000202)
CKM_MD5_HMAC                              --- --- --- sig --- vfy --- --- --- --- --- --- SW (00000211)
CKM_MD5_HMAC_GENERAL                      --- --- --- sig --- vfy --- --- --- --- --- --- SW (00000212)
CKM_SHA_1_HMAC                            --- --- --- sig --- vfy --- --- --- --- --- --- SW (00000221)
CKM_SHA_1_HMAC_GENERAL                    --- --- --- sig --- vfy --- --- --- --- --- --- SW (00000222)
CKM_SHA224_HMAC                           --- --- --- sig --- vfy --- --- --- --- --- --- SW (00000256)
CKM_SHA224_HMAC_GENERAL                   --- --- --- sig --- vfy --- --- --- --- --- --- SW (00000257)
CKM_SHA256_HMAC                           --- --- --- sig --- vfy --- --- --- --- --- --- SW (00000251)
CKM_SHA256_HMAC_GENERAL                   --- --- --- sig --- vfy --- --- --- --- --- --- SW (00000252)
CKM_SHA384_HMAC                           --- --- --- sig --- vfy --- --- --- --- --- --- SW (00000261)
CKM_SHA384_HMAC_GENERAL                   --- --- --- sig --- vfy --- --- --- --- --- --- SW (00000262)
CKM_SHA512_HMAC                           --- --- --- sig --- vfy --- --- --- --- --- --- SW (00000271)
CKM_SHA512_HMAC_GENERAL                   --- --- --- sig --- vfy --- --- --- --- --- --- SW (00000272)
CKM_NSS_HKDF_SHA1                        *--- --- --- --- --- --- --- --- --- --- --- der SW (ce534353)
CKM_NSS_HKDF_SHA256                      *--- --- --- --- --- --- --- --- --- --- --- der SW (ce534354)
CKM_NSS_HKDF_SHA384                      *--- --- --- --- --- --- --- --- --- --- --- der SW (ce534355)
CKM_NSS_HKDF_SHA512                      *--- --- --- --- --- --- --- --- --- --- --- der SW (ce534356)
CKM_GENERIC_SECRET_KEY_GEN                --- --- --- --- --- --- --- gen --- --- --- --- SW (00000350)
CKM_PBE_MD2_DES_CBC                       --- --- --- --- --- --- --- --- --- --- --- der SW (000003a0)
CKM_PBE_MD5_DES_CBC                       --- --- --- --- --- --- --- --- --- --- --- der SW (000003a1)
CKM_NETSCAPE_PBE_SHA1_DES_CBC            *--- --- --- --- --- --- --- gen --- --- --- --- SW (80000002)
CKM_NETSCAPE_PBE_SHA1_FAULTY_3DES_CBC    *--- --- --- --- --- --- --- gen --- --- --- --- SW (80000008)
CKM_PBE_SHA1_DES3_EDE_CBC                 --- --- --- --- --- --- --- gen --- --- --- --- SW (000003a8)
CKM_PBE_SHA1_DES2_EDE_CBC                 --- --- --- --- --- --- --- gen --- --- --- --- SW (000003a9)
CKM_PBE_SHA1_RC2_40_CBC                   --- --- --- --- --- --- --- gen --- --- --- --- SW (000003ab)
CKM_PBE_SHA1_RC2_128_CBC                  --- --- --- --- --- --- --- gen --- --- --- --- SW (000003aa)
CKM_PBE_SHA1_RC4_40                       --- --- --- --- --- --- --- gen --- --- --- --- SW (000003a7)
CKM_PBE_SHA1_RC4_128                      --- --- --- --- --- --- --- gen --- --- --- --- SW (000003a6)
CKM_PBA_SHA1_WITH_SHA1_HMAC               --- --- --- --- --- --- --- gen --- --- --- --- SW (000003c0)
CKM_PKCS5_PBKD2                           --- --- --- --- --- --- --- gen --- --- --- --- SW (000003b0)
CKM_NETSCAPE_PBE_SHA1_HMAC_KEY_GEN       *--- --- --- --- --- --- --- gen --- --- --- --- SW (80000009)
CKM_NETSCAPE_PBE_MD5_HMAC_KEY_GEN        *--- --- --- --- --- --- --- gen --- --- --- --- SW (8000000a)
CKM_NETSCAPE_PBE_MD2_HMAC_KEY_GEN        *--- --- --- --- --- --- --- gen --- --- --- --- SW (8000000b)
CKM_VENDOR_DEFINED                       *--- --- --- --- --- --- --- gen --- --- --- --- SW (ce53436d)
CKM_VENDOR_DEFINED                       *--- --- --- --- --- --- --- gen --- --- --- --- SW (ce53436e)
CKM_VENDOR_DEFINED                       *--- --- --- --- --- --- --- gen --- --- --- --- SW (ce53436f)
CKM_VENDOR_DEFINED                       *--- --- --- --- --- --- --- gen --- --- --- --- SW (ce534370)
CKM_NSS_AES_KEY_WRAP                     *enc dec --- --- --- --- --- --- --- wra unw --- SW (ce534351)
CKM_NSS_AES_KEY_WRAP_PAD                 *enc dec --- --- --- --- --- --- --- wra unw --- SW (ce534352)
CKM_NSS_JPAKE_ROUND1_SHA1                *--- --- --- --- --- --- --- gen --- --- --- --- SW (ce534357)
CKM_NSS_JPAKE_ROUND1_SHA256              *--- --- --- --- --- --- --- gen --- --- --- --- SW (ce534358)
CKM_NSS_JPAKE_ROUND1_SHA384              *--- --- --- --- --- --- --- gen --- --- --- --- SW (ce534359)
CKM_NSS_JPAKE_ROUND1_SHA512              *--- --- --- --- --- --- --- gen --- --- --- --- SW (ce53435a)
CKM_NSS_JPAKE_ROUND2_SHA1                *--- --- --- --- --- --- --- --- --- --- --- der SW (ce53435b)
CKM_NSS_JPAKE_ROUND2_SHA256              *--- --- --- --- --- --- --- --- --- --- --- der SW (ce53435c)
CKM_NSS_JPAKE_ROUND2_SHA384              *--- --- --- --- --- --- --- --- --- --- --- der SW (ce53435d)
CKM_NSS_JPAKE_ROUND2_SHA512              *--- --- --- --- --- --- --- --- --- --- --- der SW (ce53435e)
CKM_NSS_JPAKE_FINAL_SHA1                 *--- --- --- --- --- --- --- --- --- --- --- der SW (ce53435f)
CKM_NSS_JPAKE_FINAL_SHA256               *--- --- --- --- --- --- --- --- --- --- --- der SW (ce534360)
CKM_NSS_JPAKE_FINAL_SHA384               *--- --- --- --- --- --- --- --- --- --- --- der SW (ce534361)
CKM_NSS_JPAKE_FINAL_SHA512               *--- --- --- --- --- --- --- --- --- --- --- der SW (ce534362)
CKM_NSS_HMAC_CONSTANT_TIME               *--- --- hsh --- --- --- --- --- --- --- --- --- SW (ce534363)
CKM_NSS_SSL3_MAC_CONSTANT_TIME           *--- --- hsh --- --- --- --- --- --- --- --- --- SW (ce534364)

References