BlueZ Secure Systems
IBM Research

-

Overview

KeyMan is a management tool for the client side of the public key infrastructure (PKI). KeyMan manages keys, certificates, certificate revocation lists (CRLs), and the respective repositories to store and retrieve these items. The full life cycle of certificates is supported and processes involved in handling user certificates.

-

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

This is version 1.69 of KeyMan. The latest release of IBM KeyMan can be downloaded from alphaWorks site. IBMers can get more advanced and more recent releases from IBM intranet site: BlueZ - Secure Systems.

[Top][Contents]

-

System
Requirements

KeyMan requires JDK 1.2 or higher or any Java system compatible with the respective version of Sun's JDK. Swing is not required. Since AWT has numerous bugs in different versions of JDK and across different platforms and because JIT compilers also have subtle bugs which have desastrous effects on cryptographic algorithms we recommend to use either Sun JDK 1.2.2 or higher or Microsoft jview version 5.00 or higher.

[Top][Contents]

-

Basics

KeyMan manages repositories which contain collections of keys, certificates, and revocation lists. A repository is called a token. A token comprises the trust settings for a particular application (e.g. IBM BlueZ SSLite). Usually, a token contains private keys and the associated certificate chains to authenticate a user to other sites. In addition, a token holds certificates of trusted communication partners and certification authorities (CAs).

[Top][Contents]

-

Supported
Token
Types

KeyMan supports a number of different types of tokens. Tokens are repositories holding keys, certificates, CRLs, and trust settings. Some tokens can only store a subset of these item 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.

PKCS #7 and PKCS #12 are soft tokens and can be retrieved from different media (e.g. files, URI, clipboard, etc).

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

KeyMan supports direct access to Windows Crypto API (MSCAPI) and access to certificate stores. This support requires a Windows operation system (95/98, NT, or 2000). A DLL is installed which mediates the Java calls to the underlying operating system APIs. You can use KeyMan to manage keys and certificates in the Windows operating system.

[Top][Contents]

-

Accessing
Hardware
Tokens

Hardware tokens are supported on Windows, Linux, AIX, and Solaris. KeyMan interacts with hardware tokens through the PKCS #11 interface. The token must have a DLL which implements the PKCS #11 API Version 2.01. When a token is opened you are asked to enter the DLL file. You can omit the path if the DLL is reachable via the PATH environment variable.

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

KeyMan supports a number of standard data formats. Their meaning and usage context are described below.
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

This chapter describes how to request certificates from CAs using KeyMan. The first step is to create a new key (menu Action -> Generate). This can be done in a PKCS #12 token or on a hardware token. If there is more than one private key select the key for which you want to request a certificate and go to menu Action -> Request Certificate. Depending on the CA choose one of the possible request messages.

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

PKCS #12 tokens and hardware tokens allow a user to setup trust in certificates. Depending on this trust level an application, like IBM BlueZ SSLite, will behave differently. There are two trust properties that can be set:
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.

The application will not trust a certificate at all if none of both flags are set. These settings control i.e. the acceptance of trusted SSL connections in the IBM BlueZ SSLite package. Trust can be setup by opening the certificate details window and selecting the tools icon.

[Top][Contents]

-

Retrieving
Certificates
via LDAP

To retrieve certificates from public directories via LDAP select Open/New -> Remote -> LDAP. To access a LDAP directory the following information is required: a host name and a port number where the LDAP server listens. The X.500 name of the search root. In many cases this is an empty string and can be omitted. But sometimes a specific name is required. This information is entered in the following way:
      host:port/name
The part ":port" can be omitted if the server listens at the LDAP default port (389). The part "/name" can be omitted if the name is an empty string. Here are some examples of LDAP server specifications:
      directory.verisign.com
      directory.verisign.com:389
      ldap.infospace.com:389/c=US
After you have entered the LDAP server specification you must enter a search filter to retrieve specfic certificates. The simple search filter will scan the "cn" (common name) and "mail" attributes. The special character `*' replaces a sequence of unknown characters. Below are some sample filters:
    Thomas Eir*
    *Eirich
    *Eir*
    Tho*Eir*
Note, not all servers will be able to process arbitrary truncations. Most of the servers are able to process filters with a trailing `*'.

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

KeyMan has the ability to generate instant certificates. This function is useful to generate self signed certificates for Web servers that do not need publicly trusted certificates. Note, this function does not turn KeyMan into a certification authority (CA).

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

KeyMan can be used to sign and verify Java code archives (JAR or Zip files). Select a private certificate and choose the menu Action -> Sign JAR File to specify the archive to be signed. For verification just specify the code archive via menu Action -> Verify JAR File. The verification process will consider all private, peer, and CA certificates. If the verification was successful KeyMan will select the certificate that actually verified the archive.

[Top][Contents]

-

Signing
CAP Files

KeyMan can be used to sign Java Card Converted Applet (CAP) files according to Open Platform 2.0.1' or Global Platform 2.1.1. Select a private certificate and choose the menu Action -> Sign CAP File to specify the archive to be signed.

[Top][Contents]

-

Creating
Signed
FINlet
Files

KeyMan can be used to create signed FINlet (FINREAD applet) download files (CWA 14174-5:2001 Part 5: Download File Format) from JEFF (ISO/IEC 20970:2002) FCRA and (optional) FCRIA files. KeyMan also accepts and converts Java .class, JAR or Zip files if the JEFF Converter and Dumper classes of the J Consortium are installed. Select a private certificate and choose the menu Action -> Create Signed FINlet to specify the files to be signed.

[Top][Contents]

-

Command Line
Options&Arguments

Besides the interactive usage of KeyMan via the graphic user interface you can exercise some functions via command line arguments. This makes KeyMan also a tool for writing batch or shell scripts. For more information on command line functions pass the argument "-help" from a command prompt.

[Top][Contents]

-

Advanced
Technical
Information

This section provides advanced technical information on KeyMan. Normal users can safely skip this section.

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

If KeyMan does not work properly then try to run with JIT compiler disabled. If the problem suddenly disappears then you can assume that the JIT compiler is buggy. If the problem persists then try to run it on Windows with JDK 1.2.2. If the problem disappears then your JDK/platform combination is most likely buggy. If the problem still exists you probably found a bug in KeyMan. Please report your exact Java and system settings and describe your problem in detail. Supply any material necessary to reproduce the problem.

[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

For general questions about cryptography and related terms we refer to RSA Laboratories and their "Frequently Asked Questions About Today's Cryptography" The following FAQ discusses questions related to KeyMan.
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