From 36d22d82aa202bb199967e9512281e9a53db42c9 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 7 Apr 2024 21:33:14 +0200 Subject: Adding upstream version 115.7.0esr. Signed-off-by: Daniel Baumann --- .../nss/doc/rst/legacy/tools/certutil/index.rst | 702 ++++++++++++++++ .../nss/doc/rst/legacy/tools/cmsutil/index.rst | 111 +++ .../nss/doc/rst/legacy/tools/crlutil/index.rst | 229 ++++++ security/nss/doc/rst/legacy/tools/index.rst | 125 +++ .../nss/doc/rst/legacy/tools/modutil/index.rst | 640 +++++++++++++++ .../tools/nss_tools_certutil-tasks/index.rst | 32 + .../rst/legacy/tools/nss_tools_certutil/index.rst | 666 +++++++++++++++ .../rst/legacy/tools/nss_tools_cmsutil/index.rst | 119 +++ .../rst/legacy/tools/nss_tools_crlutil/index.rst | 441 ++++++++++ .../legacy/tools/nss_tools_dbck-tasks/index.rst | 28 + .../legacy/tools/nss_tools_modutil-tasks/index.rst | 24 + .../rst/legacy/tools/nss_tools_modutil/index.rst | 912 +++++++++++++++++++++ .../tools/nss_tools_pk12util-tasks/index.rst | 23 + .../rst/legacy/tools/nss_tools_pk12util/index.rst | 217 +++++ .../legacy/tools/nss_tools_signver-tasks/index.rst | 22 + .../legacy/tools/nss_tools_sslstrength/index.rst | 87 ++ .../rst/legacy/tools/nss_tools_ssltap/index.rst | 621 ++++++++++++++ .../nss/doc/rst/legacy/tools/pk12util/index.rst | 282 +++++++ .../nss/doc/rst/legacy/tools/signtool/index.rst | 547 ++++++++++++ .../nss/doc/rst/legacy/tools/signver/index.rst | 118 +++ security/nss/doc/rst/legacy/tools/ssltap/index.rst | 495 +++++++++++ .../nss/doc/rst/legacy/tools/vfychain/index.rst | 92 +++ .../nss/doc/rst/legacy/tools/vfyserv/index.rst | 8 + 23 files changed, 6541 insertions(+) create mode 100644 security/nss/doc/rst/legacy/tools/certutil/index.rst create mode 100644 security/nss/doc/rst/legacy/tools/cmsutil/index.rst create mode 100644 security/nss/doc/rst/legacy/tools/crlutil/index.rst create mode 100644 security/nss/doc/rst/legacy/tools/index.rst create mode 100644 security/nss/doc/rst/legacy/tools/modutil/index.rst create mode 100644 security/nss/doc/rst/legacy/tools/nss_tools_certutil-tasks/index.rst create mode 100644 security/nss/doc/rst/legacy/tools/nss_tools_certutil/index.rst create mode 100644 security/nss/doc/rst/legacy/tools/nss_tools_cmsutil/index.rst create mode 100644 security/nss/doc/rst/legacy/tools/nss_tools_crlutil/index.rst create mode 100644 security/nss/doc/rst/legacy/tools/nss_tools_dbck-tasks/index.rst create mode 100644 security/nss/doc/rst/legacy/tools/nss_tools_modutil-tasks/index.rst create mode 100644 security/nss/doc/rst/legacy/tools/nss_tools_modutil/index.rst create mode 100644 security/nss/doc/rst/legacy/tools/nss_tools_pk12util-tasks/index.rst create mode 100644 security/nss/doc/rst/legacy/tools/nss_tools_pk12util/index.rst create mode 100644 security/nss/doc/rst/legacy/tools/nss_tools_signver-tasks/index.rst create mode 100644 security/nss/doc/rst/legacy/tools/nss_tools_sslstrength/index.rst create mode 100644 security/nss/doc/rst/legacy/tools/nss_tools_ssltap/index.rst create mode 100644 security/nss/doc/rst/legacy/tools/pk12util/index.rst create mode 100644 security/nss/doc/rst/legacy/tools/signtool/index.rst create mode 100644 security/nss/doc/rst/legacy/tools/signver/index.rst create mode 100644 security/nss/doc/rst/legacy/tools/ssltap/index.rst create mode 100644 security/nss/doc/rst/legacy/tools/vfychain/index.rst create mode 100644 security/nss/doc/rst/legacy/tools/vfyserv/index.rst (limited to 'security/nss/doc/rst/legacy/tools') diff --git a/security/nss/doc/rst/legacy/tools/certutil/index.rst b/security/nss/doc/rst/legacy/tools/certutil/index.rst new file mode 100644 index 0000000000..d7d943958e --- /dev/null +++ b/security/nss/doc/rst/legacy/tools/certutil/index.rst @@ -0,0 +1,702 @@ +.. _mozilla_projects_nss_tools_certutil: + +certutil +======== + +.. container:: + + | Name + | certutil — Manage keys and certificate in the NSS database. + | Synopsis + | certutil [options] `arguments `__ + | Description + | The Certificate Database Tool, certutil, is a command-line utility that + | can create and modify certificate and key database files. It can also + | list, generate, modify, or delete certificates within the database, create + | or change the password, generate new public and private key pairs, display + | the contents of the key database, or delete key pairs within the key + | database. + | The key and certificate management process generally begins with creating + | keys in the key database, then generating and managing certificates in the + | certificate database. This document discusses certificate and key database + | management. For information security module database management, see the + | modutil manpages. + | Options and Arguments + | Running certutil always requires one (and only one) option to specify the + | type of certificate operation. Each option may take arguments, anywhere + | from none to multiple arguments. Run the command option and -H to see the + | arguments available for each command option. + | Options + | Options specify an action and are uppercase. + | -A + | Add an existing certificate to a certificate database. The + | certificate database should already exist; if one is not present, + | this option will initialize one by default. + | -B + | Run a series of commands from the specified batch file. This + | requires the -i argument. + | -C + | Create a new binary certificate file from a binary certificate + | request file. Use the -i argument to specify the certificate + | request file. If this argument is not used, certutil prompts for a + | filename. + | -D + | Delete a certificate from the certificate database. + | -E + | Add an email certificate to the certificate database. + | -F + | Delete a private key from a key database. Specify the key to + | delete with the -n argument. Specify the database from which to + | delete the key with the -d argument. Use the -k argument to + | specify explicitly whether to delete a DSA, RSA, or ECC key. If + | you don't use the -k argument, the option looks for an RSA key + | matching the specified nickname. + | When you delete keys, be sure to also remove any certificates + | associated with those keys from the certificate database, by using + | -D. Some smart cards (for example, the Litronic card) do not let + | you remove a public key you have generated. In such a case, only + | the private key is deleted from the key pair. You can display the + | public key with the command certutil -K -h tokenname. + | -G + | Generate a new public and private key pair within a key database. + | The key database should already exist; if one is not present, this + | option will initialize one by default. Some smart cards (for + | example, the Litronic card) can store only one key pair. If you + | create a new key pair for such a card, the previous pair is + | overwritten. + | -H + | Display a list of the options and arguments used by the + | Certificate Database Tool. + | -K + | List the key ID of keys in the key database. A key ID is the + | modulus of the RSA key or the publicValue of the DSA key. IDs are + | displayed in hexadecimal ("0x" is not shown). + | -L + | List all the certificates, or display information about a named + | certificate, in a certificate database. Use the -h tokenname + | argument to specify the certificate database on a particular + | hardware or software token. + | -M + | Modify a certificate's trust attributes using the values of the -t + | argument. + | -N + | Create new certificate and key databases. + | -O + | Print the certificate chain. + | -R + | Create a certificate request file that can be submitted to a + | Certificate Authority (CA) for processing into a finished + | certificate. Output defaults to standard out unless you use -o + | output-file argument. Use the -a argument to specify ASCII output. + | -S + | Create an individual certificate and add it to a certificate + | database. + | -T + | Reset the key database or token. + | -U + | List all available modules or print a single named module. + | -V + | Check the validity of a certificate and its attributes. + | -W + | Change the password to a key database. + | --merge + | Merge a source database into the target database. This is used to + | merge legacy NSS databases (cert8.db and key3.db) into the newer + | SQLite databases (cert9.db and key4.db). + | --upgrade-merge + | Upgrade an old database and merge it into a new database. This is + | used to migrate legacy NSS databases (cert8.db and key3.db) into + | the newer SQLite databases (cert9.db and key4.db). + | Arguments + | Option arguments modify an action and are lowercase. + | -a + | Use ASCII format or allow the use of ASCII format for input or + | output. This formatting follows RFC 1113. For certificate + | requests, ASCII output defaults to standard output unless + | redirected. + | -b validity-time + | Specify a time at which a certificate is required to be valid. Use + | when checking certificate validity with the -V option. The format + | of the validity-time argument is YYMMDDHHMMSS[+HHMM|-HHMM|Z], + | which allows offsets to be set relative to the validity end time. + | Specifying seconds (SS) is optional. When specifying an explicit + | time, use a Z at the end of the term, YYMMDDHHMMSSZ, to close it. + | When specifying an offset time, use YYMMDDHHMMSS+HHMM or + | YYMMDDHHMMSS-HHMM for adding or subtracting time, respectively. + | If this option is not used, the validity check defaults to the + | current system time. + | -c issuer + | Identify the certificate of the CA from which a new certificate + | will derive its authenticity. Use the exact nickname or alias of + | the CA certificate, or use the CA's email address. Bracket the + | issuer string with quotation marks if it contains spaces. + | -d [sql:]directory + | Specify the database directory containing the certificate and key + | database files. + | certutil 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 sql: + | is not used, then the tool assumes that the given databases are in + | the old format. + | -e + | Check a certificate's signature during the process of validating a + | certificate. + | -f password-file + | Specify a file that will automatically supply the password to + | include in a certificate or to access a certificate database. This + | is a plain-text file containing one password. Be sure to prevent + | unauthorized access to this file. + | -g keysize + | Set a key size to use when generating new public and private key + | pairs. The minimum is 512 bits and the maximum is 8192 bits. The + | default is 1024 bits. Any size between the minimum and maximum is + | allowed. + | -h tokenname + | Specify the name of a token to use or act on. Unless specified + | otherwise the default token is an internal slot (specifically, + | internal slot 2). This slot can also be explicitly named with the + | string "internal". An internal slots is a virtual slot maintained + | in software, rather than a hardware device. Internal slot 2 is + | used by key and certificate services. Internal slot 1 is used by + | cryptographic services. + | -i input_file + | Pass an input file to the command. Depending on the command + | option, an input file can be a specific certificate, a certificate + | request file, or a batch file of commands. + | -k rsa|dsa|ec|all + | Specify the type of a key. The valid options are RSA, DSA, ECC, or + | all. The default value is rsa. Specifying the type of key can + | avoid mistakes caused by duplicate nicknames. + | -k key-type-or-id + | Specify the type or specific ID of a key. Giving a key type + | generates a new key pair; giving the ID of an existing key reuses + | that key pair (which is required to renew certificates). + | -l + | Display detailed information when validating a certificate with + | the -V option. + | -m serial-number + | Assign a unique serial number to a certificate being created. This + | operation should be performed by a CA. The default serial number + | is 0 (zero). Serial numbers are limited to integers. + | -n nickname + | Specify the nickname of a certificate or key to list, create, add + | to a database, modify, or validate. Bracket the nickname string + | with quotation marks if it contains spaces. + | -o output-file + | Specify the output file name for new certificates or binary + | certificate requests. Bracket the output-file string with + | quotation marks if it contains spaces. If this argument is not + | used the output destination defaults to standard output. + | -P dbPrefix + | Specify the prefix used on the certificate and key database file. + | This option is provided as a special case. Changing the names of + | the certificate and key databases is not recommended. + | -p phone + | Specify a contact telephone number to include in new certificates + | or certificate requests. Bracket this string with quotation marks + | if it contains spaces. + | -q pqgfile + | Read an alternate PQG value from the specified file when + | generating DSA key pairs. If this argument is not used, certutil + | generates its own PQG value. PQG files are created with a separate + | DSA utility. + | -q curve-name + | Set the elliptic curve name to use when generating ECC key pairs. + | A complete list of ECC curves is given in the help (-H). + | -r + | Display a certificate's binary DER encoding when listing + | information about that certificate with the -L option. + | -s subject + | Identify a particular certificate owner for new certificates or + | certificate requests. Bracket this string with quotation marks if + | it contains spaces. The subject identification format follows RFC + | #1485. + | -t trustargs + | Specify the trust attributes to modify in an existing certificate + | or to apply to a certificate when creating it or adding it to a + | database. There are three available trust categories for each + | certificate, expressed in the order SSL, email, object signing for + | each trust setting. In each category position, use none, any, or + | all of the attribute codes: + | o p - Valid peer + | o P - Trusted peer (implies p) + | o c - Valid CA + | o T - Trusted CA to issue client certificates (implies c) + | o C - Trusted CA to issue server certificates (SSL only) + | (implies c) + | o u - Certificate can be used for authentication or signing + | o w - Send warning (use with other attributes to include a + | warning when the certificate is used in that context) + | The attribute codes for the categories are separated by commas, + | and the entire set of attributes enclosed by quotation marks. For + | example: + | -t "TCu,Cu,Tuw" + | Use the -L option to see a list of the current certificates and + | trust attributes in a certificate database. + | -u certusage + | Specify a usage context to apply when validating a certificate + | with the -V option. + | The contexts are the following: + | o C (as an SSL client) + | o V (as an SSL server) + | o S (as an email signer) + | o R (as an email recipient) + | o O (as an OCSP status responder) + | o J (as an object signer) + | -v valid-months + | Set the number of months a new certificate will be valid. The + | validity period begins at the current system time unless an offset + | is added or subtracted with the -w option. If this argument is not + | used, the default validity period is three months. When this + | argument is used, the default three-month period is automatically + | added to any value given in the valid-month argument. For example, + | using this option to set a value of 3 would cause 3 to be added to + | the three-month default, creating a validity period of six months. + | You can use negative values to reduce the default period. For + | example, setting a value of -2 would subtract 2 from the default + | and create a validity period of one month. + | -w offset-months + | Set an offset from the current system time, in months, for the + | beginning of a certificate's validity period. Use when creating + | the certificate or adding it to a database. Express the offset in + | integers, using a minus sign (-) to indicate a negative offset. If + | this argument is not used, the validity period begins at the + | current system time. The length of the validity period is set with + | the -v argument. + | -X + | Force the key and certificate database to open in read-write mode. + | This is used with the -U and -L command options. + | -x + | Use certutil to generate the signature for a certificate being + | created or added to a database, rather than obtaining a signature + | from a separate CA. + | -y exp + | Set an alternate exponent value to use in generating a new RSA + | public key for the database, instead of the default value of + | 65537. The available alternate values are 3 and 17. + | -z noise-file + | Read a seed value from the specified file to generate a new + | private and public key pair. This argument makes it possible to + | use hardware-generated seed values or manually create a value from + | the keyboard. The minimum file size is 20 bytes. + | -0 SSO_password + | Set a site security officer password on a token. + | -1 \| --keyUsage keyword,keyword + | Set a Netscape Certificate Type Extension in the certificate. + | There are several available keywords: + | o digital signature + | o nonRepudiation + | o keyEncipherment + | o dataEncipherment + | o keyAgreement + | o certSigning + | o crlSigning + | o critical + | -2 + | Add a basic constraint extension to a certificate that is being + | created or added to a database. This extension supports the + | certificate chain verification process. certutil prompts for the + | certificate constraint extension to select. + | X.509 certificate extensions are described in RFC 5280. + | -3 + | Add an authority key ID extension to a certificate that is being + | created or added to a database. This extension supports the + | identification of a particular certificate, from among multiple + | certificates associated with one subject name, as the correct + | issuer of a certificate. The Certificate Database Tool will prompt + | you to select the authority key ID extension. + | X.509 certificate extensions are described in RFC 5280. + | -4 + | Add a CRL distribution point extension to a certificate that is + | being created or added to a database. This extension identifies + | the URL of a certificate's associated certificate revocation list + | (CRL). certutil prompts for the URL. + | X.509 certificate extensions are described in RFC 5280. + | -5 \| --nsCertType keyword,keyword + | Add a Netscape certificate type extension to a certificate that is + | being created or added to the database. There are several + | available keywords: + | o sslClient + | o sslServer + | o smime + | o objectSigning + | o sslCA + | o smimeCA + | o objectSigningCA + | o critical + | X.509 certificate extensions are described in RFC 5280. + | -6 \| --extKeyUsage keyword,keyword + | Add an extended key usage extension to a certificate that is being + | created or added to the database. Several keywords are available: + | o serverAuth + | o clientAuth + | o codeSigning + | o emailProtection + | o timeStamp + | o ocspResponder + | o stepUp + | o critical + | X.509 certificate extensions are described in RFC 5280. + | -7 emailAddrs + | Add a comma-separated list of email addresses to the subject + | alternative name extension of a certificate or certificate request + | that is being created or added to the database. Subject + | alternative name extensions are described in Section 4.2.1.7 of + | RFC 3280. + | -8 dns-names + | Add a comma-separated list of DNS names to the subject alternative + | name extension of a certificate or certificate request that is + | being created or added to the database. Subject alternative name + | extensions are described in Section 4.2.1.7 of RFC 3280. + | --extAIA + | Add the Authority Information Access extension to the certificate. + | X.509 certificate extensions are described in RFC 5280. + | --extSIA + | Add the Subject Information Access extension to the certificate. + | X.509 certificate extensions are described in RFC 5280. + | --extCP + | Add the Certificate Policies extension to the certificate. X.509 + | certificate extensions are described in RFC 5280. + | --extPM + | Add the Policy Mappings extension to the certificate. X.509 + | certificate extensions are described in RFC 5280. + | --extPC + | Add the Policy Constraints extension to the certificate. X.509 + | certificate extensions are described in RFC 5280. + | --extIA + | Add the Inhibit Any Policy Access extension to the certificate. + | X.509 certificate extensions are described in RFC 5280. + | --extSKID + | Add the Subject Key ID extension to the certificate. X.509 + | certificate extensions are described in RFC 5280. + | --source-dir certdir + | Identify the certificate database directory to upgrade. + | --source-prefix certdir + | Give the prefix of the certificate and key databases to upgrade. + | --upgrade-id uniqueID + | Give the unique ID of the database to upgrade. + | --upgrade-token-name name + | Set the name of the token to use while it is being upgraded. + | -@ pwfile + | Give the name of a password file to use for the database being + | upgraded. + | Usage and Examples + | Most of the command options in the examples listed here have more + | arguments available. The arguments included in these examples are the most + | common ones or are used to illustrate a specific scenario. Use the -H + | option to show the complete list of arguments for each command option. + | Creating New Security Databases + | Certificates, keys, and security modules related to managing certificates + | are stored in three related databases: + | o cert8.db or cert9.db + | o key3.db or key4.db + | o secmod.db or pkcs11.txt + | These databases must be created before certificates or keys can be + | generated. + | certutil -N -d [sql:]directory + | Creating a Certificate Request + | A certificate request contains most or all of the information that is used + | to generate the final certificate. This request is submitted separately to + | a certificate authority and is then approved by some mechanism + | (automatically or by human review). Once the request is approved, then the + | certificate is generated. + | $ certutil -R -k key-type-or-id [-q pqgfile|curve-name] -g key-size -s subject [-h tokenname] + -d [sql:]directory [-p phone] [-o output-file] [-a] + | The -R command options requires four arguments: + | o -k to specify either the key type to generate or, when renewing a + | certificate, the existing key pair to use + | o -g to set the keysize of the key to generate + | o -s to set the subject name of the certificate + | o -d to give the security database directory + | The new certificate request can be output in ASCII format (-a) or can be + | written to a specified file (-o). + | For example: + | $ certutil -R -k ec -q nistb409 -g 512 -s "CN=John Smith,O=Example Corp,L=Mountain + View,ST=California,C=US" -d sql:/home/my/sharednssdb -p 650-555-0123 -a -o cert.cer + | Generating key. This may take a few moments... + | Certificate request generated by Netscape + | Phone: 650-555-0123 + | Common Name: John Smith + | Email: (not ed) + | Organization: Example Corp + | State: California + | Country: US + | -----BEGIN NEW CERTIFICATE REQUEST----- + | MIIBIDCBywIBADBmMQswCQYDVQQGEwJVUzETMBEGA1UECBMKQ2FsaWZvcm5pYTEW + | MBQGA1UEBxMNTW91bnRhaW4gVmlldzEVMBMGA1UEChMMRXhhbXBsZSBDb3JwMRMw + | EQYDVQQDEwpKb2huIFNtaXRoMFwwDQYJKoZIhvcNAQEBBQADSwAwSAJBAMVUpDOZ + | KmHnOx7reP8Cc0Lk+fFWEuYIDX9W5K/BioQOKvEjXyQZhit9aThzBVMoSf1Y1S8J + | CzdUbCg1+IbnXaECAwEAAaAAMA0GCSqGSIb3DQEBBQUAA0EAryqZvpYrUtQ486Ny + | qmtyQNjIi1F8c1Z+TL4uFYlMg8z6LG/J/u1E5t1QqB5e9Q4+BhRbrQjRR1JZx3tB + | 1hP9Gg== + | -----END NEW CERTIFICATE REQUEST----- + | Creating a Certificate + | A valid certificate must be issued by a trusted CA. This can be done by + | specifying a CA certificate (-c) that is stored in the certificate + | database. If a CA key pair is not available, you can create a self-signed + | certificate using the -x argument with the -S command option. + | $ certutil -S -k rsa|dsa|ec -n certname -s subject [-c issuer \|-x] -t trustargs -d + [sql:]directory [-m serial-number] [-v valid-months] [-w offset-months] [-p phone] [-1] [-2] + [-3] [-4] [-5 keyword] [-6 keyword] [-7 emailAddress] [-8 dns-names] [--extAIA] [--extSIA] + [--extCP] [--extPM] [--extPC] [--extIA] [--extSKID] + | The series of numbers and --ext\* options set certificate extensions that + | can be added to the certificate when it is generated by the CA. + | For example, this creates a self-signed certificate: + | $ certutil -S -s "CN=Example CA" -n my-ca-cert -x -t "C,C,C" -1 -2 -5 -m 3650 + | From there, new certificates can reference the self-signed certificate: + | $ certutil -S -s "CN=My Server Cert" -n my-server-cert -c "my-ca-cert" -t "u,u,u" -1 -5 -6 -8 + -m 730 + | Generating a Certificate from a Certificate Request + | When a certificate request is created, a certificate can be generated by + | using the request and then referencing a certificate authority signing + | certificate (the issuer specified in the -c argument). The issuing + | certificate must be in the certificate database in the specified + | directory. + | certutil -C -c issuer -i cert-request-file -o output-file [-m serial-number] [-v valid-months] + [-w offset-months] -d [sql:]directory [-1] [-2] [-3] [-4] [-5 keyword] [-6 keyword] [-7 + emailAddress] [-8 dns-names] + | For example: + | $ certutil -C -c "my-ca-cert" -i /home/certs/cert.req -o cert.cer -m 010 -v 12 -w 1 -d + sql:/home/my/sharednssdb -1 nonRepudiation,dataEncipherment -5 sslClient -6 clientAuth -7 + jsmith@example.com + | Generating Key Pairs + | Key pairs are generated automatically with a certificate request or + | certificate, but they can also be generated independently using the -G + | command option. + | certutil -G -d [sql:]directory \| -h tokenname -k key-type -g key-size [-y exponent-value] -q + pqgfile|curve-name + | For example: + | $ certutil -G -h lunasa -k ec -g 256 -q sect193r2 + | Listing Certificates + | The -L command option lists all of the certificates listed in the + | certificate database. The path to the directory (-d) is required. + | $ certutil -L -d sql:/home/my/sharednssdb + | Certificate Nickname Trust Attributes + | SSL,S/MIME,JAR/XPI + | CA Administrator of Instance pki-ca1's Example Domain ID u,u,u + | TPS Administrator's Example Domain ID u,u,u + | Google Internet Authority ,, + | Certificate Authority - Example Domain CT,C,C + | Using additional arguments with -L can return and print the information + | for a single, specific certificate. For example, the -n argument passes + | the certificate name, while the -a argument prints the certificate in + | ASCII format: + | $ certutil -L -d sql:/home/my/sharednssdb -a -n "Certificate Authority - Example Domain" + | -----BEGIN CERTIFICATE----- + | MIIDmTCCAoGgAwIBAgIBATANBgkqhkiG9w0BAQUFADA5MRcwFQYDVQQKEw5FeGFt + | cGxlIERvbWFpbjEeMBwGA1UEAxMVQ2VydGlmaWNhdGUgQXV0aG9yaXR5MB4XDTEw + | MDQyOTIxNTY1OFoXDTEyMDQxODIxNTY1OFowOTEXMBUGA1UEChMORXhhbXBsZSBE + | b21haW4xHjAcBgNVBAMTFUNlcnRpZmljYXRlIEF1dGhvcml0eTCCASIwDQYJKoZI + | hvcNAQEBBQADggEPADCCAQoCggEBAO/bqUli2KwqXFKmMMG93KN1SANzNTXA/Vlf + | Tmrih3hQgjvR1ktIY9aG6cB7DSKWmtHp/+p4PUCMqL4ZrSGt901qxkePyZ2dYmM2 + | RnelK+SEUIPiUtoZaDhNdiYsE/yuDE8vQWj0vHCVL0w72qFUcSQ/WZT7FCrnUIUI + | udeWnoPSUn70gLhcj/lvxl7K9BHyD4Sq5CzktwYtFWLiiwV+ZY/Fl6JgbGaQyQB2 + | bP4iRMfloGqsxGuB1evWVDF1haGpFDSPgMnEPSLg3/3dXn+HDJbZ29EU8/xKzQEb + | 3V0AHKbu80zGllLEt2Zx/WDIrgJEN9yMfgKFpcmL+BvIRsmh0VsCAwEAAaOBqzCB + | qDAfBgNVHSMEGDAWgBQATgxHQyRUfKIZtdp55bZlFr+tFzAPBgNVHRMBAf8EBTAD + | AQH/MA4GA1UdDwEB/wQEAwIBxjAdBgNVHQ4EFgQUAE4MR0MkVHyiGbXaeeW2ZRa/ + | rRcwRQYIKwYBBQUHAQEEOTA3MDUGCCsGAQUFBzABhilodHRwOi8vbG9jYWxob3N0 + | LmxvY2FsZG9tYWluOjkxODAvY2Evb2NzcDANBgkqhkiG9w0BAQUFAAOCAQEAi8Gk + | L3XO43u7/TDOeEsWPmq+jZsDZ3GZ85Ajt3KROLWeKVZZZa2E2Hnsvf2uXbk5amKe + | lRxdSeRH9g85pv4KY7Z8xZ71NrI3+K3uwmnqkc6t0hhYb1mw/gx8OAAoluQx3biX + | JBDxjI73Cf7XUopplHBjjiwyGIJUO8BEZJ5L+TF4P38MJz1snLtzZpEAX5bl0U76 + | bfu/tZFWBbE8YAWYtkCtMcalBPj6jn2WD3M01kGozW4mmbvsj1cRB9HnsGsqyHCu + | U0ujlL1H/RWcjn607+CTeKH9jLMUqCIqPJNOa+kq/6F7NhNRRiuzASIbZc30BZ5a + | nI7q5n1USM3eWQlVXw== + | -----END CERTIFICATE----- + | Listing Keys + | Keys are the original material used to encrypt certificate data. The keys + | generated for certificates are stored separately, in the key database. + | To list all keys in the database, use the -K command option and the + | (required) -d argument to give the path to the directory. + | $ certutil -K -d sql:/home/my/sharednssdb + | certutil: Checking token "NSS Certificate DB" in slot "NSS User Private Key and Certificate + Services " + | < 0> rsa 455a6673bde9375c2887ec8bf8016b3f9f35861d Thawte Freemail Member's Thawte + Consulting (Pty) Ltd. ID + | < 1> rsa 40defeeb522ade11090eacebaaf1196a172127df Example Domain Administrator Cert + | < 2> rsa 1d0b06f44f6c03842f7d4f4a1dc78b3bcd1b85a5 John Smith user cert + | There are ways to narrow the keys listed in the search results: + | o To return a specific key, use the -n name argument with the name of + | the key. + | o If there are multiple security devices loaded, then the -h tokenname + | argument can search a specific token or all tokens. + | o If there are multiple key types available, then the -k key-type + | argument can search a specific type of key, like RSA, DSA, or ECC. + | Listing Security Modules + | The devices that can be used to store certificates -- both internal + | databases and external devices like smart cards -- are recognized and used + | by loading security modules. The -U command option lists all of the + | security modules listed in the secmod.db database. The path to the + | directory (-d) is required. + | $ certutil -U -d sql:/home/my/sharednssdb + | slot: NSS User Private Key and Certificate Services + | token: NSS Certificate DB + | slot: NSS Internal Cryptographic Services + | token: NSS Generic Crypto Services + | Adding Certificates to the Database + | Existing certificates or certificate requests can be added manually to the + | certificate database, even if they were generated elsewhere. This uses the + | -A command option. + | certutil -A -n certname -t trustargs -d [sql:]directory [-a] [-i input-file] + | For example: + | $ certutil -A -n "CN=My SSL Certificate" -t "u,u,u" -d sql:/home/my/sharednssdb -i + /home/example-certs/cert.cer + | A related command option, -E, is used specifically to add email + | certificates to the certificate database. The -E command has the same + | arguments as the -A command. The trust arguments for certificates have the + | format SSL,S/MIME,Code-signing, so the middle trust settings relate most + | to email certificates (though the others can be set). For example: + | $ certutil -E -n "CN=John Smith Email Cert" -t ",Pu," -d sql:/home/my/sharednssdb -i + /home/example-certs/email.cer + | Deleting Certificates to the Database + | Certificates can be deleted from a database using the -D option. The only + | required options are to give the security database directory and to + | identify the certificate nickname. + | certutil -D -d [sql:]directory -n "nickname" + | For example: + | $ certutil -D -d sql:/home/my/sharednssdb -n "my-ssl-cert" + | Validating Certificates + | A certificate contains an expiration date in itself, and expired + | certificates are easily rejected. However, certificates can also be + | revoked before they hit their expiration date. Checking whether a + | certificate has been revoked requires validating the certificate. + | Validation can also be used to ensure that the certificate is only used + | for the purposes it was initially issued for. Validation is carried out by + | the -V command option. + | certutil -V -n certificate-name [-b time] [-e] [-u cert-usage] -d [sql:]directory + | For example, to validate an email certificate: + | $ certutil -V -n "John Smith's Email Cert" -e -u S,R -d sql:/home/my/sharednssdb + | Modifying Certificate Trust Settings + | The trust settings (which relate to the operations that a certificate is + | allowed to be used for) can be changed after a certificate is created or + | added to the database. This is especially useful for CA certificates, but + | it can be performed for any type of certificate. + | certutil -M -n certificate-name -t trust-args -d [sql:]directory + | For example: + | $ certutil -M -n "My CA Certificate" -d sql:/home/my/sharednssdb -t "CTu,CTu,CTu" + | Printing the Certificate Chain + | Certificates can be issued in chains because every certificate authority + | itself has a certificate; when a CA issues a certificate, it essentially + | stamps that certificate with its own fingerprint. The -O prints the full + | chain of a certificate, going from the initial CA (the root CA) through + | ever intermediary CA to the actual certificate. For example, for an email + | certificate with two CAs in the chain: + | $ certutil -d sql:/home/my/sharednssdb -O -n "jsmith@example.com" + | "Builtin Object Token:Thawte Personal Freemail CA" [E=personal-freemail@thawte.com,CN=Thawte + Personal Freemail CA,OU=Certification Services Division,O=Thawte Consulting,L=Cape + Town,ST=Western Cape,C=ZA] + | "Thawte Personal Freemail Issuing CA - Thawte Consulting" [CN=Thawte Personal Freemail + Issuing CA,O=Thawte Consulting (Pty) Ltd.,C=ZA] + | "(null)" [E=jsmith@example.com,CN=Thawte Freemail Member] + | Resetting a Token + | The device which stores certificates -- both external hardware devices and + | internal software databases -- can be blanked and reused. This operation + | is performed on the device which stores the data, not directly on the + | security databases, so the location must be referenced through the token + | name (-h) as well as any directory path. If there is no external token + | used, the default value is internal. + | certutil -T -d [sql:]directory -h token-name -0 security-officer-password + | Many networks have dedicated personnel who handle changes to security + | tokens (the security officer). This person must supply the password to + | access the specified token. For example: + | $ certutil -T -d sql:/home/my/sharednssdb -h nethsm -0 secret + | Upgrading or Merging the Security Databases + | Many networks or applications may be using older BerkeleyDB versions of + | the certificate database (cert8.db). Databases can be upgraded to the new + | SQLite version of the database (cert9.db) using the --upgrade-merge + | command option or existing databases can be merged with the new cert9.db + | databases using the ---merge command. + | The --upgrade-merge command must give information about the original + | database and then use the standard arguments (like -d) to give the + | information about the new databases. The command also requires information + | that the tool uses for the process to upgrade and write over the original + | database. + | certutil --upgrade-merge -d [sql:]directory [-P dbprefix] --source-dir directory + --source-prefix dbprefix --upgrade-id id --upgrade-token-name name [-@ password-file] + | For example: + | $ certutil --upgrade-merge -d sql:/home/my/sharednssdb --source-dir /opt/my-app/alias/ + --source-prefix serverapp- --upgrade-id 1 --upgrade-token-name internal + | The --merge command only requires information about the location of the + | original database; since it doesn't change the format of the database, it + | can write over information without performing interim step. + | certutil --merge -d [sql:]directory [-P dbprefix] --source-dir directory --source-prefix + dbprefix [-@ password-file] + | For example: + | $ certutil --merge -d sql:/home/my/sharednssdb --source-dir /opt/my-app/alias/ --source-prefix + serverapp- + | Running certutil Commands from a Batch File + | A series of commands can be run sequentially from a text file with the -B + | command option. The only argument for this specifies the input file. + | $ certutil -B -i /path/to/batch-file + | NSS Database Types + | NSS originally used BerkeleyDB databases to store security information. + | The last versions of these legacy databases are: + | o cert8.db for certificates + | o key3.db for keys + | o secmod.db for PKCS #11 module information + | 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. + | In 2009, NSS introduced a new set of databases that are SQLite databases + | rather than BerkleyDB. These new databases provide more accessibility and + | performance: + | o cert9.db for certificates + | o key4.db for keys + | o pkcs11.txt, which is listing of all of the PKCS #11 modules contained + | in a new subdirectory in the security databases directory + | Because the SQLite databases are designed to be shared, these are the + | shared database type. The shared database type is preferred; the legacy + | format is included for backward compatibility. + | By default, the tools (certutil, pk12util, modutil) assume that the given + | security databases follow the more common legacy type. Using the SQLite + | databases must be manually specified by using the sql: prefix with the + | given security directory. For example: + | $ certutil -L -d sql:/home/my/sharednssdb + | To set the shared database type as the default type for the tools, set the + | NSS_DEFAULT_DB_TYPE environment variable to sql: + | export NSS_DEFAULT_DB_TYPE="sql" + | This line can be set added to the ~/.bashrc file to make the change + | permanent. + | 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: + | o https://wiki.mozilla.org/NSS_Shared_DB_Howto + | For an engineering draft on the changes in the shared NSS databases, see + | the NSS project wiki: + | o https://wiki.mozilla.org/NSS_Shared_DB + | See Also + | pk12util (1) + | modutil (1) + | certutil has arguments or operations that use features defined in several + | IETF RFCs. + | o `http://tools.ietf.org/html/rfc5280 `__ + | o `http://tools.ietf.org/html/rfc1113 `__ + | o `http://tools.ietf.org/html/rfc1485 `__ + | The NSS wiki has information on the new database design and how to + | configure applications to use it. + | o https://wiki.mozilla.org/NSS_Shared_DB_Howto + | o https://wiki.mozilla.org/NSS_Shared_DB + | Additional Resources + | For information about NSS and other tools related to NSS (like JSS), check + | out the NSS project wiki at + | + [1]\ `http://www.mozilla.org/projects/security/pki/nss/ `__. + The NSS site relates + | directly to NSS code changes and releases. + | Mailing lists: https://lists.mozilla.org/listinfo/dev-tech-crypto + | IRC: Freenode at #dogtag-pki + | Authors + | The NSS tools were written and maintained by developers with Netscape, Red + | Hat, and Sun. + | Authors: Elio Maldonado , Deon Lackey + | . + | Copyright + | (c) 2010, Red Hat, Inc. Licensed under the GNU Public License version 2. + | References + | Visible links + | 1. + `http://www.mozilla.org/projects/security/pki/nss/ `__ \ No newline at end of file diff --git a/security/nss/doc/rst/legacy/tools/cmsutil/index.rst b/security/nss/doc/rst/legacy/tools/cmsutil/index.rst new file mode 100644 index 0000000000..1a56ff4713 --- /dev/null +++ b/security/nss/doc/rst/legacy/tools/cmsutil/index.rst @@ -0,0 +1,111 @@ +.. _mozilla_projects_nss_tools_cmsutil: + +NSS tools : cmsutil +=================== + +.. container:: + + | Name + | cmsutil — Performs basic cryptograpic operations, such as encryption and + | decryption, on Cryptographic Message Syntax (CMS) messages. + | Synopsis + | cmsutil [options] `arguments `__ + | Description + | The cmsutil command-line uses the S/MIME Toolkit to perform basic + | operations, such as encryption and decryption, on Cryptographic Message + | Syntax (CMS) messages. + | To run cmsutil, type the command cmsutil option [arguments] where option + | and arguments are combinations of the options and arguments listed in the + | following section. Each command takes one option. Each option may take + | zero or more arguments. To see a usage string, issue the command without + | options. + | Options and Arguments + | Options + | Options specify an action. Option arguments modify an action. The options + | and arguments for the cmsutil command are defined as follows: + | -D + | Decode a message. + | -C + | Encrypt a message. + | -E + | Envelope a message. + | -O + | Create a certificates-only message. + | -S + | Sign a message. + | Arguments + | Option arguments modify an action and are lowercase. + | -c content + | Use this detached content (decode only). + | -d dbdir + | Specify the key/certificate database directory (default is ".") + | -e envfile + | Specify a file containing an enveloped message for a set of + | recipients to which you would like to send an encrypted message. + | If this is the first encrypted message for that set of recipients, + | a new enveloped message will be created that you can then use for + | future messages (encrypt only). + | -G + | Include a signing time attribute (sign only). + | -h num + | Generate email headers with info about CMS message (decode only). + | -i infile + | Use infile as a source of data (default is stdin). + | -N nickname + | Specify nickname of certificate to sign with (sign only). + | -n + | Suppress output of contents (decode only). + | -o outfile + | Use outfile as a destination of data (default is stdout). + | -P + | Include an S/MIME capabilities attribute. + | -p password + | Use password as key database password. + | -r recipient1,recipient2, ... + | Specify list of recipients (email addresses) for an encrypted or + | enveloped message. For certificates-only message, list of + | certificates to send. + | -T + | Suppress content in CMS message (sign only). + | -u certusage + | Set type of cert usage (default is certUsageEmailSigner). + | -Y ekprefnick + | Specify an encryption key preference by nickname. + | Usage + | Encrypt Example + | cmsutil -C [-i infile] [-o outfile] [-d dbdir] [-p password] -r "recipient1,recipient2, . . ." + -e envfile + | Decode Example + | cmsutil -D [-i infile] [-o outfile] [-d dbdir] [-p password] [-c content] [-n] [-h num] + | Envelope Example + | cmsutil -E [-i infile] [-o outfile] [-d dbdir] [-p password] -r "recipient1,recipient2, ..." + | Certificate-only Example + | cmsutil -O [-i infile] [-o outfile] [-d dbdir] [-p password] -r "cert1,cert2, . . ." + | Sign Message Example + | cmsutil -S [-i infile] [-o outfile] [-d dbdir] [-p password] -N nickname[-TGP] [-Y ekprefnick] + | See also + | certutil(1) + | See Also + | Additional Resources + | NSS is maintained in conjunction with PKI and security-related projects + | through Mozilla dn Fedora. The most closely-related project is Dogtag PKI, + | with a project wiki at [1]\ http://pki.fedoraproject.org/wiki/. + | For information specifically about NSS, the NSS project wiki is located at + | + [2]\ `http://www.mozilla.org/projects/security/pki/nss/ `__. + The NSS site relates + | directly to NSS code changes and releases. + | Mailing lists: pki-devel@redhat.com and pki-users@redhat.com + | IRC: Freenode at #dogtag-pki + | Authors + | The NSS tools were written and maintained by developers with Netscape and + | now with Red Hat. + | Authors: Elio Maldonado , Deon Lackey + | . + | Copyright + | (c) 2010, Red Hat, Inc. Licensed under the GNU Public License version 2. + | References + | Visible links + | 1. http://pki.fedoraproject.org/wiki/ + | 2. + `http://www.mozilla.org/projects/security/pki/nss/ `__ \ No newline at end of file diff --git a/security/nss/doc/rst/legacy/tools/crlutil/index.rst b/security/nss/doc/rst/legacy/tools/crlutil/index.rst new file mode 100644 index 0000000000..ee68b4dbfb --- /dev/null +++ b/security/nss/doc/rst/legacy/tools/crlutil/index.rst @@ -0,0 +1,229 @@ +.. _mozilla_projects_nss_tools_crlutil: + +NSS tools : crlutil +=================== + +.. container:: + + | Name + | crlutil — List, generate, modify, or delete CRLs within the NSS security + | database file(s) and list, create, modify or delete certificates entries + | in a particular CRL. + | Synopsis + | crlutil [options] `arguments `__ + | Description + | The Certificate Revocation List (CRL) Management Tool, crlutil, is a + | command-line utility that can list, generate, modify, or delete CRLs + | within the NSS security database file(s) and list, create, modify or + | delete certificates entries in a particular CRL. + | The key and certificate management process generally begins with creating + | keys in the key database, then generating and managing certificates in the + | certificate database(see certutil tool) and continues with certificates + | expiration or revocation. + | This document discusses certificate revocation list management. For + | information on security module database management, see Using the Security + | Module Database Tool. For information on certificate and key database + | management, see Using the Certificate Database Tool. + | To run the Certificate Revocation List Management Tool, type the command + | crlutil option [arguments] + | where options and arguments are combinations of the options and arguments + | listed in the following section. Each command takes one option. Each + | option may take zero or more arguments. To see a usage string, issue the + | command without options, or with the -H option. + | Options and Arguments + | Options + | Options specify an action. Option arguments modify an action. The options + | and arguments for the crlutil command are defined as follows: + | -G + | Create new Certificate Revocation List(CRL). + | -D + | Delete Certificate Revocation List from cert database. + | -I + | Import a CRL to the cert database + | -E + | Erase all CRLs of specified type from the cert database + | -L + | List existing CRL located in cert database file. + | -M + | Modify existing CRL which can be located in cert db or in + | arbitrary file. If located in file it should be encoded in ASN.1 + | encode format. + | -G + | Arguments + | Option arguments modify an action and are lowercase. + | -B + | Bypass CA signature checks. + | -P dbprefix + | Specify the prefix used on the NSS security database files (for + | example, my_cert8.db and my_key3.db). This option is provided as a + | special case. Changing the names of the certificate and key + | databases is not recommended. + | -a + | Use ASCII format or allow the use of ASCII format for input and + | output. This formatting follows RFC #1113. + | -c crl-gen-file + | Specify script file that will be used to control crl + | generation/modification. See crl-cript-file format below. If + | options -M|-G is used and -c crl-script-file is not specified, + | crlutil will read script data from standard input. + | -d directory + | Specify the database directory containing the certificate and key + | database files. On Unix the Certificate Database Tool defaults to + | $HOME/.netscape (that is, ~/.netscape). On Windows NT the default + | is the current directory. + | The NSS database files must reside in the same directory. + | -i crl-import-file + | Specify the file which contains the CRL to import + | -f password-file + | Specify a file that will automatically supply the password to + | include in a certificate or to access a certificate database. This + | is a plain-text file containing one password. Be sure to prevent + | unauthorized access to this file. + | -l algorithm-name + | Specify a specific signature algorithm. List of possible + | algorithms: MD2 \| MD4 \| MD5 \| SHA1 \| SHA256 \| SHA384 \| SHA512 + | -n nickname + | Specify the nickname of a certificate or key to list, create, add + | to a database, modify, or validate. Bracket the nickname string + | with quotation marks if it contains spaces. + | -o output-file + | Specify the output file name for new CRL. Bracket the output-file + | string with quotation marks if it contains spaces. If this + | argument is not used the output destination defaults to standard + | output. + | -t crl-type + | Specify type of CRL. possible types are: 0 - SEC_KRL_TYPE, 1 - + | SEC_CRL_TYPE. This option is obsolete + | -u url + | Specify the url. + | CRL Generation script syntax + | CRL generation script file has the following syntax: + | \* Line with comments should have # as a first symbol of a line + | \* Set "this update" or "next update" CRL fields: + | update=YYYYMMDDhhmmssZ nextupdate=YYYYMMDDhhmmssZ + | Field "next update" is optional. Time should be in GeneralizedTime format + | (YYYYMMDDhhmmssZ). For example: 20050204153000Z + | \* Add an extension to a CRL or a crl certificate entry: + | addext extension-name critical/non-critical [arg1[arg2 ...]] + | Where: + | extension-name: string value of a name of known extensions. + | critical/non-critical: is 1 when extension is critical and 0 otherwise. + | arg1, arg2: specific to extension type extension parameters + | addext uses the range that was set earlier by addcert and will install an + | extension to every cert entries within the range. + | \* Add certificate entries(s) to CRL: + | addcert range date + | range: two integer values separated by dash: range of certificates that + | will be added by this command. dash is used as a delimiter. Only one cert + | will be added if there is no delimiter. date: revocation date of a cert. + | Date should be represented in GeneralizedTime format (YYYYMMDDhhmmssZ). + | \* Remove certificate entry(s) from CRL + | rmcert range + | Where: + | range: two integer values separated by dash: range of certificates that + | will be added by this command. dash is used as a delimiter. Only one cert + | will be added if there is no delimiter. + | \* Change range of certificate entry(s) in CRL + | range new-range + | Where: + | new-range: two integer values separated by dash: range of certificates + | that will be added by this command. dash is used as a delimiter. Only one + | cert will be added if there is no delimiter. + | Implemented Extensions + | The extensions defined for CRL provide methods for associating additional + | attributes with CRLs of theirs entries. For more information see RFC #3280 + | \* Add The Authority Key Identifier extension: + | The authority key identifier extension provides a means of identifying the + | public key corresponding to the private key used to sign a CRL. + | authKeyId critical [key-id \| dn cert-serial] + | Where: + | authKeyIdent: identifies the name of an extension critical: value of 1 of + | 0. Should be set to 1 if this extension is critical or 0 otherwise. + | key-id: key identifier represented in octet string. dn:: is a CA + | distinguished name cert-serial: authority certificate serial number. + | \* Add Issuer Alternative Name extension: + | The issuer alternative names extension allows additional identities to be + | associated with the issuer of the CRL. Defined options include an rfc822 + | name (electronic mail address), a DNS name, an IP address, and a URI. + | issuerAltNames non-critical name-list + | Where: + | subjAltNames: identifies the name of an extension should be set to 0 since + | this is non-critical extension name-list: comma separated list of names + | \* Add CRL Number extension: + | The CRL number is a non-critical CRL extension which conveys a + | monotonically increasing sequence number for a given CRL scope and CRL + | issuer. This extension allows users to easily determine when a particular + | CRL supersedes another CRL + | crlNumber non-critical number + | Where: + | crlNumber: identifies the name of an extension critical: should be set to + | 0 since this is non-critical extension number: value of long which + | identifies the sequential number of a CRL. + | \* Add Revocation Reason Code extension: + | The reasonCode is a non-critical CRL entry extension that identifies the + | reason for the certificate revocation. + | reasonCode non-critical code + | Where: + | reasonCode: identifies the name of an extension non-critical: should be + | set to 0 since this is non-critical extension code: the following codes + | are available: + | unspecified (0), keyCompromise (1), cACompromise (2), affiliationChanged + | (3), superseded (4), cessationOfOperation (5), certificateHold (6), + | removeFromCRL (8), privilegeWithdrawn (9), aACompromise (10) + | \* Add Invalidity Date extension: + | The invalidity date is a non-critical CRL entry extension that provides + | the date on which it is known or suspected that the private key was + | compromised or that the certificate otherwise became invalid. + | invalidityDate non-critical date + | Where: + | crlNumber: identifies the name of an extension non-critical: should be set + | to 0 since this is non-critical extension date: invalidity date of a cert. + | Date should be represented in GeneralizedTime format (YYYYMMDDhhmmssZ). + | Usage + | The Certificate Revocation List Management Tool's capabilities are grouped + | as follows, using these combinations of options and arguments. Options and + | arguments in square brackets are optional, those without square brackets + | are required. + | See "Implemented extensions" for more information regarding extensions and + | their parameters. + | \* Creating or modifying a CRL: + | crlutil -G|-M -c crl-gen-file -n nickname [-i crl] [-u url] [-d keydir] [-P dbprefix] [-l alg] + [-a] [-B] + | \* Listing all CRls or a named CRL: + | crlutil -L [-n crl-name] [-d krydir] + | \* Deleting CRL from db: + | crlutil -D -n nickname [-d keydir] [-P dbprefix] + | \* Erasing CRLs from db: + | crlutil -E [-d keydir] [-P dbprefix] + | \* Deleting CRL from db: + | crlutil -D -n nickname [-d keydir] [-P dbprefix] + | \* Erasing CRLs from db: + | crlutil -E [-d keydir] [-P dbprefix] + | \* Import CRL from file: + | crlutil -I -i crl [-t crlType] [-u url] [-d keydir] [-P dbprefix] [-B] + | See also + | certutil(1) + | See Also + | Additional Resources + | NSS is maintained in conjunction with PKI and security-related projects + | through Mozilla dn Fedora. The most closely-related project is Dogtag PKI, + | with a project wiki at [1]\ http://pki.fedoraproject.org/wiki/. + | For information specifically about NSS, the NSS project wiki is located at + | + [2]\ `http://www.mozilla.org/projects/security/pki/nss/ `__. + The NSS site relates + | directly to NSS code changes and releases. + | Mailing lists: pki-devel@redhat.com and pki-users@redhat.com + | IRC: Freenode at #dogtag-pki + | Authors + | The NSS tools were written and maintained by developers with Netscape and + | now with Red Hat. + | Authors: Elio Maldonado , Deon Lackey + | . + | Copyright + | (c) 2010, Red Hat, Inc. Licensed under the GNU Public License version 2. + | References + | Visible links + | 1. http://pki.fedoraproject.org/wiki/ + | 2. + `http://www.mozilla.org/projects/security/pki/nss/ `__ \ No newline at end of file diff --git a/security/nss/doc/rst/legacy/tools/index.rst b/security/nss/doc/rst/legacy/tools/index.rst new file mode 100644 index 0000000000..ac7f743339 --- /dev/null +++ b/security/nss/doc/rst/legacy/tools/index.rst @@ -0,0 +1,125 @@ +.. _mozilla_projects_nss_tools: + +NSS Tools +========= + +.. _nss_security_tools: + +`NSS Security Tools <#nss_security_tools>`__ +-------------------------------------------- + +.. container:: + + Newsgroup: `mozilla.dev.tech.crypto `__ + +`Overview <#overview>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + The NSS Security Tools allow developers to test, debug, and manage applications that use NSS. The + `Tools Information <#tools>`__ table below describes both the tools that are currently working + and those that are still under development. The links for each tool take you to the source code, + documentation, plans, and related links for each tool. The links will become active when + information is available. + + Currently, you must download the NSS 3.1 source and build it to create binary files for the NSS + tools. For information about downloading the NSS source, see + :ref:`mozilla_projects_nss_building`. + + If you have feedback or questions, please feel free to post to + `mozilla.dev.tech.crypto `__. This newsgroup is + the preferred forum for all questions about NSS and NSS tools. + +.. _overall_objectives: + +`Overall Objectives <#overall_objectives>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + #. Provide a tool for analyzing and repairing certificate databases (`dbck <#dbck>`__). + #. Migrate tools from secutil.h interface to PKCS #11 interface. + #. Eliminate redundant functionality in tools. Many tools implement private versions of + PKCS11Init(), OpenCertDB(), etc. + #. Eliminate use of getopt() and replace with NSPR calls to get command options (to eliminate + platform dependencies with getopt()). + +.. _tools_information: + +`Tools information <#tools_information>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + +--------------+-----------------------------------------+-----------------------------------------+ + | **Tool** | **Description** | **Links** | + +--------------+-----------------------------------------+-----------------------------------------+ + | certutil 2.0 | Manage certificate and key databases | ` | + | | (cert7.db and key3.db). | Source `__, | + | | | :ref | + | | | :`mozilla_projects_nss_tools_certutil`, | + | | | :ref:`moz | + | | | illa_projects_nss_tools_certutil-tasks` | + +--------------+-----------------------------------------+-----------------------------------------+ + | cmsutil 1.0 | Performs basic CMS operations such as | `So | + | | encrypting, decrypting, and signing | urce `__, | + | | | :r | + | | | ef:`mozilla_projects_nss_tools_cmsutil` | + +--------------+-----------------------------------------+-----------------------------------------+ + | crlutil | Manage certificate revocation lists | `Source `__, | + | | | :re | + | | | f:`mozilla_projects_nss_tools_crlutil`, | + +--------------+-----------------------------------------+-----------------------------------------+ + | dbck 1.0 | Analyze and repair certificate | `Source `__, | + | | | :ref: | + | | | `mozilla_projects_nss_tools_dbck-tasks` | + +--------------+-----------------------------------------+-----------------------------------------+ + | modutil 1.1 | Manage the database of PKCS11 modules | `Source `__, | + | | properties of existing modules (such as | :re | + | | whether a module is the default | f:`mozilla_projects_nss_tools_modutil`, | + | | provider of some crypto service). | :ref:`mo | + | | | zilla_projects_nss_tools_modutil-tasks` | + +--------------+-----------------------------------------+-----------------------------------------+ + | pk12util 1.0 | Import and export keys and certificates | ` | + | | between the cert/key databases and | Source `__, | + | | | :ref | + | | | :`mozilla_projects_nss_tools_pk12util`, | + | | | :ref:`moz | + | | | illa_projects_nss_tools_pk12util-tasks` | + +--------------+-----------------------------------------+-----------------------------------------+ + | signtool 1.3 | Create digitally-signed jar archives | ` | + | | containing files and/or code. | Source `__, | + | | | `Do | + | | | cumentation `__, | + +--------------+-----------------------------------------+-----------------------------------------+ + | signver 1.1 | Verify signatures on digitally-signed | `Source `__, | + | | | `Document | + | | | ation `__, | + | | | :ref:`mo | + | | | zilla_projects_nss_tools_signver-tasks` | + +--------------+-----------------------------------------+-----------------------------------------+ + | sslstrength | SSL Strength | :ref:` | + | | | mozilla_projects_nss_tools_sslstrength` | + +--------------+-----------------------------------------+-----------------------------------------+ + | ssltap 3.2 | Proxy requests for an SSL server and | `Source `__, | + | | exchanged between the client and | : | + | | server. The ssltap tool does not | ref:`mozilla_projects_nss_tools_ssltap` | + | | decrypt data, but it shows things like | | + | | the type of SSL message (clientHello, | | + | | serverHello, etc) and connection data | | + | | (protocol version, cipher suite, etc). | | + | | This tool is very useful for debugging. | | + +--------------+-----------------------------------------+-----------------------------------------+ \ No newline at end of file diff --git a/security/nss/doc/rst/legacy/tools/modutil/index.rst b/security/nss/doc/rst/legacy/tools/modutil/index.rst new file mode 100644 index 0000000000..b3251735d6 --- /dev/null +++ b/security/nss/doc/rst/legacy/tools/modutil/index.rst @@ -0,0 +1,640 @@ +.. _mozilla_projects_nss_tools_modutil: + +NSS tools : modutil +=================== + +.. container:: + + | Name + | modutil — Manage PKCS #11 module information within the security module + | database. + | Synopsis + | modutil [options] `arguments `__ + | Description + | The Security Module Database Tool, modutil, is a command-line utility for + | managing PKCS #11 module information both within secmod.db files and + | within hardware tokens. modutil can add and delete PKCS #11 modules, + | change passwords on security databases, set defaults, list module + | contents, enable or disable slots, enable or disable FIPS 140-2 + | compliance, and assign default providers for cryptographic operations. + | This tool can also create certificate, key, and module security database + | files. + | The tasks associated with security module database management are part of + | a process that typically also involves managing key databases and + | certificate databases. + | Options + | Running modutil always requires one (and only one) option to specify the + | type of module operation. Each option may take arguments, anywhere from + | none to multiple arguments. + | Options + | -add modulename + | Add the named PKCS #11 module to the database. Use this option + | with the -libfile, -ciphers, and -mechanisms arguments. + | -changepw tokenname + | Change the password on the named token. If the token has not been + | initialized, this option initializes the password. Use this option + | with the -pwfile and -newpwfile arguments. A password is + | equivalent to a personal identification number (PIN). + | -chkfips + | Verify whether the module is in the given FIPS mode. true means to + | verify that the module is in FIPS mode, while false means to + | verify that the module is not in FIPS mode. + | -create + | Create new certificate, key, and module databases. Use the -dbdir + | directory argument to specify a directory. If any of these + | databases already exist in a specified directory, modutil returns + | an error message. + | -default modulename + | Specify the security mechanisms for which the named module will be + | a default provider. The security mechanisms are specified with the + | -mechanisms argument. + | -delete modulename + | Delete the named module. The default NSS PKCS #11 module cannot be + | deleted. + | -disable modulename + | Disable all slots on the named module. Use the -slot argument to + | disable a specific slot. + | -enable modulename + | Enable all slots on the named module. Use the -slot argument to + | enable a specific slot. + | -fips [true \| false] + | Enable (true) or disable (false) FIPS 140-2 compliance for the + | default NSS module. + | -force + | Disable modutil's interactive prompts so it can be run from a + | script. Use this option only after manually testing each planned + | operation to check for warnings and to ensure that bypassing the + | prompts will cause no security lapses or loss of database + | integrity. + | -jar JAR-file + | Add a new PKCS #11 module to the database using the named JAR + | file. Use this command with the -installdir and -tempdir + | arguments. The JAR file uses the NSS PKCS #11 JAR format to + | identify all the files to be installed, the module's name, the + | mechanism flags, and the cipher flags, as well as any files to be + | installed on the target machine, including the PKCS #11 module + | library file and other files such as documentation. This is + | covered in the JAR installation file section in the man page, + | which details the special script needed to perform an installation + | through a server or with modutil. + | -list [modulename] + | Display basic information about the contents of the secmod.db + | file. Specifying a modulename displays detailed information about + | a particular module and its slots and tokens. + | -rawadd + | Add the module spec string to the secmod.db database. + | -rawlist + | Display the module specs for a specified module or for all + | loadable modules. + | -undefault modulename + | Specify the security mechanisms for which the named module will + | not be a default provider. The security mechanisms are specified + | with the -mechanisms argument. + | Arguments + | MODULE + | Give the security module to access. + | MODULESPEC + | Give the security module spec to load into the security database. + | -ciphers cipher-enable-list + | Enable specific ciphers in a module that is being added to the + | database. The cipher-enable-list is a colon-delimited list of + | cipher names. Enclose this list in quotation marks if it contains + | spaces. + | -dbdir [sql:]directory + | Specify the database directory in which to access or create + | security module database files. + | modutil 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 sql: + | is not used, then the tool assumes that the given databases are in + | the old format. + | --dbprefix prefix + | Specify the prefix used on the database files, such as my\_ for + | my_cert8.db. This option is provided as a special case. Changing + | the names of the certificate and key databases is not recommended. + | -installdir root-installation-directory + | Specify the root installation directory relative to which files + | will be installed by the -jar option. This directory should be one + | below which it is appropriate to store dynamic library files, such + | as a server's root directory. + | -libfile library-file + | Specify a path to a library file containing the implementation of + | the PKCS #11 interface module that is being added to the database. + | -mechanisms mechanism-list + | Specify the security mechanisms for which a particular module will + | be flagged as a default provider. The mechanism-list is a + | colon-delimited list of mechanism names. Enclose this list in + | quotation marks if it contains spaces. + | The module becomes a default provider for the listed mechanisms + | when those mechanisms are enabled. If more than one module claims + | to be a particular mechanism's default provider, that mechanism's + | default provider is undefined. + | modutil supports several mechanisms: RSA, DSA, RC2, RC4, RC5, AES, + | DES, DH, SHA1, SHA256, SHA512, SSL, TLS, MD5, MD2, RANDOM (for + | random number generation), and FRIENDLY (meaning certificates are + | publicly readable). + | -newpwfile new-password-file + | Specify a text file containing a token's new or replacement + | password so that a password can be entered automatically with the + | -changepw option. + | -nocertdb + | Do not open the certificate or key databases. This has several + | effects: + | o With the -create command, only a module security file is + | created; certificate and key databases are not created. + | o With the -jar command, signatures on the JAR file are not + | checked. + | o With the -changepw command, the password on the NSS internal + | module cannot be set or changed, since this password is + | stored in the key database. + | -pwfile old-password-file + | Specify a text file containing a token's existing password so that + | a password can be entered automatically when the -changepw option + | is used to change passwords. + | -secmod secmodname + | Give the name of the security module database (like secmod.db) to + | load. + | -slot slotname + | Specify a particular slot to be enabled or disabled with the + | -enable or -disable options. + | -string CONFIG_STRING + | Pass a configuration string for the module being added to the + | database. + | -tempdir temporary-directory + | Give a directory location where temporary files are created during + | the installation by the -jar option. If no temporary directory is + | specified, the current directory is used. + | Usage and Examples + | Creating Database Files + | Before any operations can be performed, there must be a set of security + | databases available. modutil can be used to create these files. The only + | required argument is the database that where the databases will be + | located. + | modutil -create -dbdir [sql:]directory + | Adding a Cryptographic Module + | Adding a PKCS #11 module means submitting a supporting library file, + | enabling its ciphers, and setting default provider status for various + | security mechanisms. This can be done by supplying all of the information + | through modutil directly or by running a JAR file and install script. For + | the most basic case, simply upload the library: + | modutil -add modulename -libfile library-file [-ciphers cipher-enable-list] [-mechanisms + mechanism-list] + | For example: + | modutil -dbdir sql:/home/my/sharednssdb -add "Example PKCS #11 Module" -libfile + "/tmp/crypto.so" -mechanisms RSA:DSA:RC2:RANDOM + | Using database directory ... + | Module "Example PKCS #11 Module" added to database. + | Installing a Cryptographic Module from a JAR File + | PKCS #11 modules can also be loaded using a JAR file, which contains all + | of the required libraries and an installation script that describes how to + | install the module. The JAR install script is described in more detail in + | [1]the section called “JAR Installation File Format”. + | The JAR installation script defines the setup information for each + | platform that the module can be installed on. For example: + | Platforms { + | Linux:5.4.08:x86 { + | ModuleName { "Example PKCS #11 Module" } + | ModuleFile { crypto.so } + | DefaultMechanismFlags{0x0000} + | CipherEnableFlags{0x0000} + | Files { + | crypto.so { + | Path{ /tmp/crypto.so } + | } + | setup.sh { + | Executable + | Path{ /tmp/setup.sh } + | } + | } + | } + | Linux:6.0.0:x86 { + | EquivalentPlatform { Linux:5.4.08:x86 } + | } + | } + | Both the install script and the required libraries must be bundled in a + | JAR file, which is specified with the -jar argument. + | modutil -dbdir sql:/home/mt"jar-install-filey/sharednssdb -jar install.jar -installdir + sql:/home/my/sharednssdb + | This installation JAR file was signed by: + | ---------------------------------------------- + | **SUBJECT NAME*\* + | C=US, ST=California, L=Mountain View, CN=Cryptorific Inc., OU=Digital ID + | Class 3 - Netscape Object Signing, OU="www.verisign.com/repository/CPS + | Incorp. by Ref.,LIAB.LTD(c)9 6", OU=www.verisign.com/CPS Incorp.by Ref + | . LIABILITY LTD.(c)97 VeriSign, OU=VeriSign Object Signing CA - Class 3 + | Organization, OU="VeriSign, Inc.", O=VeriSign Trust Network \**ISSUER + | NAME**, OU=www.verisign.com/CPS Incorp.by Ref. LIABILITY LTD.(c)97 + | VeriSign, OU=VeriSign Object Signing CA - Class 3 Organization, + | OU="VeriSign, Inc.", O=VeriSign Trust Network + | ---------------------------------------------- + | Do you wish to continue this installation? (y/n) y + | Using installer script "installer_script" + | Successfully parsed installation script + | Current platform is Linux:5.4.08:x86 + | Using installation parameters for platform Linux:5.4.08:x86 + | Installed file crypto.so to /tmp/crypto.so + | Installed file setup.sh to ./pk11inst.dir/setup.sh + | Executing "./pk11inst.dir/setup.sh"... + | "./pk11inst.dir/setup.sh" executed successfully + | Installed module "Example PKCS #11 Module" into module database + | Installation completed successfully + | Adding Module Spec + | Each module has information stored in the security database about its + | configuration and parameters. These can be added or edited using the + | -rawadd command. For the current settings or to see the format of the + | module spec in the database, use the -rawlist option. + | modutil -rawadd modulespec + | Deleting a Module + | A specific PKCS #11 module can be deleted from the secmod.db database: + | modutil -delete modulename -dbdir [sql:]directory + | Displaying Module Information + | The secmod.db database contains information about the PKCS #11 modules + | that are available to an application or server to use. The list of all + | modules, information about specific modules, and database configuration + | specs for modules can all be viewed. + | To simply get a list of modules in the database, use the -list command. + | modutil -list [modulename] -dbdir [sql:]directory + | Listing the modules shows the module name, their status, and other + | associated security databases for certificates and keys. For example: + | modutil -list -dbdir sql:/home/my/sharednssdb + | Listing of PKCS #11 Modules + | ----------------------------------------------------------- + | 1. NSS Internal PKCS #11 Module + | slots: 2 slots attached + | status: loaded + | slot: NSS Internal Cryptographic Services + | token: NSS Generic Crypto Services + | slot: NSS User Private Key and Certificate Services + | token: NSS Certificate DB + | ----------------------------------------------------------- + | Passing a specific module name with the -list returns details information + | about the module itself, like supported cipher mechanisms, version + | numbers, serial numbers, and other information about the module and the + | token it is loaded on. For example: + | modutil -list "NSS Internal PKCS #11 Module" -dbdir sql:/home/my/sharednssdb + | ----------------------------------------------------------- + | Name: NSS Internal PKCS #11 Module + | Library file: \**Internal ONLY module*\* + | Manufacturer: Mozilla Foundation + | Description: NSS Internal Crypto Services + | PKCS #11 Version 2.20 + | Library Version: 3.11 + | Cipher Enable Flags: None + | Default Mechanism Flags: RSA:RC2:RC4:DES:DH:SHA1:MD5:MD2:SSL:TLS:AES + | Slot: NSS Internal Cryptographic Services + | Slot Mechanism Flags: RSA:RC2:RC4:DES:DH:SHA1:MD5:MD2:SSL:TLS:AES + | Manufacturer: Mozilla Foundation + | Type: Software + | Version Number: 3.11 + | Firmware Version: 0.0 + | Status: Enabled + | Token Name: NSS Generic Crypto Services + | Token Manufacturer: Mozilla Foundation + | Token Model: NSS 3 + | Token Serial Number: 0000000000000000 + | Token Version: 4.0 + | Token Firmware Version: 0.0 + | Access: Write Protected + | Login Type: Public (no login required) + | User Pin: NOT Initialized + | Slot: NSS User Private Key and Certificate Services + | Slot Mechanism Flags: None + | Manufacturer: Mozilla Foundation + | Type: Software + | Version Number: 3.11 + | Firmware Version: 0.0 + | Status: Enabled + | Token Name: NSS Certificate DB + | Token Manufacturer: Mozilla Foundation + | Token Model: NSS 3 + | Token Serial Number: 0000000000000000 + | Token Version: 8.3 + | Token Firmware Version: 0.0 + | Access: NOT Write Protected + | Login Type: Login required + | User Pin: Initialized + | A related command, -rawlist returns information about the database + | configuration for the modules. (This information can be edited by loading + | new specs using the -rawadd command.) + | modutil -rawlist -dbdir sql:/home/my/sharednssdb + | name="NSS Internal PKCS #11 Module" parameters="configdir=. certPrefix= keyPrefix= + secmod=secmod.db flags=readOnly " NSS="trustOrder=75 cipherOrder=100 + slotParams={0x00000001=[slotFlags=RSA,RC4,RC2,DES,DH,SHA1,MD5,MD2,SSL,TLS,AES,RANDOM askpw=any + timeout=30 ] } Flags=internal,critical" + | Setting a Default Provider for Security Mechanisms + | Multiple security modules may provide support for the same security + | mechanisms. It is possible to set a specific security module as the + | default provider for a specific security mechanism (or, conversely, to + | prohibit a provider from supplying those mechanisms). + | modutil -default modulename -mechanisms mechanism-list + | To set a module as the default provider for mechanisms, use the -default + | command with a colon-separated list of mechanisms. The available + | mechanisms depend on the module; NSS supplies almost all common + | mechanisms. For example: + | modutil -default "NSS Internal PKCS #11 Module" -dbdir -mechanisms RSA:DSA:RC2 + | Using database directory c:\databases... + | Successfully changed defaults. + | Clearing the default provider has the same format: + | modutil -undefault "NSS Internal PKCS #11 Module" -dbdir -mechanisms MD2:MD5 + | Enabling and Disabling Modules and Slots + | Modules, and specific slots on modules, can be selectively enabled or + | disabled using modutil. Both commands have the same format: + | modutil -enable|-disable modulename [-slot slotname] + | For example: + | modutil -enable "NSS Internal PKCS #11 Module" -slot "NSS Internal Cryptographic + Services " -dbdir . + | Slot "NSS Internal Cryptographic Services " enabled. + | Be sure that the appropriate amount of trailing whitespace is after the + | slot name. Some slot names have a significant amount of whitespace that + | must be included, or the operation will fail. + | Enabling and Verifying FIPS Compliance + | The NSS modules can have FIPS 140-2 compliance enabled or disabled using + | modutil with the -fips option. For example: + | modutil -fips true -dbdir sql:/home/my/sharednssdb/ + | FIPS mode enabled. + | To verify that status of FIPS mode, run the -chkfips command with either a + | true or false flag (it doesn't matter which). The tool returns the current + | FIPS setting. + | modutil -chkfips false -dbdir sql:/home/my/sharednssdb/ + | FIPS mode enabled. + | Changing the Password on a Token + | Initializing or changing a token's password: + | modutil -changepw tokenname [-pwfile old-password-file] [-newpwfile new-password-file] + | modutil -dbdir sql:/home/my/sharednssdb -changepw "NSS Certificate DB" + | Enter old password: + | Incorrect password, try again... + | Enter old password: + | Enter new password: + | Re-enter new password: + | Token "Communicator Certificate DB" password changed successfully. + | JAR Installation File Format + | When a JAR file is run by a server, by modutil, or by any program that + | does not interpret JavaScript, a special information file must be included + | to install the libraries. There are several things to keep in mind with + | this file: + | o It must be declared in the JAR archive's manifest file. + | o The script can have any name. + | o The metainfo tag for this is Pkcs11_install_script. To declare + | meta-information in the manifest file, put it in a file that is passed + | to signtool. + | Sample Script + | For example, the PKCS #11 installer script could be in the file + | pk11install. If so, the metainfo file for signtool includes a line such as + | this: + | + Pkcs11_install_script: pk11install + | The script must define the platform and version number, the module name + | and file, and any optional information like supported ciphers and + | mechanisms. Multiple platforms can be defined in a single install file. + | ForwardCompatible { IRIX:6.2:mips SUNOS:5.5.1:sparc } + | Platforms { + | WINNT::x86 { + | ModuleName { "Example Module" } + | ModuleFile { win32/fort32.dll } + | DefaultMechanismFlags{0x0001} + | DefaultCipherFlags{0x0001} + | Files { + | win32/setup.exe { + | Executable + | RelativePath { %temp%/setup.exe } + | } + | win32/setup.hlp { + | RelativePath { %temp%/setup.hlp } + | } + | win32/setup.cab { + | RelativePath { %temp%/setup.cab } + | } + | } + | } + | WIN95::x86 { + | EquivalentPlatform {WINNT::x86} + | } + | SUNOS:5.5.1:sparc { + | ModuleName { "Example UNIX Module" } + | ModuleFile { unix/fort.so } + | DefaultMechanismFlags{0x0001} + | CipherEnableFlags{0x0001} + | Files { + | unix/fort.so { + | RelativePath{%root%/lib/fort.so} + | AbsolutePath{/usr/local/netscape/lib/fort.so} + | FilePermissions{555} + | } + | xplat/instr.html { + | RelativePath{%root%/docs/inst.html} + | AbsolutePath{/usr/local/netscape/docs/inst.html} + | FilePermissions{555} + | } + | } + | } + | IRIX:6.2:mips { + | EquivalentPlatform { SUNOS:5.5.1:sparc } + | } + | } + | Script Grammar + | The script is basic Java, allowing lists, key-value pairs, strings, and + | combinations of all of them. + | --> valuelist + | valuelist --> value valuelist + | + | value ---> key_value_pair + | string + | key_value_pair --> key { valuelist } + | key --> string + | string --> simple_string + | "complex_string" + | simple_string --> [^ \\t\n\""{""}"]+ + | complex_string --> ([^\"\\\r\n]|(\\\")|(\\\\))+ + | Quotes and backslashes must be escaped with a backslash. A complex string + | must not include newlines or carriage returns.Outside of complex strings, + | all white space (for example, spaces, tabs, and carriage returns) is + | considered equal and is used only to delimit tokens. + | Keys + | The Java install file uses keys to define the platform and module + | information. + | ForwardCompatible gives a list of platforms that are forward compatible. + | If the current platform cannot be found in the list of supported + | platforms, then the ForwardCompatible list is checked for any platforms + | that have the same OS and architecture in an earlier version. If one is + | found, its attributes are used for the current platform. + | Platforms (required) Gives a list of platforms. Each entry in the list is + | itself a key-value pair: the key is the name of the platform and the value + | list contains various attributes of the platform. The platform string is + | in the format system name:OS release:architecture. The installer obtains + | these values from NSPR. OS release is an empty string on non-Unix + | operating systems. NSPR supports these platforms: + | o AIX (rs6000) + | o BSDI (x86) + | o FREEBSD (x86) + | o HPUX (hppa1.1) + | o IRIX (mips) + | o LINUX (ppc, alpha, x86) + | o MacOS (PowerPC) + | o NCR (x86) + | o NEC (mips) + | o OS2 (x86) + | o OSF (alpha) + | o ReliantUNIX (mips) + | o SCO (x86) + | o SOLARIS (sparc) + | o SONY (mips) + | o SUNOS (sparc) + | o UnixWare (x86) + | o WIN16 (x86) + | o WIN95 (x86) + | o WINNT (x86) + | For example: + | IRIX:6.2:mips + | SUNOS:5.5.1:sparc + | Linux:2.0.32:x86 + | WIN95::x86 + | The module information is defined independently for each platform in the + | ModuleName, ModuleFile, and Files attributes. These attributes must be + | given unless an EquivalentPlatform attribute is specified. + | Per-Platform Keys + | Per-platform keys have meaning only within the value list of an entry in + | the Platforms list. + | ModuleName (required) gives the common name for the module. This name is + | used to reference the module by servers and by the modutil tool. + | ModuleFile (required) names the PKCS #11 module file for this platform. + | The name is given as the relative path of the file within the JAR archive. + | Files (required) lists the files that need to be installed for this + | module. Each entry in the file list is a key-value pair. The key is the + | path of the file in the JAR archive, and the value list contains + | attributes of the file. At least RelativePath or AbsolutePath must be + | specified for each file. + | DefaultMechanismFlags specifies mechanisms for which this module is the + | default provider; this is equivalent to the -mechanism option with the + | -add command. This key-value pair is a bitstring specified in hexadecimal + | (0x) format. It is constructed as a bitwise OR. If the + | DefaultMechanismFlags entry is omitted, the value defaults to 0x0. + | RSA: 0x00000001 + | DSA: 0x00000002 + | RC2: 0x00000004 + | RC4: 0x00000008 + | DES: 0x00000010 + | DH: 0x00000020 + | FORTEZZA: 0x00000040 + | RC5: 0x00000080 + | SHA1: 0x00000100 + | MD5: 0x00000200 + | MD2: 0x00000400 + | RANDOM: 0x08000000 + | FRIENDLY: 0x10000000 + | OWN_PW_DEFAULTS: 0x20000000 + | DISABLE: 0x40000000 + | CipherEnableFlags specifies ciphers that this module provides that NSS + | does not provide (so that the module enables those ciphers for NSS). This + | is equivalent to the -cipher argument with the -add command. This key is a + | bitstring specified in hexadecimal (0x) format. It is constructed as a + | bitwise OR. If the CipherEnableFlags entry is omitted, the value defaults + | to 0x0. + | EquivalentPlatform specifies that the attributes of the named platform + | should also be used for the current platform. This makes it easier when + | more than one platform uses the same settings. + | Per-File Keys + | Some keys have meaning only within the value list of an entry in a Files + | list. + | Each file requires a path key the identifies where the file is. Either + | RelativePath or AbsolutePath must be specified. If both are specified, the + | relative path is tried first, and the absolute path is used only if no + | relative root directory is provided by the installer program. + | RelativePath specifies the destination directory of the file, relative to + | some directory decided at install time. Two variables can be used in the + | relative path: %root% and %temp%. %root% is replaced at run time with the + | directory relative to which files should be installed; for example, it may + | be the server's root directory. The %temp% directory is created at the + | beginning of the installation and destroyed at the end. The purpose of + | %temp% is to hold executable files (such as setup programs) or files that + | are used by these programs. Files destined for the temporary directory are + | guaranteed to be in place before any executable file is run; they are not + | deleted until all executable files have finished. + | AbsolutePath specifies the destination directory of the file as an + | absolute path. + | Executable specifies that the file is to be executed during the course of + | the installation. Typically, this string is used for a setup program + | provided by a module vendor, such as a self-extracting setup executable. + | More than one file can be specified as executable, in which case the files + | are run in the order in which they are specified in the script file. + | FilePermissions sets permissions on any referenced files in a string of + | octal digits, according to the standard Unix format. This string is a + | bitwise OR. + | user read: 0400 + | user write: 0200 + | user execute: 0100 + | group read: 0040 + | group write: 0020 + | group execute: 0010 + | other read: 0004 + | other write: 0002 + | other execute: 0001 + | Some platforms may not understand these permissions. They are applied only + | insofar as they make sense for the current platform. If this attribute is + | omitted, a default of 777 is assumed. + | NSS Database Types + | NSS originally used BerkeleyDB databases to store security information. + | The last versions of these legacy databases are: + | o cert8.db for certificates + | o key3.db for keys + | o secmod.db for PKCS #11 module information + | 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. + | In 2009, NSS introduced a new set of databases that are SQLite databases + | rather than BerkleyDB. These new databases provide more accessibility and + | performance: + | o cert9.db for certificates + | o key4.db for keys + | o pkcs11.txt, which is listing of all of the PKCS #11 modules contained + | in a new subdirectory in the security databases directory + | Because the SQLite databases are designed to be shared, these are the + | shared database type. The shared database type is preferred; the legacy + | format is included for backward compatibility. + | By default, the tools (certutil, pk12util, modutil) assume that the given + | security databases follow the more common legacy type. Using the SQLite + | databases must be manually specified by using the sql: prefix with the + | given security directory. For example: + | modutil -create -dbdir sql:/home/my/sharednssdb + | To set the shared database type as the default type for the tools, set the + | NSS_DEFAULT_DB_TYPE environment variable to sql: + | export NSS_DEFAULT_DB_TYPE="sql" + | This line can be set added to the ~/.bashrc file to make the change + | permanent. + | 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: + | o https://wiki.mozilla.org/NSS_Shared_DB_Howto + | For an engineering draft on the changes in the shared NSS databases, see + | the NSS project wiki: + | o https://wiki.mozilla.org/NSS_Shared_DB + | See Also + | certutil (1) + | pk12util (1) + | signtool (1) + | The NSS wiki has information on the new database design and how to + | configure applications to use it. + | o https://wiki.mozilla.org/NSS_Shared_DB_Howto + | o https://wiki.mozilla.org/NSS_Shared_DB + | Additional Resources + | For information about NSS and other tools related to NSS (like JSS), check + | out the NSS project wiki at + | + [2]\ `http://www.mozilla.org/projects/security/pki/nss/ `__. + The NSS site relates + | directly to NSS code changes and releases. + | Mailing lists: https://lists.mozilla.org/listinfo/dev-tech-crypto + | IRC: Freenode at #dogtag-pki + | Authors + | The NSS tools were written and maintained by developers with Netscape, Red + | Hat, and Sun. + | Authors: Elio Maldonado , Deon Lackey + | . + | Copyright + | (c) 2010, Red Hat, Inc. Licensed under the GNU Public License version 2. + | References + | Visible links + | 1. JAR Installation File Format + | ``file:///tmp/xmlto.6gGxS0/modutil.pro...r-install-file`` + | 2. https://www.mozilla.org/projects/security/pki/nss/ \ No newline at end of file diff --git a/security/nss/doc/rst/legacy/tools/nss_tools_certutil-tasks/index.rst b/security/nss/doc/rst/legacy/tools/nss_tools_certutil-tasks/index.rst new file mode 100644 index 0000000000..f3ea257f2c --- /dev/null +++ b/security/nss/doc/rst/legacy/tools/nss_tools_certutil-tasks/index.rst @@ -0,0 +1,32 @@ +.. _mozilla_projects_nss_tools_nss_tools_certutil-tasks: + +NSS Tools certutil-tasks +======================== + +.. container:: + + .. rubric:: NSS Security Tools: certutil Tasks + :name: NSS_Security_Tools_certutil_Tasks + + | Newsgroup: `mozilla.dev.tech.crypto `__ + + .. rubric:: Task List + :name: Task_List + + #. Better error reporting. Most certutil errors provide no detail. Mistakes with command-line + options just print a usage message. + #. Improve certificate listings. Allow for sorting by name and trust. Sorting by trust will + return CA certs first. + #. Allow listing and lookup of keys by index and nickname. + #. Improve coherence of key and certificate nicknames. + #. Remove keys "stranded" without a certificate (except for the imminent (????) encryption key + for password files). + #. Support importing keys from a file. + #. Improve hardware token support. + #. (bugfix) Some certificate extensions cause certutil to crash. + #. (bugfix) Certificate entries require a serial number; one should be generated automatically if + not provided. + #. (bugfix) Null password is given to new ``key3.db``; should prompt user for an initial + password. + #. (bugfix) Listing provate keys does not work: requires password authentication. + #. (bugfix) Listing certificate extensions has typos and does not provide much information. \ No newline at end of file diff --git a/security/nss/doc/rst/legacy/tools/nss_tools_certutil/index.rst b/security/nss/doc/rst/legacy/tools/nss_tools_certutil/index.rst new file mode 100644 index 0000000000..06a8f0022d --- /dev/null +++ b/security/nss/doc/rst/legacy/tools/nss_tools_certutil/index.rst @@ -0,0 +1,666 @@ +.. _mozilla_projects_nss_tools_nss_tools_certutil: + +NSS Tools certutil +================== + +.. _using_the_certificate_database_tool: + +`Using the Certificate Database Tool <#using_the_certificate_database_tool>`__ +------------------------------------------------------------------------------ + +.. container:: + + The Certificate Database Tool is a command-line utility that can create and modify the Netscape + Communicator ``cert8.db`` and ``key3.db``\ database files. It can also list, generate, modify, or + delete certificates within the ``cert8.db``\ file and create or change the password, generate new + public and private key pairs, display the contents of the key database, or delete key pairs + within the ``key3.db`` file. + + Starting from NSS 3.35, the database format was upgraded to support SQLite as described in this + `document `__. It means that ``cert9.db`` and ``key4.db`` + files may be targeted instead. + + The key and certificate management process generally begins with creating keys in the key + database, then generating and managing certificates in the certificate database. + + This document discusses certificate and key database management. For information security module + database management, see :ref:`mozilla_projects_nss_reference_nss_tools_:_modutil` + +`Availability <#availability>`__ +-------------------------------- + +.. container:: + + See the release notes for the platforms this tool is available on. + +`Syntax <#syntax>`__ +-------------------- + +.. container:: + + To run the Certificate Database Tool, type the command + + .. code:: + + certutil option [arguments ] + + where *options* and *arguments* are combinations of the options and arguments listed in the + following section. Each command takes one option. Each option may take zero or more arguments. To + see a usage string, issue the command without options, or with the ``-H`` option. + +.. _options_and_arguments: + +`Options and Arguments <#options_and_arguments>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Options specify an action and are uppercase. Option arguments modify an action and are lowercase. + Certificate Database Tool command options and their arguments are defined as follows: + + +-------------------------------------------------+-------------------------------------------------+ + | **Options** | | + +-------------------------------------------------+-------------------------------------------------+ + | ``-N`` | Create new certificate and key databases. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-S`` | Create an individual certificate and add it to | + | | a certificate database. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-R`` | Create a certificate-request file that can be | + | | submitted to a Certificate Authority (CA) for | + | | processing into a finished certificate. Output | + | | defaults to standard out unless you use | + | | ``-o``\ *output-file* argument. Use the ``-a`` | + | | argument to specify ASCII output. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-C`` | Create a new binary certificate file from a | + | | binary certificate-request file. Use the ``-i`` | + | | argument to specify the certificate-request | + | | file. If this argument is not used Certificate | + | | Database Tool prompts for a filename. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-G`` | Generate a new public and private key pair | + | | within a key database. The key database should | + | | already exist; if one is not present, this | + | | option will initialize one by default. Some | + | | smart cards (for example, the Litronic card) | + | | can store only one key pair. If you create a | + | | new key pair for such a card, the previous pair | + | | is overwritten. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-F`` | Delete a private key from a key database. | + | | Specify the key to delete with the ``-n`` | + | | argument. Specify the database from which to | + | | delete the key with the ``-d`` argument. | + | | | + | | Use the ``-k`` argument to specify explicitly | + | | whether to delete a DSA or an RSA key. If you | + | | don't use the ``-k`` argument, the option looks | + | | for an RSA key matching the specified nickname. | + | | | + | | When you delete keys, be sure to also remove | + | | any certificates associated with those keys | + | | from the certificate database, by using ``-D``. | + | | | + | | Some smart cards (for example, the Litronic | + | | card) do not let you remove a public key you | + | | have generated. In such a case, only the | + | | private key is deleted from the key pair. You | + | | can display the public key with the command | + | | ``certutil -K -h``\ *tokenname* . | + +-------------------------------------------------+-------------------------------------------------+ + | ``-K`` | List the keyID of keys in the key database. A | + | | keyID is the modulus of the RSA key or the | + | | ``publicValue`` of the DSA key. IDs are | + | | displayed in hexadecimal ("0x" is not shown). | + +-------------------------------------------------+-------------------------------------------------+ + | ``-A`` | Add an existing certificate to a certificate | + | | database. The certificate database should | + | | already exist; if one is not present, this | + | | option will initialize one by default. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-D`` | Delete a certificate from the certificate | + | | database. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-L`` | List all the certificates, or display | + | | information about a named certificate, in a | + | | certificate database. | + | | | + | | Use the ``-h``\ *tokenname* argument to specify | + | | the certificate database on a particular | + | | hardware or software token. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-V`` | Check the validity of a certificate and its | + | | attributes. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-M`` | Modify a certificate's trust attributes using | + | | the values of the ``-t`` argument. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-H`` | Display a list of the options and arguments | + | | used by the Certificate Database Tool. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-W`` | Change the password to a key database. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-U`` | List all available modules or print a single | + | | named module. | + +-------------------------------------------------+-------------------------------------------------+ + | **Arguments** | | + +-------------------------------------------------+-------------------------------------------------+ + | ``-a`` | Use ASCII format or allow the use of ASCII | + | | format for input or output. This formatting | + | | follows `RFC | + | | 1113 `__. | + | | For certificate requests, ASCII output defaults | + | | to standard output unless redirected. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-b``\ *validity-time* | Specify a time at which a certificate is | + | | required to be valid. Use when checking | + | | certificate validity with the ``-V`` option. | + | | The format of the\ *validity-time* argument is | + | | "YYMMDDHHMMSS[+HHMM|-HHMM|Z]". Specifying | + | | seconds (SS) is optional. When specifying an | + | | explicit time, use "YYMMDDHHMMSSZ". When | + | | specifying an offset time, use | + | | "YYMMDDHHMMSS+HHMM" or "YYMMDDHHMMSS-HHMM". If | + | | this option is not used, the validity check | + | | defaults to the current system time. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-c``\ *issuer* | Identify the certificate of the CA from which a | + | | new certificate will derive its authenticity. | + | | Use the exact nickname or alias of the CA | + | | certificate, or use the CA's email address. | + | | Bracket the\ *issuer* string with quotation | + | | marks if it contains spaces. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-d``\ *directory* | Specify the database directory containing the | + | | certificate and key database files. On Unix the | + | | Certificate Database Tool defaults to | + | | ``$HOME/.netscape`` (that is, ``~/.netscape``). | + | | On Windows NT the default is the current | + | | directory. | + | | | + | | The ``cert8.db`` and ``key3.db`` database files | + | | must reside in the same directory. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-P``\ *dbprefix* | Specify the prefix used on the ``cert8.db`` and | + | | ``key3.db`` files (for example, ``my_cert8.db`` | + | | and ``my_key3.db``). This option is provided as | + | | a special case. Changing the names of the | + | | certificate and key databases is not | + | | recommended. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-e`` | Check a certificate's signature during the | + | | process of validating a certificate. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-f``\ *password-file* | Specify a file that will automatically supply | + | | the password to include in a certificate or to | + | | access a certificate database. This is a | + | | plain-text file containing one password. Be | + | | sure to prevent unauthorized access to this | + | | file. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-g``\ *keysize* | Set a key size to use when generating new | + | | public and private key pairs. The minimum is | + | | 512 bits and the maximum is 8192 bits. The | + | | default is 1024 bits. Any size that is a | + | | multiple of 8 between the minimum and maximum | + | | is allowed. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-h``\ *tokenname* | Specify the name of a token to use or act on. | + | | Unless specified otherwise the default token is | + | | an internal slot (specifically, internal slot | + | | 2). This slot can also be explicitly named with | + | | the string ``"internal"``. An internal slots is | + | | a virtual slot maintained in software, rather | + | | than a hardware device. Internal slot 2 is used | + | | by key and certificate services. Internal slot | + | | 1 is used by cryptographic services. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-i``\ *cert|cert-request-file* | Specify a specific certificate, or a | + | | certificate-request file. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-k rsa|dsa|all`` | Specify the type of a key: RSA, DSA or both. | + | | The default value is ``rsa``. By specifying the | + | | type of key you can avoid mistakes caused by | + | | duplicate nicknames. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-l`` | Display detailed information when validating a | + | | certificate with the ``-V`` option. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-m``\ *serial-number* | Assign a unique serial number to a certificate | + | | being created. This operation should be | + | | performed by a CA. The default serial number is | + | | 0 (zero). Serial numbers are limited to | + | | integers. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-n``\ *nickname* | Specify the nickname of a certificate or key to | + | | list, create, add to a database, modify, or | + | | validate. Bracket the *nickname* string with | + | | quotation marks if it contains spaces. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-o``\ *output-file* | Specify the output file name for new | + | | certificates or binary certificate requests. | + | | Bracket the\ *output-file* string with | + | | quotation marks if it contains spaces. If this | + | | argument is not used the output destination | + | | defaults to standard output. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-p``\ *phone* | Specify a contact telephone number to include | + | | in new certificates or certificate requests. | + | | Bracket this string with quotation marks if it | + | | contains spaces. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-q``\ *pqgfile* | Read an alternate PQG value from the specified | + | | file when generating DSA key pairs. If this | + | | argument is not used, the Key Database Tool | + | | generates its own PQG value. PQG files are | + | | created with a separate DSA utility. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-r`` | Display a certificate's binary DER encoding | + | | when listing information about that certificate | + | | with the ``-L`` option. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-s``\ *subject* | Identify a particular certificate owner for new | + | | certificates or certificate requests. Bracket | + | | this string with quotation marks if it contains | + | | spaces. The subject identification format | + | | follows `RFC | + | | 1485 `__. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-t``\ *trustargs* | Specify the trust attributes to modify in an | + | | existing certificate or to apply to a | + | | certificate when creating it or adding it to a | + | | database. | + | | | + | | There are three available trust categories for | + | | each certificate, expressed in this order: | + | | "*SSL* ,\ *email* ,\ *object signing* ". In | + | | each category position use zero or more of the | + | | following attribute codes: | + | | | + | | | ``p`` prohibited (explicitly distrusted) | + | | | ``P`` Trusted peer | + | | | ``c`` Valid CA | + | | | ``T`` Trusted CA to issue client | + | | certificates (implies ``c``) | + | | | ``C`` Trusted CA to issue server | + | | certificates (SSL only) | + | | | (implies ``c``) | + | | | ``u`` Certificate can be used for | + | | authentication or signing | + | | | ``w`` Send warning (use with other | + | | attributes to include a warning when the | + | | certificate is used in that context) | + | | | + | | The attribute codes for the categories are | + | | separated by commas, and the entire set of | + | | attributes enclosed by quotation marks. For | + | | example: | + | | | + | | ``-t "TCu,Cu,Tuw"`` | + | | | + | | Use the ``-L`` option to see a list of the | + | | current certificates and trust attributes in a | + | | certificate database. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-u``\ *certusage* | Specify a usage context to apply when | + | | validating a certificate with the ``-V`` | + | | option. The contexts are the following: | + | | | + | | | ``C`` (as an SSL client) | + | | | ``V`` (as an SSL server) | + | | | ``S`` (as an email signer) | + | | | ``R`` (as an email recipient) | + +-------------------------------------------------+-------------------------------------------------+ + | ``-v``\ *valid-months* | Set the number of months a new certificate will | + | | be valid. The validity period begins at the | + | | current system time unless an offset is added | + | | or subtracted with the ``-w`` option. If this | + | | argument is not used, the default validity | + | | period is three months. When this argument is | + | | used, the default three-month period is | + | | automatically added to any value given in | + | | the\ *valid-month* argument. For example, using | + | | this option to set a value of ``3`` would cause | + | | 3 to be added to the three-month default, | + | | creating a validity period of six months. You | + | | can use negative values to reduce the default | + | | period. For example, setting a value of ``-2`` | + | | would subtract 2 from the default and create a | + | | validity period of one month. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-w``\ *offset-months* | Set an offset from the current system time, in | + | | months, for the beginning of a certificate's | + | | validity period. Use when creating the | + | | certificate or adding it to a database. Express | + | | the offset in integers, using a minus sign | + | | (``-``) to indicate a negative offset. If this | + | | argument is not used, the validity period | + | | begins at the current system time. The length | + | | of the validity period is set with the ``-v`` | + | | argument. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-x`` | Use the Certificate Database Tool to generate | + | | the signature for a certificate being created | + | | or added to a database, rather than obtaining a | + | | signature from a separate CA. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-y``\ *exp* | Set an alternate exponent value to use in | + | | generating a new RSA public key for the | + | | database, instead of the default value of | + | | 65537. The available alternate values are 3 and | + | | 17. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-z``\ *noise-file* | Read a seed value from the specified binary | + | | file to use in generating a new RSA private and | + | | public key pair. This argument makes it | + | | possible to use hardware-generated seed values | + | | and unnecessary to manually create a value from | + | | the keyboard. The minimum file size is 20 | + | | bytes. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-1`` | Add a key usage extension to a certificate that | + | | is being created or added to a database. This | + | | extension allows a certificate's key to be | + | | dedicated to supporting specific operations | + | | such as SSL server or object signing. The | + | | Certificate Database Tool will prompt you to | + | | select a particular usage for the certificate's | + | | key. These usages are described under `Standard | + | | X.509 v3 Certificate | + | | Extensions `__ | + | | in Appendix A.3 of the\ *Red Hat Certificate | + | | System Administration Guide.* | + +-------------------------------------------------+-------------------------------------------------+ + | ``-2`` | Add a basic constraint extension to a | + | | certificate that is being created or added to a | + | | database. This extension supports the | + | | certificate chain verification process. The | + | | Certificate Database Tool will prompt you to | + | | select the certificate constraint extension. | + | | Constraint extensions are described in | + | | `Standard X.509 v3 Certificate | + | | Extensions `__ | + | | in Appendix A.3 of the\ *Red Hat Certificate | + | | System Administration Guide.* | + +-------------------------------------------------+-------------------------------------------------+ + | ``-3`` | Add an authority keyID extension to a | + | | certificate that is being created or added to a | + | | database. This extension supports the | + | | identification of a particular certificate, | + | | from among multiple certificates associated | + | | with one subject name, as the correct issuer of | + | | a certificate. The Certificate Database Tool | + | | will prompt you to select the authority keyID | + | | extension. Authority key ID extensions are | + | | described under `Standard X.509 v3 Certificate | + | | Extensions `__ | + | | in Appendix B.3 of the\ *Red Hat Certificate | + | | System Administration Guide.* | + +-------------------------------------------------+-------------------------------------------------+ + | ``-4`` | Add a CRL distribution point extension to a | + | | certificate that is being created or added to a | + | | database. This extension identifies the URL of | + | | a certificate's associated certificate | + | | revocation list (CRL). The Certificate Database | + | | Tool prompts you to enter the URL. CRL | + | | distribution point extensions are described in | + | | `Standard X.509 v3 Certificate | + | | Extensions `__ | + | | in Appendix A.3 of the\ *Red Hat Certificate | + | | System Administration Guide.* | + +-------------------------------------------------+-------------------------------------------------+ + | ``-5`` | Add a Netscape certificate type extension to a | + | | certificate that is being created or added to | + | | the database. Netscape certificate type | + | | extensions are described in `Standard X.509 v3 | + | | Certificate | + | | Extensions `__ | + | | in Appendix A.3 of the\ *Red Hat Certificate | + | | System Administration Guide.* | + +-------------------------------------------------+-------------------------------------------------+ + | ``-6`` | Add an extended key usage extension to a | + | | certificate that is being created or added to | + | | the database. Extended key usage extensions are | + | | described in `Standard X.509 v3 Certificate | + | | Extensions `__ | + | | in Appendix A.3 of the\ *Red Hat Certificate | + | | System Administration Guide.* | + +-------------------------------------------------+-------------------------------------------------+ + | ``-7``\ *emailAddrs* | Add a comma-separated list of email addresses | + | | to the subject alternative name extension of a | + | | certificate or certificate request that is | + | | being created or added to the database. Subject | + | | alternative name extensions are described in | + | | Section 4.2.1.7 of `RFC | + | | 3 | + | | 2800 `__. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-8``\ *dns-names* | Add a comma-separated list of DNS names to the | + | | subject alternative name extension of a | + | | certificate or certificate request that is | + | | being created or added to the database. Subject | + | | alternative name extensions are described in | + | | Section 4.2.1.7 of `RFC | + | | 32800 `__ | + +-------------------------------------------------+-------------------------------------------------+ + +`Usage <#usage>`__ +------------------ + +.. container:: + + The Certificate Database Tool's capabilities are grouped as follows, using these combinations of + options and arguments. Options and arguments in square brackets are optional, those without + square brackets are required. + + .. code:: + + -N [-d certdir ] + + .. code:: + + -S -k rsa|dsa -n certname -s subject + [-c issuer |-x] -t trustargs [-h tokenname ] + [-m serial-number ] [-v valid-months ] [-w offset-months ] + [-d certdir ] [-p phone ] [-f password-file ] [-1] [-2] [-3] [-4] + + .. code:: + + -R -k rsa|dsa -s subject [-h tokenname ] + [-d certdir ] [-p phone ] [-o output-file ] [-f password-file ] + + .. code:: + + -C -c issuer [-f password-file ] + [-h tokenname ] -i cert-request-file -o output-file [-m serial-number ] + [-v valid-months ] [-w offset-months ] [-d certdir ] [-1] [-2] [-3] + [-4] + + .. code:: + + -A -n certname -t trustargs [-h tokenname ] [-d certdir ] [-a] + [-i cert-request-file ] + + .. code:: + + -L [-n certname ] [-d certdir ] [-r] [-a] + + .. code:: + + -V -n certname -b validity-time -u certusage [-e] [-l] [-d certdir ] + + .. code:: + + -M -n certname -t trustargs [-d certdir ] + + .. code:: + + -H + + - Creating a new ``cert8.db`` file: + - Creating a new certificate and adding it to the database with one command: + - Making a separate certificate request: + - Creating a new binary certificate from a binary certificate request: + - Adding a certificate to an existing database: + - Listing all certificates or a named certificate: + - Validating a certificate: + - Modifying a certificate's trust attribute: + - Displaying a list of the options and arguments used by the Certificate Database Tool: + +`Examples <#examples>`__ +------------------------ + +.. container:: + +.. _creating_a_new_certificate_database: + +`Creating a New Certificate Database <#creating_a_new_certificate_database>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + This example creates a new certificate database (``cert8.db`` file) in the specified directory: + + .. code:: + + certutil -N -d certdir + + You must generate the associated ``key3.db`` and ``secmod.db`` files by using the Key Database + Tool or other tools. + +.. _listing_certificates_in_a_database: + +`Listing Certificates in a Database <#listing_certificates_in_a_database>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + This example lists all the certificates in the ``cert8.db`` file in the specified directory: + + .. code:: + + certutil -L -d certdir + + The Certificate Database Tool displays output similar to the following: + + | ``Certificate Name Trust Attributes`` + | ``Uptime Group Plc. Class 1 CA C,C, VeriSign Class 1 Primary CA ,C, VeriSign Class 2 Primary CA C,C,C AT&T Certificate Services C,C, GTE CyberTrust Secure Server CA C,, Verisign/RSA Commercial CA C,C, AT&T Directory Services C,C, BelSign Secure Server CA C,, Verisign/RSA Secure Server CA C,C, GTE CyberTrust Root CA C,C, Uptime Group Plc. Class 4 CA ,C, VeriSign Class 3 Primary CA C,C,C Canada Post Corporation CA C,C, Integrion CA C,C,C IBM World Registry CA C,C,C GTIS/PWGSC, Canada Gov. Web CA C,C, GTIS/PWGSC, Canada Gov. Secure CA C,C,C MCI Mall CA C,C, VeriSign Class 4 Primary CA C,C,C KEYWITNESS, Canada CA C,C, BelSign Object Publishing CA ,,C BBN Certificate Services CA Root 1 C,C, p prohibited (explicitly distrusted) P Trusted peer c Valid CA T Trusted CA to issue client certs (implies c) C Trusted CA to issue server certs(for ssl only) (implies c) u User cert w Send warning`` + +.. _creating_a_certificate_request: + +`Creating a Certificate Request <#creating_a_certificate_request>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + This example generates a binary certificate request file named ``e95c.req`` in the specified + directory: + + .. code:: + + certutil -R -s "CN=John Smith, O=Netscape, L=Mountain View, ST=California, C=US" -p "650-555-8888" -o mycert.req -d certdir + + Before it creates the request file, the Certificate Database Tool prompts you for a password: + + .. code:: + + Enter Password or Pin for "Communicator Certificate DB": + +.. _creating_a_certificate: + +`Creating a Certificate <#creating_a_certificate>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + A valid certificate must be issued by a trusted CA. If a CA key pair is not available, you can + create a self-signed certificate (for purposes of illustration) with the ``-x`` argument. This + example creates a new binary, self-signed CA certificate named ``myissuer``, in the specified + directory. + + .. code:: + + certutil -S -s "CN=My Issuer" -n myissuer -x -t "C,C,C" -1 -2 -5 -m 1234 -f password-file -d certdir + + The following example creates a new binary certificate named ``mycert.crt``, from a binary + certificate request named ``mycert.req``, in the specified directory. It is issued by the + self-signed certificate created above, ``myissuer``. + + .. code:: + + certutil -C -m 2345 -i mycert.req -o mycert.crt -c myissuer -d certdir + +.. _adding_a_certificate_to_the_database: + +`Adding a Certificate to the Database <#adding_a_certificate_to_the_database>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + This example adds a certificate to the certificate database: + + .. code:: + + certutil -A -n jsmith@netscape.com -t "p,p,p" -i mycert.crt -d certdir + + You can see this certificate in the database with this command: + + .. code:: + + certutil -L -n jsmith@netscape.com -d certdir + + The Certificate Database Tool displays output similar to the following: + + | ``Certificate: Data: Version: 3 (0x2) Serial Number: 0 (0x0) Signature Algorithm: PKCS #1 MD5 With RSA Encryption Issuer: CN=John Smith, O=Netscape, L=Mountain View, ST=California, C=US Validity: Not Before: Thu Mar 12 00:10:40 1998 Not After: Sat Sep 12 00:10:40 1998 Subject: CN=John Smith, O=Netscape, L=Mountain View, ST=California, C=US`` + | ``Subject Public Key Info: Public Key Algorithm: PKCS #1 RSA Encryption RSA Public Key: Modulus: 00:da:53:23:58:00:91:6a:d1:a2:39:26:2f:06:3a: 38:eb:d4:c1:54:a3:62:00:b9:f0:7f:d6:00:76:aa: 18:da:6b:79:71:5b:d9:8a:82:24:07:ed:49:5b:33: bf:c5:79:7c:f6:22:a7:18:66:9f:ab:2d:33:03:ec: 63:eb:9d:0d:02:1b:da:32:ae:6c:d4:40:95:9f:b3: 44:8b:8e:8e:a3:ae:ad:08:38:4f:2e:53:e9:e1:3f: 8e:43:7f:51:61:b9:0f:f3:a6:25:1e:0b:93:74:8f: c6:13:a3:cd:51:40:84:0e:79:ea:b7:6b:d1:cc:6b: 78:d0:5d:da:be:2b:57:c2:6f Exponent: 65537 (0x10001) Signature Algorithm: PKCS #1 MD5 With RSA Encryption Signature: 44:15:e5:ae:c4:30:2c:cd:60:89:f1:1d:22:ed:5e:5b:10:c8: 7e:5f:56:8c:b4:00:12:ed:5f:a4:6a:12:c3:0d:01:03:09:f2: 2f:e7:fd:95:25:47:80:ea:c1:25:5a:33:98:16:52:78:24:80: c9:53:11:40:99:f5:bd:b8:e9:35:0e:5d:3e:38:6a:5c:10:d1: c6:f9:54:af:28:56:62:f4:2f:b3:9b:50:e1:c3:a2:ba:27:ee: 07:9f:89:2e:78:5c:6d:46:b6:5e:99:de:e6:9d:eb:d9:ff:b2: 5f:c6:f6:c6:52:4a:d4:67:be:8d:fc:dd:52:51:8e:a2:d7:15: 71:3e`` + | ``Certificate Trust Flags: SSL Flags: Valid CA Trusted CA Email Flags: Valid CA Trusted CA Object Signing Flags: Valid CA Trusted CA`` + +.. _validating_a_certificate: + +`Validating a Certificate <#validating_a_certificate>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + This example validates a certificate: + + .. code:: + + certutil -V -n jsmith@netscape.com -b 9803201212Z -u SR -e -l -d certdir + + The Certificate Database Tool shows results similar to + + .. code:: + + Certificate:'jsmith@netscape.com' is valid. + + or + + .. code:: + + UID=jsmith, E=jsmith@netscape.com, CN=John Smith, O=Netscape Communications Corp., C=US : Expired certificate + + or + + .. code:: + + UID=jsmith, E=jsmith@netscape.com, CN=John Smith, O=Netscape Communications Corp., C=US : Certificate not approved for this operation \ No newline at end of file diff --git a/security/nss/doc/rst/legacy/tools/nss_tools_cmsutil/index.rst b/security/nss/doc/rst/legacy/tools/nss_tools_cmsutil/index.rst new file mode 100644 index 0000000000..9697bce4f5 --- /dev/null +++ b/security/nss/doc/rst/legacy/tools/nss_tools_cmsutil/index.rst @@ -0,0 +1,119 @@ +.. _mozilla_projects_nss_tools_nss_tools_cmsutil: + +NSS Tools cmsutil +================= + +.. _using_cmsutil: + +`Using cmsutil <#using_cmsutil>`__ +---------------------------------- + +.. container:: + + Newsgroup: `mozilla.dev.tech.crypto `__ + The cmsutil command-line utility uses the `S/MIME Toolkit <../smime/>`__ to perform basic + operations, such as encryption and decryption, on `Cryptographic Message + Syntax (CMS) `__ messages. + +.. _syntax_2: + +` <#syntax_2>`__ Syntax +----------------------- + +.. container:: + + To run cmsutil, type the command ``cmsutil``\ *option*\ ``[``\ *arguments*\ ``]`` where *option* + and *arguments* are combinations of the options and arguments listed in the following section. + Each command takes one option. Each option may take zero or more arguments. To see a usage + string, issue the command without options. + +.. _options_and_arguments: + +`Options and Arguments <#options_and_arguments>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Options specify an action. Option arguments modify an action. The options and arguments for the + ``cmsutil`` command are defined as follows: + + +------------------------------------------------+------------------------------------------------+ + | **Options** | | + +------------------------------------------------+------------------------------------------------+ + | ``-D`` | Decode a message. | + +------------------------------------------------+------------------------------------------------+ + | ``-C`` | Encrypt a message. | + +------------------------------------------------+------------------------------------------------+ + | ``-E`` | Envelope a message. | + +------------------------------------------------+------------------------------------------------+ + | ``-O`` | Create a certificates-only message. | + +------------------------------------------------+------------------------------------------------+ + | ``-S`` | Sign a message. | + +------------------------------------------------+------------------------------------------------+ + | **Arguments** | | + +------------------------------------------------+------------------------------------------------+ + | ``-c`` *content* | Use this detached content (decode only). | + +------------------------------------------------+------------------------------------------------+ + | ``-d`` *dbdir* | Specify the key/certificate database directory | + | | (default is ".") | + +------------------------------------------------+------------------------------------------------+ + | ``-e`` *envfile* | Specify a file containing an enveloped message | + | | for a set of recipients to which you would | + | | like to send an encrypted message. If this is | + | | the first encrypted message for that set of | + | | recipients, a new enveloped message will be | + | | created that you can then use for future | + | | messages (encrypt only). | + +------------------------------------------------+------------------------------------------------+ + | ``-G`` | Include a signing time attribute (sign only). | + +------------------------------------------------+------------------------------------------------+ + | ``-h`` *num* | Generate email headers with info about CMS | + | | message (decode only). | + +------------------------------------------------+------------------------------------------------+ + | ``-i`` *infile* | Use *infile* as a source of data (default is | + | | stdin). | + +------------------------------------------------+------------------------------------------------+ + | ``-N`` *nickname* | Specify nickname of certificate to sign with | + | | (sign only). | + +------------------------------------------------+------------------------------------------------+ + | ``-n`` | Suppress output of contents (decode only). | + +------------------------------------------------+------------------------------------------------+ + | ``-o`` *outfile* | Use outfile as a destination of data (default | + | | is stdout). | + +------------------------------------------------+------------------------------------------------+ + | ``-P`` | Include an S/MIME capabilities attribute. | + +------------------------------------------------+------------------------------------------------+ + | -p *password* | Use password as key database password. | + +------------------------------------------------+------------------------------------------------+ + | - | Specify list of recipients (email addresses) | + | r \ *recipient1*,\ *recipient2, . . .* | for an encrypted or enveloped message. For | + | | certificates-only message, list of | + | | certificates to send. | + +------------------------------------------------+------------------------------------------------+ + | -T | Suppress content in CMS message (sign only). | + +------------------------------------------------+------------------------------------------------+ + | -u *certusage* | Set type of cert usage (default is | + | | certUsageEmailSigner). | + +------------------------------------------------+------------------------------------------------+ + | <-Y *ekprefnick* | Specify an encryption key preference by | + | | nickname. | + +------------------------------------------------+------------------------------------------------+ + +`Usage <#usage>`__ +------------------ + +.. container:: + + cmsutil -C [-i *infile*] [-o *outfile*] [-d *dbdir*] [-p *password*] -r + "*recipient1*,\ *recipient2*, . . ." -e *envfile* + cmsutil -D [-i *infile*] [-o *outfile*] [-d *dbdir*] [-p *password*] [-c *content*] [-n] [-h + *num*] + + cmsutil -E [-i *infile*] [-o *outfile*] [-d *dbdir*] [-p *password*] -r + "*recipient1*,\ *recipient2*, . . ." + + cmsutil -O [-i *infile*] [-o *outfile*] [-d *dbdir*] [-p *password*] -r + "*cert1*,\ *cert2*, . . ." + + cmsutil -S [-i *infile*] [-o *outfile*] [-d *dbdir*] [-p *password*] -N *nickname*\ [-TGP] [-Y + *ekprefnick*] \ No newline at end of file diff --git a/security/nss/doc/rst/legacy/tools/nss_tools_crlutil/index.rst b/security/nss/doc/rst/legacy/tools/nss_tools_crlutil/index.rst new file mode 100644 index 0000000000..d190e576e9 --- /dev/null +++ b/security/nss/doc/rst/legacy/tools/nss_tools_crlutil/index.rst @@ -0,0 +1,441 @@ +.. _mozilla_projects_nss_tools_nss_tools_crlutil: + +NSS Tools crlutil +================= + +.. _using_the_certificate_revocation_list_management_tool: + +`Using the Certificate Revocation List Management Tool <#using_the_certificate_revocation_list_management_tool>`__ +------------------------------------------------------------------------------------------------------------------ + +.. container:: + + Newsgroup: `mozilla.dev.tech.crypto `__ + + The Certificate Revocation List (CRL) Management Tool is a command-line utility that can list, + generate, modify, or delete CRLs within the NSS security database file(s) and list, create, + modify or delete certificates entries in a particular CRL. + + The key and certificate management process generally begins with creating keys in the key + database, then generating and managing certificates in the certificate database(see ``certutil`` + tool) and continues with certificates expiration or revocation. + + This document discusses certificate revocation list management. For information on security + module database management, see `Using the Security Module Database Tool `__. + For information on certificate and key database management, see `Using the Certificate Database + Tool `__. + +.. _availability_2: + +` <#availability_2>`__ Availability +----------------------------------- + +.. container:: + + See the :ref:`mozilla_projects_nss_releases` for the platforms this tool is available on. + +.. _syntax_2: + +` <#syntax_2>`__ Syntax +----------------------- + +.. container:: + + To run the Certificate Revocation List Management Tool, type the command + + ``crlutil`` *option*\ ``[``\ *arguments*\ ``]`` + + where *options* and *arguments* are combinations of the options and arguments listed in the + following section. Each command takes one option. Each option may take zero or more arguments. To + see a usage string, issue the command without options, or with the ``-H`` option. + +.. _options_and_arguments: + +`Options and Arguments <#options_and_arguments>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Options specify an action and are uppercase. Option arguments modify an action and are lowercase. + Certificate Revocation List Management Tool command options and their arguments are defined as + follows: + + +-------------------------------------------------+-------------------------------------------------+ + | **Options** | | + +-------------------------------------------------+-------------------------------------------------+ + | ``-G`` | Create new Certificate Revocation List(CRL). | + +-------------------------------------------------+-------------------------------------------------+ + | ``-D`` | Delete Certificate Revocation List from cert | + | | database. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-I`` | Import a CRL to the cert database | + +-------------------------------------------------+-------------------------------------------------+ + | ``-E`` | Erase all CRLs of specified type from the cert | + | | database | + +-------------------------------------------------+-------------------------------------------------+ + | ``-L`` | List existing CRL located in cert database | + | | file. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-M`` | Modify existing CRL which can be located in | + | | cert db or in arbitrary file. If located in | + | | file it should be encoded in ASN.1 encode | + | | format. | + +-------------------------------------------------+-------------------------------------------------+ + | **Arguments** | | + +-------------------------------------------------+-------------------------------------------------+ + | ``-B`` | Bypass CA signature checks. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-P``\ *dbprefix* | Specify the prefix used on the | + | | ``NSS security database`` files (for example, | + | | ``my_cert8.db`` and ``my_key3.db``). This | + | | option is provided as a special case. Changing | + | | the names of the certificate and key databases | + | | is not recommended. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-a`` | Use ASCII format or allow the use of ASCII | + | | format for input and output. This formatting | + | | follows `RFC | + | | #1113 `__. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-c``\ *crl-gen-file* | Specify script file that will be used to | + | | control crl generation/modification. See | + | | crl-cript-file `format <#10232455>`__ below. If | + | | options *-M|-G* is used and *-c | + | | crl-script-file* is not specified, crlutil will | + | | read script data from standard input. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-d``\ *directory* | Specify the database directory containing the | + | | certificate and key database files. On Unix the | + | | Certificate Database Tool defaults to | + | | ``$HOME/.netscape`` (that is, ``~/.netscape``). | + | | On Windows NT the default is the current | + | | directory. | + | | | + | | The ``NSS database`` files must reside in the | + | | same directory. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-i``\ *crl-import-file* | Specify the file which contains the CRL to | + | | import | + +-------------------------------------------------+-------------------------------------------------+ + | ``-f``\ *password-file* | Specify a file that will automatically supply | + | | the password to include in a certificate or to | + | | access a certificate database. This is a | + | | plain-text file containing one password. Be | + | | sure to prevent unauthorized access to this | + | | file. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-l``\ *algorithm-name* | Specify a specific signature algorithm. List of | + | | possible algorithms: MD2 \| MD4 \| MD5 \| SHA1 | + | | \| SHA256 \| SHA384 \| SHA512 | + +-------------------------------------------------+-------------------------------------------------+ + | ``-n``\ *nickname* | Specify the nickname of a certificate or key to | + | | list, create, add to a database, modify, or | + | | validate. Bracket the *nickname* string with | + | | quotation marks if it contains spaces. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-o``\ *output-file* | Specify the output file name for new CRL. | + | | Bracket the *output-file* string with quotation | + | | marks if it contains spaces. If this argument | + | | is not used the output destination defaults to | + | | standard output. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-t``\ *crl-type* | Specify type of CRL. possible types are: 0 - | + | | SEC_KRL_TYPE, 1 - SEC_CRL_TYPE. **This option | + | | is obsolete** | + +-------------------------------------------------+-------------------------------------------------+ + | ``-u``\ *url* | Specify the url. | + +-------------------------------------------------+-------------------------------------------------+ + + +---+ + | | + +---+ + +.. _crl_generation_script_syntax: + +`CRL Generation script syntax: <#crl_generation_script_syntax>`__ +----------------------------------------------------------------- + +.. container:: + + CRL generation script file has the following syntax: + + - Line with comments should have \ *#*\ as a first symbol of a line + + - Set *"this update"* or *"next update"* CRL fields: + + ``update=YYYYMMDDhhmmssZ`` + ``nextupdate=YYYYMMDDhhmmssZ`` + + | Field "next update" is optional. Time should be in *GeneralizedTime* format + (YYYYMMDDhhmmssZ). + | For example: ``20050204153000Z`` + + - Add an extension to a CRL or a crl certificate entry: + + ``addext``\ *extension-name* *critical/non-critical*\ ``[``\ *arg1*\ ``[``\ *arg2* + ``...]]`` + + | Where: + + ``extension-name``: string value of a name of known extensions. + ``critical/non-critical``: is 1 when extension is critical and 0 otherwise. + ``arg1, arg2``: specific to extension type extension parameters + + ``addext`` uses the range that was set earlier by ``addcert`` and will install an extension to + every cert entries within the range. + + See `"Implemented extensions" <#3543811>`__ for more information regarding extensions and + theirs parameters. + + - Add certificate entries(s) to CRL: + + ``addcert``\ *range* *date* + + | Where: + + ``range``: two integer values separated by ``dash``: range of certificates that will be + added by this command. ``dash`` is used as a delimiter. Only one cert will be added if + there is no delimiter. + ``date``: revocation date of a cert. Date should be represented in GeneralizedTime format + (YYYYMMDDhhmmssZ). + + - Remove certificate entry(s) from CRL + + ``rmcert`` *range* + + | Where: + + ``range``: two integer values separated by ``dash``: range of certificates that will be + added by this command. ``dash`` is used as a delimiter. Only one cert will be added if + there is no delimiter. + + - Change range of certificate entry(s) in CRL + + ``range`` *new-range* + + | Where: + + ``new-range``: two integer values separated by ``dash``: range of certificates that will be + added by this command. ``dash`` is used as a delimiter. Only one cert will be added if + there is no delimiter. + +.. _implemented_extensions: + +`Implemented Extensions <#implemented_extensions>`__ +---------------------------------------------------- + +.. container:: + + The extensions defined for CRL provide methods for associating additional attributes with CRLs of + theirs entries. For more information see `RFC #3280 `__ + + - Add The Authority Key Identifier extension: + + The authority key identifier extension provides a means of identifying the public key + corresponding to the private key used to sign a CRL. + + ``authKeyId`` *critical* [*key-id* \| *dn* *cert-serial*] + + | Where: + + ``authKeyIdent``: identifies the name of an extension + ``critical``: value of 1 of 0. Should be set to 1 if this extension is critical or 0 + otherwise. + ``key-id``: key identifier represented in octet string. ``dn:``: is a CA distinguished name + ``cert-serial``: authority certificate serial number. + + - Add Issuer Alternative Name extension: + + The issuer alternative names extension allows additional identities to be associated with the + issuer of the CRL. Defined options include an rfc822 name (electronic mail address), a DNS + name, an IP address, and a URI. + + ``issuerAltNames`` *non-critical* *name-list* + + | Where: + + ``subjAltNames``: identifies the name of an extension + should be set to 0 since this is non-critical extension + ``name-list``: comma separated list of names + + - Add CRL Number extension: + + The CRL number is a non-critical CRL extension which conveys a monotonically increasing + sequence number for a given CRL scope and CRL issuer. This extension allows users to easily + determine when a particular CRL supersedes another CRL + + ``crlNumber`` *non-critical* *number* + + | Where: + + ``crlNumber``: identifies the name of an extension + ``critical``: should be set to 0 since this is non-critical extension + ``number``: value of ``long`` which identifies the sequential number of a CRL. + + - Add Revocation Reason Code extension: + + The reasonCode is a non-critical CRL entry extension that identifies the reason for the + certificate revocation. + + ``reasonCode`` *non-critical* *code* + + | Where: + + | ``reasonCode``: identifies the name of an extension + | ``non-critical``: should be set to 0 since this is non-critical extension + | ``code``: the following codes are available: + + unspecified (0), + keyCompromise (1), + cACompromise (2), + affiliationChanged (3), + superseded (4), + cessationOfOperation (5), + certificateHold (6), + removeFromCRL (8), + privilegeWithdrawn (9), + aACompromise (10) + + - Add Invalidity Date extension: + + The invalidity date is a non-critical CRL entry extension that provides the date on which it + is known or suspected that the private key was compromised or that the certificate otherwise + became invalid. + + invalidityDate *non-critical* *date* + + | Where: + + ``crlNumber``: identifies the name of an extension + ``non-critical``: should be set to 0 since this is non-critical extension ``date``: + invalidity date of a cert. Date should be represented in GeneralizedTime format + (YYYYMMDDhhmmssZ). + +.. _usage_2: + +` <#usage_2>`__ Usage +--------------------- + +.. container:: + + The Certificate Revocation List Management Tool's capabilities are grouped as follows, using + these combinations of options and arguments. Options and arguments in square brackets are + optional, those without square brackets are required. + + ``-G|-M -c crl-gen-file -n nickname [-i``\ *crl*\ ``] [-u``\ *url*\ ``] [-d``\ *keydir*\ ``] [-P``\ *dbprefix*\ ``] [-l``\ *alg*\ ``] [-a] [-B]`` + + .. + + ``-L [-n``\ *crl-name*\ ``] [-d``\ *krydir*\ ``]`` + + ``crlutil -D -n nickname [-d``\ *keydir*\ ``] [-P``\ *dbprefix*\ ``]`` + + .. + + ``crlutil -E [-d``\ *keydir*\ ``] [-P``\ *dbprefix*\ ``]`` + + ``crlutil -I -i crl [-t``\ *crlType*\ ``] [-u``\ *url*\ ``] [-d``\ *keydir*\ ``] [-P``\ *dbprefix*\ ``] [-B]`` + + - Creating or modifying a CRL: + - Listing all CRls or a named CRL: + - Deleting CRL from db: + - Erasing CRLs from db: + - Import CRL from file: + +.. _examples_2: + +` <#examples_2>`__ Examples +--------------------------- + +.. container:: + + | `Creating a New CRL `__ + | `Listing CRLs in a Database `__ + | `Deleting CRL from a Database `__ + | `Importing CRL into a Database `__ + | `Modifiying CRL in a Database `__ + +.. _creating_a_new_crl: + +`Creating a New CRL <#creating_a_new_crl>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + This example creates a new CRL and importing it in to a Database in the specified directory: + + ``crlutil -G -d``\ *certdir*\ ``-n``\ *cert-nickname*\ ``-c``\ *crl-script-file* + + or + + ``crlutil -G -d``\ *certdir*\ ``-n``\ *cert-nickname*\ ``<`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + This example lists all the CRLs in the ``NSS database`` in the specified directory: + + ``crlutil -L -d``\ *certdir* + + The CRL Management Tool displays output similar to the following: + + ``CRL Name CRL Type`` + + ``CN=NSS Test CA,O=BOGUS NSS,L=Mountain View,ST=California,C=US CRL CN=John Smith,O=Netscape,L=Mountain View,ST=California,C=US CRL`` + + | To view a particular CRL user should specify *-n nickname* parameter. + | ``crlutil -L -d``\ *certdir*\ ``-n`` *nickname* + + ``CRL Info: : Version: 2 (0x1) Signature Algorithm: PKCS #1 MD5 With RSA Encryption Issuer: "CN=NSS Test CA,O=BOGUS NSS,L=Mountain View,ST=California,C=US" This Update: Wed Feb 23 12:08:38 2005 Entry (1): Serial Number: 40 (0x28) Revocation Date: Wed Feb 23 12:08:10 2005 Entry (2): Serial Number: 42 (0x2a) Revocation Date: Wed Feb 23 12:08:40 2005`` + +.. _deleting_crl_from_a_database: + +`Deleting CRL from a Database <#deleting_crl_from_a_database>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + This example deletes CRL from a database in the specified directory: + + ``crlutil -D -n``\ *nickname*\ ``-d``\ *certdir* + +.. _importing_crl_into_a_database: + +`Importing CRL into a Database <#importing_crl_into_a_database>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + This example imports CRL into a database: + + ``crlutil -I -i``\ *crl-file*\ ``-d``\ *certdir* + + File should has binary format of ASN.1 encoded CRL data. + +.. _modifying_crl_in_a_database: + +`Modifying CRL in a Database <#modifying_crl_in_a_database>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + This example modifies a new CRL and importing it in to a Database in the specified directory: + + ``crlutil -G -d``\ *certdir*\ ``-n``\ *cert-nickname*\ ``-c``\ *crl-script-file* + + or + + ``crlutil -M -d``\ *certdir*\ ``-n``\ *cert-nickname*\ ``<`__ +------------------------------------------------------------------- + +.. container:: + + Newsgroup: `mozilla.dev.tech.crypto `__ + +.. _task_list: + +`Task List <#task_list>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + #. In analyze mode, there should be an option to create a file containing a graph of the + certificate database without any information about the user's certificates (no common names, + email addresses, etc.). This file could be mailed to a mail alias to assist in finding the + source of database corruption. + #. The dbck tool should be able to repair a currupted database. There should be command-line + options and, perhaps, an interactive mode to allow determine which certificates to keep. + #. The dbck tool should be able to update a databa \ No newline at end of file diff --git a/security/nss/doc/rst/legacy/tools/nss_tools_modutil-tasks/index.rst b/security/nss/doc/rst/legacy/tools/nss_tools_modutil-tasks/index.rst new file mode 100644 index 0000000000..ee10f77faa --- /dev/null +++ b/security/nss/doc/rst/legacy/tools/nss_tools_modutil-tasks/index.rst @@ -0,0 +1,24 @@ +.. _mozilla_projects_nss_tools_nss_tools_modutil-tasks: + +NSS Tools modutil-tasks +======================= + +.. _nss_security_tools_modutil_tasks: + +`NSS Security Tools: modutil Tasks <#nss_security_tools_modutil_tasks>`__ +------------------------------------------------------------------------- + +.. container:: + + Newsgroup: `mozilla.dev.tech.crypto `__ + +.. _task_list: + +`Task List <#task_list>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + #. The jar installation script is very fragile with respect to platform definitions (especially + version numbers). A fix was made for "HPUX B.11.00," but issues may still arise for platforms + like "Linux 2.2.12-20." Documentation needs to be explicit about the use of Fo \ No newline at end of file diff --git a/security/nss/doc/rst/legacy/tools/nss_tools_modutil/index.rst b/security/nss/doc/rst/legacy/tools/nss_tools_modutil/index.rst new file mode 100644 index 0000000000..65b4317a00 --- /dev/null +++ b/security/nss/doc/rst/legacy/tools/nss_tools_modutil/index.rst @@ -0,0 +1,912 @@ +.. _mozilla_projects_nss_tools_nss_tools_modutil: + +NSS Tools modutil +================= + +.. _using_the_security_module_database_(modutil): + +`Using the Security Module Database (modutil) <#using_the_security_module_database_(modutil)>`__ +------------------------------------------------------------------------------------------------ + +.. container:: + + Newsgroup: `mozilla.dev.tech.crypto `__ + The Security Module Database Tool is a command-line utility for managing PKCS #11 module + information within ``secmod.db`` files or within hardware tokens. You can use the tool to add and + delete PKCS #11 modules, change passwords, set defaults, list module contents, enable or disable + slots, enable or disable FIPS 140-2 compliance, and assign default providers for cryptographic + operations. This tool can also create ``key3.db``, ``cert8.db``, and ``secmod.db`` security + database files. + + The tasks associated with security module database management are part of a process that + typically also involves managing key databases (``key3.db`` files) and certificate databases + (``cert8.db`` files). The key, certificate, and PKCS #11 module management process generally + begins with creating the keys and key database necessary to generate and manage certificates and + the certificate database. This document discusses security module database management. For + information on certificate database and key database management, see `Using the Certificate + Database Tool `__. + +.. _availability_2: + +` <#availability_2>`__ Availability +----------------------------------- + +.. container:: + + This tool is known to build on Solaris 2.5.1 (SunOS 5.5.1) and Windows NT 4.0. + +.. _syntax_2: + +` <#syntax_2>`__ Syntax +----------------------- + +.. container:: + + To run the Security Module Database Tool, type the command + ``modutil``\ *option*\ ``[``\ *arguments*\ ``]`` where *option* and *arguments* are combinations + of the options and arguments listed in the following section. Each command takes one option. Each + option may take zero or more arguments. To see a usage string, issue the command without options. + +.. _options_and_arguments: + +`Options and Arguments <#options_and_arguments>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Options specify an action. Option arguments modify an action. The options and arguments for the + ``modutil`` command are defined as follows: + + +-------------------------------------------------+-------------------------------------------------+ + | **Options** | | + +-------------------------------------------------+-------------------------------------------------+ + | ``-create`` | Create new ``secmod.db``, ``key3.db``, and | + | | ``cert8.db`` files. Use the ``-dbdir`` | + | | *directory* argument to specify a directory. If | + | | any of these databases already exist in a | + | | specified directory, the Security Module | + | | Database Tool displays an error message. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-list [``\ *modulename*\ ``]`` | Display basic information about the contents of | + | | the ``secmod.db`` file. Use *modulename* to | + | | display detailed information about a particular | + | | module and its slots and tokens. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-add``\ *modulename* | Add the named PKCS #11 module to the database. | + | | Use this option with the ``-libfile``, | + | | ``-ciphers``, and ``-mechanisms`` arguments. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-jar``\ *JAR-file* | Add a new PKCS #11 module to the database using | + | | the named JAR file. Use this option with the | + | | ``-installdir`` and ``-tempdir`` arguments. The | + | | JAR file uses the Netscape Server PKCS #11 JAR | + | | format to identify all the files to be | + | | installed, the module's name, the mechanism | + | | flags, and the cipher flags. The JAR file | + | | should also contain any files to be installed | + | | on the target machine, including the PKCS #11 | + | | module library file and other files such as | + | | documentation. See the section `JAR | + | | Installation File `__ for | + | | information on creating the special script | + | | needed to perform an installation through a | + | | server or with the Security Module Database | + | | Tool (that is, in environments without | + | | JavaScript support). For general installation | + | | instructions and to install a module in | + | | environments where JavaScript support is | + | | available (as in Netscape Communicator), see | + | | the document `Using the JAR Installation | + | | Manager to Install a PKCS #11 Cryptographic | + | | Module `__. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-delete``\ *modulename* | Delete the named module. Note that you cannot | + | | delete the Netscape Communicator internal PKCS | + | | #11 module. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-changepw``\ *tokenname* | Change the password on the named token. If the | + | | token has not been initialized, this option | + | | initializes the password. Use this option with | + | | the ``-pwfile`` and ``-newpwfile`` arguments. | + | | In this context, the term "password" is | + | | equivalent to a personal identification number | + | | (PIN). | + +-------------------------------------------------+-------------------------------------------------+ + | ``-default``\ *modulename* | Specify the security mechanisms for which the | + | | named module will be a default provider. The | + | | security mechanisms are specified with the | + | | ``-mechanisms`` *mechanism-list* argument. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-undefault``\ *modulename* | Specify the security mechanisms for which the | + | | named module will *not* be a default provider. | + | | The security mechanisms are specified with | + | | the\ ``-mechanisms`` *mechanism-list* argument. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-enable``\ *modulename* | Enable all slots on the named module. Use the | + | | ``[-slot``\ *slotname*\ ``]``\ argument to | + | | enable a specific slot. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-disable``\ *modulename* | Disable all slots on the named module. Use the | + | | ``[-slot``\ *slotname*\ ``]``\ argument to | + | | disable a specific slot. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-fips [true | false]`` | Enable (``true``) or disable (``false``) FIPS | + | | 140-2 compliance for the Netscape Communicator | + | | internal module. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-force`` | Disable the Security Module Database Tool's | + | | interactive prompts so it can be run from a | + | | script. Use this option only after manually | + | | testing each planned operation to check for | + | | warnings and to ensure that bypassing the | + | | prompts will cause no security lapses or loss | + | | of database integrity. | + +-------------------------------------------------+-------------------------------------------------+ + | **Arguments** | | + +-------------------------------------------------+-------------------------------------------------+ + | ``-dbdir``\ *directory* | Specify the database directory in which to | + | | access or create security module database | + | | files. On Unix, the Security Module Database | + | | Tool defaults to the user's Netscape directory. | + | | Windows NT has no default directory, so | + | | ``-dbdir`` must be used to specify a directory. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-dbprefix`` *prefix* | Specify the prefix used on the ``cert8.db`` and | + | | ``key3.db`` files (for example, ``my_cert8.db`` | + | | and ``my_key3.db``). This option is provided as | + | | a special case. Changing the names of the | + | | certificate and key databases is not | + | | recommended. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-libfile``\ *library-file* | Specify a path to the DLL or other library file | + | | containing the implementation of the PKCS #11 | + | | interface module that is being added to the | + | | database. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-ciphers``\ *cipher-enable-list* | Enable specific ciphers in a module that is | + | | being added to the database. The | + | | *cipher-enable-list* is a colon-delimited list | + | | of cipher names. Enclose this list in quotation | + | | marks if it contains spaces. The following | + | | cipher is currently available: ``FORTEZZA``. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-mechanisms``\ *mechanism-list* | Specify the security mechanisms for which a | + | | particular module will be flagged as a default | + | | provider. The *mechanism-list* is a | + | | colon-delimited list of mechanism names. | + | | Enclose this list in quotation marks if it | + | | contains spaces. The module becomes a default | + | | provider for the listed mechanisms when those | + | | mechanisms are enabled. If more than one module | + | | claims to be a particular mechanism's default | + | | provider, that mechanism's default provider is | + | | undefined. The following mechanisms are | + | | currently available: ``RSA``, ``DSA``, ``RC2``, | + | | ``RC4``, ``RC5``, ``DES``, ``DH``, | + | | ``FORTEZZA``, ``SHA1``, ``MD5``, ``MD2``, | + | | ``RANDOM`` (for random number generation), and | + | | ``FRIENDLY`` (meaning certificates are publicly | + | | readable). | + +-------------------------------------------------+-------------------------------------------------+ + | ``-installdir``\ *root-installation-directory* | Specify the root installation directory | + | | relative to which files will be installed by | + | | the ``-jar`` *JAR-file* option. This directory | + | | should be one below which it is appropriate to | + | | store dynamic library files (for example, a | + | | server's root directory or the Netscape | + | | Communicator root directory). | + +-------------------------------------------------+-------------------------------------------------+ + | ``-tempdir``\ *temporary-directory* | The temporary directory is the location where | + | | temporary files will be created in the course | + | | of installation by the ``-jar`` *JAR-file* | + | | option. If no temporary directory is specified, | + | | the current directory will be used. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-pwfile``\ *old-password-file* | Specify a text file containing a token's | + | | existing password so that a password can be | + | | entered automatically when the ``-changepw`` | + | | *tokenname* option is used to change passwords. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-newpwfile``\ *new-password-file* | Specify a text file containing a token's new or | + | | replacement password so that a password can be | + | | entered automatically with the ``-changepw`` | + | | *tokenname* option. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-slot``\ *slotname* | Specify a particular slot to be enabled or | + | | disabled with the ``-enable`` *modulename* or | + | | ``-disable`` *modulename* options. | + +-------------------------------------------------+-------------------------------------------------+ + | -nocertdb | Do not open the certificate or key databases. | + | | This has several effects: | + | | | + | | - With the ``-create`` command, only a | + | | ``secmod.db`` file will be created; | + | | ``cert8.db`` and ``key3.db`` will not be | + | | created. | + | | - With the ``-jar`` command, signatures on the | + | | JAR file will not be checked. | + | | - With the ``-changepw`` command, the password | + | | on the Netscape internal module cannot be | + | | set or changed, since this password is | + | | stored in ``key3.db``. | + +-------------------------------------------------+-------------------------------------------------+ + +.. _usage_2: + +` <#usage_2>`__ Usage +--------------------- + +.. container:: + + The Security Module Database Tool's capabilities are grouped as follows, using these combinations + of options and arguments. The options and arguments in square brackets are optional, those + without square brackets are required. + + - Creating a set of security management database files (``key3.db``, ``cert8.db``, and + ``secmod.db``): + + ``-create`` + + - Displaying basic module information or detailed information about the contents of a given + module: + + ``-list [``\ *modulename*\ ``]`` + + - Adding a PKCS #11 module, which includes setting a supporting library file, enabling ciphers, + and setting default provider status for various security mechanisms: + + ``-add``\ *modulename*\ ``-libfile``\ *library-file* + ``[-ciphers``\ *cipher-enable-list*\ ``] [-mechanisms``\ *mechanism-list*\ ``]`` + + - Adding a PKCS #11 module from an existing JAR file: + + ``-jar``\ *JAR-file* ``-installdir``\ *root-installation-directory* + ``[-tempdir``\ *temporary-directory*\ ``]`` + + - Deleting a specific PKCS #11 module from a security module database: + + ``-delete``\ *modulename* + + - Initializing or changing a token's password: + + ``-changepw``\ *tokenname* + ``[-pwfile``\ *old-password-file*\ ``] [-newpwfile``\ *new-password-file*\ ``]`` + + - Setting the default provider status of various security mechanisms in an existing PKCS #11 + module: + + ``-default``\ *modulename* ``-mechanisms``\ *mechanism-list* + + - Clearing the default provider status of various security mechanisms in an existing PKCS #11 + module: + + ``-undefault``\ *modulename* ``-mechanisms``\ *mechanism-list* + + - Enabling a specific slot or all slots within a module: + + ``-enable``\ *modulename* ``[-slot``\ *slotname*\ ``]`` + + - Disabling a specific slot or all slots within a module: + + ``-disable``\ *modulename* ``[-slot``\ *slotname*\ ``]`` + + - Enabling or disabling FIPS 140-2 compliance within the Netscape Communicator internal module: + + ``-fips [true | false]`` + + - Disabling interactive prompts for the Security Module Database Tool, to support scripted + operation: + + ``-force`` + +.. _jar_installation_file: + +`JAR Installation File <#jar_installation_file>`__ +-------------------------------------------------- + +.. container:: + + When a JAR file is run by a server, by the Security Module Database Tool, or by any program that + does not interpret JavaScript, a special information file must be included in the format + described below. This information file contains special scripting and must be declared in the JAR + archive's manifest file. The script can have any name. The metainfo tag for this is + ``Pkcs11_install_script``. To declare meta-information in the manifest file, put it in a file + that is passed to the `Netscape Signing + Tool `__. + +.. _sample_script: + +`Sample Script <#sample_script>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + For example, the PKCS #11 installer script could be in the file ``pk11install.`` If so, the + metainfo file for the `Netscape Signing + Tool `__ would include a + line such as this: + .. code:: + + + Pkcs11_install_script: pk11install + + The sample script file could contain the following: + .. code:: + + ForwardCompatible { IRIX:6.2:mips SUNOS:5.5.1:sparc } + Platforms { + WINNT::x86 { + ModuleName { "Fortezza Module" } + ModuleFile { win32/fort32.dll } + DefaultMechanismFlags{0x0001} + DefaultCipherFlags{0x0001} + Files { + win32/setup.exe { + Executable + RelativePath { %temp%/setup.exe } + } + win32/setup.hlp { + RelativePath { %temp%/setup.hlp } + } + win32/setup.cab { + RelativePath { %temp%/setup.cab } + } + } + } + WIN95::x86 { + EquivalentPlatform {WINNT::x86} + } + SUNOS:5.5.1:sparc { + ModuleName { "Fortezza UNIX Module" } + ModuleFile { unix/fort.so } + DefaultMechanismFlags{0x0001} + CipherEnableFlags{0x0001} + Files { + unix/fort.so { + RelativePath{%root%/lib/fort.so} + AbsolutePath{/usr/local/netscape/lib/fort.so} + FilePermissions{555} + } + xplat/instr.html { + RelativePath{%root%/docs/inst.html} + AbsolutePath{/usr/local/netscape/docs/inst.html} + FilePermissions{555} + } + } + } + IRIX:6.2:mips { + EquivalentPlatform { SUNOS:5.5.1:sparc } + } + } + +.. _script_grammar: + +`Script Grammar <#script_grammar>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + The script file grammar is as follows: + .. code:: + + --> valuelist + + .. code:: + + valuelist --> value valuelist + + + .. code:: + + value ---> key_value_pair + string + + .. code:: + + key_value_pair --> key { valuelist } + + .. code:: + + key --> string + + .. code:: + + string --> simple_string + "complex_string" + + .. code:: + + simple_string --> [^ \t\n\""{""}"]+ + (No whitespace, quotes, or braces.) + + .. code:: + + complex_string --> ([^\"\\\r\n]|(\\\")|(\\\\))+ (Quotes and + backslashes must be escaped with a backslash. A complex string must not + include newlines or carriage returns.) + + Outside of complex strings, all white space (for example, spaces, tabs, and carriage returns) is + considered equal and is used only to delimit tokens. + +`Keys <#keys>`__ +~~~~~~~~~~~~~~~~ + +.. container:: + + Keys are case-insensitive. This section discusses the following keys: `Global + Keys `__ + `Per-Platform Keys `__ + `Per-File Keys `__ + .. rubric:: Global Keys + :name: global_keys + + ``ForwardCompatible`` Gives a list of platforms that are forward compatible. If the current + platform cannot be found in the list of supported platforms, then the ``ForwardCompatible`` list + is checked for any platforms that have the same OS and architecture in an earlier version. If one + is found, its attributes are used for the current platform. ``Platforms`` (required) Gives a list + of platforms. Each entry in the list is itself a key-value pair: the key is the name of the + platform and the value list contains various attributes of the platform. The ``ModuleName``, + ``ModuleFile``, and ``Files`` attributes must be specified for each platform unless an + ``EquivalentPlatform`` attribute is specified. The platform string is in the following format: + *system name*\ ``:``\ *OS release*\ ``:``\ *architecture*. The installer obtains these values + from NSPR. *OS release* is an empty string on non-Unix operating systems. The following system + names and platforms are currently defined by NSPR: + + - AIX (rs6000) + - BSDI (x86) + - FREEBSD (x86) + - HPUX (hppa1.1) + - IRIX (mips) + - LINUX (ppc, alpha, x86) + - MacOS (PowerPC) + - NCR (x86) + - NEC (mips) + - OS2 (x86) + - OSF (alpha) + - ReliantUNIX (mips) + - SCO (x86) + - SOLARIS (sparc) + - SONY (mips) + - SUNOS (sparc) + - UnixWare (x86) + - WIN16 (x86) + - WIN95 (x86) + - WINNT (x86) + + Here are some examples of valid platform strings: + .. code:: + + IRIX:6.2:mips + SUNOS:5.5.1:sparc + Linux:2.0.32:x86 + WIN95::x86. + + .. rubric:: Per-Platform Keys + :name: per-platform_keys + + These keys have meaning only within the value list of an entry in the ``Platforms`` list. + ``ModuleName`` (required) Gives the common name for the module. This name will be used to + reference the module from Netscape Communicator, the Security Module Database tool (``modutil``), + servers, or any other program that uses the Netscape security module database. ``ModuleFile`` + (required) Names the PKCS #11 module file (DLL or ``.so``) for this platform. The name is given + as the relative path of the file within the JAR archive. ``Files`` (required) Lists the files + that need to be installed for this module. Each entry in the file list is a key-value pair: the + key is the path of the file in the JAR archive, and the value list contains attributes of the + file. At least ``RelativePath`` or ``AbsolutePath`` must be specified for each file. + ``DefaultMechanismFlags`` Specifies mechanisms for which this module will be a default provider. + This key-value pair is a bitstring specified in hexadecimal (0x) format. It is constructed as a + bitwise OR of the following constants. If the ``DefaultMechanismFlags`` entry is omitted, the + value defaults to 0x0. + .. code:: + + RSA: 0x00000001 + DSA: 0x00000002 + RC2: 0x00000004 + RC4: 0x00000008 + DES: 0x00000010 + DH: 0x00000020 + FORTEZZA: 0x00000040 + RC5: 0x00000080 + SHA1: 0x00000100 + MD5: 0x00000200 + MD2: 0x00000400 + RANDOM: 0x08000000 + FRIENDLY: 0x10000000 + OWN_PW_DEFAULTS: 0x20000000 + DISABLE: 0x40000000 + + ``CipherEnableFlags`` Specifies ciphers that this module provides but Netscape Communicator does + not, so that Communicator can enable them. This key is a bitstring specified in hexadecimal (0x) + format. It is constructed as a bitwise OR of the following constants. If the + ``CipherEnableFlags`` entry is omitted, the value defaults to 0x0. + .. code:: + + FORTEZZA: 0x0000 0001 + + ``EquivalentPlatform`` Specifies that the attributes of the named platform should also be used + for the current platform. Saves typing when there is more than one platform using the same + settings. + .. rubric:: Per-File Keys + :name: per-file_keys + + These keys have meaning only within the value list of an entry in a ``Files`` list. At least one + of ``RelativePath`` and ``AbsolutePath`` must be specified. If both are specified, the relative + path is tried first, and the absolute path is used only if no relative root directory is provided + by the installer program. ``RelativePath`` Specifies the destination directory of the file, + relative to some directory decided at install time. Two variables can be used in the relative + path: "``%root%``" and "``%temp%``". "``%root%``" is replaced at run time with the directory + relative to which files should be installed; for example, it may be the server's root directory + or the Netscape Communicator root directory. The "``%temp%``" directory is created at the + beginning of the installation and destroyed at the end. The purpose of "``%temp%``" is to hold + executable files (such as setup programs) or files that are used by these programs. For example, + a Windows installation might consist of a ``setup.exe`` installation program, a help file, and a + ``.cab`` file containing compressed information. All these files could be installed in the + temporary directory. Files destined for the temporary directory are guaranteed to be in place + before any executable file is run; they are not deleted until all executable files have finished. + ``AbsolutePath`` Specifies the destination directory of the file as an absolute path. If both + ``RelativePath`` and ``AbsolutePath`` are specified, the installer attempts to use the relative + path; if it is unable to determine a relative path, it uses the absolute path. ``Executable`` + Specifies that the file is to be executed during the course of the installation. Typically this + string would be used for a setup program provided by a module vendor, such as a self-extracting + ``setup.exe``. More than one file can be specified as executable, in which case the files are run + in the order in which they are specified in the script file. ``FilePermissions`` Interpreted as a + string of octal digits, according to the standard Unix format. This string is a bitwise OR of the + following constants: + .. code:: + + user read: 0400 + user write: 0200 + user execute: 0100 + group read: 0040 + group write: 0020 + group execute: 0010 + other read: 0004 + other write: 0002 + other execute: 0001 + + Some platforms may not understand these permissions. They are applied only insofar as they make + sense for the current platform. If this attribute is omitted, a default of 777 is assumed. + +.. _examples_2: + +` <#examples_2>`__ Examples +--------------------------- + +.. container:: + + `Creating Database Files `__ + `Displaying Module Information `__ + `Setting a Default Provider `__ + `Enabling a Slot `__ + `Enabling FIPS Compliance `__ + `Adding a Cryptographic Module `__ + `Installing a Cryptographic Module from a JAR File `__ + `Changing the Password on a Token `__ + +.. _creating_database_files: + +`Creating Database Files <#creating_database_files>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + This example creates a set of security management database files in the specified directory: + .. code:: + + modutil -create -dbdir c:\databases + + The Security Module Database Tool displays a warning: + .. code:: + + WARNING: Performing this operation while Communicator is running could + cause corruption of your security databases. If Communicator is + currently running, you should exit Communicator before continuing this + operation. Type 'q ' to abort, or to continue: + + After you press Enter, the tool displays the following: + .. code:: + + Creating "c:\databases\key3.db"...done. + Creating "c:\databases\cert8.db"...done. + Creating "c:\databases\secmod.db"...done. + +.. _displaying_module_information: + +`Displaying Module Information <#displaying_module_information>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + This example gives detailed information about the specified module: + .. code:: + + modutil -list "Netscape Internal PKCS #11 Module" -dbdir c:\databases + + The Security Module Database Tool displays information similar to this: + .. code:: + + Using database directory c:\databases... + -------------------------------------------------------- + Name: Netscape Internal PKCS #11 Module + Library file: **Internal ONLY module** + Manufacturer: Netscape Communications Corp + Description: Communicator Internal Crypto Svc + PKCS #11 Version 2.0 + Library Version: 4.0 + Cipher Enable Flags: None + Default Mechanism Flags: RSA:DSA:RC2:RC4:DES:SHA1:MD5:MD2 + + .. code:: + + Slot: Communicator Internal Cryptographic Services Version 4.0 + Manufacturer: Netscape Communications Corp + Type: Software + Version Number: 4.1 + Firmware Version: 0.0 + Status: Enabled + Token Name: Communicator Generic Crypto Svcs + Token Manufacturer: Netscape Communications Corp + Token Model: Libsec 4.0 + Token Serial Number: 0000000000000000 + Token Version: 4.0 + Token Firmware Version: 0.0 + Access: Write Protected + Login Type: Public (no login required) + User Pin: NOT Initialized + + .. code:: + + Slot: Communicator User Private Key and Certificate Services + Manufacturer: Netscape Communications Corp + Type: Software + Version Number: 3.0 + Firmware Version: 0.0 + Status: Enabled + Token Name: Communicator Certificate DB + Token Manufacturer: Netscape Communications Corp + Token Model: Libsec 4.0 + Token Serial Number: 0000000000000000 + Token Version: 7.0 + Token Firmware Version: 0.0 + Access: NOT Write Protected + Login Type: Login required + User Pin: NOT Initialized + +.. _setting_a_default_provider: + +`Setting a Default Provider <#setting_a_default_provider>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + This example makes the specified module a default provider for the RSA, DSA, and RC2 security + mechanisms: + .. code:: + + modutil -default "Cryptographic Module" -dbdir + c:\databases -mechanisms RSA:DSA:RC2 + + The Security Module Database Tool displays a warning: + .. code:: + + WARNING: Performing this operation while Communicator is running could + cause corruption of your security databases. If Communicator is + currently running, you should exit Communicator before continuing this + operation. Type 'q ' to abort, or to continue: + + After you press Enter, the tool displays the following: + .. code:: + + Using database directory c:\databases... + + .. code:: + + Successfully changed defaults. + +.. _enabling_a_slot: + +`Enabling a Slot <#enabling_a_slot>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + This example enables a particular slot in the specified module: + .. code:: + + modutil -enable "Cryptographic Module" -slot + "Cryptographic Reader" -dbdir c:\databases + + The Security Module Database Tool displays a warning: + .. code:: + + WARNING: Performing this operation while Communicator is running could + cause corruption of your security databases. If Communicator is + currently running, you should exit Communicator before continuing this + operation. Type 'q ' to abort, or to continue: + + After you press Enter, the tool displays the following: + .. code:: + + Using database directory c:\databases... + + .. code:: + + Slot "Cryptographic Reader" enabled. + +.. _enabling_fips_compliance: + +`Enabling FIPS Compliance <#enabling_fips_compliance>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + This example enables FIPS 140-2 compliance in Communicator's internal module: + .. code:: + + modutil -dbdir "C:\databases" -fips true + + The Security Module Database Tool displays a warning: + .. code:: + + 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 ' to abort, or to continue: + + After you press Enter, the tool displays the following: + .. code:: + + FIPS mode enabled. + +.. _adding_a_cryptographic_module: + +`Adding a Cryptographic Module <#adding_a_cryptographic_module>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + This example adds a new cryptographic module to the database: + .. code:: + + C:\modutil> modutil -dbdir "C:\databases" -add "Cryptorific Module" - + libfile "C:\winnt\system32\crypto.dll" -mechanisms RSA:DSA:RC2:RANDOM + + The Security Module Database Tool displays a warning: + .. code:: + + WARNING: Performing this operation while Communicator is running could + cause corruption of your security databases. If Communicator is + currently running, you should exit Communicator before continuing this + operation. Type 'q ' to abort, or to continue: + + After you press Enter, the tool displays the following: + .. code:: + + Using database directory C:\databases... + Module "Cryptorific Module" added to database. + C:\modutil> + +.. _installing_a_cryptographic_module_from_a_jar_file: + +`Installing a Cryptographic Module from a JAR File <#installing_a_cryptographic_module_from_a_jar_file>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + This example installs a cryptographic module from the following sample installation script. + .. code:: + + Platforms { + WinNT::x86 { + ModuleName { "Cryptorific Module" } + ModuleFile { crypto.dll } + DefaultMechanismFlags{0x0000} + CipherEnableFlags{0x0000} + Files { + crypto.dll { + RelativePath{ %root%/system32/crypto.dll } + } + setup.exe { + Executable + RelativePath{ %temp%/setup.exe } + } + } + } + Win95::x86 { + EquivalentPlatform { Winnt::x86 } + } + } + + To install from the script, use the following command. The root directory should be the Windows + root directory (for example, ``c:\\windows``, or ``c:\\winnt``). + .. code:: + + C:\modutil> modutil -dbdir "c:\databases" -jar + install.jar -installdir "C:/winnt" + + The Security Module Database Tool displays a warning: + .. code:: + + WARNING: Performing this operation while Communicator is running could + cause corruption of your security databases. If Communicator is + currently running, you should exit Communicator before continuing this + operation. Type 'q ' to abort, or to continue: + + After you press Enter, the tool displays the following: + .. code:: + + Using database directory c:\databases... + + .. code:: + + This installation JAR file was signed by: + ---------------------------------------------- + + .. code:: + + **SUBJECT NAME** + + .. code:: + + C=US, ST=California, L=Mountain View, CN=Cryptorific Inc., OU=Digital ID + Class 3 - Netscape Object Signing, OU="www.verisign.com/repository/CPS + Incorp. by Ref.,LIAB.LTD(c)9 6", OU=www.verisign.com/CPS Incorp.by Ref + . LIABILITY LTD.(c)97 VeriSign, OU=VeriSign Object Signing CA - Class 3 + Organization, OU="VeriSign, Inc.", O=VeriSign Trust Network **ISSUER + NAME**, OU=www.verisign.com/CPS Incorp.by Ref. LIABILITY LTD.(c)97 + VeriSign, OU=VeriSign Object Signing CA - Class 3 Organization, + OU="VeriSign, Inc.", O=VeriSign Trust Network + ---------------------------------------------- + + .. code:: + + Do you wish to continue this installation? (y/n) y + Using installer script "installer_script" + Successfully parsed installation script + Current platform is WINNT::x86 + Using installation parameters for platform WinNT::x86 + Installed file crypto.dll to C:/winnt/system32/crypto.dll + Installed file setup.exe to ./pk11inst.dir/setup.exe + Executing "./pk11inst.dir/setup.exe"... + "./pk11inst.dir/setup.exe" executed successfully + Installed module "Cryptorific Module" into module database + + .. code:: + + Installation completed successfully + C:\modutil> + +.. _changing_the_password_on_a_token: + +`Changing the Password on a Token <#changing_the_password_on_a_token>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + This example changes the password for a token on an existing module. + .. code:: + + C:\modutil> modutil -dbdir "c:\databases" -changepw + "Communicator Certificate DB" + + The Security Module Database Tool displays a warning: + .. code:: + + WARNING: Performing this operation while Communicator is running could + cause corruption of your security databases. If Communicator is + currently running, you should exit Communicator before continuing this + operation. Type 'q ' to abort, or to continue: + + After you press Enter, the tool displays the following: + .. code:: + + Using database directory c:\databases... + Enter old password: + Incorrect password, try again... + Enter old password: + Enter new password: + Re-enter new password: + Token "Communicator Certificate DB" password changed successfully. + C:\modutil> + + -------------- \ No newline at end of file diff --git a/security/nss/doc/rst/legacy/tools/nss_tools_pk12util-tasks/index.rst b/security/nss/doc/rst/legacy/tools/nss_tools_pk12util-tasks/index.rst new file mode 100644 index 0000000000..f7eae7a4a8 --- /dev/null +++ b/security/nss/doc/rst/legacy/tools/nss_tools_pk12util-tasks/index.rst @@ -0,0 +1,23 @@ +.. _mozilla_projects_nss_tools_nss_tools_pk12util-tasks: + +NSS Tools pk12util-tasks +======================== + +.. _nss_security_tools_pk12util_tasks: + +`NSS Security Tools: pk12util Tasks <#nss_security_tools_pk12util_tasks>`__ +--------------------------------------------------------------------------- + +.. container:: + + Newsgroup: `mozilla.dev.tech.crypto `__ + +.. _task_list: + +`Task List <#task_list>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + #. Need to migrate code to use an up-to-date version of NSS. + #. Use NSS functions in pcertdb for handling older database \ No newline at end of file diff --git a/security/nss/doc/rst/legacy/tools/nss_tools_pk12util/index.rst b/security/nss/doc/rst/legacy/tools/nss_tools_pk12util/index.rst new file mode 100644 index 0000000000..245173e02b --- /dev/null +++ b/security/nss/doc/rst/legacy/tools/nss_tools_pk12util/index.rst @@ -0,0 +1,217 @@ +.. _mozilla_projects_nss_tools_nss_tools_pk12util: + +NSS Tools pk12util +================== + +.. _using_the_pkcs_12_tool_(pk12util): + +`Using the PKCS #12 Tool (pk12util) <#using_the_pkcs_12_tool_(pk12util)>`__ +--------------------------------------------------------------------------- + +.. container:: + + Newsgroup: `mozilla.dev.tech.crypto `__ + The PKCS #12 utility makes sharing of certificates among Enterprise server 3.x and any server + (Netscape products or non-Netscape products) that supports PKCS#12 possible. The tool allows you + to import certificates and keys from pkcs #12 files into NSS or export them and also list + certificates and keys in such files. + +.. _availability_2: + +` <#availability_2>`__ Availability +----------------------------------- + +.. container:: + + See the `release notes <../release_notes.html>`__ for the platforms this tool is available on. + +`Synopsis <#synopsis>`__ +------------------------ + +.. container:: + + **pk12util** ``-i p12File [-h tokenname] [-v] [common-options]`` + or + **pk12util** + ``-o p12File -n certname [-c keyCipher] [-C certCipher] [-m | --key_len keyLen] [-n | --cert_key_len certKeyLen] [common-options]`` + or + **pk12util** ``-l p12File [-h tokenname] [-r] [common-options]`` + where + **[common-options]** = + ``[-d dir] [-P dbprefix] [-k slotPasswordFile | -K slotPassword] [-w p12filePasswordFile | -W p12filePassword]`` + +`Syntax <#syntax>`__ +-------------------- + +.. container:: + + To run the PKCS #12 Tool, type the command ``pk12util`` *option*\ ``[``\ *arguments*\ ``]`` where + *option* and *arguments* are combinations of the options and arguments listed in the following + section. Three of the options, -i, -o, and -l, should be considered commands of the pk12util + invocation. Each command takes several options. Options may take zero or more arguments. To see a + usage string, issue the pkcs12util command without any options. + +.. _options_and_arguments: + +`Options and Arguments <#options_and_arguments>`__ +-------------------------------------------------- + +.. container:: + + Options specify an action. Option arguments modify an action. The options and arguments for the + ``pk12util`` command are defined as follows: + + +-------------------------------------------------+-------------------------------------------------+ + | **Options** | | + +-------------------------------------------------+-------------------------------------------------+ + | ``-i`` *p12file* | Import a certificate and private key from the | + | | p12file into the database. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-o`` *p12file* | Export certificate and private key, specified | + | | by the -n option, from the database to the p12 | + | | file. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-l`` *p12file* | List certificate and private key from the | + | | ``p12file`` file. | + +-------------------------------------------------+-------------------------------------------------+ + | **Arguments** | | + +-------------------------------------------------+-------------------------------------------------+ + | ``-n`` *certname* | Specify the nickname of the cert and private | + | | key to export. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-d`` *dir* | Specify the database directory into which to | + | | import to or export from certificates and keys. | + | | If not specified the directory defaults to | + | | $HOME/.netscape (when $HOME exists in the | + | | environment), or to ./.netscape (when $HOME | + | | does not exist in the environment). | + +-------------------------------------------------+-------------------------------------------------+ + | ``-P`` *prefix* | Specify the prefix used on the ``cert8.db`` and | + | | ``key3.db`` files (for example, ``my_cert8.db`` | + | | and ``my_key3.db``). This option is provided as | + | | a special case. Changing the names of the | + | | certificate and key databases is not | + | | recommended. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-h`` *tokenname* | Specify the name of the token to import into or | + | | export from | + +-------------------------------------------------+-------------------------------------------------+ + | ``-v`` | Enable debug logging when importing | + +-------------------------------------------------+-------------------------------------------------+ + | ``-k`` *slotPasswordFile* | Specify the text file containing the slot's | + | | password | + +-------------------------------------------------+-------------------------------------------------+ + | ``-K`` *slotPassword* | Specify a slot's password | + +-------------------------------------------------+-------------------------------------------------+ + | ``-w`` *p12filePasswordFile* | Specify the text file containing the pkcs 12 | + | | file's password | + +-------------------------------------------------+-------------------------------------------------+ + | ``-W`` *p12filePassword* | Specify the pkcs 12 file's password | + +-------------------------------------------------+-------------------------------------------------+ + | ``-c`` *key-cipher* | Specify the key encryption algorithm | + +-------------------------------------------------+-------------------------------------------------+ + | ``-C`` *certCipher* | Specify the PFX encryption algorithm | + +-------------------------------------------------+-------------------------------------------------+ + | ``-m | --key_len`` * | Specify the desired length of the symmetric key | + | keyLen* | to be used to encrypt the private key | + +-------------------------------------------------+-------------------------------------------------+ + | ``-n | --cert_key_len`` * | Specify the desired length of the symmetric key | + | certLeyLen* | to be used to encrypt the top level protocol | + | | data unit | + +-------------------------------------------------+-------------------------------------------------+ + + +---+ + | | + +---+ + +.. _password_based_encryption: + +` <#password_based_encryption>`__ Password Based Encryption +----------------------------------------------------------- + +.. container:: + + 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 also the entire package when allowed. If no algorithm is specified, + the tool defaults to using "PKCS12 V2 PBE With SHA1 And 3KEY Triple DES-cbc" for private key + encryption. For historical export control reasons "PKCS12 V2 PBE With SHA1 And 40 Bit RC4" is the + default for the overall package encryption when not in FIPS mode and no package encryption when + in FIPS mode. The private key is always protected with strong encryption by default. A list of + ciphers follows. + + - symmetric CBC ciphers for PKCS #5 V2: + + - "DES_CBC" + - "RC2-CBC" + - "RC5-CBCPad" + - "DES-EDE3-CBC" + --- default for key encryption + - "AES-128-CBC" + - "AES-192-CBC" + - "AES-256-CBC" + - "CAMELLIA-128-CBC" + - "CAMELLIA-192-CBC" + - "CAMELLIA-256-CBC" + + - PKCS #12 PBE Ciphers: + + - "PKCS #12 PBE With Sha1 and 128 Bit RC4" + - "PKCS #12 PBE With Sha1 and 40 Bit RC4" + - "PKCS #12 PBE With Sha1 and Triple DES CBC" + - "PKCS #12 PBE With Sha1 and 128 Bit RC2 CBC" + - "PKCS #12 PBE With Sha1 and 40 Bit RC2 CBC" + - "PKCS12 V2 PBE With SHA1 And 128 Bit RC4" + - "PKCS12 V2 PBE With SHA1 And 40 Bit RC4" + --- default for PFX encryption in non-fips mode, no encryption on fips mode + - "PKCS12 V2 PBE With SHA1 And 3KEY Triple DES-cbc" + - "PKCS12 V2 PBE With SHA1 And 2KEY Triple DES-cbc" + - "PKCS12 V2 PBE With SHA1 And 128 Bit RC2 CBC" + - "PKCS12 V2 PBE With SHA1 And 40 Bit RC2 CBC" + + - PKCS #5 PBE Ciphers: + + - "PKCS #5 Password Based Encryption with MD2 and DES CBC" + - "PKCS #5 Password Based Encryption with MD5 and DES CBC" + - "PKCS #5 Password Based Encryption with SHA1 and DES CBC" + + It should be noted that the crypto provider may be the softtoken module or an external hardware + module. It may be the case that the cryptographic module does not support the requested algorithm + and a best fit will be selected, likely to be the default. If no suitable replacement for the + desired algorithm can be found a "no security module can perform the requested operation" will + appear on the error message. + +.. _error_codes: + +` <#error_codes>`__ Error Codes +------------------------------- + +.. container:: + + **pk12util** can return the following values: + | **0** - No error + | **1** - User Cancelled + | **2** - Usage error + | **6** - NLS init error + | **8** - Certificate DB open error + | **9** - Key DB open error + | **10** - File initialization error + | **11** - Unicode conversion error + | **12** - Temporary file creation error + | **13** - PKCS11 get slot error + | **14** - PKCS12 decoder start error + | **15** - error read from import file + | **16** - pkcs12 decode error + | **17** - pkcs12 decoder verify error + | **18** - pkcs12 decoder validate bags error + | **19** - pkcs12 decoder import bags error + | **20** - key db conversion version 3 to version 2 error + | **21** - cert db conversion version 7 to version 5 error + | **22** - cert and key dbs patch error + | **23** - get default cert db error + | **24** - find cert by nickname error + | **25** - create export context error + | **26** - PKCS12 add password itegrity error + | **27** - cert and key Safes creation error + | **28** - PKCS12 add cert and key error + | **29** - PKCS12 encode error \ No newline at end of file diff --git a/security/nss/doc/rst/legacy/tools/nss_tools_signver-tasks/index.rst b/security/nss/doc/rst/legacy/tools/nss_tools_signver-tasks/index.rst new file mode 100644 index 0000000000..f8a29cd4e6 --- /dev/null +++ b/security/nss/doc/rst/legacy/tools/nss_tools_signver-tasks/index.rst @@ -0,0 +1,22 @@ +.. _mozilla_projects_nss_tools_nss_tools_signver-tasks: + +NSS Tools signver-tasks +======================= + +.. _nss_security_tools_signver_tasks: + +`NSS Security Tools: signver Tasks <#nss_security_tools_signver_tasks>`__ +------------------------------------------------------------------------- + +.. container:: + + Newsgroup: `mozilla.dev.tech.crypto `__ + +.. _task_list: + +`Task List <#task_list>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + #. Remove private hash algortihms and replace with code in lib/hash, lib/crypto, and \ No newline at end of file diff --git a/security/nss/doc/rst/legacy/tools/nss_tools_sslstrength/index.rst b/security/nss/doc/rst/legacy/tools/nss_tools_sslstrength/index.rst new file mode 100644 index 0000000000..b1b6b5dd50 --- /dev/null +++ b/security/nss/doc/rst/legacy/tools/nss_tools_sslstrength/index.rst @@ -0,0 +1,87 @@ +.. _mozilla_projects_nss_tools_nss_tools_sslstrength: + +NSS Tools sslstrength +===================== + +`sslstrength <#sslstrength>`__ +------------------------------ + +.. container:: + +`Summary <#summary>`__ +~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + A simple command-line client which connects to an SSL-server, and reports back the encryption + cipher and strength used. + +`Synopsis <#synopsis>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + 1) sslstrength ciphers + + 2) sslstrength hostname[:port] [ciphers=xyz] [debug] [verbose] [policy=export|domestic] + +`Description <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + The first form simple lists out the possible ciphers. The letter in the first column of the + output is used to identify the cipher preferences in the ciphers= command. + + The second form attempts to connect to the named ssl host. The hostname argument must be present. + However, the port number is an optional argument, and if not given, will default to the https + port (443). + + .. rubric:: Restricting Ciphers + :name: restricting_ciphers + + By default, sslstrength assumes that all the preferences are on, so it will use any preferences + in your policy. The enabled ciphersuites will always be printed out before the connection is + made. If you want to test out a particular cipher, there are two ways to affect which ciphers are + available. Firstly, you can set **policy** to be either domestic or export. This restricts the + available ciphers to the same set used by Communicator. In addition to this, the **ciphers** + command can be used to further restrict the ciphers available. The argument to the ciphers + command is a string of characters, where each single character represents a cipher. You can + obtain this list of character->cipher mappings by doing 'sslstrength ciphers'. For example, + + ** ciphers=bfi** will turn on these cipher preferences and turn off all others. + + ** policy=export** or **policy=domestic** will set your policies appropriately. + + | ** policy** will default to domestic if not specified. + | + + .. rubric:: Step-up + :name: step-up + + Step up is a mode where the connection starts out with 40-bit encryption, but due to a + 'change-cipher-spec' handshake, changes to 128-bit encryption. This is only done in 'export + mode', with servers with a special certificate. You can tell if you stepped-up, because the + output will says 'using export policy', and you'll find the secret key size was 128-bits. + +`Prerequisites <#prerequisites>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + | You should have a cert7.db in the directory in which you run sslstrength. + | + +`Other <#other>`__ +~~~~~~~~~~~~~~~~~~ + +.. container:: + + | For references, here is a table of well-known SSL port numbers: + | + + ===== === + HTTPS 443 + IMAPS 993 + NNTPS 563 + ===== === \ No newline at end of file diff --git a/security/nss/doc/rst/legacy/tools/nss_tools_ssltap/index.rst b/security/nss/doc/rst/legacy/tools/nss_tools_ssltap/index.rst new file mode 100644 index 0000000000..61544ea830 --- /dev/null +++ b/security/nss/doc/rst/legacy/tools/nss_tools_ssltap/index.rst @@ -0,0 +1,621 @@ +.. _mozilla_projects_nss_tools_nss_tools_ssltap: + +NSS Tools ssltap +================ + +.. _using_the_ssl_debugging_tool_(ssltap): + +`Using the SSL Debugging Tool (ssltap) <#using_the_ssl_debugging_tool_(ssltap)>`__ +---------------------------------------------------------------------------------- + +.. container:: + + Newsgroup: `mozilla.dev.tech.crypto `__ + The SSL Debugging Tool is an SSL-aware command-line proxy. It watches TCP connections and + displays the data going by. If a connection is SSL, the data display includes interpreted SSL + records and handshaking. + +.. _availability_2: + +` <#availability_2>`__ Availability +----------------------------------- + +.. container:: + + This tool is known to build on Solaris 2.5.1 (SunOS 5.5.1) and Windows NT 4.0. + +.. _description_2: + +` <#description_2>`__ Description +--------------------------------- + +.. container:: + + The ``ssltap`` command opens a socket on a rendezvous port and waits for an incoming connection + from the client side. Once this connection arrives, the tool makes another connection to the + specified host name and port on the server side. It passes any data sent by the client to the + server and vice versa. The tool also displays the data to the shell window from which it was + called. It can do this for plain HTTP connections or any TCP protocol, as well as for SSL + streams, as described here. The tool cannot and does not decrypt any encrypted message data. You + use the tool to look at the plain text and binary data that are part of the handshake procedure, + before the secure connection is established. + +.. _syntax_2: + +` <#syntax_2>`__ Syntax +----------------------- + +.. container:: + + To run the SSL Debugging Tool, type this command in a command shell: ``ssltap`` [``-vhfsxl``] + [``-p`` *port*] *hostname*:*port* + +` <#options>`__ Options +~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + The command does not require any options other than *hostname:port*, but you normally use them to + control the connection interception and output. The options for the command are the following: + + +-------------------------------------------------+-------------------------------------------------+ + | ``-v`` | Print a version string for the tool. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-h`` | Turn on hex/ASCII printing. Instead of | + | | outputting raw data, the command interprets | + | | each record as a numbered line of hex values, | + | | followed by the same data as ASCII characters. | + | | The two parts are separated by a vertical bar. | + | | Nonprinting characters are replaced by dots. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-f`` | Turn on fancy printing. Output is printed in | + | | colored HTML. Data sent from the client to the | + | | server is in blue; the server's reply is in | + | | red. When used with looping mode, the different | + | | connections are separated with horizontal | + | | lines. You can use this option to upload the | + | | output into a browser. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-s`` | Turn on SSL parsing and decoding. The tool does | + | | not automatically detect SSL sessions. If you | + | | are intercepting an SSL connection, use this | + | | option so that the tool can detect and decode | + | | SSL structures. | + | | | + | | If the tool detects a certificate chain, it | + | | saves the DER-encoded certificates into files | + | | in the current directory. The files are named | + | | ``cert.0``\ *x*, where *x* is the sequence | + | | number of the certificate. | + | | | + | | If the ``-s`` option is used with ``-h``, two | + | | separate parts are printed for each record: the | + | | plain hex/ASCII output, and the parsed SSL | + | | output. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-x`` | Turn on hex/ASCII printing of undecoded data | + | | inside parsed SSL records. Used only with the | + | | ``-s`` option. This option uses the same output | + | | format as the ``-h`` option. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-l`` | Turn on looping; that is, continue to accept | + | | connections rather than stopping after the | + | | first connection is complete. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-p``\ *port* | Change the default rendezvous port (1924) to | + | | another port. The following are well-known port | + | | numbers: | + | | | + | | HTTP 80 | + | | | + | | HTTPS 443 | + | | | + | | SMTP 25 | + | | | + | | FTP 21 | + | | | + | | IMAP 143 | + | | | + | | IMAPS 993 (IMAP over SSL) | + | | | + | | NNTP 119 | + | | | + | | NNTPS 563 (NNTP over SSL) | + +-------------------------------------------------+-------------------------------------------------+ + +.. _examples_2: + +` <#examples_2>`__ Examples +--------------------------- + +.. container:: + + You can use the SSL Debugging Tool to intercept any connection information. Although you can run + the tool at its most basic by issuing the ``ssltap`` command with no options other than + *hostname:port*, the information you get in this way is not very useful. For example, assume your + development machine is called ``intercept``. The simplest way to use the debugging tool is to + execute the following command from a command shell: + .. code:: + + ssltap www.netscape.com:80 + + The program waits for an incoming connection on the default port 1924. In your browser window, + enter the URL ``http://intercept:1924``. The browser retrieves the requested page from the server + at ``www.netscape.com``, but the page is intercepted and passed on to the browser by the + debugging tool on ``intercept``. On its way to the browser, the data is printed to the command + shell from which you issued the command. Data sent from the client to the server is surrounded by + the following symbols: ``--> [``\ *data*\ ``]`` Data sent from the server to the client is + surrounded by the following symbols: ``<-- [``\ *data*\ ``]`` The raw data stream is sent to + standard output and is not interpreted in any way. This can result in peculiar effects, such as + sounds, flashes, and even crashes of the command shell window. To output a basic, printable + interpretation of the data, use the ``-h`` option, or, if you are looking at an SSL connection, + the ``-s`` option. You will notice that the page you retrieved looks incomplete in the browser. + This is because, by default, the tool closes down after the first connection is complete, so the + browser is not able to load images. To make the tool continue to accept connections, switch on + looping mode with the ``-l`` option. The following examples show the output from commonly used + combinations of options. + .. rubric:: Example 1 + :name: example_1 + + The ``s`` and ``x`` options in this example turn on SSL parsing and show undecoded values in + hex/ASCII format. The output is routed to a text file. + .. rubric:: Command + :name: command + + .. code:: + + ssltap.exe -sx -p 444 interzone.mcom.com:443 > sx.txt + + .. rubric:: Output + :name: output + + Output + .. code:: + + Connected to interzone.mcom.com:443 + --> [ + alloclen = 66 bytes + [ssl2] ClientHelloV2 { + version = {0x03, 0x00} + cipher-specs-length = 39 (0x27) + sid-length = 0 (0x00) + challenge-length = 16 (0x10) + cipher-suites = { + + .. code:: + + (0x010080) SSL2/RSA/RC4-128/MD5 + (0x020080) SSL2/RSA/RC4-40/MD5 + (0x030080) SSL2/RSA/RC2CBC128/MD5 + (0x040080) SSL2/RSA/RC2CBC40/MD5 + (0x060040) SSL2/RSA/DES64CBC/MD5 + (0x0700c0) SSL2/RSA/3DES192EDE-CBC/MD5 + (0x000004) SSL3/RSA/RC4-128/MD5 + (0x00ffe0) SSL3/RSA-FIPS/3DES192EDE-CBC/SHA + (0x00000a) SSL3/RSA/3DES192EDE-CBC/SHA + (0x00ffe1) SSL3/RSA-FIPS/DES64CBC/SHA + (0x000009) SSL3/RSA/DES64CBC/SHA + (0x000003) SSL3/RSA/RC4-40/MD5 + (0x000006) SSL3/RSA/RC2CBC40/MD5 + } + session-id = { } + challenge = { 0xec5d 0x8edb 0x37c9 0xb5c9 0x7b70 0x8fe9 0xd1d3 + + .. code:: + + 0x2592 } + } + ] + <-- [ + SSLRecord { + 0: 16 03 00 03 e5 |..... + type = 22 (handshake) + version = { 3,0 } + length = 997 (0x3e5) + handshake { + 0: 02 00 00 46 |...F + type = 2 (server_hello) + length = 70 (0x000046) + ServerHello { + server_version = {3, 0} + random = {...} + 0: 77 8c 6e 26 6c 0c ec c0 d9 58 4f 47 d3 2d 01 45 | + wn&l.ì..XOG.-.E + 10: 5c 17 75 43 a7 4c 88 c7 88 64 3c 50 41 48 4f 7f | + + .. code:: + + \.uC§L.Ç.d<PAHO. + session ID = { + length = 32 + + .. code:: + + contents = {..} + 0: 14 11 07 a8 2a 31 91 29 11 94 40 37 57 10 a7 32 | ...¨*1.)..@7W.§2 + 10: 56 6f 52 62 fe 3d b3 65 b1 e4 13 0f 52 a3 c8 f6 | VoRbþ=³e±...R£È. + } + cipher_suite = (0x0003) SSL3/RSA/RC4-40/MD5 + } + 0: 0b 00 02 c5 |...Å + type = 11 (certificate) + length = 709 (0x0002c5) + CertificateChain { + chainlength = 706 (0x02c2) + Certificate { + size = 703 (0x02bf) + data = { saved in file 'cert.001' } + } + } + 0: 0c 00 00 ca |.... + type = 12 (server_key_exchange) + length = 202 (0x0000ca) + 0: 0e 00 00 00 |.... + type = 14 (server_hello_done) + length = 0 (0x000000) + } + } + ] + --> [ + SSLRecord { + 0: 16 03 00 00 44 |....D + type = 22 (handshake) + version = { 3,0 } + length = 68 (0x44) + handshake { + 0: 10 00 00 40 |...@ + type = 16 (client_key_exchange) + length = 64 (0x000040) + ClientKeyExchange { + message = {...} + } + } + } + ] + --> [ + SSLRecord { + 0: 14 03 00 00 01 |..... + type = 20 (change_cipher_spec) + version = { 3,0 } + length = 1 (0x1) + 0: 01 |. + } + SSLRecord { + 0: 16 03 00 00 38 |....8 + type = 22 (handshake) + version = { 3,0 } + length = 56 (0x38) + < encrypted > + + .. code:: + + } + ] + <-- [ + SSLRecord { + 0: 14 03 00 00 01 |..... + type = 20 (change_cipher_spec) + version = { 3,0 } + length = 1 (0x1) + 0: 01 |. + } + ] + <-- [ + SSLRecord { + 0: 16 03 00 00 38 |....8 + type = 22 (handshake) + version = { 3,0 } + length = 56 (0x38) + < encrypted > + + .. code:: + + } + ] + --> [ + SSLRecord { + 0: 17 03 00 01 1f |..... + type = 23 (application_data) + version = { 3,0 } + length = 287 (0x11f) + < encrypted > + } + ] + <-- [ + SSLRecord { + 0: 17 03 00 00 a0 |.... + type = 23 (application_data) + version = { 3,0 } + length = 160 (0xa0) + < encrypted > + + .. code:: + + } + ] + <-- [ + SSLRecord { + 0: 17 03 00 00 df |....ß + type = 23 (application_data) + version = { 3,0 } + length = 223 (0xdf) + < encrypted > + + .. code:: + + } + SSLRecord { + 0: 15 03 00 00 12 |..... + type = 21 (alert) + version = { 3,0 } + length = 18 (0x12) + < encrypted > + } + ] + Server socket closed. + + .. rubric:: Example 2 + :name: example_2 + + The ``-s`` option turns on SSL parsing. Because the ``-x`` option is not used in this example, + undecoded values are output as raw data. The output is routed to a text file. + .. rubric:: Command + :name: command_2 + + .. code:: + + ssltap.exe -s -p 444 interzone.mcom.com:443 > s.txt + + .. rubric:: Output + :name: output_2 + + .. code:: + + Connected to interzone.mcom.com:443 + --> [ + alloclen = 63 bytes + [ssl2] ClientHelloV2 { + version = {0x03, 0x00} + cipher-specs-length = 36 (0x24) + sid-length = 0 (0x00) + challenge-length = 16 (0x10) + cipher-suites = { + (0x010080) SSL2/RSA/RC4-128/MD5 + (0x020080) SSL2/RSA/RC4-40/MD5 + (0x030080) SSL2/RSA/RC2CBC128/MD5 + (0x060040) SSL2/RSA/DES64CBC/MD5 + (0x0700c0) SSL2/RSA/3DES192EDE-CBC/MD5 + (0x000004) SSL3/RSA/RC4-128/MD5 + (0x00ffe0) SSL3/RSA-FIPS/3DES192EDE-CBC/SHA + (0x00000a) SSL3/RSA/3DES192EDE-CBC/SHA + (0x00ffe1) SSL3/RSA-FIPS/DES64CBC/SHA + (0x000009) SSL3/RSA/DES64CBC/SHA + (0x000003) SSL3/RSA/RC4-40/MD5 + } + session-id = { } + challenge = { 0x713c 0x9338 0x30e1 0xf8d6 0xb934 0x7351 0x200c + 0x3fd0 } + ] + <-- [ + SSLRecord { + type = 22 (handshake) + version = { 3,0 } + length = 997 (0x3e5) + handshake { + type = 2 (server_hello) + length = 70 (0x000046) + ServerHello { + server_version = {3, 0} + random = {...} + session ID = { + length = 32 + contents = {..} + } + cipher_suite = (0x0003) SSL3/RSA/RC4-40/MD5 + } + type = 11 (certificate) + length = 709 (0x0002c5) + CertificateChain { + chainlength = 706 (0x02c2) + Certificate { + size = 703 (0x02bf) + data = { saved in file 'cert.001' } + } + } + type = 12 (server_key_exchange) + length = 202 (0x0000ca) + type = 14 (server_hello_done) + length = 0 (0x000000) + } + } + ] + --> [ + SSLRecord { + type = 22 (handshake) + version = { 3,0 } + length = 68 (0x44) + handshake { + type = 16 (client_key_exchange) + length = 64 (0x000040) + ClientKeyExchange { + message = {...} + } + } + } + ] + --> [ + SSLRecord { + type = 20 (change_cipher_spec) + version = { 3,0 } + length = 1 (0x1) + } + SSLRecord { + type = 22 (handshake) + version = { 3,0 } + length = 56 (0x38) + < encrypted > + } + ] + <-- [ + SSLRecord { + type = 20 (change_cipher_spec) + version = { 3,0 } + length = 1 (0x1) + } + ] + <-- [ + SSLRecord { + type = 22 (handshake) + version = { 3,0 } + length = 56 (0x38) + < encrypted > + } + ] + --> [ + SSLRecord { + type = 23 (application_data) + version = { 3,0 } + length = 287 (0x11f) + < encrypted > + } + ] + [ + SSLRecord { + type = 23 (application_data) + version = { 3,0 } + length = 160 (0xa0) + < encrypted > + } + ] + <-- [ + SSLRecord { + type = 23 (application_data) + version = { 3,0 } + length = 223 (0xdf) + < encrypted > + } + SSLRecord { + type = 21 (alert) + version = { 3,0 } + length = 18 (0x12) + < encrypted > + } + ] + Server socket closed. + + .. rubric:: Example 3 + :name: example_3 + + In this example, the ``-h`` option turns hex/ASCII format. There is no SSL parsing or decoding. + The output is routed to a text file. + .. rubric:: Command + :name: command_3 + + .. code:: + + ssltap.exe -h -p 444 interzone.mcom.com:443 > h.txt + + .. rubric:: Output + :name: output_3 + + .. code:: + + Connected to interzone.mcom.com:443 + --> [ + 0: 80 40 01 03 00 00 27 00 00 00 10 01 00 80 02 00 | .@....'......... + 10: 80 03 00 80 04 00 80 06 00 40 07 00 c0 00 00 04 | .........@...... + 20: 00 ff e0 00 00 0a 00 ff e1 00 00 09 00 00 03 00 | ........á....... + 30: 00 06 9b fe 5b 56 96 49 1f 9f ca dd d5 ba b9 52 | ..þ[V.I.\xd9 ...º¹R + 40: 6f 2d |o- + ] + <-- [ + 0: 16 03 00 03 e5 02 00 00 46 03 00 7f e5 0d 1b 1d | ........F....... + 10: 68 7f 3a 79 60 d5 17 3c 1d 9c 96 b3 88 d2 69 3b | h.:y`..<..³.Òi; + 20: 78 e2 4b 8b a6 52 12 4b 46 e8 c2 20 14 11 89 05 | x.K.¦R.KFè. ... + 30: 4d 52 91 fd 93 e0 51 48 91 90 08 96 c1 b6 76 77 | MR.ý..QH.....¶vw + 40: 2a f4 00 08 a1 06 61 a2 64 1f 2e 9b 00 03 00 0b | *ô..¡.a¢d...... + 50: 00 02 c5 00 02 c2 00 02 bf 30 82 02 bb 30 82 02 | ..Å......0...0.. + 60: 24 a0 03 02 01 02 02 02 01 36 30 0d 06 09 2a 86 | $ .......60...*. + 70: 48 86 f7 0d 01 01 04 05 00 30 77 31 0b 30 09 06 | H.÷......0w1.0.. + 80: 03 55 04 06 13 02 55 53 31 2c 30 2a 06 03 55 04 | .U....US1,0*..U. + 90: 0a 13 23 4e 65 74 73 63 61 70 65 20 43 6f 6d 6d | ..#Netscape Comm + a0: 75 6e 69 63 61 74 69 6f 6e 73 20 43 6f 72 70 6f | unications Corpo + b0: 72 61 74 69 6f 6e 31 11 30 0f 06 03 55 04 0b 13 | ration1.0...U... + c0: 08 48 61 72 64 63 6f 72 65 31 27 30 25 06 03 55 | .Hardcore1'0%..U + d0: 04 03 13 1e 48 61 72 64 63 6f 72 65 20 43 65 72 | ....Hardcore Cer + e0: 74 69 66 69 63 61 74 65 20 53 65 72 76 65 72 20 | tificate Server + f0: 49 49 30 1e 17 0d 39 38 30 35 31 36 30 31 30 33 | II0...9805160103 + + ] + + Server socket closed. + + .. rubric:: Example 4 + :name: example_4 + + In this example, the ``-s`` option turns on SSL parsing, and the ``-h`` options turns on + hex/ASCII format. Both formats are shown for each record. The output is routed to a text file. + .. rubric:: Command + :name: command_4 + + .. code:: + + ssltap.exe -hs -p 444 interzone.mcom.com:443 > hs.txt + + .. rubric:: Output + :name: output_4 + + .. code:: + + Connected to interzone.mcom.com:443 + --> [ + 0: 80 3d 01 03 00 00 24 00 00 00 10 01 00 80 02 00 | .=....$......... + 10: 80 03 00 80 04 00 80 06 00 40 07 00 c0 00 00 04 | .........@...... + 20: 00 ff e0 00 00 0a 00 ff e1 00 00 09 00 00 03 03 | ........á....... + 30: 55 e6 e4 99 79 c7 d7 2c 86 78 96 5d b5 cf e9 |U..yÇ\xb0 ,.x.]µÏé + alloclen = 63 bytes + [ssl2] ClientHelloV2 { + version = {0x03, 0x00} + cipher-specs-length = 36 (0x24) + sid-length = 0 (0x00) + challenge-length = 16 (0x10) + cipher-suites = { + (0x010080) SSL2/RSA/RC4-128/MD5 + (0x020080) SSL2/RSA/RC4-40/MD5 + (0x030080) SSL2/RSA/RC2CBC128/MD5 + (0x040080) SSL2/RSA/RC2CBC40/MD5 + (0x060040) SSL2/RSA/DES64CBC/MD5 + (0x0700c0) SSL2/RSA/3DES192EDE-CBC/MD5 + (0x000004) SSL3/RSA/RC4-128/MD5 + (0x00ffe0) SSL3/RSA-FIPS/3DES192EDE-CBC/SHA + (0x00000a) SSL3/RSA/3DES192EDE-CBC/SHA + (0x00ffe1) SSL3/RSA-FIPS/DES64CBC/SHA + (0x000009) SSL3/RSA/DES64CBC/SHA + (0x000003) SSL3/RSA/RC4-40/MD5 + } + session-id = { } + challenge = { 0x0355 0xe6e4 0x9979 0xc7d7 0x2c86 0x7896 0x5db + + 0xcfe9 } + } + ] + + Server socket closed. + +.. _usage_tips: + +`Usage Tips <#usage_tips>`__ +---------------------------- + +.. container:: + + - When SSL restarts a previous session, it makes use of cached information to do a partial + handshake. If you wish to capture a full SSL handshake, restart the browser to clear the + session id cache. + - If you run the tool on a machine other than the SSL server to which you are trying to connect, + the browser will complain that the host name you are trying to connect to is different from + the certificate. If you are using the default BadCert callback, you can still connect through + a dialog. If you are not using the default BadCert callback, the one you supply must allow for + this possibility. + + -------------- \ No newline at end of file diff --git a/security/nss/doc/rst/legacy/tools/pk12util/index.rst b/security/nss/doc/rst/legacy/tools/pk12util/index.rst new file mode 100644 index 0000000000..b08da3276f --- /dev/null +++ b/security/nss/doc/rst/legacy/tools/pk12util/index.rst @@ -0,0 +1,282 @@ +.. _mozilla_projects_nss_tools_pk12util: + +NSS tools : pk12util +==================== + +.. container:: + + | Name + | pk12util — Export and import keys and certificate to or from a PKCS #12 + | file and the NSS database + | Synopsis + | pk12util [-i p12File [-h tokenname] [-v] [common-options] ] [ -l p12File + | [-h tokenname] [-r] [common-options] ] [ -o p12File -n certname [-c + | keyCipher] [-C certCipher] [-m|--key_len keyLen] [-n|--cert_key_len + | certKeyLen] [common-options] ] [ common-options are: [-d [sql:]directory] + | [-P dbprefix] [-k slotPasswordFile|-K slotPassword] [-w + | p12filePasswordFile|-W p12filePassword] ] + | Description + | The PKCS #12 utility, pk12util, 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. + | Options and Arguments + | Options + | -i p12file + | Import keys and certificates from a PKCS#12 file into a security + | database. + | -l p12file + | List the keys and certificates in PKCS#12 file. + | -o p12file + | Export keys and certificates from the security database to a + | PKCS#12 file. + | Arguments + | -n certname + | Specify the nickname of the cert and private key to export. + | -d [sql:]directory + | Specify the database directory into which to import to or export + | from certificates and keys. + | pk12util 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 sql: + | is not used, then the tool assumes that the given databases are in + | the old format. + | -P prefix + | 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. + | -h tokenname + | Specify the name of the token to import into or export from. + | -v + | Enable debug logging when importing. + | -k slotPasswordFile + | Specify the text file containing the slot's password. + | -K slotPassword + | Specify the slot's password. + | -w p12filePasswordFile + | Specify the text file containing the pkcs #12 file password. + | -W p12filePassword + | Specify the pkcs #12 file password. + | -c keyCipher + | Specify the key encryption algorithm. + | -C certCipher + | Specify the key cert (overall package) encryption algorithm. + | -m \| --key-len keyLength + | Specify the desired length of the symmetric key to be used to + | encrypt the private key. + | -n \| --cert-key-len certKeyLength + | Specify the desired length of the symmetric key to be used to + | encrypt the certificates and other meta-data. + | -r + | 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. + | Return Codes + | o 0 - No error + | o 1 - User Cancelled + | o 2 - Usage error + | o 6 - NLS init error + | o 8 - Certificate DB open error + | o 9 - Key DB open error + | o 10 - File initialization error + | o 11 - Unicode conversion error + | o 12 - Temporary file creation error + | o 13 - PKCS11 get slot error + | o 14 - PKCS12 decoder start error + | o 15 - error read from import file + | o 16 - pkcs12 decode error + | o 17 - pkcs12 decoder verify error + | o 18 - pkcs12 decoder validate bags error + | o 19 - pkcs12 decoder import bags error + | o 20 - key db conversion version 3 to version 2 error + | o 21 - cert db conversion version 7 to version 5 error + | o 22 - cert and key dbs patch error + | o 23 - get default cert db error + | o 24 - find cert by nickname error + | o 25 - create export context error + | o 26 - PKCS12 add password itegrity error + | o 27 - cert and key Safes creation error + | o 28 - PKCS12 add cert and key error + | o 29 - PKCS12 encode error + | Examples + | Importing Keys and Certificates + | The most basic usage of pk12util for importing a certificate or key is the + | PKCS#12 input file (-i) and some way to specify the security database + | being accessed (either -d for a directory or -h for a token). + | pk12util -i p12File [-h tokenname] [-v] [-d [sql:]directory] [-P dbprefix] [-k + slotPasswordFile|-K slotPassword] [-w p12filePasswordFile|-W p12filePassword] + | For example: + | # 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 + | Exporting Keys and Certificates + | Using the pk12util command to export certificates and keys requires both + | the name of the certificate to extract from the database (-n) 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. + | 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] + | For example: + | # pk12util -o certs.p12 -n Server-Cert -d sql:/home/my/sharednssdb + | Enter password for PKCS12 file: + | Re-enter password: + | Listing Keys and Certificates + | 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. + | pk12util -l p12File [-h tokenname] [-r] [-d [sql:]directory] [-P dbprefix] [-k + slotPasswordFile|-K slotPassword] [-w p12filePasswordFile|-W p12filePassword] + | For example, this prints the default ASCII output: + | # pk12util -l certs.p12 + | Enter password for PKCS12 file: + | Key(shrouded): + | Friendly Name: Thawte Freemail Member's 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" + | .... + | Alternatively, the -r 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: + | # pk12util -l test.p12 -r + | Enter password for PKCS12 file: + | Key(shrouded): + | Friendly Name: Thawte Freemail Member's 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's Thawte Consulting (Pty) Ltd. ID + | Password Encryption + | 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 PKCS12 V2 PBE with SHA1 and 3KEY Triple DES-cbc for + | private key encryption. PKCS12 V2 PBE with SHA1 and 40 Bit RC4 is the + | default for the overall package encryption when not in FIPS mode. When in + | FIPS mode, there is no package encryption. + | The private key is always protected with strong encryption by default. + | Several types of ciphers are supported. + | Symmetric CBC ciphers for PKCS#5 V2 + | DES_CBC + | o RC2-CBC + | o RC5-CBCPad + | o DES-EDE3-CBC (the default for key encryption) + | o AES-128-CBC + | o AES-192-CBC + | o AES-256-CBC + | o CAMELLIA-128-CBC + | o CAMELLIA-192-CBC + | o CAMELLIA-256-CBC + | PKCS#12 PBE ciphers + | PKCS #12 PBE with Sha1 and 128 Bit RC4 + | o PKCS #12 PBE with Sha1 and 40 Bit RC4 + | o PKCS #12 PBE with Sha1 and Triple DES CBC + | o PKCS #12 PBE with Sha1 and 128 Bit RC2 CBC + | o PKCS #12 PBE with Sha1 and 40 Bit RC2 CBC + | o PKCS12 V2 PBE with SHA1 and 128 Bit RC4 + | o PKCS12 V2 PBE with SHA1 and 40 Bit RC4 (the default for + | non-FIPS mode) + | o PKCS12 V2 PBE with SHA1 and 3KEY Triple DES-cbc + | o PKCS12 V2 PBE with SHA1 and 2KEY Triple DES-cbc + | o PKCS12 V2 PBE with SHA1 and 128 Bit RC2 CBC + | o PKCS12 V2 PBE with SHA1 and 40 Bit RC2 CBC + | PKCS#5 PBE ciphers + | PKCS #5 Password Based Encryption with MD2 and DES CBC + | o PKCS #5 Password Based Encryption with MD5 and DES CBC + | o PKCS #5 Password Based Encryption with SHA1 and DES CBC + | 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 no security module can perform the + | requested operation. + | NSS Database Types + | NSS originally used BerkeleyDB databases to store security information. + | The last versions of these legacy databases are: + | o cert8.db for certificates + | o key3.db for keys + | o secmod.db for PKCS #11 module information + | 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. + | In 2009, NSS introduced a new set of databases that are SQLite databases + | rather than BerkleyDB. These new databases provide more accessibility and + | performance: + | o cert9.db for certificates + | o key4.db for keys + | o pkcs11.txt, which is listing of all of the PKCS #11 modules contained + | in a new subdirectory in the security databases directory + | Because the SQLite databases are designed to be shared, these are the + | shared database type. The shared database type is preferred; the legacy + | format is included for backward compatibility. + | By default, the tools (certutil, pk12util, modutil) assume that the given + | security databases follow the more common legacy type. Using the SQLite + | databases must be manually specified by using the sql: prefix with the + | given security directory. For example: + | # pk12util -i /tmp/cert-files/users.p12 -d sql:/home/my/sharednssdb + | To set the shared database type as the default type for the tools, set the + | NSS_DEFAULT_DB_TYPE environment variable to sql: + | export NSS_DEFAULT_DB_TYPE="sql" + | This line can be set added to the ~/.bashrc file to make the change + | permanent. + | 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: + | o https://wiki.mozilla.org/NSS_Shared_DB_Howto + | For an engineering draft on the changes in the shared NSS databases, see + | the NSS project wiki: + | o https://wiki.mozilla.org/NSS_Shared_DB + | See Also + | certutil (1) + | modutil (1) + | The NSS wiki has information on the new database design and how to + | configure applications to use it. + | o https://wiki.mozilla.org/NSS_Shared_DB_Howto + | o https://wiki.mozilla.org/NSS_Shared_DB + | Additional Resources + | For information about NSS and other tools related to NSS (like JSS), check + | out the NSS project wiki at + | + [1]\ `http://www.mozilla.org/projects/security/pki/nss/ `__. + The NSS site relates + | directly to NSS code changes and releases. + | Mailing lists: https://lists.mozilla.org/listinfo/dev-tech-crypto + | IRC: Freenode at #dogtag-pki + | Authors + | The NSS tools were written and maintained by developers with Netscape, Red + | Hat, and Sun. + | Authors: Elio Maldonado , Deon Lackey + | . + | Copyright + | (c) 2010, Red Hat, Inc. Licensed under the GNU Public License version 2. + | References + | Visible links + | 1. + `http://www.mozilla.org/projects/security/pki/nss/ `__ \ No newline at end of file diff --git a/security/nss/doc/rst/legacy/tools/signtool/index.rst b/security/nss/doc/rst/legacy/tools/signtool/index.rst new file mode 100644 index 0000000000..5e67407793 --- /dev/null +++ b/security/nss/doc/rst/legacy/tools/signtool/index.rst @@ -0,0 +1,547 @@ +.. _mozilla_projects_nss_tools_signtool: + +NSS tools : signtool +==================== + +.. container:: + + | Name + | signtool — Digitally sign objects and files. + | Synopsis + | signtool [-k keyName] `-h <-h>`__ `-H <-H>`__ `-l <-l>`__ `-L <-L>`__ `-M <-M>`__ + `-v <-v>`__ `-w <-w>`__ + | `-G nickname <-G_nickname>`__ `-s size <--keysize>`__ `-b basename <-b_basename>`__ [[-c + Compression + | Level] ] [[-d cert-dir] ] [[-i installer script] ] [[-m metafile] ] [[-x + | name] ] [[-f filename] ] [[-t|--token tokenname] ] [[-e extension] ] [[-o] + | ] [[-z] ] [[-X] ] [[--outfile] ] [[--verbose value] ] [[--norecurse] ] + | [[--leavearc] ] [[-j directory] ] [[-Z jarfile] ] [[-O] ] [[-p password] ] + | [directory-tree] [archive] + | Description + | The Signing Tool, signtool, creates digital signatures and uses a Java + | Archive (JAR) file to associate the signatures with files in a directory. + | Electronic software distribution over any network involves potential + | security problems. To help address some of these problems, you can + | associate digital signatures with the files in a JAR archive. Digital + | signatures allow SSL-enabled clients to perform two important operations: + | \* Confirm the identity of the individual, company, or other entity whose + | digital signature is associated with the files + | \* Check whether the files have been tampered with since being signed + | If you have a signing certificate, you can use Netscape Signing Tool to + | digitally sign files and package them as a JAR file. An object-signing + | certificate is a special kind of certificate that allows you to associate + | your digital signature with one or more files. + | An individual file can potentially be signed with multiple digital + | signatures. For example, a commercial software developer might sign the + | files that constitute a software product to prove that the files are + | indeed from a particular company. A network administrator manager might + | sign the same files with an additional digital signature based on a + | company-generated certificate to indicate that the product is approved for + | use within the company. + | The significance of a digital signature is comparable to the significance + | of a handwritten signature. Once you have signed a file, it is difficult + | to claim later that you didn't sign it. In some situations, a digital + | signature may be considered as legally binding as a handwritten signature. + | Therefore, you should take great care to ensure that you can stand behind + | any file you sign and distribute. + | For example, if you are a software developer, you should test your code to + | make sure it is virus-free before signing it. Similarly, if you are a + | network administrator, you should make sure, before signing any code, that + | it comes from a reliable source and will run correctly with the software + | installed on the machines to which you are distributing it. + | Before you can use Netscape Signing Tool to sign files, you must have an + | object-signing certificate, which is a special certificate whose + | associated private key is used to create digital signatures. For testing + | purposes only, you can create an object-signing certificate with Netscape + | Signing Tool 1.3. When testing is finished and you are ready to + | disitribute your software, you should obtain an object-signing certificate + | from one of two kinds of sources: + | \* An independent certificate authority (CA) that authenticates your + | identity and charges you a fee. You typically get a certificate from an + | independent CA if you want to sign software that will be distributed over + | the Internet. + | \* CA server software running on your corporate intranet or extranet. + | Netscape Certificate Management System provides a complete management + | solution for creating, deploying, and managing certificates, including CAs + | that issue object-signing certificates. + | You must also have a certificate for the CA that issues your signing + | certificate before you can sign files. If the certificate authority's + | certificate isn't already installed in your copy of Communicator, you + | typically install it by clicking the appropriate link on the certificate + | authority's web site, for example on the page from which you initiated + | enrollment for your signing certificate. This is the case for some test + | certificates, as well as certificates issued by Netscape Certificate + | Management System: you must download the CA certificate in addition to + | obtaining your own signing certificate. CA certificates for several + | certificate authorities are preinstalled in the Communicator certificate + | database. + | When you receive an object-signing certificate for your own use, it is + | automatically installed in your copy of the Communicator client software. + | Communicator supports the public-key cryptography standard known as PKCS + | #12, which governs key portability. You can, for example, move an + | object-signing certificate and its associated private key from one + | computer to another on a credit-card-sized device called a smart card. + | Options + | -b basename + | Specifies the base filename for the .rsa and .sf files in the + | META-INF directory to conform with the JAR format. For example, -b + | signatures causes the files to be named signatures.rsa and + | signatures.sf. The default is signtool. + | -c# + | Specifies the compression level for the -J or -Z option. The + | symbol # represents a number from 0 to 9, where 0 means no + | compression and 9 means maximum compression. The higher the level + | of compression, the smaller the output but the longer the + | operation takes. If the -c# option is not used with either the -J + | or the -Z option, the default compression value used by both the + | -J and -Z options is 6. + | -d certdir + | Specifies your certificate database directory; that is, the + | directory in which you placed your key3.db and cert7.db files. To + | specify the current directory, use "-d." (including the period). + | The Unix version of signtool assumes ~/.netscape unless told + | otherwise. The NT version of signtool always requires the use of + | the -d option to specify where the database files are located. + | -e extension + | Tells signtool to sign only files with the given extension; for + | example, use -e".class" to sign only Java class files. Note that + | with Netscape Signing Tool version 1.1 and later this option can + | appear multiple times on one command line, making it possible to + | specify multiple file types or classes to include. + | -f commandfile + | Specifies a text file containing Netscape Signing Tool options and + | arguments in keyword=value format. All options and arguments can + | be expressed through this file. For more information about the + | syntax used with this file, see "Tips and Techniques". + | -i scriptname + | Specifies the name of an installer script for SmartUpdate. This + | script installs files from the JAR archive in the local system + | after SmartUpdate has validated the digital signature. For more + | details, see the description of -m that follows. The -i option + | provides a straightforward way to provide this information if you + | don't need to specify any metadata other than an installer script. + | -j directory + | Specifies a special JavaScript directory. This option causes the + | specified directory to be signed and tags its entries as inline + | JavaScript. This special type of entry does not have to appear in + | the JAR file itself. Instead, it is located in the HTML page + | containing the inline scripts. When you use signtool -v, these + | entries are displayed with the string NOT PRESENT. + | -k key ... directory + | Specifies the nickname (key) of the certificate you want to sign + | with and signs the files in the specified directory. The directory + | to sign is always specified as the last command-line argument. + | Thus, it is possible to write signtool -k MyCert -d . signdir You + | may have trouble if the nickname contains a single quotation mark. + | To avoid problems, escape the quotation mark using the escape + | conventions for your platform. It's also possible to use the -k + | option without signing any files or specifying a directory. For + | example, you can use it with the -l option to get detailed + | information about a particular signing certificate. + | -G nickname + | Generates a new private-public key pair and corresponding + | object-signing certificate with the given nickname. The newly + | generated keys and certificate are installed into the key and + | certificate databases in the directory specified by the -d option. + | With the NT version of Netscape Signing Tool, you must use the -d + | option with the -G option. With the Unix version of Netscape + | Signing Tool, omitting the -d option causes the tool to install + | the keys and certificate in the Communicator key and certificate + | databases. If you are installing the keys and certificate in the + | Communicator databases, you must exit Communicator before using + | this option; otherwise, you risk corrupting the databases. In all + | cases, the certificate is also output to a file named x509.cacert, + | which has the MIME-type application/x-x509-ca-cert. Unlike + | certificates normally used to sign finished code to be distributed + | over a network, a test certificate created with -G is not signed + | by a recognized certificate authority. Instead, it is self-signed. + | In addition, a single test signing certificate functions as both + | an object-signing certificate and a CA. When you are using it to + | sign objects, it behaves like an object-signing certificate. When + | it is imported into browser software such as Communicator, it + | behaves like an object-signing CA and cannot be used to sign + | objects. The -G option is available in Netscape Signing Tool 1.0 + | and later versions only. By default, it produces only RSA + | certificates with 1024-byte keys in the internal token. However, + | you can use the -s option specify the required key size and the -t + | option to specify the token. For more information about the use of + | the -G option, see "Generating Test Object-Signing + | Certificates""Generating Test Object-Signing Certificates" on page + | 1241. + | -l + | Lists signing certificates, including issuing CAs. If any of your + | certificates are expired or invalid, the list will so specify. + | This option can be used with the -k option to list detailed + | information about a particular signing certificate. The -l option + | is available in Netscape Signing Tool 1.0 and later versions only. + | -J + | Signs a directory of HTML files containing JavaScript and creates + | as many archive files as are specified in the HTML tags. Even if + | signtool creates more than one archive file, you need to supply + | the key database password only once. The -J option is available + | only in Netscape Signing Tool 1.0 and later versions. The -J + | option cannot be used at the same time as the -Z option. If the + | -c# option is not used with the -J option, the default compression + | value is 6. Note that versions 1.1 and later of Netscape Signing + | Tool correctly recognizes the CODEBASE attribute, allows paths to + | be expressed for the CLASS and SRC attributes instead of filenames + | only, processes LINK tags and parses HTML correctly, and offers + | clearer error messages. + | -L + | Lists the certificates in your database. An asterisk appears to + | the left of the nickname for any certificate that can be used to + | sign objects with signtool. + | --leavearc + | Retains the temporary .arc (archive) directories that the -J + | option creates. These directories are automatically erased by + | default. Retaining the temporary directories can be an aid to + | debugging. + | -m metafile + | Specifies the name of a metadata control file. Metadata is signed + | information attached either to the JAR archive itself or to files + | within the archive. This metadata can be any ASCII string, but is + | used mainly for specifying an installer script. The metadata file + | contains one entry per line, each with three fields: field #1: + | file specification, or + if you want to specify global metadata + | (that is, metadata about the JAR archive itself or all entries in + | the archive) field #2: the name of the data you are specifying; + | for example: Install-Script field #3: data corresponding to the + | name in field #2 For example, the -i option uses the equivalent of + | this line: + Install-Script: script.js This example associates a + | MIME type with a file: movie.qt MIME-Type: video/quicktime For + | information about the way installer script information appears in + | the manifest file for a JAR archive, see The JAR Format on + | Netscape DevEdge. + | -M + | Lists the PKCS #11 modules available to signtool, including smart + | cards. The -M option is available in Netscape Signing Tool 1.0 and + | later versions only. For information on using Netscape Signing + | Tool with smart cards, see "Using Netscape Signing Tool with Smart + | Cards". For information on using the -M option to verify + | FIPS-140-1 validated mode, see "Netscape Signing Tool and + | FIPS-140-1". + | --norecurse + | Blocks recursion into subdirectories when signing a directory's + | contents or when parsing HTML. + | -o + | Optimizes the archive for size. Use this only if you are signing + | very large archives containing hundreds of files. This option + | makes the manifest files (required by the JAR format) considerably + | smaller, but they contain slightly less information. + | --outfile outputfile + | Specifies a file to receive redirected output from Netscape + | Signing Tool. + | -p password + | Specifies a password for the private-key database. Note that the + | password entered on the command line is displayed as plain text. + | -s keysize + | Specifies the size of the key for generated certificate. Use the + | -M option to find out what tokens are available. The -s option can + | be used with the -G option only. + | -t token + | Specifies which available token should generate the key and + | receive the certificate. Use the -M option to find out what tokens + | are available. The -t option can be used with the -G option only. + | -v archive + | Displays the contents of an archive and verifies the cryptographic + | integrity of the digital signatures it contains and the files with + | which they are associated. This includes checking that the + | certificate for the issuer of the object-signing certificate is + | listed in the certificate database, that the CA's digital + | signature on the object-signing certificate is valid, that the + | relevant certificates have not expired, and so on. + | --verbosity value + | Sets the quantity of information Netscape Signing Tool generates + | in operation. A value of 0 (zero) is the default and gives full + | information. A value of -1 suppresses most messages, but not error + | messages. + | -w archive + | Displays the names of signers of any files in the archive. + | -x directory + | Excludes the specified directory from signing. Note that with + | Netscape Signing Tool version 1.1 and later this option can appear + | multiple times on one command line, making it possible to specify + | several particular directories to exclude. + | -z + | Tells signtool not to store the signing time in the digital + | signature. This option is useful if you want the expiration date + | of the signature checked against the current date and time rather + | than the time the files were signed. + | -Z jarfile + | Creates a JAR file with the specified name. You must specify this + | option if you want signtool to create the JAR file; it does not do + | so automatically. If you don't specify -Z, you must use an + | external ZIP tool to create the JAR file. The -Z option cannot be + | used at the same time as the -J option. If the -c# option is not + | used with the -Z option, the default compression value is 6. + | The Command File Format + | Entries in a Netscape Signing Tool command file have this general format: + | keyword=value Everything before the = sign on a single line is a keyword, + | and everything from the = sign to the end of line is a value. The value + | may include = signs; only the first = sign on a line is interpreted. Blank + | lines are ignored, but white space on a line with keywords and values is + | assumed to be part of the keyword (if it comes before the equal sign) or + | part of the value (if it comes after the first equal sign). Keywords are + | case insensitive, values are generally case sensitive. Since the = sign + | and newline delimit the value, it should not be quoted. + | Subsection + | basename + | Same as -b option. + | compression + | Same as -c option. + | certdir + | Same as -d option. + | extension + | Same as -e option. + | generate + | Same as -G option. + | installscript + | Same as -i option. + | javascriptdir + | Same as -j option. + | htmldir + | Same as -J option. + | certname + | Nickname of certificate, as with -k and -l -k options. + | signdir + | The directory to be signed, as with -k option. + | list + | Same as -l option. Value is ignored, but = sign must be present. + | listall + | Same as -L option. Value is ignored, but = sign must be present. + | metafile + | Same as -m option. + | modules + | Same as -M option. Value is ignored, but = sign must be present. + | optimize + | Same as -o option. Value is ignored, but = sign must be present. + | password + | Same as -p option. + | keysize + | Same as -s option. + | token + | Same as -t option. + | verify + | Same as -v option. + | who + | Same as -w option. + | exclude + | Same as -x option. + | notime + | Same as -z option. value is ignored, but = sign must be present. + | jarfile + | Same as -Z option. + | outfile + | Name of a file to which output and error messages will be + | redirected. This option has no command-line equivalent. + | Extended Examples + | The following example will do this and that + | Listing Available Signing Certificates + | You use the -L option to list the nicknames for all available certificates + | and check which ones are signing certificates. + | signtool -L + | using certificate directory: /u/jsmith/.netscape + | S Certificates + | - ------------ + | BBN Certificate Services CA Root 1 + | IBM World Registry CA + | VeriSign Class 1 CA - Individual Subscriber - VeriSign, Inc. + | GTE CyberTrust Root CA + | Uptime Group Plc. Class 4 CA + | \* Verisign Object Signing Cert + | Integrion CA + | GTE CyberTrust Secure Server CA + | AT&T Directory Services + | \* test object signing cert + | Uptime Group Plc. Class 1 CA + | VeriSign Class 1 Primary CA + | - ------------ + | Certificates that can be used to sign objects have \*'s to their left. + | Two signing certificates are displayed: Verisign Object Signing Cert and + | test object signing cert. + | You use the -l option to get a list of signing certificates only, + | including the signing CA for each. + | signtool -l + | using certificate directory: /u/jsmith/.netscape + | Object signing certificates + | --------------------------------------- + | Verisign Object Signing Cert + | Issued by: VeriSign, Inc. - Verisign, Inc. + | Expires: Tue May 19, 1998 + | test object signing cert + | Issued by: test object signing cert (Signtool 1.0 Testing + | Certificate (960187691)) + | Expires: Sun May 17, 1998 + | --------------------------------------- + | For a list including CAs, use the -L option. + | Signing a File + | 1. Create an empty directory. + | mkdir signdir + | 2. Put some file into it. + | echo boo > signdir/test.f + | 3. Specify the name of your object-signing certificate and sign the + | directory. + | signtool -k MySignCert -Z testjar.jar signdir + | using key "MySignCert" + | using certificate directory: /u/jsmith/.netscape + | Generating signdir/META-INF/manifest.mf file.. + | --> test.f + | adding signdir/test.f to testjar.jar + | Generating signtool.sf file.. + | Enter Password or Pin for "Communicator Certificate DB": + | adding signdir/META-INF/manifest.mf to testjar.jar + | adding signdir/META-INF/signtool.sf to testjar.jar + | adding signdir/META-INF/signtool.rsa to testjar.jar + | tree "signdir" signed successfully + | 4. Test the archive you just created. + | signtool -v testjar.jar + | using certificate directory: /u/jsmith/.netscape + | archive "testjar.jar" has passed crypto verification. + | status path + | ------------ ------------------- + | verified test.f + | Using Netscape Signing Tool with a ZIP Utility + | To use Netscape Signing Tool with a ZIP utility, you must have the utility + | in your path environment variable. You should use the zip.exe utility + | rather than pkzip.exe, which cannot handle long filenames. You can use a + | ZIP utility instead of the -Z option to package a signed archive into a + | JAR file after you have signed it: + | cd signdir + | zip -r ../myjar.jar \* + | adding: META-INF/ (stored 0%) + | adding: META-INF/manifest.mf (deflated 15%) + | adding: META-INF/signtool.sf (deflated 28%) + | adding: META-INF/signtool.rsa (stored 0%) + | adding: text.txt (stored 0%) + | Generating the Keys and Certificate + | The signtool option -G generates a new public-private key pair and + | certificate. It takes the nickname of the new certificate as an argument. + | The newly generated keys and certificate are installed into the key and + | certificate databases in the directory specified by the -d option. With + | the NT version of Netscape Signing Tool, you must use the -d option with + | the -G option. With the Unix version of Netscape Signing Tool, omitting + | the -d option causes the tool to install the keys and certificate in the + | Communicator key and certificate databases. In all cases, the certificate + | is also output to a file named x509.cacert, which has the MIME-type + | application/x-x509-ca-cert. + | Certificates contain standard information about the entity they identify, + | such as the common name and organization name. Netscape Signing Tool + | prompts you for this information when you run the command with the -G + | option. However, all of the requested fields are optional for test + | certificates. If you do not enter a common name, the tool provides a + | default name. In the following example, the user input is in boldface: + | signtool -G MyTestCert + | using certificate directory: /u/someuser/.netscape + | Enter certificate information. All fields are optional. Acceptable + | characters are numbers, letters, spaces, and apostrophes. + | certificate common name: Test Object Signing Certificate + | organization: Netscape Communications Corp. + | organization unit: Server Products Division + | state or province: California + | country (must be exactly 2 characters): US + | username: someuser + | email address: someuser@netscape.com + | Enter Password or Pin for "Communicator Certificate DB": [Password will not echo] + | generated public/private key pair + | certificate request generated + | certificate has been signed + | certificate "MyTestCert" added to database + | Exported certificate to x509.raw and x509.cacert. + | The certificate information is read from standard input. Therefore, the + | information can be read from a file using the redirection operator (<) in + | some operating systems. To create a file for this purpose, enter each of + | the seven input fields, in order, on a separate line. Make sure there is a + | newline character at the end of the last line. Then run signtool with + | standard input redirected from your file as follows: + | signtool -G MyTestCert inputfile + | The prompts show up on the screen, but the responses will be automatically + | read from the file. The password will still be read from the console + | unless you use the -p option to give the password on the command line. + | Using the -M Option to List Smart Cards + | You can use the -M option to list the PKCS #11 modules, including smart + | cards, that are available to signtool: + | signtool -d "c:\netscape\users\jsmith" -M + | using certificate directory: c:\netscape\users\username + | Listing of PKCS11 modules + | ----------------------------------------------- + | 1. Netscape Internal PKCS #11 Module + | (this module is internally loaded) + | slots: 2 slots attached + | status: loaded + | slot: Communicator Internal Cryptographic Services Version 4.0 + | token: Communicator Generic Crypto Svcs + | slot: Communicator User Private Key and Certificate Services + | token: Communicator Certificate DB + | 2. CryptOS + | (this is an external module) + | DLL name: core32 + | slots: 1 slots attached + | status: loaded + | slot: Litronic 210 + | token: + | ----------------------------------------------- + | Using Netscape Signing Tool and a Smart Card to Sign Files + | The signtool command normally takes an argument of the -k option to + | specify a signing certificate. To sign with a smart card, you supply only + | the fully qualified name of the certificate. + | To see fully qualified certificate names when you run Communicator, click + | the Security button in Navigator, then click Yours under Certificates in + | the left frame. Fully qualified names are of the format smart + | card:certificate, for example "MyCard:My Signing Cert". You use this name + | with the -k argument as follows: + | signtool -k "MyCard:My Signing Cert" directory + | Verifying FIPS Mode + | Use the -M option to verify that you are using the FIPS-140-1 module. + | signtool -d "c:\netscape\users\jsmith" -M + | using certificate directory: c:\netscape\users\jsmith + | Listing of PKCS11 modules + | ----------------------------------------------- + | 1. Netscape Internal PKCS #11 Module + | (this module is internally loaded) + | slots: 2 slots attached + | status: loaded + | slot: Communicator Internal Cryptographic Services Version 4.0 + | token: Communicator Generic Crypto Svcs + | slot: Communicator User Private Key and Certificate Services + | token: Communicator Certificate DB + | ----------------------------------------------- + | This Unix example shows that Netscape Signing Tool is using a FIPS-140-1 + | module: + | signtool -d "c:\netscape\users\jsmith" -M + | using certificate directory: c:\netscape\users\jsmith + | Enter Password or Pin for "Communicator Certificate DB": [password will not echo] + | Listing of PKCS11 modules + | ----------------------------------------------- + | 1. Netscape Internal FIPS PKCS #11 Module + | (this module is internally loaded) + | slots: 1 slots attached + | status: loaded + | slot: Netscape Internal FIPS-140-1 Cryptographic Services + | token: Communicator Certificate DB + | ----------------------------------------------- + | See Also + | signver (1) + | The NSS wiki has information on the new database design and how to + | configure applications to use it. + | o https://wiki.mozilla.org/NSS_Shared_DB_Howto + | o https://wiki.mozilla.org/NSS_Shared_DB + | Additional Resources + | For information about NSS and other tools related to NSS (like JSS), check + | out the NSS project wiki at + | + [1]\ `http://www.mozilla.org/projects/security/pki/nss/ `__. + The NSS site relates + | directly to NSS code changes and releases. + | Mailing lists: https://lists.mozilla.org/listinfo/dev-tech-crypto + | IRC: Freenode at #dogtag-pki + | Authors + | The NSS tools were written and maintained by developers with Netscape, Red + | Hat, and Sun. + | Authors: Elio Maldonado , Deon Lackey + | . + | Copyright + | (c) 2010, Red Hat, Inc. Licensed under the GNU Public License version 2. + | References + | Visible links + | 1. + `http://www.mozilla.org/projects/security/pki/nss/ `__ \ No newline at end of file diff --git a/security/nss/doc/rst/legacy/tools/signver/index.rst b/security/nss/doc/rst/legacy/tools/signver/index.rst new file mode 100644 index 0000000000..18fa331bd7 --- /dev/null +++ b/security/nss/doc/rst/legacy/tools/signver/index.rst @@ -0,0 +1,118 @@ +.. _mozilla_projects_nss_tools_signver: + +NSS tools : signver +=================== + +.. container:: + + | Name + | signver — Verify a detached PKCS#7 signature for a file. + | Synopsis + | signtool -A \| -V -d directory [-a] [-i input_file] [-o output_file] [-s + | signature_file] [-v] + | Description + | The Signature Verification Tool, signver, is a simple command-line utility + | that unpacks a base-64-encoded PKCS#7 signed object and verifies the + | digital signature using standard cryptographic techniques. The Signature + | Verification Tool can also display the contents of the signed object. + | Options + | -A + | Displays all of the information in the PKCS#7 signature. + | -V + | Verifies the digital signature. + | -d [sql:]directory + | Specify the database directory which contains the certificates and + | keys. + | signver 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 sql: + | is not used, then the tool assumes that the given databases are in + | the old format. + | -a + | Sets that the given signature file is in ASCII format. + | -i input_file + | Gives the input file for the object with signed data. + | -o output_file + | Gives the output file to which to write the results. + | -s signature_file + | Gives the input file for the digital signature. + | -v + | Enables verbose output. + | Extended Examples + | Verifying a Signature + | The -V option verifies that the signature in a given signature file is + | valid when used to sign the given object (from the input file). + | signver -V -s signature_file -i signed_file -d sql:/home/my/sharednssdb + | signatureValid=yes + | Printing Signature Data + | The -A option prints all of the information contained in a signature file. + | Using the -o option prints the signature file information to the given + | output file rather than stdout. + | signver -A -s signature_file -o output_file + | NSS Database Types + | NSS originally used BerkeleyDB databases to store security information. + | The last versions of these legacy databases are: + | o cert8.db for certificates + | o key3.db for keys + | o secmod.db for PKCS #11 module information + | 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. + | In 2009, NSS introduced a new set of databases that are SQLite databases + | rather than BerkleyDB. These new databases provide more accessibility and + | performance: + | o cert9.db for certificates + | o key4.db for keys + | o pkcs11.txt, which is listing of all of the PKCS #11 modules contained + | in a new subdirectory in the security databases directory + | Because the SQLite databases are designed to be shared, these are the + | shared database type. The shared database type is preferred; the legacy + | format is included for backward compatibility. + | By default, the tools (certutil, pk12util, modutil) assume that the given + | security databases follow the more common legacy type. Using the SQLite + | databases must be manually specified by using the sql: prefix with the + | given security directory. For example: + | # signver -A -s signature -d sql:/home/my/sharednssdb + | To set the shared database type as the default type for the tools, set the + | NSS_DEFAULT_DB_TYPE environment variable to sql: + | export NSS_DEFAULT_DB_TYPE="sql" + | This line can be set added to the ~/.bashrc file to make the change + | permanent. + | 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: + | o https://wiki.mozilla.org/NSS_Shared_DB_Howto + | For an engineering draft on the changes in the shared NSS databases, see + | the NSS project wiki: + | o https://wiki.mozilla.org/NSS_Shared_DB + | See Also + | signtool (1) + | The NSS wiki has information on the new database design and how to + | configure applications to use it. + | o Setting up the shared NSS database + | https://wiki.mozilla.org/NSS_Shared_DB_Howto + | o Engineering and technical information about the shared NSS database + | https://wiki.mozilla.org/NSS_Shared_DB + | Additional Resources + | For information about NSS and other tools related to NSS (like JSS), check + | out the NSS project wiki at + | + [1]\ `http://www.mozilla.org/projects/security/pki/nss/ `__. + The NSS site relates + | directly to NSS code changes and releases. + | Mailing lists: https://lists.mozilla.org/listinfo/dev-tech-crypto + | IRC: Freenode at #dogtag-pki + | Authors + | The NSS tools were written and maintained by developers with Netscape, Red + | Hat, and Sun. + | Authors: Elio Maldonado , Deon Lackey + | . + | Copyright + | (c) 2010, Red Hat, Inc. Licensed under the GNU Public License version 2. + | References + | Visible links + | 1. + `http://www.mozilla.org/projects/security/pki/nss/ `__ \ No newline at end of file diff --git a/security/nss/doc/rst/legacy/tools/ssltap/index.rst b/security/nss/doc/rst/legacy/tools/ssltap/index.rst new file mode 100644 index 0000000000..3c63acc5c2 --- /dev/null +++ b/security/nss/doc/rst/legacy/tools/ssltap/index.rst @@ -0,0 +1,495 @@ +.. _mozilla_projects_nss_tools_ssltap: + +NSS tools : ssltap +================== + +.. container:: + + | Name + | ssltap — Tap into SSL connections and display the data going by + | Synopsis + | libssltap [-vhfsxl] [-p port] [hostname:port] + | Description + | The SSL Debugging Tool ssltap is an SSL-aware command-line proxy. It + | watches TCP connections and displays the data going by. If a connection is + | SSL, the data display includes interpreted SSL records and handshaking + | Options + | -v + | Print a version string for the tool. + | -h + | Turn on hex/ASCII printing. Instead of outputting raw data, the + | command interprets each record as a numbered line of hex values, + | followed by the same data as ASCII characters. The two parts are + | separated by a vertical bar. Nonprinting characters are replaced + | by dots. + | -f + | Turn on fancy printing. Output is printed in colored HTML. Data + | sent from the client to the server is in blue; the server's reply + | is in red. When used with looping mode, the different connections + | are separated with horizontal lines. You can use this option to + | upload the output into a browser. + | -s + | Turn on SSL parsing and decoding. The tool does not automatically + | detect SSL sessions. If you are intercepting an SSL connection, + | use this option so that the tool can detect and decode SSL + | structures. + | If the tool detects a certificate chain, it saves the DER-encoded + | certificates into files in the current directory. The files are + | named cert.0x, where x is the sequence number of the certificate. + | If the -s option is used with -h, two separate parts are printed + | for each record: the plain hex/ASCII output, and the parsed SSL + | output. + | -x + | Turn on hex/ASCII printing of undecoded data inside parsed SSL + | records. Used only with the -s option. This option uses the same + | output format as the -h option. + | -l prefix + | Turn on looping; that is, continue to accept connections rather + | than stopping after the first connection is complete. + | -p port + | Change the default rendezvous port (1924) to another port. + | The following are well-known port numbers: + | \* HTTP 80 + | \* HTTPS 443 + | \* SMTP 25 + | \* FTP 21 + | \* IMAP 143 + | \* IMAPS 993 (IMAP over SSL) + | \* NNTP 119 + | \* NNTPS 563 (NNTP over SSL) + | Usage and Examples + | You can use the SSL Debugging Tool to intercept any connection + | information. Although you can run the tool at its most basic by issuing + | the ssltap command with no options other than hostname:port, the + | information you get in this way is not very useful. For example, assume + | your development machine is called intercept. The simplest way to use the + | debugging tool is to execute the following command from a command shell: + | $ ssltap www.netscape.com + | The program waits for an incoming connection on the default port 1924. In + | your browser window, enter the URL http://intercept:1924. The browser + | retrieves the requested page from the server at www.netscape.com, but the + | page is intercepted and passed on to the browser by the debugging tool on + | intercept. On its way to the browser, the data is printed to the command + | shell from which you issued the command. Data sent from the client to the + | server is surrounded by the following symbols: --> [ data ] Data sent from + | the server to the client is surrounded by the following symbols: "left + | arrow"-- [ data ] The raw data stream is sent to standard output and is + | not interpreted in any way. This can result in peculiar effects, such as + | sounds, flashes, and even crashes of the command shell window. To output a + | basic, printable interpretation of the data, use the -h option, or, if you + | are looking at an SSL connection, the -s option. You will notice that the + | page you retrieved looks incomplete in the browser. This is because, by + | default, the tool closes down after the first connection is complete, so + | the browser is not able to load images. To make the tool continue to + | accept connections, switch on looping mode with the -l option. The + | following examples show the output from commonly used combinations of + | options. + | Example 1 + | $ ssltap.exe -sx -p 444 interzone.mcom.com:443 > sx.txt + | Output + | Connected to interzone.mcom.com:443 + | -->; [ + | alloclen = 66 bytes + | [ssl2] ClientHelloV2 { + | version = {0x03, 0x00} + | cipher-specs-length = 39 (0x27) + | sid-length = 0 (0x00) + | challenge-length = 16 (0x10) + | cipher-suites = { + | (0x010080) SSL2/RSA/RC4-128/MD5 + | (0x020080) SSL2/RSA/RC4-40/MD5 + | (0x030080) SSL2/RSA/RC2CBC128/MD5 + | (0x040080) SSL2/RSA/RC2CBC40/MD5 + | (0x060040) SSL2/RSA/DES64CBC/MD5 + | (0x0700c0) SSL2/RSA/3DES192EDE-CBC/MD5 + | (0x000004) SSL3/RSA/RC4-128/MD5 + | (0x00ffe0) SSL3/RSA-FIPS/3DES192EDE-CBC/SHA + | (0x00000a) SSL3/RSA/3DES192EDE-CBC/SHA + | (0x00ffe1) SSL3/RSA-FIPS/DES64CBC/SHA + | (0x000009) SSL3/RSA/DES64CBC/SHA + | (0x000003) SSL3/RSA/RC4-40/MD5 + | (0x000006) SSL3/RSA/RC2CBC40/MD5 + | } + | session-id = { } + | challenge = { 0xec5d 0x8edb 0x37c9 0xb5c9 0x7b70 0x8fe9 0xd1d3 + | 0x2592 } + | } + | ] + | <-- [ + | SSLRecord { + | 0: 16 03 00 03 e5 \|..... + | type = 22 (handshake) + | version = { 3,0 } + | length = 997 (0x3e5) + | handshake { + | 0: 02 00 00 46 \|...F + | type = 2 (server_hello) + | length = 70 (0x000046) + | ServerHello { + | server_version = {3, 0} + | random = {...} + | 0: 77 8c 6e 26 6c 0c ec c0 d9 58 4f 47 d3 2d 01 45 \| + | wn&l.ì..XOG.-.E + | 10: 5c 17 75 43 a7 4c 88 c7 88 64 3c 50 41 48 4f 7f \| + | \.uC§L.Ç.d [ + | SSLRecord { + | 0: 16 03 00 00 44 \|....D + | type = 22 (handshake) + | version = { 3,0 } + | length = 68 (0x44) + | handshake { + | 0: 10 00 00 40 \|...@ + | type = 16 (client_key_exchange) + | length = 64 (0x000040) + | ClientKeyExchange { + | message = {...} + | } + | } + | } + | ] + | --> [ + | SSLRecord { + | 0: 14 03 00 00 01 \|..... + | type = 20 (change_cipher_spec) + | version = { 3,0 } + | length = 1 (0x1) + | 0: 01 \|. + | } + | SSLRecord { + | 0: 16 03 00 00 38 \|....8 + | type = 22 (handshake) + | version = { 3,0 } + | length = 56 (0x38) + | < encrypted > + | } + | ] + | <-- [ + | SSLRecord { + | 0: 14 03 00 00 01 \|..... + | type = 20 (change_cipher_spec) + | version = { 3,0 } + | length = 1 (0x1) + | 0: 01 \|. + | } + | ] + | <-- [ + | SSLRecord { + | 0: 16 03 00 00 38 \|....8 + | type = 22 (handshake) + | version = { 3,0 } + | length = 56 (0x38) + | < encrypted > + | } + | ] + | --> [ + | SSLRecord { + | 0: 17 03 00 01 1f \|..... + | type = 23 (application_data) + | version = { 3,0 } + | length = 287 (0x11f) + | < encrypted > + | } + | ] + | <-- [ + | SSLRecord { + | 0: 17 03 00 00 a0 \|.... + | type = 23 (application_data) + | version = { 3,0 } + | length = 160 (0xa0) + | < encrypted > + | } + | ] + | <-- [ + | SSLRecord { + | 0: 17 03 00 00 df \|....ß + | type = 23 (application_data) + | version = { 3,0 } + | length = 223 (0xdf) + | < encrypted > + | } + | SSLRecord { + | 0: 15 03 00 00 12 \|..... + | type = 21 (alert) + | version = { 3,0 } + | length = 18 (0x12) + | < encrypted > + | } + | ] + | Server socket closed. + | Example 2 + | The -s option turns on SSL parsing. Because the -x option is not used in + | this example, undecoded values are output as raw data. The output is + | routed to a text file. + | $ ssltap -s -p 444 interzone.mcom.com:443 > s.txt + | Output + | Connected to interzone.mcom.com:443 + | --> [ + | alloclen = 63 bytes + | [ssl2] ClientHelloV2 { + | version = {0x03, 0x00} + | cipher-specs-length = 36 (0x24) + | sid-length = 0 (0x00) + | challenge-length = 16 (0x10) + | cipher-suites = { + | (0x010080) SSL2/RSA/RC4-128/MD5 + | (0x020080) SSL2/RSA/RC4-40/MD5 + | (0x030080) SSL2/RSA/RC2CBC128/MD5 + | (0x060040) SSL2/RSA/DES64CBC/MD5 + | (0x0700c0) SSL2/RSA/3DES192EDE-CBC/MD5 + | (0x000004) SSL3/RSA/RC4-128/MD5 + | (0x00ffe0) SSL3/RSA-FIPS/3DES192EDE-CBC/SHA + | (0x00000a) SSL3/RSA/3DES192EDE-CBC/SHA + | (0x00ffe1) SSL3/RSA-FIPS/DES64CBC/SHA + | (0x000009) SSL3/RSA/DES64CBC/SHA + | (0x000003) SSL3/RSA/RC4-40/MD5 + | } + | session-id = { } + | challenge = { 0x713c 0x9338 0x30e1 0xf8d6 0xb934 0x7351 0x200c + | 0x3fd0 } + | ] + | >-- [ + | SSLRecord { + | type = 22 (handshake) + | version = { 3,0 } + | length = 997 (0x3e5) + | handshake { + | type = 2 (server_hello) + | length = 70 (0x000046) + | ServerHello { + | server_version = {3, 0} + | random = {...} + | session ID = { + | length = 32 + | contents = {..} + | } + | cipher_suite = (0x0003) SSL3/RSA/RC4-40/MD5 + | } + | type = 11 (certificate) + | length = 709 (0x0002c5) + | CertificateChain { + | chainlength = 706 (0x02c2) + | Certificate { + | size = 703 (0x02bf) + | data = { saved in file 'cert.001' } + | } + | } + | type = 12 (server_key_exchange) + | length = 202 (0x0000ca) + | type = 14 (server_hello_done) + | length = 0 (0x000000) + | } + | } + | ] + | --> [ + | SSLRecord { + | type = 22 (handshake) + | version = { 3,0 } + | length = 68 (0x44) + | handshake { + | type = 16 (client_key_exchange) + | length = 64 (0x000040) + | ClientKeyExchange { + | message = {...} + | } + | } + | } + | ] + | --> [ + | SSLRecord { + | type = 20 (change_cipher_spec) + | version = { 3,0 } + | length = 1 (0x1) + | } + | SSLRecord { + | type = 22 (handshake) + | version = { 3,0 } + | length = 56 (0x38) + | > encrypted > + | } + | ] + | >-- [ + | SSLRecord { + | type = 20 (change_cipher_spec) + | version = { 3,0 } + | length = 1 (0x1) + | } + | ] + | >-- [ + | SSLRecord { + | type = 22 (handshake) + | version = { 3,0 } + | length = 56 (0x38) + | > encrypted > + | } + | ] + | --> [ + | SSLRecord { + | type = 23 (application_data) + | version = { 3,0 } + | length = 287 (0x11f) + | > encrypted > + | } + | ] + | [ + | SSLRecord { + | type = 23 (application_data) + | version = { 3,0 } + | length = 160 (0xa0) + | > encrypted > + | } + | ] + | >-- [ + | SSLRecord { + | type = 23 (application_data) + | version = { 3,0 } + | length = 223 (0xdf) + | > encrypted > + | } + | SSLRecord { + | type = 21 (alert) + | version = { 3,0 } + | length = 18 (0x12) + | > encrypted > + | } + | ] + | Server socket closed. + | Example 3 + | In this example, the -h option turns hex/ASCII format. There is no SSL + | parsing or decoding. The output is routed to a text file. + | $ ssltap -h -p 444 interzone.mcom.com:443 > h.txt + | Output + | Connected to interzone.mcom.com:443 + | --> [ + | 0: 80 40 01 03 00 00 27 00 00 00 10 01 00 80 02 00 \| .@....'......... + | 10: 80 03 00 80 04 00 80 06 00 40 07 00 c0 00 00 04 \| .........@...... + | 20: 00 ff e0 00 00 0a 00 ff e1 00 00 09 00 00 03 00 \| ........á....... + | 30: 00 06 9b fe 5b 56 96 49 1f 9f ca dd d5 ba b9 52 \| ..þ[V.I.\xd9 ...º¹R + | 40: 6f 2d \|o- + | ] + | <-- [ + | 0: 16 03 00 03 e5 02 00 00 46 03 00 7f e5 0d 1b 1d \| ........F....... + | 10: 68 7f 3a 79 60 d5 17 3c 1d 9c 96 b3 88 d2 69 3b \| h.:y`..<..³.Òi; + | 20: 78 e2 4b 8b a6 52 12 4b 46 e8 c2 20 14 11 89 05 \| x.K.¦R.KFè. ... + | 30: 4d 52 91 fd 93 e0 51 48 91 90 08 96 c1 b6 76 77 \| MR.ý..QH.....¶vw + | 40: 2a f4 00 08 a1 06 61 a2 64 1f 2e 9b 00 03 00 0b \| \*ô..¡.a¢d...... + | 50: 00 02 c5 00 02 c2 00 02 bf 30 82 02 bb 30 82 02 \| ..Å......0...0.. + | 60: 24 a0 03 02 01 02 02 02 01 36 30 0d 06 09 2a 86 \| $ .......60...*. + | 70: 48 86 f7 0d 01 01 04 05 00 30 77 31 0b 30 09 06 \| H.÷......0w1.0.. + | 80: 03 55 04 06 13 02 55 53 31 2c 30 2a 06 03 55 04 \| .U....US1,0*..U. + | 90: 0a 13 23 4e 65 74 73 63 61 70 65 20 43 6f 6d 6d \| ..#Netscape Comm + | a0: 75 6e 69 63 61 74 69 6f 6e 73 20 43 6f 72 70 6f \| unications Corpo + | b0: 72 61 74 69 6f 6e 31 11 30 0f 06 03 55 04 0b 13 \| ration1.0...U... + | c0: 08 48 61 72 64 63 6f 72 65 31 27 30 25 06 03 55 \| .Hardcore1'0%..U + | d0: 04 03 13 1e 48 61 72 64 63 6f 72 65 20 43 65 72 \| ....Hardcore Cer + | e0: 74 69 66 69 63 61 74 65 20 53 65 72 76 65 72 20 \| tificate Server + | f0: 49 49 30 1e 17 0d 39 38 30 35 31 36 30 31 30 33 \| II0...9805160103 + | + | ] + | + | Server socket closed. + | Example 4 + | In this example, the -s option turns on SSL parsing, and the -h option + | turns on hex/ASCII format. Both formats are shown for each record. The + | output is routed to a text file. + | $ ssltap -hs -p 444 interzone.mcom.com:443 > hs.txt + | Output + | Connected to interzone.mcom.com:443 + | --> [ + | 0: 80 3d 01 03 00 00 24 00 00 00 10 01 00 80 02 00 \| .=....$......... + | 10: 80 03 00 80 04 00 80 06 00 40 07 00 c0 00 00 04 \| .........@...... + | 20: 00 ff e0 00 00 0a 00 ff e1 00 00 09 00 00 03 03 \| ........á....... + | 30: 55 e6 e4 99 79 c7 d7 2c 86 78 96 5d b5 cf e9 \|U..yÇ\xb0 ,.x.]µÏé + | alloclen = 63 bytes + | [ssl2] ClientHelloV2 { + | version = {0x03, 0x00} + | cipher-specs-length = 36 (0x24) + | sid-length = 0 (0x00) + | challenge-length = 16 (0x10) + | cipher-suites = { + | (0x010080) SSL2/RSA/RC4-128/MD5 + | (0x020080) SSL2/RSA/RC4-40/MD5 + | (0x030080) SSL2/RSA/RC2CBC128/MD5 + | (0x040080) SSL2/RSA/RC2CBC40/MD5 + | (0x060040) SSL2/RSA/DES64CBC/MD5 + | (0x0700c0) SSL2/RSA/3DES192EDE-CBC/MD5 + | (0x000004) SSL3/RSA/RC4-128/MD5 + | (0x00ffe0) SSL3/RSA-FIPS/3DES192EDE-CBC/SHA + | (0x00000a) SSL3/RSA/3DES192EDE-CBC/SHA + | (0x00ffe1) SSL3/RSA-FIPS/DES64CBC/SHA + | (0x000009) SSL3/RSA/DES64CBC/SHA + | (0x000003) SSL3/RSA/RC4-40/MD5 + | } + | session-id = { } + | challenge = { 0x0355 0xe6e4 0x9979 0xc7d7 0x2c86 0x7896 0x5db + | 0xcfe9 } + | } + | ] + | + | Server socket closed. + | Usage Tips + | When SSL restarts a previous session, it makes use of cached information + | to do a partial handshake. If you wish to capture a full SSL handshake, + | restart the browser to clear the session id cache. + | If you run the tool on a machine other than the SSL server to which you + | are trying to connect, the browser will complain that the host name you + | are trying to connect to is different from the certificate. If you are + | using the default BadCert callback, you can still connect through a + | dialog. If you are not using the default BadCert callback, the one you + | supply must allow for this possibility. + | See Also + | The NSS Security Tools are also documented at + | + [1]\ `http://www.mozilla.org/projects/security/pki/nss/ `__. + | Additional Resources + | NSS is maintained in conjunction with PKI and security-related projects + | through Mozilla dn Fedora. The most closely-related project is Dogtag PKI, + | with a project wiki at [2]\ http://pki.fedoraproject.org/wiki/. + | For information specifically about NSS, the NSS project wiki is located at + | + [3]\ `http://www.mozilla.org/projects/security/pki/nss/ `__. + The NSS site relates + | directly to NSS code changes and releases. + | Mailing lists: pki-devel@redhat.com and pki-users@redhat.com + | IRC: Freenode at #dogtag-pki + | Authors + | The NSS tools were written and maintained by developers with Netscape and + | now with Red Hat and Sun. + | Authors: Elio Maldonado , Deon Lackey + | . + | Copyright + | (c) 2010, Red Hat, Inc. Licensed under the GNU Public License version 2. + | References + | Visible links + | 1. + `http://www.mozilla.org/projects/secu.../pki/nss/tools `__ + | 2. http://pki.fedoraproject.org/wiki/ + | 3. + `http://www.mozilla.org/projects/security/pki/nss/ `__ \ No newline at end of file diff --git a/security/nss/doc/rst/legacy/tools/vfychain/index.rst b/security/nss/doc/rst/legacy/tools/vfychain/index.rst new file mode 100644 index 0000000000..ffd1cdf86a --- /dev/null +++ b/security/nss/doc/rst/legacy/tools/vfychain/index.rst @@ -0,0 +1,92 @@ +.. _mozilla_projects_nss_tools_vfychain: + +NSS tools : vfychain +==================== + +.. container:: + + | Name + | vfychain — vfychain [options] [revocation options] certfile [[options] + | certfile] ... + | Synopsis + | vfychain + | Description + | The verification Tool, vfychain, verifies certificate chains. modutil can + | add and delete PKCS #11 modules, change passwords on security databases, + | set defaults, list module contents, enable or disable slots, enable or + | disable FIPS 140-2 compliance, and assign default providers for + | cryptographic operations. This tool can also create certificate, key, and + | module security database files. + | The tasks associated with security module database management are part of + | a process that typically also involves managing key databases and + | certificate databases. + | Options + | -a + | the following certfile is base64 encoded + | -b YYMMDDHHMMZ + | Validate date (default: now) + | -d directory + | database directory + | -f + | Enable cert fetching from AIA URL + | -o oid + | Set policy OID for cert validation(Format OID.1.2.3) + | -p + | Use PKIX Library to validate certificate by calling: + | \* CERT_VerifyCertificate if specified once, + | \* CERT_PKIXVerifyCert if specified twice and more. + | -r + | Following certfile is raw binary DER (default) + | -t + | Following cert is explicitly trusted (overrides db trust) + | -u usage + | 0=SSL client, 1=SSL server, 2=SSL StepUp, 3=SSL CA, 4=Email + | signer, 5=Email recipient, 6=Object signer, + | 9=ProtectedObjectSigner, 10=OCSP responder, 11=Any CA + | -v + | Verbose mode. Prints root cert subject(double the argument for + | whole root cert info) + | -w password + | Database password + | -W pwfile + | Password file + | Revocation options for PKIX API (invoked with -pp options) is a + | collection of the following flags: [-g type [-h flags] [-m type + | [-s flags]] ...] ... + | Where: + | -g test-type + | Sets status checking test type. Possible values are "leaf" or + | "chain" + | -g test type + | Sets status checking test type. Possible values are "leaf" or + | "chain". + | -h test flags + | Sets revocation flags for the test type it follows. Possible + | flags: "testLocalInfoFirst" and "requireFreshInfo". + | -m method type + | Sets method type for the test type it follows. Possible types are + | "crl" and "ocsp". + | -s method flags + | Sets revocation flags for the method it follows. Possible types + | are "doNotUse", "forbidFetching", "ignoreDefaultSrc", + | "requireInfo" and "failIfNoInfo". + | Additional Resources + | For information about NSS and other tools related to NSS (like JSS), check + | out the NSS project wiki at + | + [1]\ `http://www.mozilla.org/projects/security/pki/nss/ `__. + The NSS site relates + | directly to NSS code changes and releases. + | Mailing lists: https://lists.mozilla.org/listinfo/dev-tech-crypto + | IRC: Freenode at #dogtag-pki + | Authors + | The NSS tools were written and maintained by developers with Netscape, Red + | Hat, and Sun. + | Authors: Elio Maldonado , Deon Lackey + | . + | Copyright + | (c) 2010, Red Hat, Inc. Licensed under the GNU Public License version 2. + | References + | Visible links + | 1. + `http://www.mozilla.org/projects/security/pki/nss/ `__ \ No newline at end of file diff --git a/security/nss/doc/rst/legacy/tools/vfyserv/index.rst b/security/nss/doc/rst/legacy/tools/vfyserv/index.rst new file mode 100644 index 0000000000..13ad4245fc --- /dev/null +++ b/security/nss/doc/rst/legacy/tools/vfyserv/index.rst @@ -0,0 +1,8 @@ +.. _mozilla_projects_nss_tools_vfyserv: + +NSS tools : vfyserv +=================== + +.. container:: + + Coming soon \ No newline at end of file -- cgit v1.2.3