-

Overview

-

Features at a Glance

• Full support of user certificate life cycle
• Management of various key/certificate repositories
• Supports cryptographic tokens via PKCS #11 interface
• Supports Windows cryptographic providers and certificate stores
• Import of OpenSSL PEM encoded keys & certificates
• Trust management for BlueZ SSLite
• X.509/PKIX (certificates V3, CRLs V2) supported
• Compliant with PKCS standards (#7,#10,#11,#12)
• Supports Netscape certificate requests (SPKAC)
• Integration with VeriSign and other CAs
• Access to LDAP directories for certificate retrieval
• 100% Java, runs on JDK 1.2
• Easy to use GUI

-

Contents

• Version & Updates
• System Requirements
• Basic Concepts
• Supported Token Types
• Support of Windows Cryptography
• Accessing Hardware Tokens
• Supported Standard Data Formats
• Requesting Certificates
• Trust Settings
• Retrieving Certifictes via LDAP
• Generating Certificates
• Signing/Verifying JAR Files
• Signing CAP Files
• Creating Signed FINlet Files
• Command line options&arguments
• Advanced Technical Information
• Trouble Shooting & Bugs
• Glossary & References
• FAQ
• Change Log

-

Version
& Updates

[Top][Contents]

-

System
Requirements

[Top][Contents]

-

Basics

[Top][Contents]

-

Supported
Token
Types

The types of supported tokens:

PKCS #7 token:

Contains a set of certificates and, optionally, associated CRLs. Keys cannot be stored in this type of repository. This repository does not require authentication. Certificates and CRLs are protected by a signature. However, an adversary can change the set of items as stored in a particular PKCS #7 token. This type of token is used when the expected set of items is defined by some context.

PKCS #12 token:

Contains private keys, certificates, and associated CRLs. The content is protected by a user passphrase. The public items (certificates, CRLs) and the private items (keys) can be protected by algorithms with different strengths.

PKCS #11 (CryptoKi) repositories:

PKCS #11 defines an interface to cryptographic tokens. These tokens can store keys and certificates. Storage of CRLs is not supported. Access to a token is protected by a personal identification number (PIN). You have to specify the token specific PKCS #11 DLL which is used by KeyMan to access the token.

KeyMan supports PKCS #11 version 2.01 and 2.10 DLLs.

KeyMan has the special ability to construct PKCS #7 tokens from data with unknown format. It scans the data for X.509 certificates and CRLs and constructs a PKCS #7 token from the detected certificates and CRLs. If you have emails containing certificates or CRLs you can open the email folder in KeyMan and KeyMan will try to extract the X.509 items. Of course, the data cannot be stored back in the original format. The extracted data can be stored in a file using the PKCS #7 format.

[Top][Contents]

-

Support of
Windows
Cryptography

[Top][Contents]

-

Accessing
Hardware
Tokens

Before the token is read you have to enter your personal identification number (PIN) which authorizes access to the data stored in the token. If the PIN is blocked (after several unsuccessful tries) or if you enter a blank PIN then you will be directed to a dialog which allows you unblock or change your PIN. You must know the security officer PIN or unblocking PIN do reset the user PIN. Consult the manual of the hardware token for more information.

Sometimes a PKCS #11 DLL serves more than one token in several slots. By default, KeyMan will access slot 0. If you append a string to the DLL name you can access other slots and other tokens. Append a string ":slotnumber" to select arbitrary slots. You can select a token as well by appending a token label instead of the slot number.

[Top][Contents]

-

Supported
Standard
Data Formats

PKCS #7

This data format is a collection of certificates and CRLs. The set of certificates and CRLs as described by PKCS #7 is not protected. However, each single certificate and CRL is protected by a signature. PKCS #7 is used whenever the expected set of certificates and CRLs is defined by some context.

On Windows systems the standard file suffixes for PKCS #7 files are .p7r and .p7b.

PKCS #10

PKCS #10 defines a certificate request message. It contains the public key and information about the X.500 name of the requestor. The message is signed with the corresponding private key. PKCS #10 messages can be generated in binary format and in ASCII armored format. The message must be submitted to a certificate authority (CA).

PKCS #12

PKCS #12 is used by browsers and Web servers for import and export of private keys and associated certificates. KeyMan can read and write those PKCS #12 files. While these programs understand only a very specific profile of PKCS #12 KeyMan can generate more general PKCS #12 files. KeyMan can store sets of private keys, certificates, CRLs, and corresponding trust settings in a single PKCS #12 file. PKCS #12 files are protected by a passphrase.

Usually, a PKCS #12 token contains the trust policy for a particular application. In case of IBM BlueZ SSLite the keys and associated certificate chains will be used for client/server authentication. Other certificates represent trusted CAs or trusted servers depending on respective trust settings.

On Windows systems the standard file suffixes for PKCS #12 files are .p12 and .pfx.

SPKAC

SignedPublicKeyAndChallenge (SPKAC) is a data format to request certificates from a CA. This particular format is generated by Netscape whenever the HTML tag <keygen> is used. It contains the signed public key and challenge. This data format can be generated by KeyMan in binary and in Base64 format.

X.509 V3 Certificates

KeyMan can read X.509 V3 certificates in binary format or wrapped in ASCII armor. These files can be opened or imported into KeyMan. It is also possible to write single certificates from a token in these two formats (Certificate details -> Save Icon).

On Windows systems the standard file suffixes for X.509 certificate files are .crt, .cer, and .der.

X.509 V2 Certificate Revocation Lists (CRLs)

KeyMan can read X.509 V2 CRLs in binary format or wrapped in ASCII armor. A single CRL cannot be opened. KeyMan can only import CRLs into tokens which already contains the associated CA certificate. It is possible to write single CRLs in binary or ASCII armored format (certifiate details -> CRLs details -> Save Icon).

On Windows systems the standard file suffix for X.509 CRL files is .crl.

For reasons of backward compatibility KeyMan also supports IBM SSLight KeyRings. This key ring format is a proprietary format as defined by IBM SSLight package. KeyMan can read this format. If the token is written its format is automatically converted to PKCS #12 standard format. Java class files with embedded SSLight key rings can be read as well. The key ring data is stored in a String object in the constant pool of a Java class file. Use of the SSLight key ring format and wrapping into a Java class file is not recommended any longer.

[Top][Contents]

-

Requesting
Certificates

If you choose PKCS #10 or SPKAC format you must save the generated request message (in a file or in the clipboard) and transmit it to the CA. You should have instruction on how to submit the request to the CA.

KeyMan also supports some online CAs. You need Internet access to reach these CAs. The dialog for the respecive online CA will provide further instructions. Eventually, KeyMan will launch a browser and you have to fill out a Web form.

When the CA has created your certificate it will notify you. Either this is done immediately by displaying a Web page or by sending an email with furher instructions. In any case you have to import the certificate into the token which contains the corresponding private key. If the CA has sent the certificate in an email as ASCII armored data or as binary attachement then save the email or the attchement into a file and import this into KeyMan. If the CA has sent a URL where the certificate can be retrieved then import it from this remote location.

[Top][Contents]

-

Trust
Settings

CA certificate

The application will trust any certificate that is directly or indirectly signed by this CA certificate.

Peer certificate

The application will trust only this certificate but not any certificates that are signed by it.

[Top][Contents]

-

Retrieving
Certificates
via LDAP

      host:port/name

      directory.verisign.com
      directory.verisign.com:389
      ldap.infospace.com:389/c=US

    Thomas Eir*
    *Eirich
    *Eir*
    Tho*Eir*

KeyMan also accepts more complicated filters. These are defined in RFC2254. In most cases the simple filters are sufficient. If you are familiar with LDAP and the directory structure you can also enter more sophisticated filter expressions using the RFC2254 syntax.

[Top][Contents]

-

Generating
Certificates

You can generate self-signed certificates and you can sign keys with some certificate creating user certificates or intermediate CA certificates.

The menu Action -> Create Certificate will guide you through the creation of a certificate. To create a self signed certificate you need a key pair in the token. The created self signed certificate will be added to the current token.

To create user certificates or intermediate CA certificates perform the following steps:

• Open or create token with the key pair to be certified
• Create a PKCS #10 certificate request using this key pair
• Export the PKCS #10 request to the clipboard
• Open the token that contains the private CA certificate
• Select Create Certificate and choose sign PKCS #10 request
• Export created certificate to clipboard
• Switch to initial token with the key pair and import certificate from clipboard
• Optionally, import the CA certificate into the first token to obtain a certificate chain

[Top][Contents]

-

Signing
Verifying
JAR Files

[Top][Contents]

-

Signing
CAP Files

[Top][Contents]

-

Creating
Signed
FINlet
Files

[Top][Contents]

-

Command Line
Options&Arguments

[Top][Contents]

-

Advanced
Technical
Information

KeyMan is built using IBM BlueZ SSLite/CryptoLite package. They offer cryptographic functions and APIs to manage public key infrastructure. KeyMan basically is a GUI to exploit these functions easily by non technical users. The underlying IBM BlueZ SSLite/CryptoLite are highly efficient in terms of execution performance and footprint. KeyMan is only about 250KB big mostly because of the extremely small footprint of the underlying packages.

Some functions of KeyMan can be adjusted after installation. The Java runtime engine can be changed by modifying the script files. (non-Windows platforms). For Windows installation change the following registry key:

   HKEY_LOCAL_MACHINE\Software\IBM\BlueZ Software\KeyMan\CMDLINE

Other settings can be found in the file km.setup in the installation directory of KeyMan and in the file .keyman.setup (copied to the user's Windows home directory). These files defines serveral other properties used by KeyMan. To learn more read the comments in these files.

[Top][Contents]

-

Trouble Shooting
& Bugs

[Top][Contents]

-

Glossary &
References

ASCII Armor

looks like:

       -----BEGIN X-----
       base64
       -----END X-----

where X and base64 stand for a string describing the type of object (e.g. CERTIFICATE) and the Base64 encoding of the object, respectively.

PKCS #7

Cryptographic Message Syntax Standard

PKCS #10

Certification Request Syntax Standard

PKCS #11

Cryptographic token interface Standard (CryptoKi). KeyMan supports version 2.01 of PKCS #11.

PKCS #12

Personal Information Exchange Syntax Standard

PKIX/X.509

Internet X.509 Public Key Infrastructure Certificate and CRL Profile

SPKAC

SignedPublicKeyAndChallenge ASN.1 data type as defined by Netscape.

SSLight

IBM SSLight is the precursor of IBM BlueZ SSLite.

BlueZ SSLite

IBM BlueZ SSLite package implements SSL V3 and is used in many IBM products. It is a very fast and small SSL in Java. It has an extremly small foot print (<40KB) and is highly configurable. IBM BlueZ SSLite is available in IBM intranet at BlueZ site. Externally, IBM BlueZ SSLite can be offered as part of IBM solutions. Get in touch with IBM IGS or IBM Crypto Competency Center in Denmark (Leo Moesgaard).

A comprehensive list of terms related to security and cryptography can be found in RSA's Glossary of "Frequently Asked Questions About Today's Cryptography".

[Top][Contents]

-

FAQ

Can KeyMan read PKCS #12 files generated by Netscape or Internet Explorer?

PKCS #12 files generated by Netscape browser or Internet Explorer can be read by KeyMan provided you know the password that protects their contents.

Can KeyMan create PKCS #12 files which are readable by Netscape or Internet Explorer?

The PKCS #12 standard offers a lot of freedom to choose algorithms and to arrange contents. The browsers only accept a very specific profile of all those possible options. KeyMan can generate PKCS #12 files that are readable by Netscape and Internet Explorer. Since KeyMan allows you to do much more things with PKCS #12 you can create files that are not understood by these browsers. The common profile for browsers looks like this: the public/private encryption (see menu Options -> PKCS #12 Settings) should be "RC2 (40 bits)"/"DES (168 bits)", respectively. Furthermore, there should be exactly one private certificate in the PKCS #12 token.

What is a private certificate?

If KeyMan detects a matching key and certificate it combines these two items into a private certificate. This means, for any private certificate you also own the corresponding private key. If you import certificates into a token KeyMan checks whether there is a matching private key and will automatically combine the key and the imported certificate into a private certificate. If this happens KeyMan will notify you with a dialog.

What is a CA or peer certificate?

Certificates contained in a token establish trust. They define whom you trust. What trust means and the exact evaluation of the certificates depends on the application using the token. With KeyMan you can setup two types of trust for certificates: CA and peer. If you trust a certificate as CA you implicitly trust any certificate directly or indirectly signed by this CA. If you set the trust level to "Peer" you trust only this particular certificate. Trust is not extended to certificates signed by a "Peer" certificate.

What are these certificates that are neither private, nor CA, nor peer certificates?

KeyMan tries to store for each private certificate the full chain up to the root certificate. These certificates need not be trusted and therefore will not appear among the CA or peer certificates. You can find these certificate if you select the key ring "All Certificate Items". The untrusted certificates do not have an icon.

What is a token?

A token is a collection of keys, certificates, and CRLs. A token is stored on some media (e.g. a file, a URL, piece of hardware, etc.) There are different types of tokens with different capabilites: software tokens and hardware tokens, unprotected tokens, and tokens protected by passwords or PINs.

What is a key ring?

A token consists of a set of key rings. A particular key ring identifies a specific set of items (E.g. certificates of the same trust level, or certificates for which you own the private key, or keys without matching certificates).

[Top][Contents]

-

Change Log

1.69

Workaround for a bug in an IBM JVM (AWT.repaint(milliseconds) is broken).

In some cases when opening a remote resource the next panel would not be shown.

1.68

Bug fix in code signing. Missing delimiter line in generated manifest (MANIFEST.MF) if input manifest had no trailing empty line.

1.67

Support for access to Netscape 4/7 key/certificate repositories (read only).

Support for access to GSKit KDB v3.2 repositories (read only).

Export of private keys from MSCAPI supported (if provider allows export).

1.66

Code siging problems on JDK 1.4 fixed.

Problem in DSA key generation fixed

Problem with DSA signatures on IBM JDK1.4 fixed.

1.65

Problems when opening KeyStores with private keys.

Signing JAR files: input archive manifest is merged with generated manifest (e.g. 'Main-Class', 'Sealed', and other properties can be set this way).

1.64

Bugs fixed in code signing (certificate chain added, problems with uncompressed archive entries removed)

1.63

Command line instructions to add signatures for FIPS 140-2 certification. KanMan can sign JAR files containing CryptoLite in Java and DLLs containing CryptoLite in C.

1.62

KeyMan now uses internally CryptoLite v3 (possiblity to speedup crypto via accelerator DLL).

Installshield version repackaged

Customizable X.500 name fields (see km.cnf for more info/example)

1.61

Windows certifictate stores could not be read if there are unknown certificates (e.g. with unknown public key algorithms). These certificates are now skipped to allow access to all others.

1.60

Support for certificate extensions has been added (for more details on extensions see RFC 3280). The current version supports the following set of extensions: subjectAlternativeName, basicConstraints, extKeyUsage, keyUsage. Values for these extensions can be specified during certificate generation. Display of certificate details shows the contents of these extensions and the presence of other extensions.

1.53

2048/1536 bit key sizes added.
Input for optional JCE provider on KeyStore tokens
Based on SSLite 2.14.

1.52

No change log information prior to 1.53.

[Top][Contents]

-

(C) 1999-2002 IBM Corporation