Java Doc for UserCredentialManager.java in  » 6.0-JDK-Modules » j2me » javax » microedition » pki » Java Source Code / Java DocumentationJava Source Code and Java Documentation

In a public key cryptographic system, a user has two distinct keys. One key is kept private while the other is made public. There are a number of public key cryptographic systems, some of which may be used for the creation of digital signatures (for example, DSA), while others can be used for encryption (for example, Rabin). Some systems may be used for both encryption and digital signatures (for example, RSA). Generally the private key, which is only known to the user, is used to generate a signature or to decrypt a message. The public key, as can be deduced from the name, is public knowledge and is used to verify the user's signature or to encrypt information intended for the user.

When selecting a public key to encrypt a message or verify a digital signature, it is important to be able to link the public key either to the user for which the encrypted message is intended or to the user that generated the signature. Public key infrastructure (PKI) provides a mechanism for binding an identity to a public key. The binding is expressed in a data structure known as a certificate. The X.509 certificate format is one of the most widely adopted certificate formats. X.509 certificates generally contain at least the following information:

• An X.500 name that can potentially be linked to the identity of the user.
• The public key associated with the X.500 name.
• A validity period for the certificate (Not Before and Not After).
• Information on the certificate issuer (an X.500 name for the issuer and a serial number). This uniquely identifies a certificate in a PKI.

The process that a CA follows before issuing a certificate is governed by the certification practice statement (CPS) of the CA. This usually involves both technical and non-technical steps that need to be completed before a certificate is issued. Technical steps include obtaining the public key that must be certified, verifying that the user is in possession of the corresponding private key, and returning the certificate or a reference to the certificate once it is issued. Non-technical steps include the processes followed to establish the certificate requesters identity. Upon completion of the technical and non-technical steps of the registration process, the user is said to be enrolled into the PKI.

The purpose of this class is to provide the technical building blocks required to enroll a user in a PKI. This will allow a user to obtain a certificate that can be used in conjunction with the sign and authenticate methods in the javax.microedition.securityservice.CMSMessageSignatureService class. This can also be used for renewing and deleting certificates once they have expired. With this package it is possible to:

• Obtain a certificate signing request that can be sent to a PKI.
• Add a certificate or certificate URI to a certificate store.
• Remove a certificate or certificate URI from a certificate store.

Example

 // Parameters for certificate request message.
 String nameInfo = new String("CN=User Name");
 byte[] enrollmentRequest = null;
 int keyLength = 1024;
 // User friendly names and prompts.
 String securityElementID = new String("Bank XYZ");
 String securityElementPrompt = new String
 ("Please insert bank XYZ security element before proceeding");
 String friendlyName = new String("My Credential");
 // Certificate chain and URI from registration response.
 byte[] pkiPath; 
 String uri;     
 // Obtain a certificate enrollment request message.
 try {
 enrollmentRequest = UserCredentialManager.generateCSR
 (nameInfo, UserCredentialManager.ALGORITHM_RSA, keyLength,
 UserCredentialManager.KEY_USAGE_NON_REPUDIATION, 
 securityElementID, securityElementPrompt, false);
 // Send it to a registration server.
 ...
 // Assign values for pkipath and certificate uri
 // from the registration response.
 ...
 // Store the certificate on the security element.
 UserCredentialManager.addCredential(friendlyName,
 pkiPath, uri);
 } catch (IllegalArgumentException iae) {
 iae.printStackTrace();
 } catch (NullPointerException npe) {
 npe.printStackTrace();
 } catch (CMSMessageSignatureServiceException cmse) {
 cmse.printStackTrace();
 } catch (UserCredentialManagerException pkie) {
 pkie.printStackTrace();
 }
 

Note regarding UI implementations

User prompts and notifications should be implemented in such a way that:

• the UI is distinguishable from a UI generated by external sources (for example J2ME applications).
• external sources are not able to modify the data presented to the user.
• external sources are not able to retrieve the PIN data.

A credential is registered using an ordered sequence of certificates, called a PKI Path. The PKI Path is defined in ITU-T RECOMMENDATION X.509 (2000) | ISO/IEC 9594-8:2001, Technical Corrigendum 1 (DTC 2) and is used by the J2SE CertPath Encodings.

PkiPath: an ASN.1 DER encoded sequence of certificates, defined as follows:

 PkiPath ::= SEQUENCE OF Certificate
 

The implementation uses the securityElementID and the securityElementPrompt to choose an appropriate security element.

Removal of the credential from the certificate store must be confirmed by the user.

A credential is registered using an ordered sequence of certificates, called a PKI Path. The PKI Path is defined in ITU-T RECOMMENDATION X.509 (2000) | ISO/IEC 9594-8:2001, Technical Corrigendum 1 (DTC 2) and is used by the J2SE CertPath Encodings.

PkiPath: an ASN.1 DER encoded sequence of certificates, defined as follows:

 PkiPath ::= SEQUENCE OF Certificate
 

The use of the certificate URI is platform dependent. Some platforms may not store the user certificate, but may instead keep a copy of the URI. If only the URI is retained instead of the certificates included in the pkiPath, the implementation MUST parse the user certificate in the pkiPath to obtain relevant information such as the issuing CA name, the user certificate serial number, the public key, and user distinguished name. Some of these fields may be required by the underlying security element. The certificate URI parameter can be null in deployments where off device access to certificate storage is not supported.

Some platforms MAY store the credential information with a specific security element, while other platforms MAY have a central repository for credentials. It is platform dependent where the information is maintained.

Storing the requested credential must be confirmed by the user. The implementation must display the user friendly name of the certificate or the certificate URL. The user should have the option to view the detailed information of the credential, such as the certificate issuer, certificate subject, and certificate validity period. This method returns false if the user cancels the request to add the credential.

Authorization to store the requested credential is also subject to the policy of the underlying security element or the platform. If user authorization is required through the entry of PIN, the implementation of this method is responsible for collecting the PIN from the user. Incorrect PIN entry is handled by the implementation. The number of retries following incorrect PIN entry is governed by the policy of the security element or the platform. If the PIN is blocked due to an excessive number of incorrect PIN entries, the implementation must throw a SecurityException exception.

The implementation uses the securityElementID and the securityElementPrompt to choose an appropriate security element. If an appropriate security element cannot be found, a UserCredentialManagerException is thrown and the getReason method MUST return SE_NOT_FOUND. The implementation MUST use the algorithm, keyLen, and keyUsage parameters to select a specific key to use in signing the certificate request. If the algorithm is not supported or the specific key parameters can not be fulfilled, then a UserCredentialManagerException MUST be thrown and the getReason method MUST return SE_NO_KEYS.

If the platform can select a security element and the security element contains multiple keys, it is up to the platform to select an appropriate key (when key generation is not forced). If a key is found that is not yet associated with a user certificate or a user certificate request, the platform MUST select such a key in preference to keys that are already associated with a user certificate or certificate request. If all keys are associated with a certificate or a certificate request, the implementation MUST select the key associated with a certificate request in preference to keys that are associated with a certificate. If all keys are already associated with a user certificate and key generation was not forced, the platform MAY select one of the existing keys for inclusion in the certificate signing request, depending on the security element policy.

The application requests key generation by setting the forceKeyGen flag. If a key is requested of a security element that is not capable of key generation, a UserCredentialManagerException MUST be thrown and the getReason method MUST return SE_NO_KEYGEN. If the key can not be generated with the requested key parameters, a UserCredentialManagerException MUST be thrown and the getReason method MUST return SE_NO_KEYS. If the security element requires the user to specify a new PIN that is used to protect the keys to be generated, the implementation of this method is responsible for collecting the new PIN from the user.

If a security element is found, but it contains no keys that can be used, then a UserCredentialManagerException MUST be thrown and the getReason method MUST return SE_NO_KEYS. If a security element is found, but all available keys have been associated with certificates and if the platform does not allow selection of keys already associated with certificates, then a UserCredentialManagerException MUST be thrown and the getReason method MUST return SE_NO_UNASSOCIATED_KEYS.

If a security element can be selected and an appropriate key is available (either generated or already existing) the certification request is generated and formatted. The certification request will be formatted as a PKCS#10 certificate request. The request may contain additional attributes.

See "X.690 - Information technology - ASN.1 encoding rules: Specification of Basic Encoding Rules (BER), Canonical Encoding Rules (CER) and Distinguished Encoding Rules (DER)" at http://www.itu.int/ITU-T/studygroups/com17/languages/ for details about ASN.1 encoding rules.

Generation of the certificate enrollment request and the key pair must be confirmed by the user. The user should have the option to view the detailed information of the key used in signing the certificate request, such as the key usage, key length, public key algorithm. This method returns null if the user cancels the certificate enrollment request.

Authorization to generate certificate enrollment request is also subject to the policy of the underlying security element. If user authorization is required through the entry of PIN, the implementation of this method is responsible for collecting the PIN from the user. Incorrect PIN entry is handled by the implementation. The number of retries following incorrect PIN entry is governed by the security element policy. If the PIN is blocked due to an excessive number of incorrect PIN entries, the implementation must throw a SecurityException exception.

Removal of the credential from the certificate store must be confirmed by the user. The implementation must display the user friendly name of the certificate or the certificate URL. The user should have the option to view the detailed information of the credential, such as the certificate issuer, certificate subject, and certificate validity period. This method returns false if the user cancels the request to remove the credential.

Authorization to remove the requested credential is also subject to the policy of the underlying security element or the platform. If user authorization is required through the entry of PIN, the implementation of this method is responsible for collecting the PIN from the user. Incorrect PIN entry is handled by the implementation. The number of retries following incorrect PIN entry is governed by the policy of the security element or the platform. If the PIN is blocked due to an excessive number of incorrect PIN entries, the implementation must throw a SecurityException exception.