The Tor Browser / file revision

 '\" t

 .\"     Title: PK12UTIL

 .\"    Author: [see the "Authors" section]

 .\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>

 .\"      Date:  5 June 2014

 .\"    Manual: NSS Security Tools

 .\"    Source: nss-tools

 .\"  Language: English

 .\"

 .TH "PK12UTIL" "1" "5 June 2014" "nss-tools" "NSS Security Tools"

 .\" -----------------------------------------------------------------

 .\" * Define some portability stuff

 .\" -----------------------------------------------------------------

 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 .\" http://bugs.debian.org/507673

 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html

 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 .ie \n(.g .ds Aq \(aq

 .el       .ds Aq '

 .\" -----------------------------------------------------------------

 .\" * set default formatting

 .\" -----------------------------------------------------------------

 .\" disable hyphenation

 .nh

 .\" disable justification (adjust text to left margin only)

 .ad l

 .\" -----------------------------------------------------------------

 .\" * MAIN CONTENT STARTS HERE *

 .\" -----------------------------------------------------------------

 .SH "NAME"

 pk12util \- Export and import keys and certificate to or from a PKCS #12 file and the NSS database

 .SH "SYNOPSIS"

 .HP \w'\fBpk12util\fR\ 'u

 \fBpk12util\fR [\-i\ p12File|\-l\ p12File|\-o\ p12File] [\-d\ [sql:]directory] [\-h\ tokenname] [\-P\ dbprefix] [\-r] [\-v] [\-k\ slotPasswordFile|\-K\ slotPassword] [\-w\ p12filePasswordFile|\-W\ p12filePassword]

 .SH "STATUS"

 .PP

 This documentation is still work in progress\&. Please contribute to the initial review in

 \m[blue]\fBMozilla NSS bug 836477\fR\m[]\&\s-2\u[1]\d\s+2

 .SH "DESCRIPTION"

 .PP

 The PKCS #12 utility,

 \fBpk12util\fR, enables sharing certificates among any server that supports PKCS#12\&. The tool can import certificates and keys from PKCS#12 files into security databases, export certificates, and list certificates and keys\&.

 .SH "OPTIONS AND ARGUMENTS"

 .PP

 \fBOptions\fR

 .PP

 \-i p12file

 .RS 4

 Import keys and certificates from a PKCS#12 file into a security database\&.

 .RE

 .PP

 \-l p12file

 .RS 4

 List the keys and certificates in PKCS#12 file\&.

 .RE

 .PP

 \-o p12file

 .RS 4

 Export keys and certificates from the security database to a PKCS#12 file\&.

 .RE

 .PP

 \fBArguments\fR

 .PP

 \-c keyCipher

 .RS 4

 Specify the key encryption algorithm\&.

 .RE

 .PP

 \-C certCipher

 .RS 4

 Specify the key cert (overall package) encryption algorithm\&.

 .RE

 .PP

 \-d [sql:]directory

 .RS 4

 Specify the database directory into which to import to or export from certificates and keys\&.

 .sp

 \fBpk12util\fR

 supports two types of databases: the legacy security databases (cert8\&.db,

 key3\&.db, and

 secmod\&.db) and new SQLite databases (cert9\&.db,

 key4\&.db, and

 pkcs11\&.txt)\&. If the prefix

 \fBsql:\fR

 is not used, then the tool assumes that the given databases are in the old format\&.

 .RE

 .PP

 \-h tokenname

 .RS 4

 Specify the name of the token to import into or export from\&.

 .RE

 .PP

 \-k slotPasswordFile

 .RS 4

 Specify the text file containing the slot\*(Aqs password\&.

 .RE

 .PP

 \-K slotPassword

 .RS 4

 Specify the slot\*(Aqs password\&.

 .RE

 .PP

 \-m | \-\-key\-len keyLength

 .RS 4

 Specify the desired length of the symmetric key to be used to encrypt the private key\&.

 .RE

 .PP

 \-n | \-\-cert\-key\-len certKeyLength

 .RS 4

 Specify the desired length of the symmetric key to be used to encrypt the certificates and other meta\-data\&.

 .RE

 .PP

 \-n certname

 .RS 4

 Specify the nickname of the cert and private key to export\&.

 .RE

 .PP

 \-P prefix

 .RS 4

 Specify the prefix used on the certificate and key databases\&. This option is provided as a special case\&. Changing the names of the certificate and key databases is not recommended\&.

 .RE

 .PP

 \-r

 .RS 4

 Dumps all of the data in raw (binary) form\&. This must be saved as a DER file\&. The default is to return information in a pretty\-print ASCII format, which displays the information about the certificates and public keys in the p12 file\&.

 .RE

 .PP

 \-v

 .RS 4

 Enable debug logging when importing\&.

 .RE

 .PP

 \-w p12filePasswordFile

 .RS 4

 Specify the text file containing the pkcs #12 file password\&.

 .RE

 .PP

 \-W p12filePassword

 .RS 4

 Specify the pkcs #12 file password\&.

 .RE

 .SH "RETURN CODES"

 .sp

 .RS 4

 .ie n \{\

 \h'-04'\(bu\h'+03'\c

 .\}

 .el \{\

 .sp -1

 .IP \(bu 2.3

 .\}

 0 \- No error

 .RE

 .sp

 .RS 4

 .ie n \{\

 \h'-04'\(bu\h'+03'\c

 .\}

 .el \{\

 .sp -1

 .IP \(bu 2.3

 .\}

 1 \- User Cancelled

 .RE

 .sp

 .RS 4

 .ie n \{\

 \h'-04'\(bu\h'+03'\c

 .\}

 .el \{\

 .sp -1

 .IP \(bu 2.3

 .\}

 2 \- Usage error

 .RE

 .sp

 .RS 4

 .ie n \{\

 \h'-04'\(bu\h'+03'\c

 .\}

 .el \{\

 .sp -1

 .IP \(bu 2.3

 .\}

 6 \- NLS init error

 .RE

 .sp

 .RS 4

 .ie n \{\

 \h'-04'\(bu\h'+03'\c

 .\}

 .el \{\

 .sp -1

 .IP \(bu 2.3

 .\}

 8 \- Certificate DB open error

 .RE

 .sp

 .RS 4

 .ie n \{\

 \h'-04'\(bu\h'+03'\c

 .\}

 .el \{\

 .sp -1

 .IP \(bu 2.3

 .\}

 9 \- Key DB open error

 .RE

 .sp

 .RS 4

 .ie n \{\

 \h'-04'\(bu\h'+03'\c

 .\}

 .el \{\

 .sp -1

 .IP \(bu 2.3

 .\}

 10 \- File initialization error

 .RE

 .sp

 .RS 4

 .ie n \{\

 \h'-04'\(bu\h'+03'\c

 .\}

 .el \{\

 .sp -1

 .IP \(bu 2.3

 .\}

 11 \- Unicode conversion error

 .RE

 .sp

 .RS 4

 .ie n \{\

 \h'-04'\(bu\h'+03'\c

 .\}

 .el \{\

 .sp -1

 .IP \(bu 2.3

 .\}

 12 \- Temporary file creation error

 .RE

 .sp

 .RS 4

 .ie n \{\

 \h'-04'\(bu\h'+03'\c

 .\}

 .el \{\

 .sp -1

 .IP \(bu 2.3

 .\}

 13 \- PKCS11 get slot error

 .RE

 .sp

 .RS 4

 .ie n \{\

 \h'-04'\(bu\h'+03'\c

 .\}

 .el \{\

 .sp -1

 .IP \(bu 2.3

 .\}

 14 \- PKCS12 decoder start error

 .RE

 .sp

 .RS 4

 .ie n \{\

 \h'-04'\(bu\h'+03'\c

 .\}

 .el \{\

 .sp -1

 .IP \(bu 2.3

 .\}

 15 \- error read from import file

 .RE

 .sp

 .RS 4

 .ie n \{\

 \h'-04'\(bu\h'+03'\c

 .\}

 .el \{\

 .sp -1

 .IP \(bu 2.3

 .\}

 16 \- pkcs12 decode error

 .RE

 .sp

 .RS 4

 .ie n \{\

 \h'-04'\(bu\h'+03'\c

 .\}

 .el \{\

 .sp -1

 .IP \(bu 2.3

 .\}

 17 \- pkcs12 decoder verify error

 .RE

 .sp

 .RS 4

 .ie n \{\

 \h'-04'\(bu\h'+03'\c

 .\}

 .el \{\

 .sp -1

 .IP \(bu 2.3

 .\}

 18 \- pkcs12 decoder validate bags error

 .RE

 .sp

 .RS 4

 .ie n \{\

 \h'-04'\(bu\h'+03'\c

 .\}

 .el \{\

 .sp -1

 .IP \(bu 2.3

 .\}

 19 \- pkcs12 decoder import bags error

 .RE

 .sp

 .RS 4

 .ie n \{\

 \h'-04'\(bu\h'+03'\c

 .\}

 .el \{\

 .sp -1

 .IP \(bu 2.3

 .\}

 20 \- key db conversion version 3 to version 2 error

 .RE

 .sp

 .RS 4

 .ie n \{\

 \h'-04'\(bu\h'+03'\c

 .\}

 .el \{\

 .sp -1

 .IP \(bu 2.3

 .\}

 21 \- cert db conversion version 7 to version 5 error

 .RE

 .sp

 .RS 4

 .ie n \{\

 \h'-04'\(bu\h'+03'\c

 .\}

 .el \{\

 .sp -1

 .IP \(bu 2.3

 .\}

 22 \- cert and key dbs patch error

 .RE

 .sp

 .RS 4

 .ie n \{\

 \h'-04'\(bu\h'+03'\c

 .\}

 .el \{\

 .sp -1

 .IP \(bu 2.3

 .\}

 23 \- get default cert db error

 .RE

 .sp

 .RS 4

 .ie n \{\

 \h'-04'\(bu\h'+03'\c

 .\}

 .el \{\

 .sp -1

 .IP \(bu 2.3

 .\}

 24 \- find cert by nickname error

 .RE

 .sp

 .RS 4

 .ie n \{\

 \h'-04'\(bu\h'+03'\c

 .\}

 .el \{\

 .sp -1

 .IP \(bu 2.3

 .\}

 25 \- create export context error

 .RE

 .sp

 .RS 4

 .ie n \{\

 \h'-04'\(bu\h'+03'\c

 .\}

 .el \{\

 .sp -1

 .IP \(bu 2.3

 .\}

 26 \- PKCS12 add password itegrity error

 .RE

 .sp

 .RS 4

 .ie n \{\

 \h'-04'\(bu\h'+03'\c

 .\}

 .el \{\

 .sp -1

 .IP \(bu 2.3

 .\}

 27 \- cert and key Safes creation error

 .RE

 .sp

 .RS 4

 .ie n \{\

 \h'-04'\(bu\h'+03'\c

 .\}

 .el \{\

 .sp -1

 .IP \(bu 2.3

 .\}

 28 \- PKCS12 add cert and key error

 .RE

 .sp

 .RS 4

 .ie n \{\

 \h'-04'\(bu\h'+03'\c

 .\}

 .el \{\

 .sp -1

 .IP \(bu 2.3

 .\}

 29 \- PKCS12 encode error

 .RE

 .SH "EXAMPLES"

 .PP

 \fBImporting Keys and Certificates\fR

 .PP

 The most basic usage of

 \fBpk12util\fR

 for importing a certificate or key is the PKCS#12 input file (\fB\-i\fR) and some way to specify the security database being accessed (either

 \fB\-d\fR

 for a directory or

 \fB\-h\fR

 for a token)\&.

 .PP

 pk12util \-i p12File [\-h tokenname] [\-v] [\-d [sql:]directory] [\-P dbprefix] [\-k slotPasswordFile|\-K slotPassword] [\-w p12filePasswordFile|\-W p12filePassword]

 .PP

 For example:

 .PP

 .sp

 .if n \{\

 .RS 4

 .\}

 .nf

 # pk12util \-i /tmp/cert\-files/users\&.p12 \-d sql:/home/my/sharednssdb

 Enter a password which will be used to encrypt your keys\&.

 The password should be at least 8 characters long,

 and should contain at least one non\-alphabetic character\&.

 Enter new password: 

 Re\-enter password: 

 Enter password for PKCS12 file: 

 pk12util: PKCS12 IMPORT SUCCESSFUL

 .fi

 .if n \{\

 .RE

 .\}

 .PP

 \fBExporting Keys and Certificates\fR

 .PP

 Using the

 \fBpk12util\fR

 command to export certificates and keys requires both the name of the certificate to extract from the database (\fB\-n\fR) and the PKCS#12\-formatted output file to write to\&. There are optional parameters that can be used to encrypt the file to protect the certificate material\&.

 .PP

 pk12util \-o p12File \-n certname [\-c keyCipher] [\-C certCipher] [\-m|\-\-key_len keyLen] [\-n|\-\-cert_key_len certKeyLen] [\-d [sql:]directory] [\-P dbprefix] [\-k slotPasswordFile|\-K slotPassword] [\-w p12filePasswordFile|\-W p12filePassword]

 .PP

 For example:

 .sp

 .if n \{\

 .RS 4

 .\}

 .nf

 # pk12util \-o certs\&.p12 \-n Server\-Cert \-d sql:/home/my/sharednssdb

 Enter password for PKCS12 file: 

 Re\-enter password: 

 .fi

 .if n \{\

 .RE

 .\}

 .PP

 \fBListing Keys and Certificates\fR

 .PP

 The information in a

 \&.p12

 file are not human\-readable\&. The certificates and keys in the file can be printed (listed) in a human\-readable pretty\-print format that shows information for every certificate and any public keys in the

 \&.p12

 file\&.

 .PP

 pk12util \-l p12File [\-h tokenname] [\-r] [\-d [sql:]directory] [\-P dbprefix] [\-k slotPasswordFile|\-K slotPassword] [\-w p12filePasswordFile|\-W p12filePassword]

 .PP

 For example, this prints the default ASCII output:

 .sp

 .if n \{\

 .RS 4

 .\}

 .nf

 # pk12util \-l certs\&.p12

 Enter password for PKCS12 file: 

 Key(shrouded):

     Friendly Name: Thawte Freemail Member\*(Aqs Thawte Consulting (Pty) Ltd\&. ID

     Encryption algorithm: PKCS #12 V2 PBE With SHA\-1 And 3KEY Triple DES\-CBC

         Parameters:

             Salt:

                 45:2e:6a:a0:03:4d:7b:a1:63:3c:15:ea:67:37:62:1f

             Iteration Count: 1 (0x1)

 Certificate:

     Data:

         Version: 3 (0x2)

         Serial Number: 13 (0xd)

         Signature Algorithm: PKCS #1 SHA\-1 With RSA Encryption

         Issuer: "E=personal\-freemail@thawte\&.com,CN=Thawte Personal Freemail C

             A,OU=Certification Services Division,O=Thawte Consulting,L=Cape T

             own,ST=Western Cape,C=ZA"

 .fi

 .if n \{\

 .RE

 .\}

 .PP

 Alternatively, the

 \fB\-r\fR

 prints the certificates and then exports them into separate DER binary files\&. This allows the certificates to be fed to another application that supports

 \&.p12

 files\&. Each certificate is written to a sequentially\-number file, beginning with

 file0001\&.der

 and continuing through

 file000N\&.der, incrementing the number for every certificate:

 .sp

 .if n \{\

 .RS 4

 .\}

 .nf

 pk12util \-l test\&.p12 \-r

 Enter password for PKCS12 file: 

 Key(shrouded):

     Friendly Name: Thawte Freemail Member\*(Aqs Thawte Consulting (Pty) Ltd\&. ID

     Encryption algorithm: PKCS #12 V2 PBE With SHA\-1 And 3KEY Triple DES\-CBC

         Parameters:

             Salt:

                 45:2e:6a:a0:03:4d:7b:a1:63:3c:15:ea:67:37:62:1f

             Iteration Count: 1 (0x1)

 Certificate    Friendly Name: Thawte Personal Freemail Issuing CA \- Thawte Consulting

 Certificate    Friendly Name: Thawte Freemail Member\*(Aqs Thawte Consulting (Pty) Ltd\&. ID

 .fi

 .if n \{\

 .RE

 .\}

 .SH "PASSWORD ENCRYPTION"

 .PP

 PKCS#12 provides for not only the protection of the private keys but also the certificate and meta\-data associated with the keys\&. Password\-based encryption is used to protect private keys on export to a PKCS#12 file and, optionally, the entire package\&. If no algorithm is specified, the tool defaults to using

 \fBPKCS12 V2 PBE with SHA1 and 3KEY Triple DES\-cbc\fR

 for private key encryption\&.

 \fBPKCS12 V2 PBE with SHA1 and 40 Bit RC4\fR

 is the default for the overall package encryption when not in FIPS mode\&. When in FIPS mode, there is no package encryption\&.

 .PP

 The private key is always protected with strong encryption by default\&.

 .PP

 Several types of ciphers are supported\&.

 .PP

 Symmetric CBC ciphers for PKCS#5 V2

 .RS 4

 .sp

 .RS 4

 .ie n \{\

 \h'-04'\(bu\h'+03'\c

 .\}

 .el \{\

 .sp -1

 .IP \(bu 2.3

 .\}

 DES\-CBC

 .RE

 .sp

 .RS 4

 .ie n \{\

 \h'-04'\(bu\h'+03'\c

 .\}

 .el \{\

 .sp -1

 .IP \(bu 2.3

 .\}

 RC2\-CBC

 .RE

 .sp

 .RS 4

 .ie n \{\

 \h'-04'\(bu\h'+03'\c

 .\}

 .el \{\

 .sp -1

 .IP \(bu 2.3

 .\}

 RC5\-CBCPad

 .RE

 .sp

 .RS 4

 .ie n \{\

 \h'-04'\(bu\h'+03'\c

 .\}

 .el \{\

 .sp -1

 .IP \(bu 2.3

 .\}

 DES\-EDE3\-CBC (the default for key encryption)

 .RE

 .sp

 .RS 4

 .ie n \{\

 \h'-04'\(bu\h'+03'\c

 .\}

 .el \{\

 .sp -1

 .IP \(bu 2.3

 .\}

 AES\-128\-CBC

 .RE

 .sp

 .RS 4

 .ie n \{\

 \h'-04'\(bu\h'+03'\c

 .\}

 .el \{\

 .sp -1

 .IP \(bu 2.3

 .\}

 AES\-192\-CBC

 .RE

 .sp

 .RS 4

 .ie n \{\

 \h'-04'\(bu\h'+03'\c

 .\}

 .el \{\

 .sp -1

 .IP \(bu 2.3

 .\}

 AES\-256\-CBC

 .RE

 .sp

 .RS 4

 .ie n \{\

 \h'-04'\(bu\h'+03'\c

 .\}

 .el \{\

 .sp -1

 .IP \(bu 2.3

 .\}

 CAMELLIA\-128\-CBC

 .RE

 .sp

 .RS 4

 .ie n \{\

 \h'-04'\(bu\h'+03'\c

 .\}

 .el \{\

 .sp -1

 .IP \(bu 2.3

 .\}

 CAMELLIA\-192\-CBC

 .RE

 .sp

 .RS 4

 .ie n \{\

 \h'-04'\(bu\h'+03'\c

 .\}

 .el \{\

 .sp -1

 .IP \(bu 2.3

 .\}

 CAMELLIA\-256\-CBC

 .RE

 .RE

 .PP

 PKCS#12 PBE ciphers

 .RS 4

 .sp

 .RS 4

 .ie n \{\

 \h'-04'\(bu\h'+03'\c

 .\}

 .el \{\

 .sp -1

 .IP \(bu 2.3

 .\}

 PKCS #12 PBE with Sha1 and 128 Bit RC4

 .RE

 .sp

 .RS 4

 .ie n \{\

 \h'-04'\(bu\h'+03'\c

 .\}

 .el \{\

 .sp -1

 .IP \(bu 2.3

 .\}

 PKCS #12 PBE with Sha1 and 40 Bit RC4

 .RE

 .sp

 .RS 4

 .ie n \{\

 \h'-04'\(bu\h'+03'\c

 .\}

 .el \{\

 .sp -1

 .IP \(bu 2.3

 .\}

 PKCS #12 PBE with Sha1 and Triple DES CBC

 .RE

 .sp

 .RS 4

 .ie n \{\

 \h'-04'\(bu\h'+03'\c

 .\}

 .el \{\

 .sp -1

 .IP \(bu 2.3

 .\}

 PKCS #12 PBE with Sha1 and 128 Bit RC2 CBC

 .RE

 .sp

 .RS 4

 .ie n \{\

 \h'-04'\(bu\h'+03'\c

 .\}

 .el \{\

 .sp -1

 .IP \(bu 2.3

 .\}

 PKCS #12 PBE with Sha1 and 40 Bit RC2 CBC

 .RE

 .sp

 .RS 4

 .ie n \{\

 \h'-04'\(bu\h'+03'\c

 .\}

 .el \{\

 .sp -1

 .IP \(bu 2.3

 .\}

 PKCS12 V2 PBE with SHA1 and 128 Bit RC4

 .RE

 .sp

 .RS 4

 .ie n \{\

 \h'-04'\(bu\h'+03'\c

 .\}

 .el \{\

 .sp -1

 .IP \(bu 2.3

 .\}

 PKCS12 V2 PBE with SHA1 and 40 Bit RC4 (the default for non\-FIPS mode)

 .RE

 .sp

 .RS 4

 .ie n \{\

 \h'-04'\(bu\h'+03'\c

 .\}

 .el \{\

 .sp -1

 .IP \(bu 2.3

 .\}

 PKCS12 V2 PBE with SHA1 and 3KEY Triple DES\-cbc

 .RE

 .sp

 .RS 4

 .ie n \{\

 \h'-04'\(bu\h'+03'\c

 .\}

 .el \{\

 .sp -1

 .IP \(bu 2.3

 .\}

 PKCS12 V2 PBE with SHA1 and 2KEY Triple DES\-cbc

 .RE

 .sp

 .RS 4

 .ie n \{\

 \h'-04'\(bu\h'+03'\c

 .\}

 .el \{\

 .sp -1

 .IP \(bu 2.3

 .\}

 PKCS12 V2 PBE with SHA1 and 128 Bit RC2 CBC

 .RE

 .sp

 .RS 4

 .ie n \{\

 \h'-04'\(bu\h'+03'\c

 .\}

 .el \{\

 .sp -1

 .IP \(bu 2.3

 .\}

 PKCS12 V2 PBE with SHA1 and 40 Bit RC2 CBC

 .RE

 .RE

 .PP

 PKCS#5 PBE ciphers

 .RS 4

 .sp

 .RS 4

 .ie n \{\

 \h'-04'\(bu\h'+03'\c

 .\}

 .el \{\

 .sp -1

 .IP \(bu 2.3

 .\}

 PKCS #5 Password Based Encryption with MD2 and DES CBC

 .RE

 .sp

 .RS 4

 .ie n \{\

 \h'-04'\(bu\h'+03'\c

 .\}

 .el \{\

 .sp -1

 .IP \(bu 2.3

 .\}

 PKCS #5 Password Based Encryption with MD5 and DES CBC

 .RE

 .sp

 .RS 4

 .ie n \{\

 \h'-04'\(bu\h'+03'\c

 .\}

 .el \{\

 .sp -1

 .IP \(bu 2.3

 .\}

 PKCS #5 Password Based Encryption with SHA1 and DES CBC

 .RE

 .RE

 .PP

 With PKCS#12, the crypto provider may be the soft token module or an external hardware module\&. If the cryptographic module does not support the requested algorithm, then the next best fit will be selected (usually the default)\&. If no suitable replacement for the desired algorithm can be found, the tool returns the error

 \fIno security module can perform the requested operation\fR\&.

 .SH "NSS DATABASE TYPES"

 .PP

 NSS originally used BerkeleyDB databases to store security information\&. The last versions of these

 \fIlegacy\fR

 databases are:

 .sp

 .RS 4

 .ie n \{\

 \h'-04'\(bu\h'+03'\c

 .\}

 .el \{\

 .sp -1

 .IP \(bu 2.3

 .\}

 cert8\&.db for certificates

 .RE

 .sp

 .RS 4

 .ie n \{\

 \h'-04'\(bu\h'+03'\c

 .\}

 .el \{\

 .sp -1

 .IP \(bu 2.3

 .\}

 key3\&.db for keys

 .RE

 .sp

 .RS 4

 .ie n \{\

 \h'-04'\(bu\h'+03'\c

 .\}

 .el \{\

 .sp -1

 .IP \(bu 2.3

 .\}

 secmod\&.db for PKCS #11 module information

 .RE

 .PP

 BerkeleyDB has performance limitations, though, which prevent it from being easily used by multiple applications simultaneously\&. NSS has some flexibility that allows applications to use their own, independent database engine while keeping a shared database and working around the access issues\&. Still, NSS requires more flexibility to provide a truly shared security database\&.

 .PP

 In 2009, NSS introduced a new set of databases that are SQLite databases rather than BerkleyDB\&. These new databases provide more accessibility and performance:

 .sp

 .RS 4

 .ie n \{\

 \h'-04'\(bu\h'+03'\c

 .\}

 .el \{\

 .sp -1

 .IP \(bu 2.3

 .\}

 cert9\&.db for certificates

 .RE

 .sp

 .RS 4

 .ie n \{\

 \h'-04'\(bu\h'+03'\c

 .\}

 .el \{\

 .sp -1

 .IP \(bu 2.3

 .\}

 key4\&.db for keys

 .RE

 .sp

 .RS 4

 .ie n \{\

 \h'-04'\(bu\h'+03'\c

 .\}

 .el \{\

 .sp -1

 .IP \(bu 2.3

 .\}

 pkcs11\&.txt, which is listing of all of the PKCS #11 modules contained in a new subdirectory in the security databases directory

 .RE

 .PP

 Because the SQLite databases are designed to be shared, these are the

 \fIshared\fR

 database type\&. The shared database type is preferred; the legacy format is included for backward compatibility\&.

 .PP

 By default, the tools (\fBcertutil\fR,

 \fBpk12util\fR,

 \fBmodutil\fR) assume that the given security databases follow the more common legacy type\&. Using the SQLite databases must be manually specified by using the

 \fBsql:\fR

 prefix with the given security directory\&. For example:

 .sp

 .if n \{\

 .RS 4

 .\}

 .nf

 # pk12util \-i /tmp/cert\-files/users\&.p12 \-d sql:/home/my/sharednssdb

 .fi

 .if n \{\

 .RE

 .\}

 .PP

 To set the shared database type as the default type for the tools, set the

 \fBNSS_DEFAULT_DB_TYPE\fR

 environment variable to

 \fBsql\fR:

 .sp

 .if n \{\

 .RS 4

 .\}

 .nf

 export NSS_DEFAULT_DB_TYPE="sql"

 .fi

 .if n \{\

 .RE

 .\}

 .PP

 This line can be set added to the

 ~/\&.bashrc

 file to make the change permanent\&.

 .PP

 Most applications do not use the shared database by default, but they can be configured to use them\&. For example, this how\-to article covers how to configure Firefox and Thunderbird to use the new shared NSS databases:

 .sp

 .RS 4

 .ie n \{\

 \h'-04'\(bu\h'+03'\c

 .\}

 .el \{\

 .sp -1

 .IP \(bu 2.3

 .\}

 https://wiki\&.mozilla\&.org/NSS_Shared_DB_Howto

 .RE

 .PP

 For an engineering draft on the changes in the shared NSS databases, see the NSS project wiki:

 .sp

 .RS 4

 .ie n \{\

 \h'-04'\(bu\h'+03'\c

 .\}

 .el \{\

 .sp -1

 .IP \(bu 2.3

 .\}

 https://wiki\&.mozilla\&.org/NSS_Shared_DB

 .RE

 .SH "SEE ALSO"

 .PP

 certutil (1)

 .PP

 modutil (1)

 .PP

 The NSS wiki has information on the new database design and how to configure applications to use it\&.

 .sp

 .RS 4

 .ie n \{\

 \h'-04'\(bu\h'+03'\c

 .\}

 .el \{\

 .sp -1

 .IP \(bu 2.3

 .\}

 https://wiki\&.mozilla\&.org/NSS_Shared_DB_Howto

 .RE

 .sp

 .RS 4

 .ie n \{\

 \h'-04'\(bu\h'+03'\c

 .\}

 .el \{\

 .sp -1

 .IP \(bu 2.3

 .\}

 https://wiki\&.mozilla\&.org/NSS_Shared_DB

 .RE

 .SH "ADDITIONAL RESOURCES"

 .PP

 For information about NSS and other tools related to NSS (like JSS), check out the NSS project wiki at

 \m[blue]\fBhttp://www\&.mozilla\&.org/projects/security/pki/nss/\fR\m[]\&. The NSS site relates directly to NSS code changes and releases\&.

 .PP

 Mailing lists: https://lists\&.mozilla\&.org/listinfo/dev\-tech\-crypto

 .PP

 IRC: Freenode at #dogtag\-pki

 .SH "AUTHORS"

 .PP

 The NSS tools were written and maintained by developers with Netscape, Red Hat, Sun, Oracle, Mozilla, and Google\&.

 .PP

 Authors: Elio Maldonado <emaldona@redhat\&.com>, Deon Lackey <dlackey@redhat\&.com>\&.

 .SH "LICENSE"

 .PP

 Licensed under the Mozilla Public License, v\&. 2\&.0\&. If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla\&.org/MPL/2\&.0/\&.

 .SH "NOTES"

 .IP " 1." 4

 Mozilla NSS bug 836477

 .RS 4

 \%https://bugzilla.mozilla.org/show_bug.cgi?id=836477

 .RE