|
SATSA - JSR177 | ||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||||
java.lang.Object | +--javax.microedition.pki.UserCredentialManager
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 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:
// 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();
}
User prompts and notifications should be implemented in such a way that:
| Field Summary | |
static String |
ALGORITHM_DSA
Algorithm identifier for a DSA signature key. |
static 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(String certDisplayName,
byte[] pkiPath,
String uri)
Adds a user certificate or certificate URI to a certificate store. |
static byte[] |
generateCSR(String nameInfo,
String algorithm,
int keyLen,
int keyUsage,
String securityElementID,
String securityElementPrompt,
boolean forceKeyGen)
Creates a DER encoded PKCS#10 certificate enrollment request. |
static boolean |
removeCredential(String certDisplayName,
byte[] issuerAndSerialNumber,
String securityElementID,
String securityElementPrompt)
Removes a certificate or certificate URI from a certificate store. |
| Methods inherited from class java.lang.Object |
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
| Field Detail |
public static final String ALGORITHM_RSA
String representation of the
OID identifying the RSA algorithm.
public static final String ALGORITHM_DSA
String representation of the
OID identifying a DSA signature key.
public static final int KEY_USAGE_AUTHENTICATION
public static final int KEY_USAGE_NON_REPUDIATION
| Method Detail |
public static final byte[] generateCSR(String nameInfo,
String algorithm,
int keyLen,
int keyUsage,
String securityElementID,
String securityElementPrompt,
boolean forceKeyGen)
throws UserCredentialManagerException,
CMSMessageSignatureServiceException
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.
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.
null if the certificate
enrollment request was cancelled by the user before completion.
IllegalArgumentException - if the parameters are not valid
UserCredentialManagerException - if an error occurs while
generating the certificate request
SecurityException - if the caller is not
authorized to access the user certificate store
CMSMessageSignatureServiceException - if an
error occurs while signing the certificate request
public static final boolean addCredential(String certDisplayName,
byte[] pkiPath,
String uri)
throws UserCredentialManagerException
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.
UserCredentialManagerException is thrown and
the getReason method MUST return
CREDENTIAL_NOT_SAVED.
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.
false if the operation to add the
credential was cancelled by the user
before completion.
IllegalArgumentException - if parameters are not
valid
UserCredentialManagerException - if an error occurs
while adding a user credential
SecurityException - if the caller is not
authorized to add to the user certificate store
public static final boolean removeCredential(String certDisplayName,
byte[] issuerAndSerialNumber,
String securityElementID,
String securityElementPrompt)
throws UserCredentialManagerException
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.
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.
false if the operation to remove the
credential was cancelled by the user
before completion.
IllegalArgumentException - if the parameters are not valid
UserCredentialManagerException - if an error occurs
while removing the credential
SecurityException - if the caller is not
authorized to remove from the user certificate store
|
SATSA - JSR177 | ||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||||