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