Use is subject to License Terms. Your use of this web site or any of its contents or software indicates your agreement to be bound by these License Terms.

Copyright © 2006 Sun Microsystems, Inc. All rights reserved.
Overview  Package   Class  Tree  Deprecated  Index  Help 
JSR 177
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.microedition.pki
Class UserCredentialManager

java.lang.Object
  extended by javax.microedition.pki.UserCredentialManager

public final class UserCredentialManager
extends java.lang.Object

This class provides functionality for user credential management which includes creating certificate signing requests, adding user credentials, and removing credentials that may be used to generate digital signatures as specified in the CMSMessageSignatureService class. The initial version of credential management supports X.509 version 3 Certificates and URIs that resolve to X.509 Certificates.

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:

The certificate may contain additional information. The certificate itself is signed by the certificate issuer. The certificate issuer is usually referred to as a Certificate Authority (CA).

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:

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:

Field Summary
static java.lang.String ALGORITHM_DSA
          Algorithm identifier for a DSA signature key.
static java.lang.String ALGORITHM_RSA
          Algorithm identifier for an RSA signature key.
static int KEY_USAGE_AUTHENTICATION
          Indicates a key used for authentication.
static int KEY_USAGE_NON_REPUDIATION
          Indicates a key used for digital signatures.
 
Method Summary
static boolean addCredential(java.lang.String certDisplayName, byte[] pkiPath, java.lang.String uri)
          Adds a user certificate or certificate URI to a certificate store.
static byte[] generateCSR(java.lang.String nameInfo, java.lang.String algorithm, int keyLen, int keyUsage, java.lang.String securityElementID, java.lang.String securityElementPrompt, boolean forceKeyGen)
          Creates a DER encoded PKCS#10 certificate enrollment request.
static boolean removeCredential(java.lang.String certDisplayName, byte[] issuerAndSerialNumber, java.lang.String securityElementID, java.lang.String securityElementPrompt)
          Removes a certificate or certificate URI from a certificate store.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

ALGORITHM_RSA

public static final java.lang.String ALGORITHM_RSA
Algorithm identifier for an RSA signature key. This is the String representation of the OID identifying the RSA algorithm.

See Also:
Constant Field Values

ALGORITHM_DSA

public static final java.lang.String ALGORITHM_DSA
Algorithm identifier for a DSA signature key. This is the String representation of the OID identifying a DSA signature key.

See Also:
Constant Field Values

KEY_USAGE_AUTHENTICATION

public static final int KEY_USAGE_AUTHENTICATION
Indicates a key used for authentication.

See Also:
Constant Field Values

KEY_USAGE_NON_REPUDIATION

public static final int KEY_USAGE_NON_REPUDIATION
Indicates a key used for digital signatures.

See Also:
Constant Field Values
Method Detail

generateCSR

public static final byte[] generateCSR(java.lang.String nameInfo,
                                       java.lang.String algorithm,
                                       int keyLen,
                                       int keyUsage,
                                       java.lang.String securityElementID,
                                       java.lang.String securityElementPrompt,
                                       boolean forceKeyGen)
                                throws UserCredentialManagerException,
                                       CMSMessageSignatureServiceException
Creates a DER encoded PKCS#10 certificate enrollment request.

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.

Parameters:
nameInfo - the distinguished name to be included in the PKCS#10 certificate signing request. The distinguished name MUST follow the encoding rules of RFC2253. If null is passed as the parameter value, it is up to the implementation to choose an appropriate distinguished name (for example, the WIM serial number). If nameInfo is empty or not formatted according RFC2253 an IllegalArgumentException is thrown.
algorithm - the Object Identifier (OID) for the public key algorithm to use. (see RFC 1778) The static variables UserCredentialManager.ALGORITHM_RSA and UserCredentialManager.ALGORITHM_DSA may be used to indicate either RSA or DSA signature keys. If algorithm is empty or not formatted according RFC1778 an IllegalArgumentException is thrown. If the requested algorithm is not supported on the platform then a UserCredentialManagerException MUST be thrown and the getReason method MUST return SE_NO_KEYS.
keyLen - the key length (typically 1024 for RSA) If keyLen is incorrect an IllegalArgumentException is thrown.
keyUsage - the functionality for which the key is marked inside the security element. This may be one of UserCredentialManager.KEY_USAGE_AUTHENTICATION or UserCredentialManager.KEY_USAGE_NON_REPUDIATION. If keyUsage is incorrect an IllegalArgumentException is thrown.
securityElementID - identifies the security element on which the key resides or will be generated. If this parameter is null the implementation MUST choose the first available security element that meets the specified requirements. If no appropriate security element is found, the securityElementPrompt parameter MUST be used to guide the user on selecting the correct security element. If no security element can be selected, a UserCredentialManagerException is thrown and the getReason method MUST return SE_NOT_FOUND.
securityElementPrompt - guides a user to insert the correct security element, if the suitable security element is removable and not detected. If this parameter is set to null, a user prompt is not used to guide the user to select an appropriate security element.
forceKeyGen - if set to true a new key MUST be generated. If the security element does not support key generation it MUST throw an UserCredentialManagerException and the getReason method MUST return a SE_NO_KEYGEN error code. If set to false no key generation is required and an existing key may be used.
Returns:
DER encoded PKCS#10 certificate enrollment request, or null if the certificate enrollment request was cancelled by the user before completion.
Throws:
java.lang.IllegalArgumentException - if the parameters are not valid
UserCredentialManagerException - if an error occurs while generating the certificate request
java.lang.SecurityException - if the caller is not authorized to access the user certificate store
CMSMessageSignatureServiceException - if an error occurs while signing the certificate request

addCredential

public static final boolean addCredential(java.lang.String certDisplayName,
                                          byte[] pkiPath,
                                          java.lang.String uri)
                                   throws UserCredentialManagerException
Adds a user certificate or certificate URI to a certificate store.

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
Within the sequence, the order of certificates is such that the subject of the first certificate is the issuer of the second certificate, etc. Each certificate in PkiPath shall be unique. No certificate may appear more than once in a value of Certificate in PkiPath. The last certificate is the end entity user 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.

If the requested certificate can not be stored, a UserCredentialManagerException is thrown and the getReason method MUST return CREDENTIAL_NOT_SAVED.

Parameters:
certDisplayName - the user friendly name associated with the certificate. If certDisplayName is null or an empty string an IllegalArgumentException is thrown. Applications MUST use unique user friendly names to make selection easier. If the certDisplayName is already registered, an IllegalArgumentException is thrown.
pkiPath - the DER encoded PKIPath containing user certificate and certificate authority certificates. If pkiPath is null or incorrectly formatted an IllegalArgumentException is thrown. If pkiPath is already registered, an IllegalArgumentException is thrown.
uri - a URI that resolves to a X.509v3 certificate. The uri can be null.
Returns:
false if the operation to add the credential was cancelled by the user before completion.
Throws:
java.lang.IllegalArgumentException - if parameters are not valid
UserCredentialManagerException - if an error occurs while adding a user credential
java.lang.SecurityException - if the caller is not authorized to add to the user certificate store

removeCredential

public static final boolean removeCredential(java.lang.String certDisplayName,
                                             byte[] issuerAndSerialNumber,
                                             java.lang.String securityElementID,
                                             java.lang.String securityElementPrompt)
                                      throws UserCredentialManagerException
Removes a certificate or certificate URI from a certificate store.

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.

Parameters:
certDisplayName - the user friendly name associated with the certificate. If certDisplayName is null or an empty string an IllegalArgumentException is thrown.
issuerAndSerialNumber - the DER encoded ASN.1 structure that contains the certificate issuer and serial number as defined in RFC 3369. If issuerAndSerialNumber is null or not properly formatted according to RFC3369 an IllegalArgumentException is thrown. If the requested certificate is not found, a UserCredentialManagerException is thrown and the getReason method MUST return CREDENTIAL_NOT_FOUND.
securityElementID - identifies the security element on which the key resides. If this parameter is null the implementation MUST choose the first available security element that meets the specified requirements. If no appropriate security element is found, the securityElementPrompt parameter MUST be used to guide the user on selecting the correct security element. If no security element can be selected, a UserCredentialManagerException is thrown and the getReason method MUST return SE_NOT_FOUND.
securityElementPrompt - guides the user to insert the correct security element if the security element is removable and not detected. If this parameter is set to null, no information regarding which security element to use is displayed to the user.
Returns:
false if the operation to remove the credential was cancelled by the user before completion.
Throws:
java.lang.IllegalArgumentException - if the parameters are not valid
UserCredentialManagerException - if an error occurs while removing the credential
java.lang.SecurityException - if the caller is not authorized to remove from the user certificate store
Overview  Package   Class  Tree  Deprecated  Index  Help 
JSR 177
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Copyright © 2006 Sun Microsystems, Inc. All rights reserved. Use is subject to License Terms. Your use of this web site or any of its content or software indicates your agreement to be bound by these License Terms.

For more information, please consult the JSR 177 specification.