File	Doc	Category	Size	Date	Package
UserCredentialManager.java	API Doc	phoneME MR2 API (J2ME)	28412	Wed May 02 18:00:38 BST 2007	javax.microedition.pki

UserCredentialManager

• java.lang.Object

// 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();
}

Fields Summary
public static final String	ALGORITHM_RSA Algorithm identifier for an RSA signature key. This is the String representation of the OID identifying the RSA algorithm.
public static final String	ALGORITHM_DSA Algorithm identifier for a DSA signature key. This is the String representation of the OID identifying a DSA signature key.
public static final int	KEY_USAGE_AUTHENTICATION Indicates a key used for authentication.
public static final int	KEY_USAGE_NON_REPUDIATION Indicates a key used for digital signatures.
private static boolean	keygen Indicates that key generation is supported on the platform.

Constructors Summary
private UserCredentialManager() Constructor for the UserCredentialManager class. String generation = Configuration .getProperty("com.sun.satsa.keygen"); if (generation != null) { keygen = generation.equals("true"); }

Methods Summary
public static final boolean	addCredential(java.lang.String certDisplayName, byte[] pkiPath, java.lang.String uri) 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. param 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. param 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. param uri a URI that resolves to a X.509v3 certificate. The uri can be null. throws IllegalArgumentException if parameters are not valid throws UserCredentialManagerException if an error occurs while adding a user credential throws SecurityException if the caller is not authorized to add to the user certificate store return false if the operation to add the credential was cancelled by the user before completion. return com.sun.satsa.pki.PKIManager.addCredential(certDisplayName, pkiPath, uri);
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) 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. param 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. param 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. param keyLen the key length (typically 1024 for RSA) If keyLen is incorrect an IllegalArgumentException is thrown. param 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. param 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. param 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. param 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. return DER encoded PKCS#10 certificate enrollment request, or null if the certificate enrollment request was cancelled by the user before completion. throws IllegalArgumentException if the parameters are not valid throws UserCredentialManagerException if an error occurs while generating the certificate request throws SecurityException if the caller is not authorized to access the user certificate store throws CMSMessageSignatureServiceException if an error occurs while signing the certificate request /* User requested a new key be generated. */ if (forceKeyGen) { if (! UserCredentialManager.keygen) { // Configuration parameter disabled key generation. throw new UserCredentialManagerException (UserCredentialManagerException.SE_NO_KEYGEN); } } return com.sun.satsa.pki.PKIManager.generateCSR(nameInfo, algorithm, keyLen, keyUsage, securityElementID, securityElementPrompt, forceKeyGen);
public static final 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. 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. param certDisplayName the user friendly name associated with the certificate. If certDisplayName is null or an empty string an IllegalArgumentException is thrown. param 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. param 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. param 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. throws IllegalArgumentException if the parameters are not valid throws UserCredentialManagerException if an error occurs while removing the credential throws SecurityException if the caller is not authorized to remove from the user certificate store return false if the operation to remove the credential was cancelled by the user before completion. return com.sun.satsa.pki.PKIManager.removeCredential( certDisplayName, issuerAndSerialNumber, securityElementID, securityElementPrompt);