Working with Digital Signatures and OpenPGP Keys in UNIX

With SecureZIP, 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.

PKZIP authenticates digital signatures on files signed by others, but you must have SecureZIP to attach digital signatures of your own .

SecureZIP 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 entire archive has not changed. Both PKZIP and SecureZIP authenticate digital signatures on extraction.

SecureZIP 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.

SecureZIP 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 SecureZIP to sign files, you must have a digital certificate. Digital certificates are available from various certificate authorities.

This chapter describes the SecureZIP tools and commands that work with digital certificates under both X.509 and OpenPGP standards.

Public-Key Infrastructure and Digital Certificates

SecureZIP 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, PKZIP 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 SecureZIP 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 SecureZIP 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.

SecureZIP may use a private key maintained in X.509 PKCS#12 format. To access such keys, a password must be entered for each SecureZIP 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.

SecureZIP 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. See "Attaching Digital Signatures" and "Authenticating Digital Signatures" 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

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:

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.

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:

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 PKZIP 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, PKZIP 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 PKZIP to check to see if a certificate that you propose to use for digital signing, encryption, or authentication appears in a CRL accessible to PKZIP. If it does, PKZIP displays a warning, (W42) Certificate was revoked.

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 PKZIP 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 PKZIP refuse to use a revoked certificate for signing or encrypting, use the strict option. Unless you include the strict option, PKZIP 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 PKZIP to access a CRL, the CRL must be downloaded and imported into a certificate store that PKZIP 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. PKZIP does not access CRLs published on the Web.

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.

Setting Up Stores for Digital Certificates  

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 PKZIP can use. To address this, PKZIP provides a utility program—PKCertTool—to set up and manage certificate stores on UNIX/Linux for use with PKZIP.

To digitally sign files or to enable other people to strongly encrypt files specifically for you as a recipient, you need SecureZIP 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, 1024-bit minimum) and how to get one.

Setting Up the Certificate Stores

The PKWARE utility PKCertTool sets up the PKZIP certificate stores and imports certificates into them, along with any certificate revocation lists you want PKZIP 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, PKZIP 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:

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.

PKZIP and PKCertTool can import certificates, CRLs, and keys in the following file formats:

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 PKZIP 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 PKZIP.

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 "Shared or Separate AddressBook Stores" and "Setting Environment Variables for Certificate Stores" sections for more information.

Certificates that include a private key can be safely added to the AddressBook store: PKZIP does not add private keys to, or read private keys from, the AddressBook store. PKZIP 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. PKZIP 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.

PKZIP uses the first store (of the appropriate type) that it finds. If a user points PKZIP to an unshared AddressBook store, that is the only AddressBook store that PKZIP 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.

1. 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 "Setting Environment Variables for Certificate Stores."
2. Locate $HOME/certificates.db, where $HOME is the user's home directory.
3. Create $HOME/certificates.db.

PKCertTool Commands and Options

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

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 PKZIP 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. 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 PKZIP, a friendly name that you assign with PKCertTool can be used with the PKZIP -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>]

— 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 

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>

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>]

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>

MY 
AddressBook 
ROOT 
CA  

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>

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>

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.

Setting Environment Variables for Certificate Stores

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

You can use PKCertTool to set up certificate databases having custom names and locations if you do not want to use the PKZIP 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
   
   
3. 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/.certificate

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.

PKZIP and SecureZIP extract and decrypt files that comply with the OpenPGP standard, RFC 4880. SecureZIP 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 PKZIP 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.

Setting Up OpenPGP Keyrings

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

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

$PK_OPENPGP_PUBLIC_RING
$HOME/.pgp/pubring.pkr
$HOME/.gnupg/pubring.gpg
$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. SecureZIP 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> [groupdesc=<description>] [-groupfile=<group file name>]<item>

You must add at least one item to a group when you create it. SecureZIP 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" 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 SecureZIP 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" 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

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

Managing Key Stores on Hardware Security Modules

SecureZIP supports command-line access to key stores located on a hardware security module (HSM). These devices, also known as key management servers, are cards or boxes (though they can exist as a virtual machine as a "cloud-based HSM") dedicated to securely storing digital certificates. These keys can be based on the X.509 standard or public/private key pairs. Typically an HSM attaches to a workstation or network server, and allows access to the stored keys via passphrase. An HSM may host a Certificate Authority to generate key pairs as well.

Many HSMs (including the SafeNet KeySecure and DataSecure systems) adhere to the Key Management Interoperability Protocol (KMIP), a standard for allowing different types of key management servers to store the same keys. The Organization for the Advancement of Structured Information Standards (OASIS) develops this evolving standard.

Many vendors have key management server products, and each of them have different ways of storing and managing access to keys. This guide will use SafeNet key management products as an example of the kinds of tasks needed to integrate SecureZIP CLI with an HSM. Consult the documentation for your key management server product for information on integrating other software with the key management server.

Working with HSM Devices

Before you can do anything with SecureZIP and SafeNet, you must tell SecureZIP CLI where the SafeNet Network-Attached Encryption (NAE) Properties file is located. With SecureZIP installed, type this command to configure SecureZIP to use the SafeNet Properties file. In this example, that file is located in C:\safenet :

pkzipc -config -kmip=Safenet=C:\safenet\ProtectAPPICAPI.properties

The properties file contains the location of critical files, which should be stored in the same folder as the properties file itself. These include:

• KMIP tag file, kmip_tags.csv
• Network configuration files for the NAE Server, including the network ports used by NAE and KMIP
• The client and server certificates and other credentials to authenticate Secure Socket Layer (SSL) connections between you and the NAE Server

Your SafeNet (DataSecure or KeySecure) properties file must be properly configured to use SSL for both NAE and KMIP protocol exchanges.

Make sure that SecureZIP has access through your firewall to the network ports used by NAE and KMIP configured for your product. SecureZIP needs this access to communicate with your key management server product.

To use SecureZIP with SafeNet, a Dynamic Link Library (DLL) must be provided from the SafeNet device under license from SafeNet.

Configuring KMIPOptions

After connecting SecureZIP CLI to the key management server, use KMIPOptions to define how SecureZIP uses keys from your KMIP provider when identifying recipients for your secure communications. SavePass allows you to include a passphrase with your encrypted attachments, while comment stores a reference (label) to this passphrase in a ZIP comment. For example:

pkzipc -config -kmipoptions=<HSM>=recipients,savepass

Listing Keys and Certificates

Use the listcertificates (or listcert) command to list available public/private key pairs and X.509 certificates in a specified store. By default, SecureZIP will display certificates and key pairs in your key management server. Typing the command:

pkzipc -listcert

will display something like this:

TestRSAKey1 (<keyID>): (<HSM>)
TestRSAKey2 (<keyID>): (<HSM>)
    KMIP_PGP (<keyID>): (<HSM>)
      PGPKey1 (<keyID>): (<HSM>)

Listing Key Names in the HSM

KMIPListPassname displays a list of key names available from the key store. Typing this command:

pkzipc –kmiplistpassname

will display something like this:

The following passphrase names are known to SecureZIP

SafeNet:

pktestdb7
Secret_PKWARE_Test70
Secret_PKWARE_Test7
TestSecret9
TestSecret8
JASSecret1
TestSecret7
TestSecret2

Working with Encrypted Archives with Keys Stored On the Key Management Server

Once you have connected SecureZIP CLI with the key management server, you can run many standard SecureZIP commands, accessing your keys from the key management server just as if your certificate store was on another network server. In the following examples, SecureZIP will access a SafeNet appliance.

Encrypt with a X.509 key stored on a SafeNet key store:

pkzipc -add -recipient="PKWARE Test3" MyZip.zip TestFile.txt

Encrypt with an existing SafeNet stored passphrase

pkzipc -add -pass=@safenet=TestSecret2 MyZip.zip TestFile.txt

Encrypt and store a new known passphrase

When running this command, TestSecret9 should not already exist.

pkzipc -add -pass=<encryption-passphrase-to-store> -pass=@safenet=TestSecret9 MyZip.zip TestFile.txt

Encrypt and store a new "auto-generated" random passphrase (up to 240 chars)

When running this command, TestSecret10 should not already exist.

pkzipc -add -pass=@safenet=TestSecret10 MyZip.zip TestFile.txt

Decrypt with a SafeNet stored X.509 key

pkzipc -extract MyZip.zip

Decrypt with a SafeNet stored passphrase

pkzipc -extract MyZip.zip

pkzipc -extract -pass=@SafeNet=TestSecret10 MyZip.zip

Sign using a certificate from SafeNet store

You must use a fully qualified digital certificate (not just a public/private key pair) to sign a file with SecureZIP.

pkzipc -add -cert="PKWARE Test3" MyZip.zip TestFile.txt