The configurations were tested on the following environment, for others check working path, and available tested release.
See our best practices to install clients and keep them up to date.

Because KEYMAN is a JAVA application the GUI (Graphical user Interface) is very similar on the different implementation platforms.

Windows XP Sp 2

JAVA (tm) SE Runtime environment 6 update 1
JXv3.2

Window 2000 Sp 4

JAVA (tm) SE Runtime environment 6 update 1
JXv3.2

You may use Keyman to request a user certificate and once obtained, create a keyset in JKS (Java key store) or PKCS12 format. These are the basic steps:

1. Generate key
2. Generate PKCS10 certificate request
3. Save the request to a file (or clipboard) and send it to the CA (Certification authority)
4. Save your private key
5. Send you PKCS10 file request to a certification authority
6. wait for your certificate file (signed by a CA and sent to you)

Follow the GUI (Graphical user interface)

1. Launch keyman and choose to generate a key set keymanInit
2. Choose your keyset format (PKCS12) keymanFormat
3. Go to Keyman Actions menu keymanActions
4. Choose Generate key (your private key)keymanGenerate
5. Check your generation process whith RSA:1024 bits keymanRSA
6. Check private key display and go to "Actions:Request Certificate" keymanCheck
7. Request (generate) a certificate in PKCS10 format keymanRequest
8. Fill your certificate subject content keymanFillDN
9. Save your request in a file (i.e: MyName.csr) or clipboard keymanSaveReq
10. Set your keyset password (PKCS12 format) keymanPasswd
11. Save your keyset in a file (i.e: MyName.p12) keymanSave
12. Close Keyman

Return to top of page topKeyman

Launch KEYMAN and choose to generate a key set

A keyset is a private key with its associated public certificate. The public certificate should be signed by a CA (Certification authority). You have several CA over Internet, some commercial, some open source, some corporates, some personals.

Return to top of page topKeyman

Choose your keyset format (PKCS12)

KEYMAN uses the term "Token" instead of "Keyset".

Return to top of page topKeyman

Go to Keyman Actions menu

Return to top of page topKeyman

Choose Generate key (your private key)

You MUST NOT change "RSA". You may change "1024" strengh to less (512) or more (2048). If it is "512" its faster to use the key, but it can be discovered under some circumstances. With "2048" you have a load penalty but an advanced security.

Return to top of page topKeyman

Check your generation process whith RSA:1024 bits

Return to top of page topKeyman

Check private key display and go to "Actions:Request Certificate"

You should have a key icon with i.e: RSA/1024 bits indicating your key was successfully generated. Then you may request a certificate.

Return to top of page topKeyman

Request (generate) a certificate and choose how to reach a certification authority (CA)

PKCS10 is the more common format fo an off line request. The resulting PKCS10 file may be sent by e-mail or open / paste in an on line certification form.

SPKAC means "Signed Public Key And Challenge". It's not widely used except by Netscape. A SPKAC request doesn't contain any subject (DN) information, nor extension's attributes.

The Keyman "online" choice is limited to very few commercial CA. I suggest that you don't use it. When you will have a PKCS10 request file, you will be able to submit it to any CA of your choice i.e: openosi.org .

Unable to render embedded object: File (keyman-7-Request.gif) not found.

Return to top of page topKeyman

Fill your certificate subject content

The certificate's subject is also called DN for Distinguished Name. Note that many CA will add your e-mail in an "alternate certificate's subject" when signing the certificate.

For more details see the topKeyman Tab Understanding OSI names and the topKeyman Tab Filling DN (cert. subject)

Return to top of page topKeyman

Save your request in a file (i.e: MyName.csr) or clipboard

You may also indicate a full path for your file. If not its in default KEYMAN installation directory i.e: C:\Program Files\IBM\BlueZ\KeyMan

Return to top of page topKeyman

Set your keyset password (PKCS12 format)

With PKCS12 format your private key encryption password and your PKCS12 keyset password are the same. In others format like JKS they could be different, although they must not. You MAY have unencrypted private keys, obviously this is not recommended. When you import a PKCS12 file in your browser, private keys are decrypted and then encrypted again with a choosen level of security. I.e: Firefox may use FIPS security module

Return to top of page topKeyman

Save your keyset in a file (i.e: MyName.p12)

OSI stands for "Open Standards for Interconnection" from ISO / ITU
an OSI name is called a "Distinguished name" which is used in all OSI related technologies such as

• Certificates (X509)
• LDAP directories including Microsoft Active directory (X500)
• Military and aeronautical messaging systems (X400)

A "Distinguished name" (DN) is a collection of one or more of the following components

• CN Common name
• OU Organisation Unit
• O Organization
• C Country
• and many others like "givenname","sn surname","l location" ......

Example DN
DN: cn=My_full_name,ou=Related_Organisation_Unit,ou=other_related_unit,o=Company_name,c=country

or with the alternate DC scheme mostly used in directories.

DN:cn=My_full_name,ou=Related_Organisation_Unit,ou=other_related_unit,dc=example,c=com

Useful Information If you want to participate in the openLDAP referral service (ldap://root.openldap.org) you MUST use the DC scheme and set appropriate SRV records in your DNS.

Common meanings of OU are as follows:

• OU=Hosts
• OU=People # users
• OU=Services # Daemons

openOSI also uses in its naming scheme:

• OU=VirtualHosts
• OU=VirtualPeople # nicknames
• OU=PKI # Certification authorities

In principle you are free to use what you want as DN components value, unless you request a certification authority to certify these values. That is unless you intend a public use of these names to participate in an Internet of trust (similarly to the dns - Domain name system).

You MUST use a "Distinguished name" to generate a certificate request, see fillingDN

For additional information check the various OSI X500 and RFC

Useful Information There could be links between DNS and OSI naming scheme, especially when domain components are used for distinguished names. Some people stores DNS DB in an LDAP directory (like Microsoft optionally). Most people don't in order to keep loosely coupling between DNS and Directories. There is an interesting use of LDAP directories for certificates when storing these certificates and their revocation list (CRL) in the directories. Therefore you MAY imagine a scheme that facilitate directory searching for your certificate retrieval. That is unless you use a third part directory like openOSI (directory.opensosi.org). openOSI practice is to store your certificate in virtual OU unit according the openOSI naming scheme without relying on the distinguished name of the certificate. See certCheck, and CAcertsRetrieve

Filling your certificate subject

Warning You should be careful when choosing your certificate subject (DN). When authenticating with your certificate you will no more be asked for username and password. Very often you will be uniquely identified by your embedded e-mail address, but you also may be identified by your certificate subject. You cannot change your certificate's subject once it's signed by a CA.

The certificate subject is bind to the cryptographic material of your certificate (the private key). Here is the real nature of a certificate. Therefore a certificate for a user should be bind to some acceptable user ID. Check "Understanding OSI names" tab in topJXPLORER

Assign a user name to common name component. ie: cn=FirstnameLastname
The others, optional, parts of the subject are

1. Either a set of Organisation name and Country code_ ie: o=My_Organisation, c=US
2. Either a set of many Domain Components ie: "dc=example,dc=com" standing for example.com
3. Optionally you may have organisation units ie: ou=Finance or ou=people or ou=services
4. Optionally you may have additional cn as used by Microsoft naming scheme (cn=MyName,cn=Users,..)

Finally you obtain your subject value called a Distinguished Name abreviated as DN

1. example 1: cn=FirstnameLastname
2. example 2: cn=FirstnameLastname,o=My_Organisation,c=US
3. example 3: cn=FirstnameLastname,dc=example,dc=com
4. example 4: cn=FirstnameLastname,ou=people,dc=example,dc=com

This is the OSI naming scheme, also used in LDAP directories (like Microsoft AD) and X400 mail systems. If your certificate is stored in an LDAP directory, it could be stored in the same DIT (Directory Information Tree) as the one of it's Distinguished name, or it could be stored under another DIT.
openOSI stores the public signed certificates this way for class 1

• DIT is "ou=VirtualPeople,dc=openosi,dc=org"
• ObjectClass=top, ObjectClass=Person, ObjectClass=organizationalPerson, ObjectClass=InetOrgPerson
• cn=FirstnameLastname - The cn value of certificate subject
• sn=Lastname (default to cn value)
• mail=My.Name@example.com (default to verified e-mail address of the request)
• userCertificate="Binary form of your public certificate"
• OTIONS
  • givenName=Firstname

That is, if requesting an openOSI signed certificate, there is no need to fill something else than the common name as your user name, because openOSI will not certify additional information for its class 1 certification. Others parts like "o=My_Organisation, c=US" will be removed from the certificate unless you require a class 2 certificate (not available for now and subject to peer agreement).

Most of the time it is useful to have a unique value in that field, although, unique is always in a "local" context. The certificate subject alternative name refine (or replace) the subject (i.e: with e-mail address), but some authentication mechanisms like SASL EXTERNAL only uses the subject DN.

It is possible to put an e-mail address in the cn value, but many applications will fail (i.e: Liferay portal). Therefore, avoid this solution because you may have unpredictable situations with a given application.

Finaly, I recommend, when possible, to insert an "uid" component in the DN, which may look like this;
SASL_User_Name="dn:uid=My_name1234,cn=My_name,o=My_company,c=us"
Where "uid" in example, MAY be build like follows:
FirstName: John
LastName: SMITH
Last 4 digit of social security number: 1234 (or whatever algorytm)
uid=JohnSmith1234
cn="John SMITH"

This uid is supposed to be unique in the scope of a given directory (MUST be unique if you enforce controlled uid delivery). The email address remains the only worldwide unique id, if present in the subject alternative name. Note that a person MAY have multiple virtual identities, one for each of its email addresses. This is defaults for openosi.org online certification authority. The pre-registration for the certificate retrieval enforces uniqueness of the UID in the openosi directory

You may also put this UID value in the CN.

Handy Hint If you choose to generate yourself a certificate request (CSR) using keyman or any other tools including Linux based tools like openssl, it could be mandatory to fill all attributes like country, organisation, organisation unit, location .... We recommend you enter as few information as possible, entering blanks where appropriate, because a certification authority is supposed to verify all the requested attributes. This is not necessary for most authentications and is costly (however the CA could silently drop some of your unverified attributes).