'\" t .\" Title: PK12UTIL .\" Author: [see the "Authors" section] .\" Generator: DocBook XSL Stylesheets vsnapshot .\" Date: 27 October 2017 .\" Manual: NSS Security Tools .\" Source: nss-tools .\" Language: English .\" .TH "PK12UTIL" "1" "27 October 2017" "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 certiticate 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 associated certificates\&. If no algorithm is specified, the tool defaults to using PKCS #12 SHA\-1 and 3\-key triple DES for private key encryption\&. When not in FIPS mode, PKCS #12 SHA\-1 and 40\-bit RC4 is used for certificate encryption\&. When in FIPS mode, there is no certificate encryption\&. If certificate encryption is not wanted, specify \fB"NONE"\fR as the argument of the \fB\-C\fR option\&. .PP The private key is always protected with strong encryption by default\&. .PP Several types of ciphers are supported\&. .PP PKCS #5 password\-based encryption .RS 4 .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} PBES2 with AES\-CBC\-Pad as underlying encryption scheme (\fB"AES\-128\-CBC"\fR, \fB"AES\-192\-CBC"\fR, and \fB"AES\-256\-CBC"\fR) .RE .RE .PP PKCS #12 password\-based encryption .RS 4 .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} SHA\-1 and 128\-bit RC4 (\fB"PKCS #12 V2 PBE With SHA\-1 And 128 Bit RC4"\fR or \fB"RC4"\fR) .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} SHA\-1 and 40\-bit RC4 (\fB"PKCS #12 V2 PBE With SHA\-1 And 40 Bit RC4"\fR) (used by default for certificate encryption in non\-FIPS mode) .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} SHA\-1 and 3\-key triple\-DES (\fB"PKCS #12 V2 PBE With SHA\-1 And 3KEY Triple DES\-CBC"\fR or \fB"DES\-EDE3\-CBC"\fR) .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} SHA\-1 and 128\-bit RC2 (\fB"PKCS #12 V2 PBE With SHA\-1 And 128 Bit RC2 CBC"\fR or \fB"RC2\-CBC"\fR) .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} SHA\-1 and 40\-bit RC2 (\fB"PKCS #12 V2 PBE With SHA\-1 And 40 Bit RC2 CBC"\fR) .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 "COMPATIBILITY NOTES" .PP The exporting behavior of \fBpk12util\fR has changed over time, while importing files exported with older versions of NSS is still supported\&. .PP Until the 3\&.30 release, \fBpk12util\fR used the UTF\-16 encoding for the PKCS #5 password\-based encryption schemes, while the recommendation is to encode passwords in UTF\-8 if the used encryption scheme is defined outside of the PKCS #12 standard\&. .PP Until the 3\&.31 release, even when \fB"AES\-128\-CBC"\fR or \fB"AES\-192\-CBC"\fR is given from the command line, \fBpk12util\fR always used 256\-bit AES as the underlying encryption scheme\&. .PP For historical reasons, \fBpk12util\fR accepts password\-based encryption schemes not listed in this document\&. However, those schemes are not officially supported and may have issues in interoperability with other tools\&. .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 , Deon Lackey \&. .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