Working with Digital Signatures and OpenPGP Keys

With Smartcrypt, you can attach a digital signature to files in an archive, or to an archive itself. A digital signature assures people who receive the signed file that it is really from the person who signed it and has not been changed.
Smartcrypt allows you to digitally sign individual files in an archive, the central directory of the archive, or both. The central directory contains a list of files in the archive. Signing the central directory enables a recipient to confirm that the archive as a whole has not changed.
Smartcrypt signing functionality is based on the X.509 (version 3) certificate standard and is compatible with standard authenticity functionality in other applications such as Microsoft's Internet Explorer. These certificates must be in 1024-bit (minimum) RSA format and must contain a private key.
Smartcrypt also supports digital signatures under the OpenPGP (RFC 4880) standard. PKZIP will authenticate signatures in OpenPGP files and validated by PGP keyrings on your system.
To use Smartcrypt to sign files, you must have a digital certificate. Digital certificates are available from various certificate authorities. Visit the PKWARE Web site for information on obtaining a certificate:
http://www.pkware.com
This chapter describes the Smartcrypt tools and commands that work with digital certificates under both X.509 and OpenPGP standards.

Public-Key Infrastructure and Digital Certificates

Smartcrypt uses digital certificates in two important contexts:

  • Confirming and authenticating a person's identity through a digital signature
  • Encrypting and decrypting files through the use of recipient lists

To apply or authenticate digital signatures, or to encrypt or decrypt files for recipients, Smartcrypt needs to access keys in the certificates used. In this section, you'll learn some background and terminology that will help you understand how digital certificates work.

Public-Key Infrastructure (PKI)

Use of digital certificates for encryption and digital signing relies on a combination of supporting elements known as a public-key infrastructure (PKI). These elements include software applications such as Smartcrypt that work with certificates and keys as well as underlying technologies and services.
The heart of PKI is a mechanism by which two cryptographic keys associated with a piece of data called a certificate are used for encryption/decryption and for digital signing and authentication. The keys look like long character strings but represent very large numbers. One of the keys is private and must be kept secure so that only its owner can use it. The other is a public key that may be freely distributed for anyone to use to encrypt data intended for the owner of the certificate or to authenticate signatures.

How the Keys Are Used

With encryption/decryption, a copy of the public key is used to encrypt data such that only the possessor of the private key can decrypt it. Thus anyone with the public key can encrypt for a recipient, and only the targeted recipient has the key with which to decrypt.
With digital signing and authentication, the owner of the certificate uses the private key to sign data, and anyone with access to a copy of the certificate containing the public key can authenticate the signature and be assured that the signed data really proceeds unchanged from the signer.
Authentication has one additional step. As an assurance that the signer is who he says he is—that the certificate with Bob's name on it is not fraudulent—the signer's certificate itself is signed by an issuing certificate authority (CA). The CA in effect vouches that Bob is who he says he is. The CA signature is authenticated using the public key of the CA certificate used. This CA certificate too may be signed, but at some point the trust chain stops with a self-signed root CA certificate that is simply trusted. The PKI provides for these several layers of end-user public key certificates, intermediate CA certificates, and root certificates, as well as for users' private keys.

X.509

X.509 is an International Telecommunication Union (ITU-T) standard for PKI. X.509 specifies, among other things, standard formats for public-key certificates. A public-key certificate consists of the public portion of an asymmetric cryptographic key (the public key), together with identity information, such as a person's name, all signed by a certificate authority. The CA essentially guarantees that the public key belongs to the named entity.

Digital Certificates

A digital certificate is a special message that contains a public key and identity information about the owner, usually including name and perhaps email address. An ordinary, end-user digital certificate is digitally signed by the CA that issued it to warrant that the CA issued the certificate and has received satisfactory documentation that the owner of the certificate is who he says he is. This warrant, from a trusted CA, enables the certificate to be used to support digital signing and authentication, and encryption of data uniquely for the owner of a certificate.
For example, Web servers frequently use digital certificates to authenticate the server to a user and create an encrypted communications session to protect transmitted secret information such as Personal Identification Numbers (PINs) and passphrases.
Similarly, an email message may be digitally signed, enabling the recipient of the message to authenticate its authorship and that it was not altered during transmission.
To use PKI technology in Smartcrypt command line for encryption and to attach digital signatures, you must have a digital certificate.

Certificate Authority (CA)

A certificate authority (CA) is a company (usually) that, for a fee, will issue a public-key certificate. The CA signs the certificate to warrant that the CA issued the certificate and has received satisfactory documentation that the owner of the new certificate is who he says he is.

Private Key

A private key is used to decrypt data encrypted with the associated public key and to attach digital signatures.
A private key must be accessible solely by the owner of the certificate because it represents that person and provides access to encrypted data intended only for the owner.
Smartcrypt may use a private key maintained in X.509 PKCS#12 format. To access such keys, a password must be entered for each Smartcrypt request.

Public Key

A public key consists of the public portion of an asymmetric cryptographic key in a certificate that also contains identity information, such as the certificate owner's name.
The public key is used to authenticate digital signatures created with the private key and to encrypt files for the owner of the key's certificate. You can add key usage flags to the public key to designate it for use in encrypting files, authentication of the key's holder, or both.

Certificate Authority and Root Certificates

End entity certificates and their related keys are used for signing and authentication. They are created at the end of the trust hierarchy of certificate authorities. Each certificate is signed by its CA issuer and is identified in the "Issued By" field in the end certificate. In turn, a CA certificate can also be issued by a higher level CA. Such certificates are known as intermediate CA certificates. At the top of the issuing chain is a self-signed certificate known as the root.
Smartcrypt command line uses public-key certificates in PKCS#7 format. The intermediate CA certificates are maintained independently from the ROOT certificates.

Using X.509 Digital Signatures

This section describes less common tasks relating to signing archives and files inside archives. You will also see special tasks for using and handling certificates in Windows and UNIX systems. See "Attaching Digital Signatures" in Chapter 4 and "Authenticating Digital Signatures" in Chapter 5 for information on these tasks.

Attaching a Signature to an Existing Archive

You can use sign as a command to sign an existing archive's files as well as its central directory.
Examples:
To digitally sign all files and central directory in save.zip using the "My Name" certificate:
pkzipc -certificate="My Name" -sign=all save.zip
To digitally sign *.doc in save.zip using the "My Name" certificate
pkzipc -certificate="My Name" -sign=files save.zip *.doc
To digitally sign the central directory of save.zip using the "My Name" certificate
pkzipc -certificate="My Name" -sign=cd save.zip
Note: If you intend to perform multiple operations on the archive, always put -sign last.

Applying Strict Checking to Certificates

strict
The strict option is for use when doing certificate-based encryption or attaching digital signatures. The option turns on strict checking: in other words, it checks to be sure that certificates are

  • Valid
  • Designated (on the certificate) to be used for the purpose for which they are about to be used in the current command line, namely, encryption or signing

By and large, a certificate is valid if, and only if, it is trusted, not expired, and not revoked. The table below explains the significance of each possibility:

Status

What it Means

Trusted

The certificate can be trusted to indicate who the files really come from

Not Trusted

The certificate cannot be trusted to indicate who the files really come from.
The files may not really be signed by the person that the certificate says signed them.

Expired

The current date does not fall within the date range for which the certificate is valid.
A certificate is valid only for a certain period. If the files were signed or encrypted while the certificate was valid, there is probably no problem. Otherwise, the certificate should be treated as Not Trusted. (A certificate may also show as expired if the date on your computer is incorrect.)

Not Expired

The current date is within the valid range of dates for the certificate

Time nested

The period of validity of the certificate does not extend past the dates when the issuer certificate is valid. For example, if the issuer certificate is valid from February 1, 2005, to January 31, 2008, the date range during which the selected certificate is supposed to be valid does not begin before February 1, 2005, or end after January 31, 2008.

Not time-nested

The period of validity of the certificate extends past the dates when the issuer certificate is valid.
This condition does not necessarily mean that the selected certificate is fraudulent. For example, it may inadvertently have been given too long a period of validity when it was issued. On the other hand, if the issuer certificate was expired when the selected certificate supposedly begins to be valid, the situation may be worth investigating more closely.

Revoked

The certificate has been canceled by either the issuer or the owner.
A certificate might be revoked for a variety of reasons: Perhaps the owner lost the private key or someone else gained access to it; perhaps the issuer determined that the certificate was fraudulently obtained. In general, you should not trust files that were signed with a Revoked certificate.

Not Revoked

The certificate has not been revoked

A field on the certificate shows whether the certificate is designated for use only for a specified purpose. Strict checking excludes certificates that are either not designated for any purpose or are designated for the wrong one. For example, strict checking excludes a certificate from being used for encryption if it is designated for signing.
Note: Strict checking only applies to X.509 certificates.
The usage flags listed in this table can optionally be turned off before a strict check is performed:

Option

Description

KeyUsage

Check the purpose for which the certificate is designated (encryption or signing).

TimeNesting

Check whether the period of validity of the certificate does not extend past the dates when the issuer certificate is valid. For example, if the issuer certificate is valid from February 1, 2005, to January 31, 2008, the date range during which the selected certificate is supposed to be valid does not begin before February 1, 2005, or end after January 31, 2008.

TimeValid

Check whether the current date is within the valid range of dates for the certificate

The following command line applies strict checking to the certificate to be used to encrypt for a recipient:
pkzipc -add -cryptalgorithm -recipient="John Q. Public" -strict test.zip *.doc
If a certificate does not pass strict checking, it is not used, and Smartcrypt displays a warning like the following:

(W76) Warning! John Q. Public does not pass the strict certificate checks, and will not be used.
When a certificate fails strict checking and is not used, other warnings may display as well. For example, if the certificate in the sample command line above fails strict checking, Smartcrypt also displays the following two warnings because a strong encryption method was specified (cryptalgorithm) but no certificate survived strict checking:
(W47) Warning! No recipients specified
(W63) Warning! You must specify -passphrase or -recipient to encrypt files!

Checking for Revoked Certificates

crl
Digital certificates used to apply signatures and to do recipient-based encryption are issued by a certificate authority (CA).
Periodically, CAs publish lists of certificates that have been revoked for one reason or another. For example, an employer might request revocation of a certificate that belongs to an employee who has left the company. Or revocation might be requested for a certificate that has been lost or stolen with its private key.
A CA's list of revoked certificates is called a certificate revocation list (CRL). It consists of a file that contains serial numbers of certificates that have been revoked and the dates. The CRL is signed by the issuing CA.
The crl option tells Smartcrypt to check to see if a certificate that you propose to use for digital signing, encryption, or authentication appears in a CRL accessible to Smartcrypt. If it does, Smartcrypt displays a warning, (W42) Certificate was revoked.
Note: CAs periodically update CRLs. The fact that you can use the crl option and not receive a warning only guarantees that the certificate you accessed is not on a CRL that Smartcrypt checked. The certificate could still have been revoked subsequent to publication of your list.
The following sample command line checks any certificates used for signatures in an archive to be extracted:
pkzipc -extract -crl test.zip
You can configure the crl option so that it is used by default.
The following command line checks the certificate used to encrypt for a recipient:
pkzipc -add -recipient="John Q. Public" -crl test.zip *.doc
The command line below checks the certificate used to apply John Adams' signature to an archive:
pkzipc -add -certificate="John Adams" -crl test.zip
To have Smartcrypt refuse to use a revoked certificate for signing or encrypting, use the strict option. Unless you include the strict option, Smartcrypt merely warns if a certificate is revoked and uses it anyway for signing or encrypting.
The following sample command line checks the certificate used to encrypt for a recipient and uses the strict option to ensure that the certificate is used only if it is not known to be revoked:
pkzipc -add -recipient="John Q. Public" -crl -strict test.zip *.doc

Obtaining a CRL

Certificate authorities commonly make CRLs available for downloading on their Web sites. A CA is apt to provide different CRLs for different series or types of certificates. You must find the CRL for the type of certificate that you want to use it for.
For Smartcrypt to access a CRL, the CRL must be downloaded and imported into a certificate store that Smartcrypt checks for certificates. Such a downloaded and imported CRL is called a static CRL to distinguish it from a dynamic CRL that may be published on the Web. Smartcrypt does not access CRLs published on the Web.
In Windows, you can import a CRL by double-clicking the downloaded file. On UNIX, use the PKCertTool utility to import a CRL. (See "PKCertTool Commands and Options" later in this chapter.)

Making an Online Certificate Status Protocol (OCSP) Request

The Internet Engineering Task Force (IETF) created the Online Certificate Status Protocol (OCSP) as an alternative method for determining whether a certificate is valid. Many Certificate Authorities maintain OCSP responders that allow you to check the validity of a certificate.
To test whether a certificate signing a ZIP archive is valid using OCSP, type:
pkzipc -test -crl=ocsp signed.zip
The OCSP responder will reply to this request with good, revoked or unknown.

Using Digital Certificates on Windows

Microsoft Windows sets up certificate stores on the local system, and you can use the Windows Control Panel to work with certificates, private and public keys.

Exporting Public Keys in Windows

If an archive is signed or contains signed files, certificates that have the public keys needed to authenticate the signatures are included in the archive. You can export these public key certificates to install on your system if you do not already have them. (A method that works on most Windows systems is to right-click the exported certificate file in Windows Explorer and choose Install certificate.) Once the certificate is installed, you can use its key with email that you send or receive from the owner. To export public keys for certificates used to sign files in the current archive:

  1. Choose Export to open a Save As dialog.
  2. Enter a name and location for the file.

Typically, this type of file will have the file name extension.p7c unless you specify a different one.
Note: A .p7c file can contain all the certificates in a certificate chain. Certificates are issued in chains: one certificate may be issued by another certificate further back in the chain. The chain starts with a root certificate issued by a trusted certificate authority.

Backing Up Private Keys in Windows

You can back up a private key to a .pfx file from the Windows Control Panel or Internet Explorer. The following steps describe how to do this in Windows 7 with Internet Explorer version 8. The specific process will differ, depending on your version of Internet Explorer.

  1. Go to Start > Control Panel > Internet Options.
  2. Select the Content page and click Certificates.
  3. Select a certificate and choose the Export button to open the Certificate Export Wizard.
  4. In the Export Wizard screen, click Next.
  5. The Export Private Key screen appears. Select "Yes, export the private key."
  6. In the Certificate Export File Format screen select "Personal Information Exchange." Check the box "Include all certificates in the certificate path if possible" and check the box "Enable strong protection". Click Next.
  7. Type an export password twice. Click Next.
  8. Use the Browse button to identify the directory where the certificate is to be stored. Name the file. Click Next.
  9. Click Finish to complete the Certificate Manager Export Wizard.

Importing an Exported Certificate

To restore a previously exported certificate to your Windows system:

  1. Go to Start > Control Panel > Internet Options.
  2. Select the Content page and click Certificates.
  3. Click Import to open the Certificate Import Wizard.
  4. In the Import Wizard screen, click Next.
  5. In the File to Import box, click Browse and locate the saved Certificate file. Use the dropdown menu on the right to change X.509 Certificate (.cer;.crt) to the .PFX extension, Click the file, click Open, and then click Next.
  6. Type the password in the Password Protection for Private Keys box to access the file, click to select both the Enable strong private key protection and the Mark the private key as exportable boxes, and then click Next.
  7. In the Certificate Store screen, choose whether to Automatically select the Certificate Store based on the type of certificate, or keep all certificates in a specific store (most likely Personal). Click Next.
  8. Click Finish to complete the Certificate Import Wizard.
  9. In the screen that appears, click Set Security Level.
  10. Select High to activate password protection for your certificate. Click Next.
  11. Enter the new password twice and click Finish.

See the second note in "Notes on Using Certificates in Windows" for more information on setting security levels.

Notes on Using Certificates in Windows

  • Smartcrypt does not work directly with Mozilla Network Security Services (NSS) certificate stores. For Smartcrypt to access a certificate that you used the Mozilla Firefox browser to install, you must export the certificate from Firefox and then install it in the Windows certificate stores (usually by double-clicking on the certificate file in Windows Explorer).
  • When you install a certificate on your system, the level of security configured can affect what you may see when compressing files with digital certificates. The level of security— medium or high—determines what type of notification you may see when your private key is accessed by an application. Since Smartcrypt uses your private key to sign a file, you may receive additional prompts or dialogs when signing a file.
  • If you selected low security, Smartcrypt will be allowed to access your private key as needed with no additional prompts or dialogs. If you use medium security (the default), you will receive an additional notification dialog each time you access the private key. If you use high security, you will be prompted to enter the passphrase (the one entered when the certificate was installed on your computer) before the certificate can be used.

Setting Up Stores for Digital Certificates on UNIX/Linux

Unlike Windows, UNIX and Linux do not have a single standard facility for storing digital certificates or a standard way to import certificates and convert them into a form that Smartcrypt can use. To address this, Smartcrypt provides a utility program—PKCertTool—to set up and manage certificate stores on UNIX/Linux for use with Smartcrypt.
Note: To digitally sign files or to enable other people to strongly encrypt files specifically for you as a recipient, you need Smartcrypt and your own personal digital certificate or an organizational certificate such as an SSL certificate. Visit the PKWARE Web site for information on the type of certificate you need (RSA format, 2048-bit minimum) and how to get one.

Setting Up the Certificate Stores

The PKWARE utility PKCertTool sets up the Smartcrypt certificate stores and imports certificates into them, along with any certificate revocation lists you want Smartcrypt to use.
A certificate revocation list (CRL) is a list of certificates that have been revoked by their issuing certificate authority. Before using a certificate, Smartcrypt can check CRLs in its stores to be sure the certificate is not listed as revoked. (See the crl option.) CRLs are published by certificate authorities and can be included in files that contain certificates, though this is rare in practice.
PKCertTool sets up the following certificate stores:

Store

Description

ROOT

A store for certificates used to validate other certificates. These certificates are "trusted" by the users of the system. They are the certificates at the top of a certificate chain and do not derive from any "more trusted" antecedent certificates.

CA

CA stands for Certificate Authority. Certificates in this store are used to validate other certificates. The certificates generally do not belong to particular users and are not used for encryption or authentication. They are intermediate certificates in a certificate chain that derives from some root certificate. They enable a certificate to be traced back to its root.

AddressBook

A store for certificates used to encrypt files for other people. Certificates in this store contain only public keys; they do not contain private keys.

MY

A store for personal certificates with their respective private keys. Private keys are used to sign files and to decrypt files encrypted specifically for the user with the associated public key.
Each user should have his own personal store, accessible only to him, to ensure that only that user can use a certificate's private key to sign or decrypt files.
(Private keys in the MY store are encrypted using PKCS#8 format and PKCS#5 version 2.)

PKCertTool sets up the certificate stores as tables in a SQL database. PKCertTool creates databases and tables as necessary and manages all database interactions. You just need to specify certificates and keys and the stores to put them in. If you add a certificate without specifying a store, PKCertTool determines the appropriate store for you, based on the certificate.
See "Migrating Certificates from a PKZIP 6.x Store," later in this chapter, if you have certificates in a PKZIP version 6 certificate store.
Smartcrypt and PKCertTool can import certificates, CRLs, and keys in the following file formats:

Format

Description

PEM

Contains one or more certificate(s) and/or private key(s). Can also contain a CRL.
Common file extensions: .pem, .cer, .key

PKCS#12

Can contain one or (in theory) more certificates and both their public and private keys. In practice, a PKCS#12 file usually contains only multiple certificates with a single private key.
Common file extensions: .pfx, .p12

PKCS#7

Can contain one or more certificates and their public keys and CRLs; does not contain private keys.
Common file extensions: .p7, .p7b, .p7c

You must use the add command to tell PKCertTool what certificates and keys to import. PKCertTool copies the existing certificates and keys from their specified location and adds them to the appropriate stores. If the stores do not already exist where you tell PKCertTool to look for them, PKCertTool automatically creates the necessary database and/or tables.

Setting Up Stores for One User or Shared Environments

In most cases, you will be running Smartcrypt command line on your system, with all your relevant certificate stores in your $HOME directory. In some situations, you may need to access a certificate store that exists in a shared directory on your system. You can use PKCertTool to set up these stores or recognize them for use with Smartcrypt.
To create a single certificate store in $HOME, run PKCertTool with your end-user account. PKCertTool will create $HOME/certificates.db.
If you have certificates stored in a shared directory, the system administrator should set up environment variables that point the system to the appropriate certificate store(s). The system administrator can also run PKCertTool to create a database containing the ROOT, AddressBook, and CA certificate stores as shared stores, accessible to all users. See the sections, "Shared or Separate AddressBook Stores" and "Setting Environment Variables for Certificate Stores" later in this chapter for more information.
Certificates that include a private key can be safely added to the AddressBook store: Smartcrypt does not add private keys to, or read private keys from, the AddressBook store. Smartcrypt adds private keys only to the MY store.
After the shared stores are created, each user must run PKCertTool to create a database and set up a MY store in the $HOME directory for personal certificates and private keys.
Once certificate stores are set up, PKCertTool needs to be run again only to add new certificates and CRLs. Smartcrypt accesses certificates in the stores as needed.

Shared or Separate AddressBook Stores

You can set up a single, shared AddressBook store for multiple users, or different AddressBook stores for different users.
If certificates containing public keys are placed in a shared AddressBook store, all users can access them. Alternatively, users can use PKCertTool to create their own AddressBook stores in the same (unshared) database with their MY store. Other users cannot access public key certificates in this AddressBook store.
Smartcrypt uses the first store (of the appropriate type) that it finds. If a user points Smartcrypt to an unshared AddressBook store, that is the only AddressBook store that Smartcrypt searches.
A user who wants to add a certificate to a shared AddressBook store for other users to access should ask the administrator of the shared store to add the certificate.

Locating Certificate Store Databases

You can specify your own names for certificate database files, and you can locate the databases anywhere you want. By default, PKCertTool names any certificate database it creates certificates.db.

If you do not tell PKCertTool where to look for a certificate database when you add certificates, PKCertTool will take the following actions, in order: Search locations (if any) specified by the following environment variables:

  • $ROOT_CERTIFICATES for the database containing the ROOT store
  • $CA_CERTIFICATES for the database containing the CA store
  • $ADDRESS_BOOK_CERTIFICATES for the database containing the AddressBook store
  • $MY_CERTIFICATES for the database containing the MY store

See the section "Setting Environment Variables for Certificate Stores," later in this chapter.

  1. Locate $HOME/certificates.db, where $HOME is the user's home directory.
  2. Create $HOME/certificates.db.

PKCertTool Commands and Options

PKCertTool is a separate program from Smartcrypt. It has the following commands for operating on certificates:

CommandDescription
add Add certificates and certificate revocation lists (CRLs) to a store
listList information about certificates and CRLs
delDelete certificates and CRLs
keys List public key hashes for all private keys in a certificate store database
export Export certificates and CRLs
viewDisplay information about the certificates and CRLs in a certificate file.
upgradeUpgrade certificate store database

Each PKCertTool command can be used with one or more options. Most of the options are not required. When entering a PKCertTool command or option, prefix it with a hyphen in the command line as you do with a Smartcrypt command or option.

The PKCertTool add Command

Usage:

pkcerttool -add [-store <store name>] [-database <database file>] [-all] [-f <friendly name>] [-passin <passphrase>] [-passout <passphrase>] <certfile> [<keyfile>]

Command / Option

Description

-add

Tells PKCertTool to add certificates and any CRLs signed by those certificates to a store.
A CRL in a PKCS#7-format file is added automatically if the certificate used to sign it is added unless a newer CRL for that certificate already exists in the store.
CRLs are added to the same store as the accompanying certificates used to sign them.

-store <store name>

The store to which to add certificates. Valid store names are:
MY
AddressBook
ROOT
CA
If no store is specified, PKCertTool picks the most appropriate one based on the certificate. End-entity certificates in PKCS#7 files and in PEM files that do not include private keys are added to the AddressBook store. CA certificates in such files are added to the Root store if they are self-signed or to the CA store if they are not.
NOTE: PKWARE recommends using a PKCS#7 file to add certificates to the AddressBook store.

-database <database>

The location of the database containing the store to use.
If this parameter is omitted, PKCertTool uses the first database (that PKCertTool can write to) found by searching the places listed above in the section "Locating Certificate Store Databases."

-all

Adds all certificates in the file specified in the <certfile> argument. Also adds all CRLs in a PKCS#7 file except that
An older CRL is not added if a newer CRL already exists in the store
A CRL is not added if its signature cannot be validated
If this parameter is omitted, PKCertTool adds only the first certificate found in the file.

<certfile>

The location of a file containing one or more certificates to add.
The location can be either a file that contains certificates or a directory that contains such files.
A certificate file can be in PEM, PKCS#7, or PKCS#12 format. Multiple certificates can be added from a single file.
When the name of a directory, PKCS#7 file, or PEM file is used, PKCertTool adds only the first certificate found if -all is not specified. With certificates in a PKCS#12 file, PKCertTool adds only the end-entity certificate if -all is not specified.

<keyfile>

The path name of a PEM file that contains the private key for a certificate in a PEM format <cert file>.
Use <keyfile> to specify the location of a private key if the <certfile> does not itself contain this key.
<keyfile> cannot be used with -all or with a PKCS#7-format <certfile>: a PKCS#7 file cannot contain a private key.

-f <friendly name>

Sets a friendly name for a certificate—for example, My 2003 Cert. A friendly name can be used to reference a certificate in the <certfile> argument of the PKCertTool -list and -del commands.
A friendly name is useful to distinguish multiple certificates that have the same common name. For example, you might give a different friendly name to a newer, renewed personal certificate to tell it from older, expired certificates that you keep to decrypt files encrypted using those certificates.
The friendly name is added only to the first certificate in a file.
In Smartcrypt, a friendly name that you assign with PKCertTool can be used with the Smartcrypt -recipient and -certificate options.

-passin <passphrase>

The passphrase used to decrypt a private key specified by <keyfile> or used to decrypt a PKCS#12 file specified by <cert file>.
If -passin is not used, PKCertTool prompts for a passphrase needed to decrypt a private key.

-passout <passphrase>

The passphrase to use to encrypt a private key when it is stored in the certificates database.
If -passout is not used, PKCertTool prompts for a passphrase to use to encrypt a private key.

Examples

The following command line adds all certificates and accompanying CRLs to the AddressBook store:
pkcerttool -add -all -store AddressBook mycerts.p7c
The following command line adds the certificate from mycert.pfx to the store. It uses MyPassPhrase to decrypt the PKCS#12 file, and it uses MyStorePassPhrase to encrypt the private key in the store:
pkcerttool -add -passin MyPassPhrase -passout MyStorePassPhrase mycert.pfx

The PKCertTool list Command

Usage:

pkcerttool -list [-store <store name>] [-database <database file>] [-v] [-pemout] [-passin <passphrase>] [-crl] [-thumbprint <thumbprint>] [<certificate name>|<certfile>]

Command / Option

Description

-list

Lists information about the certificates and CRLs in the specified store

-store <store name>

The store for which to list certificates.
Valid store names are:
MY
AddressBook
ROOT
CA
If this argument is omitted, PKCertTool lists certificates in the MY store

-database <database>

The location of the database containing the store to list.
If this parameter is omitted, PKCertTool uses the first database found by searching the places listed above in the section "Locating Certificate Store Databases."

<certificate name>

The common name of a certificate to list. Alternatively, you can use an email address contained in the certificate, or a certificate's friendly name as set with the -f option of the -add command. Any of these can be used instead of <certfile> to reference a certificate.

<certfile>

The location of a file containing one or more certificates. A certificate file can be in PEM, PKCS#7, or PKCS#12 format.
The -list command lists information about the Smartcrypt store copy of the first certificate listed in the file. (Use the PKCertTool -view command to see which certificate is listed first.)

-v

Displays a verbose (more detailed) listing of information about the certificate

-crl

Lists any certificate revocation lists in the store. If used with the -v option, produces a display like this:
— CRL 1 —
<Issuer Certificate Name>
Last Update:
Thu Oct 14 09:42:33 2004
Next Update:
Sat Oct 15 09:42:33 2005
Version: <version number>
Revoked Serial Numbers (<count of serial number>):
<First serial number>
<Second serial number>
------------------
1 CRL
If -crl is used without the -v option, the display omits the CRL version number and the serial numbers of revoked certificates.

-thumbprint <thumbprint>

Identifies a particular certificate by its thumbprint, that is, by the value listed as SHA-1 Hash of Certificate when the certificate is viewed in PKCertTool using the -view or -list command with the -v option. (See example after this table.)
The -thumbprint option is useful to distinguish certificates that have the exact same common name and friendly name in a store. Such identical listings can come about when, for example, root and CA certificates are imported from a Windows system, or when a renewed personal certificate is installed without specifying a unique friendly name.
A thumbprint is not case-sensitive and can be truncated. You need enter only enough of the thumbprint to match the certificate(s) you want.
The -list command lists all certificates matching both a specified thumbprint and specified common or friendly name.
A thumbprint can be entered with or without spaces. Set off the thumbprint with quotes if it contains spaces. For example:
pkcerttool -list -v -thumbprint "25 28 Y0 YY" "John J. Adams"
or:
pkcerttool -list -v -thumbprint 2528Y0YY "John J. Adams"

-passin <passphrase>

The passphrase used to decrypt a PKCS#12 file specified by <certfile>.
If -passin is not used, PKCertTool prompts for a passphrase needed to decrypt a private key.

-pemout

Prints out the certificate(s) in PEM format

Example

The following command line gives a verbose listing of certificates in the MY store:
pkcerttool -list -v

 -----------
MY
-----------
— Certificate 1 —
John J. Adams
Subject:
O=VeriSign, Inc.
OU=VeriSign Trust Network
OU=www.verisign.com/repository/RPA Incorp. by Ref.,LIAB.LTD(c)98
OU=Persona Not Validated
OU=Digital ID Class 1 - Microsoft Full Service
CN=John J. Adams
E=john.adams@acme.com
Issuer:
O=VeriSign, Inc.
OU=VeriSign Trust Network
OU=www.verisign.com/repository/RPA Incorp. By Ref.,LIAB.LTD(c)98
CN=VeriSign Class 1 CA Individual Subscriber-Persona Not Validated
SerialNumber:
1M M0 UJ 41 H3 24 U3 J3 8J 42 YH JJ 77 Y0 65 3H
NotBefore:
Tue Sep 4 19:00:00 2001
NotAfter:
Thu Sep 5 18:59:59 2002
SHA-1 Hash of Certificate:
25 28 Y0 YY 37 YU J9 01 6J YY 9Y 1H 79 0J 97 2Y
1M 73 23 Y2
Public Key Hash:
31 Y2 98 Y3 76 PU U2 J3 HH 25 U6 PY 9Y 6J 03 0U
73 61 1H 8M
— Certificate 2 —
Thawte Freemail Member
Subject:
CN=Thawte Freemail Member
E=todda@acme.com
Issuer:
C=ZA
S=Western Cape
L=Durbanville
O=Thawte
OU=Certificate Services
CN=Personal Freemail RSA 1999.9.16
SerialNumber:
2F 52 03
NotBefore:
Thu Sep 7 12:26:30 2000
NotAfter:
Fri Sep 7 12:26:30 2001
SHA-1 Hash of Certificate:
M3 L6 J5 PM L4 74 M1 15 P6 PL 22 J3 11 94 30 L7
LP 9Y 85 J6
Public Key Hash:
01 6J 30 JJ 8Y 12 P5 18 YJ 9P 7U 8H 52 MP PY 94
P4 81 4H 42
------------------
2 certificates

The following command line gives a verbose listing of the certificates matching both the specified certificate name and thumbprint and in the MY store:
pkcerttool -list -v -thumbprint 2528Y0YY "John J. Adams"


-----------
MY
-----------
— Certificate 1 —
John J. Adams
Subject:
O=VeriSign, Inc.
OU=VeriSign Trust Network
OU=www.verisign.com/repository/RPA Incorp. by Ref.,LIAB.LTD(c)98
OU=Persona Not Validated
OU=Digital ID Class 1 - Microsoft Full Service
CN=John J. Adams
E=john.adams@acme.com
Issuer:
O=VeriSign, Inc.
OU=VeriSign Trust Network
OU=www.verisign.com/repository/RPA Incorp. By Ref.,LIAB.LTD(c)98
CN=VeriSign Class 1 CA Individual Subscriber-Persona Not Validated
SerialNumber:
1M M0 UJ 41 H3 24 U3 J3 8J 42 YH JJ 77 Y0 65 3H
NotBefore:
Tue Sep 4 19:00:00 2001
NotAfter:
Thu Sep 5 18:59:59 2002
SHA-1 Hash of Certificate:
25 28 Y0 YY 37 YU J9 01 6J YY 9Y 1H 79 0J 97 2Y
1M 73 23 Y2
Public Key Hash:
31 Y2 98 Y3 76 PU U2 J3 HH 25 U6 PY 9Y 6J 03 0U
73 61 1H 8M
------------------
1 certificates


The following command line uses the pemout option to print the certificates in the root store in PEM format:
hrvsrv-szgw2# pkcerttool -list -store root -pemout

PKCertTool(tm) Version 1.40
Portions copyright (C) 2001-2008 PKWARE, Inc. All Rights Reserved.
Build Version ($BuildRev: 1025 $)
----------------------------------------------------------------
Certificates in ROOT in the database: /usr/local/certificates.db
----------------------------------------------------------------
----BEGIN CERTIFICATE----
RJJWAWLLAkynAwJBAnJVAOP4uB6+R/698+StFaSh/pSotfTbRA0GLSqGSJb3WQEB
BQUARLJxJWAeBnNVBARTF29tYXNyWJ1AeRW3RJ5wa3WhLRUuY29tRB4XWTA4RTJx
RjJyRjL0RVoXWTA5RTJxRjJyRjL0RVowJjEnRB4GA1UEAxRXb21hL3J2LXN6A3Ly
LnBrW2FyAS5jb20wnnEJRA0GLSqGSJb3WQEBAQUAA4JBWwAwnnEKAoJBAQLkLOOk
49RrSJvRxnkuGPtRj8+WUYAklFbT9A4OTPo8NLaqSWRGQtsUsLGy+SBLuEeqYxoW
Or6TR4n4ThwHrWHnpyN/30Y/+JpJP0GU2roR+qUAnRX6RKJ/4keHP+huLn0PAOo6
LwNUJKuLpwx7nuXW3HljV6lRbnl4nVAWJAYJTRnlqUrrnRql5bAGTxBtHX8R13XY
nR2bbaUytX4aRRLVTXonkpsOXHVFFGuJ0WLnOGLLo1/qxVRqVo5RARRoSJKfoEF+
8QnpGbL0G2WjL+Sq1WyY2onSqnuL+u35JQlJ49Xrw73JAbrAJb8vlHnLTteN4tL+
LejBLfAWKJKLhVtBAnRBAAGjnAAwnY0wHQYWVR0OBBYEFFy5WQbqLwBwULvH5qqP
q8vaQtSURF4GA1UWJwRXRFWAFFy5WQbqLwBwULvH5qqPq8vaQtSUoSakJWAJRSAw
HnYWVQQWExWvbWFALnYtL3pnWAJuLGt3YXJlLRNvbYJVAOP4uB6+R/698+StFaSh
/pSotfTbRAwGA1UWEwEB/wQLRAAwWQYJKoAJhvLNAQEFBQAWnnEBAJQy0JLLWulG
1EARv+YetAQLAB14jR2LJh+rUV/TRL03L5Y8Sunj7Epq19JPn0V4nLRAKASYrFNp
6epA4n+qbtAayap3y8Qf6WT3B+/YnN9rQjRLyvGAwJpXbKbBLRxwNeuBrt7R4fSJ
UK+2jyfnuAAsRB7TWntK6XLoPnHYJ9t9vkru6Wq+0vR1SHQA56Oqj0yAlA+HR1n+
0ErLe+kWGWY9lQER+UnsYtVfanHAyrNXvAE8UoUyo2pJRQLjNAoAHNJHahs7WRNR
y6VJR4eLRkQ4O0eASR8p7J6KpbbpbrKrTJAoRRBNUuQ5AuFleYsAVpU39qRwRwrt
1WNuqLeehQA=
----END CERTIFICATE----

The PKCertTool del Command

Usage:

pkcerttool -del [-store <store name>] [-database <database file>] [-passin <passphrase>] [-crl] [-thumbprint <thumbprint>] <certificate name>|<certfile>

Command / Option

Description

-del

Deletes a specified certificate and any associated CRL from a Smartcrypt store.
If a specified certificate has an associated CRL—that is, has been used to sign a CRL—the CRL is deleted with the certificate. If for some reason the CRL cannot be deleted, the certificate is not deleted either.

-store <store name>

The store from which to delete a certificate.
Valid store names are:
MY
AddressBook
ROOT
CA
If this argument is omitted, PKCertTool looks for the certificate in the MY store. PKCertTool warns if the certificate is not found.

-database <database>

The location of the database containing the store from which to delete a certificate.
If this parameter is omitted, PKCertTool uses the first database found by searching the places listed above in the section "Locating Certificate Store Databases."

-passin <passphrase>

The passphrase used to decrypt a PKCS#12 file specified by <certfile>.
If -passin is not used, PKCertTool prompts for a passphrase needed to decrypt a private key.

-thumbprint <thumbprint>

Identifies a particular certificate by its thumbprint, that is, by the value listed as SHA-1 Hash of Certificate when the certificate is viewed in PKCertTool using the -view or -list command with the -v option. (See example below.)
The -thumbprint option is useful to distinguish certificates that have the exact same common name and friendly name in a store. Such identical listings can come about when, for example, root and CA certificates are imported from a Windows system, or when a renewed personal certificate is installed without specifying a unique friendly name.
A thumbprint is not case-sensitive and can be truncated.
With -del, if a truncated thumbprint matches multiple certificates, the first certificate found is selected.
A thumbprint can be entered with or without spaces. Set off the thumbprint with quotes if it contains spaces. For example:
pkcerttool -del -thumbprint "25 28 Y0 YY" "John J. Adams"
or:
pkcerttool -del -thumbprint 2528Y0YY "John J. Adams"

<certificate name>

The common name of a certificate to delete. Alternatively, you can use an email address contained in the certificate, or a certificate's friendly name as set with the -f option of the -add command. Any of these can be used instead of <certfile> to reference a certificate.

<certfile>

The location of a file containing one or more certificates. A certificate file can be in PEM, PKCS#7, or PKCS#12 format.
The -del command deletes the Smartcrypt store copy of the first certificate listed in the file. (Use the PKCertTool -view command to see which certificate is listed first.) The -del command does not delete certificates from files or delete the files themselves.

-crl

Deletes from the store only a CRL signed by the specified certificate; does not delete the certificate itself.

Example

The following command line deletes the certificate for John J. Adams from the AddressBook store:
pkcerttool -del -store AddressBook "John J. Adams"
The following command line deletes from the AddressBook store a CRL signed by the certificate identified by <issuer name>. Only the CRL is deleted, not the certificate:
pkcerttool -del -store CA <issuer name> -crl

The PKCertTool keys Command

Usage:

pkcerttool -keys [-database <database file>]

Command

Description

-keys

Lists the public key hashes of all private keys in a certificate store database.
This command is for troubleshooting. You can compare its output to the output of -list -v to find the certificates for which you have private keys.

-database <database>

The location of the database.
If this parameter is omitted, PKCertTool uses the first database found by searching the places listed above in the section "Locating Certificate Store Databases."

Example

pkcerttool -keys

 -----------
Private keys in /home/george/certificates.db
-----------
— PrivateKey 1 —
01 6J 30 JJ 8Y 12 P5 18 YJ 9P 7U 8H 52 MP PY 94
P4 81 4H 42
— PrivateKey 2 —
1M M0 UJ 41 H3 24 U3 J3 8J 42 YH JJ 77 Y0 65 3H
2U 8P 20 YY
— PrivateKey 3 —
31 Y2 98 Y3 76 PU U2 J3 HH 25 U6 PY 9Y 6J 03 0U
73 61 1H 8M
------------------
3 private keys

The PKCertTool export Command

Usage:

pkcerttool -export [-store <store name>] [-database <database file>] [-passin <passphrase>] [-passout <passphrase>] [-crl] [-thumbprint <thumbprint>] [-all|<certificate name>] <output file>

Command

Description

-export

Exports certificates and CRLs from a specified store.

-store <store name>

The store from which to export certificates.
Valid store names are:
MY
AddressBook
ROOT
CA
If this argument is omitted, PKCertTool exports certificates from the MY store

-database <database>

The location of the database.
If this parameter is omitted, PKCertTool uses the first database found by searching the places listed above in the section "Locating Certificate Store Databases."

-passin <passphrase>

The passphrase to decrypt a private key in the store so that it can be exported. For use when exporting a certificate with its private key.
Cannot be used with -all.

-passout <passphrase>

The passphrase to use to encrypt a private key in an exported PKCS#12 file. This is the passphrase that a user must supply to access the key in the exported PKCS#12 file.
Cannot be used with -all.

-crl

Includes any CRL issued by the certificate when a single certificate is specified.
Cannot be used with -all.

-thumbprint <thumbprint>

Identifies a particular certificate by its thumbprint, that is, by the value listed as SHA-1 Hash of Certificate when the certificate is viewed in PKCertTool using the -view or -list command with the -v option. (See example below.)
The -thumbprint option is useful to distinguish certificates that have the exact same common name and friendly name in a store. Such identical listings can come about when, for example, root and CA certificates are imported from a Windows system, or when a renewed personal certificate is installed without specifying a unique friendly name.
A thumbprint is not case-sensitive and can be truncated.
With -export, if a truncated thumbprint matches multiple certificates, the first certificate found is selected.
A thumbprint can be entered with or without spaces. Set off the thumbprint with quotes if it contains spaces. For example:
pkcerttool -export -thumbprint "25 28 Y0 YY" "John J. Adams"
or:
pkcerttool -export -thumbprint 2528Y0YY "John J. Adams"

-all

Exports all certificates and CRLs in the store

<certificate name>

The name of the certificate to export, in quotes.
Cannot be used with -all.

<output file>

The name to give the output file. For information on the file format used, see the notes following this table.

Output file format: The format of the output file to which certificates are exported is determined by the following rules:

  • If the -all or -crl option is used, the output file is saved in PKCS#7 format. No associated private key is exported even if one is present.
  • If a single certificate that does not have a private key is specified (and the -crl option is not used), the certificate is saved in DER format.
  • If a single certificate that does have a private key is specified (and the -crl option is not used), then the private key is exported and the output file is saved in PKCS#12 format if you specify a file name that has the extension .p12 or .pfx. or no "dot" extension at all. Otherwise, the private key is not exported, and the output file is saved in DER format.

Examples

The following command line exports all certificates and CRLs in the MY store to a PKCS#7 file; no private keys are exported.
pkcerttool -export -all mycerts.p7
The following command line exports from the CA store the "GTZ Cybertrust" certificate, with any associated CRL from the same store, to a PKCS#7 file; no private key is exported.
pkcerttool -export -store CA "GTZ Cybertrust" -crl cybertrust_ca.p7
The following command line exports from the MY store a personal certificate, with its private key, to a PKCS#12 file.
pkcerttool -export "George Washington" mycert.p12
The following command line exports from the AddressBook store a single certificate that has no private key to a raw CRL-format file.
pkcerttool -export -store addressbook "John Q. Public" johnpublic.crl

The PKCertTool view Command

Usage:

pkcerttool -view [-ca] [-endentity] [-v] [-pemout] [-passin <passphrase>] <certfile>

Command

Description

-view

Displays information about the certificates and CRLs in a certificate file. The information is similar to that produced by the PKCertTool -list command.

-ca

A filter to view only certificate authority (CA) certificates

-endentity

A filter to view only end entity certificates

-v

Displays a verbose (more detailed) listing of information about the certificates

-passin <passphrase>

The passphrase to decrypt a private key in a PKCS#12 certificate file so that it can be viewed

<certfile>

The location of a file containing one or more certificates. The certificate file can be in PEM, PKCS#7, or PKCS#12 format.

-pemout

Prints out the certificate(s) in PEM format

Examples

The following command line displays a verbose listing of information about the certificates and CRLs in a PKCS#7 file:
pkcerttool -view -v mycerts.p7
The following command line displays a verbose listing of information about the certificate in a PKCS#12 file:
pkcerttool -view -v -passin "mypassphrase" my_personal_certs.p12
The following command line prints out certificate hrvsrv-szgw2.pkware.com.cert in PEM format:
hrvsrv-szgw2# pkcerttool -view -endentity -pemout /etc/partnergw/hrvsrv-szgw2.mycompany.com.cert
The output looks like this:

 PKCertTool(tm) Version 1.40
Portions copyright (C) 2001-2008 PKWARE, Inc. All Rights Reserved.
Build Version ($BuildRev: 1025 $)
----BEGIN CERTIFICATE----
RJJWAWLLAkynAwJBAnJVAOP4uB6+R/698+StFaSh/pSotfTbRA0GLSqGSJb3WQEB
BQUARLJxJWAeBnNVBARTF29tYXNyWJ1AeRW3RJ5wa3WhLRUuY29tRB4XWTA4RTJx
RjJyRjL0RVoXWTA5RTJxRjJyRjL0RVowJjEnRB4GA1UEAxRXb21hL3J2LXN6A3Ly
LnBrW2FyAS5jb20wnnEJRA0GLSqGSJb3WQEBAQUAA4JBWwAwnnEKAoJBAQLkLOOk
49RrSJvRxnkuGPtRj8+WUYAklFbT9A4OTPo8NLaqSWRGQtsUsLGy+SBLuEeqYxoW
Or6TR4n4ThwHrWHnpyN/30Y/+JpJP0GU2roR+qUAnRX6RKJ/4keHP+huLn0PAOo6
LwNUJKuLpwx7nuXW3HljV6lRbnl4nVAWJAYJTRnlqUrrnRql5bAGTxBtHX8R13XY
nR2bbaUytX4aRRLVTXonkpsOXHVFFGuJ0WLnOGLLo1/qxVRqVo5RARRoSJKfoEF+
8QnpGbL0G2WjL+Sq1WyY2onSqnuL+u35JQlJ49Xrw73JAbrAJb8vlHnLTteN4tL+
LejBLfAWKJKLhVtBAnRBAAGjnAAwnY0wHQYWVR0OBBYEFFy5WQbqLwBwULvH5qqP
q8vaQtSURF4GA1UWJwRXRFWAFFy5WQbqLwBwULvH5qqPq8vaQtSUoSakJWAJRSAw
HnYWVQQWExWvbWFALnYtL3pnWAJuLGt3YXJlLRNvbYJVAOP4uB6+R/698+StFaSh
/pSotfTbRAwGA1UWEwEB/wQLRAAwWQYJKoAJhvLNAQEFBQAWnnEBAJQy0JLLWulG
1EARv+YetAQLAB14jR2LJh+rUV/TRL03L5Y8Sunj7Epq19JPn0V4nLRAKASYrFNp
6epA4n+qbtAayap3y8Qf6WT3B+/YnN9rQjRLyvGAwJpXbKbBLRxwNeuBrt7R4fSJ
UK+2jyfnuAAsRB7TWntK6XLoPnHYJ9t9vkru6Wq+0vR1SHQA56Oqj0yAlA+HR1n+
0ErLe+kWGWY9lQER+UnsYtVfanHAyrNXvAE8UoUyo2pJRQLjNAoAHNJHahs7WRNR
y6VJR4eLRkQ4O0eASR8p7J6KpbbpbrKrTJAoRRBNUuQ5AuFleYsAVpU39qRwRwrt
1WNuqLeehQA=
----END CERTIFICATE----

The PKCertTool upgrade Command

Usage:

pkcerttool -database <database>

Command

Description

-database <database>

The location of the database.
If this parameter is omitted, PKCertTool uses the first database found by searching the places listed above in the section "Locating Certificate Store Databases."

Example

The following command upgrades your default certificates database file to be in the new format, and save a copy of the original as $HOME/certificates.db.old.

pkcerttool -database

Exit Codes for PKCertTool

PKCertTool generates the exit codes described in the table below.

Code

Meaning

0

Success

1

Unknown option

2

Out of memory

3

Missing option or argument. For example, -f is used but no friendly name is supplied; or -add is used but no cert file is given.

4

Invalid database specification. A database specified (with a command other than -add) does not exist, or a directory is specified in place of a database.

5

Conflicting commands. For example, specifying both -add and -del.

6

Action failed. For example, PKCertTool cannot open a store, or cannot list a specified certificate, or cannot find any certificates to list.

Setting Environment Variables for Certificate Stores

Smartcrypt checks the environment variables listed below for the locations of certificate stores. If these variables are set, Smartcrypt uses the certificate databases specified by the variables instead of looking in the default location.

Environment Variable

Certificate Store

$ROOT_CERTIFICATES

ROOT

$CA_CERTIFICATES

CA

$ADDRESS_BOOK_CERTIFICATES

AddressBook

$MY_CERTIFICATES

MY

You can use PKCertTool to set up certificate databases having custom names and locations if you do not want to use the Smartcrypt defaults (see "Locating Certificate Store Databases," above). You can then set the environment variables to point to the databases you have set up.
Use command lines like the following to set the variables for sh-based shells (sh, ksh, bash, zsh). Replace the database names and paths with your own:
ROOT_CERTIFICATES=/usr/local/certificates/certificates.db
export ROOT_CERTIFICATES
CA_CERTIFICATES=/usr/local/certificates/certificates.db
export CA_CERTIFICATES
ADDRESS_BOOK_CERTIFICATES=/usr/local/certificates/certificates.db
export ADDRESS_BOOK_CERTIFICATES
MY_CERTIFICATES=/home/certificates.db

export MY_CERTIFICATES
With csh or tcsh, use command lines like these:
setenv ROOT_CERTIFICATES /usr/local/certificates/certificates.db
setenv CA_CERTIFICATES /usr/local/certificates/certificates.db
setenv ADDRESS_BOOK_CERTIFICATES /usr/local/certificates/certificates.db
setenv MY_CERTIFICATES /home/certificates.db
Put the commands in users' login files (.profile for sh users, .cshrc for csh users) to set the variables each time users log on.

Migrating Certificates from a PKZIP 6.x Store

PKZIP version 6 used a different arrangement for storing certificates. On this arrangement, certificates were stored in PKCS#7, PKCS#12, and PEM files in directories in the file system, and the environment variables pointed to the directories.
To migrate certificates from a PKZIP version 6 store, follow these steps:

  1. If the environment variables described in the preceding section are set, make a note of the settings and unset the variables.
  2. To import shared certificates from the old databases into the new one, have an administrator with access to the directories containing the certificates run the PKCertTool command lines below.

If necessary, replace the default paths shown in the command lines with the actual paths to the old stores. (The values, if any, that you noted down for the environment variables should give these paths.)
pkcerttool -add -store ROOT -all /usr/local/certificates/ROOT
pkcerttool -add -store CA -all /usr/local/certificates/CA
pkcerttool -add -store AddressBook -all /usr/local/certificates/AddressBook

Have each user run the command line below to import personal certificates and private keys.

PKCertTool will likely prompt the user to enter a passphrase for each certificate in a PKCS#12 file to decrypt the private key. PKCertTool will prompt again for a passphrase to use to encrypt each private key to be added.
pkcerttool -add -store MY -all $HOME/.certificates

Advanced Encryption Options in Windows

cryptoptions
This option covers three special cases involving encryption under Windows. One sub-option enables Windows systems equipped with newer Intel processors that include an AES instruction set to take advantage of the increased encryption speed. The other two sub-options enable Smartcrypt to support certificate-based encryption compatible with most smart cards.
The FastAES sub-option tells Smartcrypt to use the fastest version of the Advanced Encryption Standard (AES) available on the system. This option is only available if FIPS Mode is disabled, as this option is not FIPS-compatible. See "Encrypting Using Only FIPS-Approved Algorithms" in Chapter 4 for more information on FIPS. By default, this sub-option is turned off.
On Windows, Smartcrypt can access certificates stored on smart cards to decrypt strongly encrypted files if the smart cards work with Windows' facilities for managing digital certificates.
Support for using smart card and token certificates is available only on Windows, not on UNIX or Linux.
These two cryptoptions sub-options are both on by default. They can be turned off to provide compatible certificate-based encryption for two special cases:

  • smartcard sub-option: Turn off to support certificate-based encryption for recipients using versions of PKZIP v6.0 or earlier.
  • win2000 sub-option: Turn off to provide pure AES certificate-based encryption

The smartcard sub-option enables smart cards to decrypt files encrypted for a recipient list. However, if the smartcard sub-option is set, versions of PKZIP prior to 6.1 cannot decrypt files encrypted for a recipient list. To enable users of these earlier versions of PKZIP to decrypt such files, turn off the smartcard sub-option. Note, though, that files encrypted with this sub-option off cannot be decrypted by smart cards.
The sub-option affects only recipient-list encryption (that is, encryption using the recipient option). All versions of PKZIP can decrypt passphrase-encrypted files regardless of how the smartcard sub-option is set.
If any of your recipients run an older PC with Windows 2000 or older, use the win2000 sub-option so those recipients can extract files encrypted with AES for a recipient list. You may also need this option if your recipient uses a smart card to decrypt.
By default when using a certificate to encrypt data with AES, Smartcrypt uses 3DES to protect the key. This is necessary to enable recipients using smart cards or running an older version of Windows to decrypt the files.
Turn off the win2000 sub-option if you want to avoid any use of the 3DES encryption algorithm when doing AES encryption. Turning off the option causes Smartcrypt to use only AES. Realize that recipients using smart cards or running older versions of Windows will likely be unable to extract files encrypted for a recipient list with AES.
Like the smartcard sub-option, the win2000 sub-option affects only recipient-list encryption (that is, encryption using the recipient option). Users of Windows 2000 or older can decrypt files encrypted using AES with a passphrase even with the sub-option off. (Smart cards do not support passphrase-based encryption.)
All three sub-options are set independently of one another. Turning smartcard off does not affect Win2000. Nor does turning on FastAES affect the other sub-options.
For example, the configuration display of initial defaults shows both of these sub-options turned on (see "Viewing Configuration Settings" in Chapter 8):

CryptOptions = Smartcard, Win2000

To configure one of the sub-options off, prefix it with a hyphen:
pkzipc -config -cryptoptions=-smartcard
or, to configure both off:
pkzipc -config -cryptoptions=-smartcard,-win2000
Either option can also be turned off just for the current command line, to override a configured default setting:
pkzipc -add -cryptoptions=-smartcard -recipient="John Q. Public" test.zip
To turn one of the sub-options on, omit the hyphen prefix. For example, the following command line configures all sub-options on:
pkzipc -config -cryptoptions=smartcard,win2000,fastaes

Working with OpenPGP Files

Some organizations use encryption tools based on the OpenPGP standard, rather than X.509. OpenPGP uses the same basic Public Key Infrastructure principles for exchanging encrypted files, but uses a decentralized "Web of Trust" method of authenticating signatures.
Smartcrypt extracts and decrypts files that comply with the OpenPGP standard, RFC 4880. Smartcrypt command line can also create OpenPGP-compliant files and sign files with OpenPGP keys. In this section, you'll learn more about the OpenPGP standard, and how to use Smartcrypt command line with OpenPGP.

Overview: OpenPGP vs. X.509

As described in "Public-Key Infrastructure and Digital Certificates" earlier in this chapter, the X.509 standard relies on a hierarchical "trust chain" model, where an individual digital signature is issued by an intermediate Certificate Authority (CA), which is assumed to have received enough documentation to determine that an individual is who he says he is. The intermediate CA's certificate gets its certificate, in turn, from a Root CA. Each certificate says who issued it, and theoretically if you question the authenticity of a certificate, you can find the documentation presented to the original CA.
OpenPGP keys are typically created by individuals, and authenticated by other individuals. In the real world, you have friends who can vouch that you are who you say you are. If you walk into a room full of strangers, your friend can introduce you to the people he knows. Since you trust that your friend is correctly identifying his friends and acquaintances, that trust extends to his friends too.
When you translate the above experience to the electronic, OpenPGP world, it works this way: You create a pair of OpenPGP keys (public and private) to identify yourself. When a friend comes to visit, display the public key. The friend can now sign your public key (often called "key signing") and certify that this key represents you. Now everyone who trusts the person who signed your key can also trust that your key is authentic. A Web of Trust is developed as more people authenticate each certificate. Everyone in the Web of Trust can also exchange messages in the OpenPGP format.

Supported OpenPGP Algorithms

This table lists the supported OpenPGP algorithms used for encryption, signing, and hashing.

Algorithm

Type

RSA

Public-Key Signature or Encryption

Elgamal

Public-Key Encryption

DSA

Public-Key Signature

3DES

Symmetric-Key (Passphrase)

CAST5

Symmetric-Key (Passphrase)

IDEA

Symmetric-Key (Passphrase)

AES (128-bit)

Symmetric-Key (Passphrase)

AES (192-bit)

Symmetric-Key (Passphrase)

AES (256-bit)

Symmetric-Key (Passphrase)

Uncompressed

Data Compression

ZIP (RFC 1951)

Data Compression

BZIP2

Data Compression

SHA-1

Hash

SHA-256

Hash

SHA-384

Hash

SHA-512

Hash

MD5

Hash

Setting Up OpenPGP Keyrings

Where X.509 certificates are housed in "stores," OpenPGP keys are stored in "keyrings." Public and private keys are stored into separate rings. Use these commands to identify existing OpenPGP private and public key pairs for use in creating and signing OpenPGP files:
pkzipc -listcertificates
pkzipc -listcertificates=AddressBook

Setting Up Public Keyrings

In Windows, Smartcrypt searches for these public keyring files:

%PK_OPENPGP_PUBLIC_RING%
<Documents>\PGP\pubring.pkr
<AppData>\gnupg\pubring.gpg

If your public keyring is installed in a different location than listed here, add this environment variable to your Windows system:

PK_OPENPGP_PUBLIC_RING=<PATH>\pubring.pkr 

On UNIX systems, Smartcrypt searches for these public keyring files:

$PK_OPENPGP_PUBLIC_RING
$HOME/.pgp/pubring.pkr
$HOME/.gnupg/pubring.gpg

Setting Up Private Keyrings

Windows:

%PK_OPENPGP_SECRET_RING%
<Documents>\PGP\secring.skr
<AppData>\gnupg\secring.gpg

If your secret keyring is installed in a different location than listed here, add this environment variable to your Windows system:

PK_OPENPGP_SECRET_RING=<PATH>\secring.skr 

UNIX:

$PK_OPENPGP_SECRET_RING
$HOME/.pgp/secring.skr
$HOME/.gnupg/secring.gpg

Working with Recipient Groups

You may have multiple recipients that you regularly send ZIP or OpenPGP files to. Smartcrypt allows you to create and configure groups of recipients (whether those recipients use OpenPGP or X.509 to identify themselves) to simplify sending encrypted files to such groups.

Creating a Group

To create a new group, you need to name the group. You can also include a description of the group. Use this syntax:

pkzipc -groupadd=<name>,<item> [-groupdesc=<description>] [-groupfile=<group file name>]

You must add at least one item to a group when you create it. Smartcrypt recognizes any value for the recipient command as a group item. These include Common Name, Friendly Name, email address, KeyID (for OpenPGP). You can also use an LDAP search filter to identify multiple items. See "Specifying Recipients" in Chapter 4 for more information.
Use groupdesc to (optionally) add a brief description of the group.
By default, the file holding all the group information is called group.xml, and is stored in the same location as the Smartcrypt configuration file. You can rename this file or point it to another folder either directly from the command line or (preferably) through your configuration file. See "Changing a Default Value" in Chapter 8 for more information.
Groups can also contain other groups. To add an individual recipient and the members of the test group to the existing multi group:
pkzipc -groupadd=multi,user1@example.com,test
Note: When you send OpenPGP files to a group, only group members with OpenPGP keys will be able to decrypt the files.

Listing Groups

Grouplist displays a list (with any description) of all your existing groups:
pkzipc -grouplist
Use groupdetail to see the content of either a specified group, or all groups:
pkzipc -groupdetail=<group name>
If you have multiple group files, you can also optionally specify a group file to list:
pkzipc -grouplist -groupfile=<group file name>
pkzipc -groupdetail -groupfile=<group file name>

Removing Items from a Group

Use groupremove to remove one or more keys from a particular group:
pkzipc -groupremove=<name>,<item>
To remove an entire group:
pkzipc -groupremove=<name>
You may also specify a groupfile name with this option:
pkzipc -groupremove=<name>,<item> -groupfile=<group file name>

Creating an OpenPGP file to Send to a Group

To create a new OpenPGP file named file.pgp and specify a group of recipients:
pkzipc -add -archivetype=pgp -recipient=group=<name> <file.pgp> <file1>
You can optionally specify a groupfile in this command.

Configuring Other OpenPGP Settings

You can configure both the default hash and encryption algorithm and default signing key for OpenPGP files separately from the X.509 algorithms. To do this, you must always include the archivetype=PGP option. For example, to use SHA-256 as the default hash algorithm for OpenPGP files, use this command:
pkzipc -archivetype=pgp -config -hash=sha256