Class UserCredentialManager

java.lang.Object

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:

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

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.

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.

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) (you can obtain this document from ITU website) and is used
by the J2SE
CertPath Encodings.

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.

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.