|
SATSA - JSR177 | ||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||||
java.lang.Object | +--javax.microedition.securityservice.CMSMessageSignatureService
Provides signature services for cryptographic messages.
Cryptographic operations are frequently required to realize authentication, authorization, integrity, and privacy services. These services may be provided at various layers (for example, communication layer, application layer, and so on). These services form critical security components of larger systems and services such as e-commerce, e-government, or corporate applications. The layer at which these services are used are governed by the security requirements of the system and the policies used to formulate those requirements.
The services of authentication and authorization are often delivered through the use of digital signatures. For a digital signature to be useful, it must be possible to determine what was signed, which algorithms were used, and who generated the signature. Additional information may be included. The combination of this information into a single construct is referred to as a formatted digital signature.
A formatted digital signature is well suited to deliver the services of authentication, authorization, and integrity of information at the application layer within numerous systems. The generation of a formatted digital signature involves the use of multiple cryptographic operations including random number generation, hash generation, and the application of a suitable signature algorithm. The cryptographic operations are often performed on a security element that is trusted for secure storage of cryptographic keys and secure computation of cryptographic operations. The result of these cryptographic operations is combined with information such as the user's identity and the data on which the cryptographic operations are performed. This is then combined and presented in a specific format that is expressed in ASN.1 or XML. The result is referred to as a formatted digital signature. Examples of formatted digital signatures include PKCS#7, CMS, and XML Digital Signature. This class supports signature messages that conform to the Cryptographic Message Syntax (CMS) format as specified in RFC 2630 with enhanced security services for RFC 2634.
The complexity of generating a formatted digital signature is reduced through the use of a high-level interface. The implementation is responsible for identifying and managing the appropriate security elements, requesting the required cryptographic operations from the system and security element, as well as performing the appropriate formatting of the results. The advantages of this interface is twofold. First, the complexity of generating a formatted digital signature is removed from the application developer. Second, the size of the implementation can be drastically reduced, removing the need for separate packages to access and manage security elements, perform specific cryptographic operations, and formatting the results appropriately.
This class provides a compact and high-level cryptographic interface that utilizes security elements available on a J2ME device.
In this version of the interface, signature generation is defined for
authentication and authorization purposes. The sign
and authenticate methods return CMS-formatted
signatures. The signed message can be constructed with content
included (opaque signature) or without the content (detached
signature).
For the purpose of this interface, a security element is a device
or part of a
device that is trusted to provide secure storage of user credentials
and certificates as well as cryptographic keys. In addition, such a
device is trusted to perform secure computation involving
the cryptographic keys that are securely stored on the device.
If a requested security element can not be found, a
UserCredentialManagerException is thrown and
the getReason method MUST return
UserCredentialManagerException.SE_NOT_FOUND.
A device may have multiple security elements. The security elements may be removable. Public information such as the user credential and a reference to the corresponding security element may be cached on the J2ME device.
Authorization of the use of a key in a security element will be governed by the policy of the security element (for example, no authorization required, PIN entry required, biometric required, and so on).
Cryptographic keys may be marked for different purposes, such as non-repudiation or authentication. The implementation will honor the key usage defined by a security element.
This class honors the key usage policy defined by the security
element by splitting
the generation of formatted digital signatures between two methods,
namely the
sign and authenticate methods. The sign method is
associated with keys marked for digital signature and non-repudiation. The
authenticate method is associated with keys marked for digital
signature only,
or digital signature and a key usage apart from non-repudiation (such as
authentication).
These two methods, apart from being associated with a specific key
usage, also have
distinct behavior regarding user interaction. The
sign method will always display the text that is
about to be signed. The authenticate method
is overloaded and does not display the data that is about to be
signed, if that data is passed as a byte array. If the
data that is about to be signed is passed as a String,
it is always displayed.
The sign method should be used for higher-value transactions and
authorizations while the authenticate method should be used
whenever a digital signature is required to authenticate a user.
This is an example of how this interface may be used to generate a formatted digital signature used for authentication or non-repudiation purposes.
String caName = new String("cn=ca_name,ou=ou_name,o=org_name,c=ie");
String[] caNames = new String[1];
String stringToSign = new String("JSR 177 Approved");
String userPrompt = new String("Please insert the security element "
+ "issued by bank ABC"
+ "for the application XYZ.");
byte[] byteArrayToSign = new byte[8];
byte[] authSignature;
byte[] signSignature;
caNames[0] = caName;
try {
// Generate a formatted authentication signature that includes the
// content that was signed in addition to the certificate.
// Selection of the key is implicit in selection of the certificate,
// which is selected through the caNames parameter.
// If the appropriate key is not found in any of the security
// elements present in the device, the implementation may guide
// the user to insert an alternative security element using
// the securityElementPrompt parameter.
authSignature = CMSMessageSignatureService.authenticate(
byteArrayToSign,
CMSMessageSignatureService.SIG_INCLUDE_CERTIFICATE
|CMSMessageSignatureService.SIG_INCLUDE_CONTENT,
caNames, userPrompt);
// Generate a formatted signature that includes the
// content that was signed in addition to the certificate.
// Selection of the key is implicit in selection of the certificate,
// which is selected through the caNames parameter.
// If the appropriate key is not found in any of the
// security elements present in the device, the implementation
// may guide the user to insert an alternative
// security element using the securityElementPrompt parameter.
signSignature = CMSMessageSignatureService.sign(
stringToSign,
CMSMessageSignatureService.SIG_INCLUDE_CERTIFICATE
|CMSMessageSignatureService.SIG_INCLUDE_CONTENT,
caNames, userPrompt);
} catch (IllegalArgumentException iae) {
// Perform error handling
iae.printStackTrace();
} catch (CMSMessageSignatureServiceException ce) {
if (ce.getReason() == ce.CRYPTO_FORMAT_ERROR) {
System.out.println("Error formatting signature.");
} else {
System.out.println(ce.getMessage());
}
}
...
The user prompts and notifications should be implemented in such a way that:
| Field Summary | |
static int |
SIG_INCLUDE_CERTIFICATE
Includes the user certificate in the signature. |
static int |
SIG_INCLUDE_CONTENT
Includes the content that was signed in the signature. |
| Method Summary | |
static byte[] |
authenticate(byte[] byteArrayToAuthenticate,
int options,
String[] caNames,
String securityElementPrompt)
Generates a signature that may be used for authentication purposes. |
static byte[] |
authenticate(String stringToAuthenticate,
int options,
String[] caNames,
String securityElementPrompt)
Generates a signature that may be used for authentication purposes. |
static byte[] |
sign(String stringToSign,
int options,
String[] caNames,
String securityElementPrompt)
Generates a CMS signed message. |
| Methods inherited from class java.lang.Object |
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
| Field Detail |
public static final int SIG_INCLUDE_CONTENT
sign
and authenticate methods do not support
opaque signatures, a
CMSMessageSignatureServiceException
exception MUST be thrown and the
getReason method
MUST return the CRYPTO_NO_OPAQUE_SIG
error code.
public static final int SIG_INCLUDE_CERTIFICATE
CMSMessageSignatureServiceException
exception MUST be thrown and the
getReason method
MUST return the CRYPTO_NO_CERTIFICATE
error code.
| Method Detail |
public static final byte[] sign(String stringToSign,
int options,
String[] caNames,
String securityElementPrompt)
throws CMSMessageSignatureServiceException,
UserCredentialManagerException
The signature may be generated using key pairs that are marked
for non-repudiation. It is up to
the implementation to search the available security
elements for relevant keys. Selection of the appropriate
key is facilitated by the caNames
parameter. Only keys certified by the specified certificate
authority will be eligible for key selection.
If the appropriate key is not found in any of the security elements
present in the device, the implementation may guide the user to
insert an alternative security element using the
securityElementPrompt parameter.
The implementation MUST display the user friendly name of the certificate or the certificate URI to the user. If more than one certificate is found, the user MUST be presented with a list of certificate friendly names. It is up to the user to select the appropriate certificate based on the certificate friendly name.
The signature format is controlled through the
options parameter. If the
options parameter is non-zero and is
not a valid combination of
CMSMessageSignatureService.SIG_INCLUDE_CERTIFICATE
and
CMSMessageSignatureService.SIG_INCLUDE_CONTENT,
an IllegalArgumentException exception
MUST be thrown.
Before requesting confirmation of the signature through a
PIN or some other means, the implementation of this method
MUST display the stringToSign to the user.
Authorization of the use of the private key to generate a
signature is subject to the policy of the underlying
security element.
If signature authorization is required through the entry
of a PIN, the implementation of this method is responsible
for collecting the PIN from the user and presenting the
PIN to the security element. 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.
The signature MUST be generated on the UTF-8
encoding of the stringToSign.
The signature format returned by this method MUST follow
the CMS
signature format as specified in RFC2630.
stringToSign - the string that is to be signedoptions - the bitwise OR of the following options:
CMSMessageSignatureService.SIG_INCLUDE_CONTENT and
CMSMessageSignatureService.SIG_INCLUDE_CERTIFICATE.
If the implementation
does not support detached signatures
(signatures without the original content),
the absence of the
CMSMessageSignatureService.SIG_INCLUDE_CONTENT
option will result in a
CMSMessageSignatureServiceException with a reason
code of
CRYPTO_NO_DETACHED_SIG. If the implementation
does not support opaque signatures and the
CMSMessageSignatureService.SIG_INCLUDE_CONTENT
option is specified, a
CMSMessageSignatureServiceException
exception with a reason code of
CRYPTO_NO_OPAQUE_SIG MUST be thrown. If
certificate URIs are used instead of certificates and the
CMSMessageSignatureService.SIG_INCLUDE_CERTIFICATE
option is specified, a
CMSMessageSignatureServiceException exception
with a reason code of CRYPTO_NO_CERTIFICATE
MUST be thrown.caNames - an array of Strings that
contain the distinguished names of certification
authorities that are trusted to issue certificates that
may be used for authenticating a user.
The distinguished name MUST be formatted according
to
RFC 2253. If this parameter is set to null
or the array is empty,
it is up to the implementation to interact with the user to
select an appropriate certificate that may be used for
digital signatures.
If an entry in the caNames array is
null, contains an empty String, or
is not properly formatted according to RFC2253
an IllegalArgumentException
is thrown.
If, for a given collection of caNames more than
one certificate
is available, a list of available certificates that are
currently valid (i.e. not expired) MUST be displayed to the
user for selection. The system clock MUST be used to determine
the validity of certificates.securityElementPrompt - guides a 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.
If there are no certificates that can be selected to
complete the operation a
CMSMessageSignatureServiceException is thrown
and the getReason method
MUST return the CRYPTO_NO_CERTIFICATE
error code.
null if the signature generation was cancelled by
the user before completion
CMSMessageSignatureServiceException - if an
error occurs during signature generation
IllegalArgumentException - if the parameters are not
valid
SecurityException - if the caller is not
authorized to sign messages
UserCredentialManagerException - if a security element
is not found
public static final byte[] authenticate(byte[] byteArrayToAuthenticate,
int options,
String[] caNames,
String securityElementPrompt)
throws CMSMessageSignatureServiceException,
UserCredentialManagerException
caNames parameter.
If the appropriate key is not found in any of the security elements
present in the device, the implementation may guide the user to
insert an alternative security element using the
securityElementPrompt parameter.
The implementation SHOULD display the user friendly name of the certificate or the certificate URI to the user. If more than one certificate is found, the user SHOULD be presented with a list of certificate friendly names. It is up to the user to select the appropriate certificate based on the certificate friendly name.
The signature format is controlled through the
options parameter. If the
options parameter is non-zero and is
not a valid combination of
CMSMessageSignatureService.SIG_INCLUDE_CERTIFICATE
and
CMSMessageSignatureService.SIG_INCLUDE_CONTENT,
an IllegalArgumentException exception
MUST be thrown.
Authorization of the use of the private key to generate a
signature is subject to the policy of the underlying
security element.
If signature authorization is required through the entry of
PIN, the implementation of this method is responsible for
collecting the PIN from the user and presenting the PIN to
the security element. 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.
This method does not display the data that is about to be signed. The fact that a user is blindly signing information introduces the risk of a man-in-the-middle attack. For this reason it is recommended that access to this method is controlled using the standard access control mechanisms as defined by MIDP 2.0.
The signature format returned by this method MUST follow
the CMS
signature format as specified in RFC 2630.
byteArrayToAuthenticate - the byte array that is to be signedoptions - the bitwise OR of the following options:
CMSMessageSignatureService.SIG_INCLUDE_CONTENT and
CMSMessageSignatureService.SIG_INCLUDE_CERTIFICATE.
If the implementation
does not support detached signatures
(signatures without the original content),
the absence of the
CMSMessageSignatureService.SIG_INCLUDE_CONTENT
option will result in a
CMSMessageSignatureServiceException with a reason
code of
CRYPTO_NO_DETACHED_SIG. If the implementation
does not support opaque signatures and the
CMSMessageSignatureService.SIG_INCLUDE_CONTENT
option is specified, a
CMSMessageSignatureServiceException
exception with a reason code of
CRYPTO_NO_OPAQUE_SIG MUST be thrown. If
certificate URIs are used instead of certificates and the
CMSMessageSignatureService.SIG_INCLUDE_CERTIFICATE
option is specified, a
CMSMessageSignatureServiceException exception
with a reason code of CRYPTO_NO_CERTIFICATE
MUST be thrown.caNames - an array of Strings that
contain the distinguished names of certification
authorities that are trusted to issue certificates that
may be used for authenticating a user.
The distinguished name MUST be formatted according
to
RFC 2253. If this parameter is set to null
or the array is empty,
it is up to the implementation to interact with the user to
select an appropriate certificate that may be used for
authentication.
If an entry in the caNames array is
null, contains an empty String, or
is not properly formatted according to RFC2253
an IllegalArgumentException
is thrown.
If, for a given collection of caNames more than
one certificate
is available, a list of available certificates that are
currently valid (i.e. not expired) MUST be displayed to the
user for selection. The system clock MUST be used to determine
the validity of certificates.securityElementPrompt - guides a 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.
If there are no certificates that can be selected to
complete the operation a
CMSMessageSignatureServiceException is thrown
and the getReason method
MUST return the CRYPTO_NO_CERTIFICATE
error code.
null if the signature generation was cancelled by
the user before completion
CMSMessageSignatureServiceException - if an
error occurs during signature generation
IllegalArgumentException - if the parameters are not
valid
SecurityException - if the caller is not
authorized to generate authentication messages
UserCredentialManagerException - if a security element
is not found
public static final byte[] authenticate(String stringToAuthenticate,
int options,
String[] caNames,
String securityElementPrompt)
throws CMSMessageSignatureServiceException,
UserCredentialManagerException
caNames parameter.
If the appropriate key is not found in any of the security elements
present in the device, the implementation may guide the user to
insert an alternative security element using the
securityElementPrompt parameter.
The implementation MUST display the user friendly name of the certificate or the certificate URI to the user. If more than one certificate is found, the user MUST be presented with a list of certificate friendly names. It is up to the user to select the appropriate certificate based on the certificate friendly name.
The signature format is controlled through the
options parameter. If the
options parameter is non-zero and is
not a valid combination of
CMSMessageSignatureService.SIG_INCLUDE_CERTIFICATE
and
CMSMessageSignatureService.SIG_INCLUDE_CONTENT,
an IllegalArgumentException exception
MUST be thrown.
Before requesting confirmation of the signature through a
PIN or some other means, the implementation of this method
MUST display the stringToAuthenticate to the user.
Authorization to use a private key to generate a
signature is subject to the policy of the underlying
security element.
If signature authorization is required through the entry of a
PIN, the implementation of this method is responsible for
collecting the PIN from the user and presenting the PIN to
the security element. Incorrect PIN entry is handled
by the implementation. The number of retries following an
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.
The signature MUST be generated on the UTF-8
encoding of the stringToAuthenticate.
The signature format returned by this method MUST follow
the CMS
signature format as specified in RFC 2630.
stringToAuthenticate - the string that is to be signedoptions - the bitwise OR of the following options:
CMSMessageSignatureService.SIG_INCLUDE_CONTENT and
CMSMessageSignatureService.SIG_INCLUDE_CERTIFICATE.
If the implementation
does not support detached signatures
(signatures without the original content),
the absence of the
CMSMessageSignatureService.SIG_INCLUDE_CONTENT
option will result in a
CMSMessageSignatureServiceException with a reason
code of
CRYPTO_NO_DETACHED_SIG. If the implementation
does not support opaque signatures and the
CMSMessageSignatureService.SIG_INCLUDE_CONTENT
option is specified, a
CMSMessageSignatureServiceException
exception with a reason code of
CRYPTO_NO_OPAQUE_SIG MUST be thrown. If
certificate URIs are used instead of certificates and the
CMSMessageSignatureService.SIG_INCLUDE_CERTIFICATE
option is specified, a
CMSMessageSignatureServiceException exception
with a reason code of CRYPTO_NO_CERTIFICATE
MUST be thrown.caNames - an array of Strings that
contain the distinguished names of certification
authorities that are trusted to issue certificates that
may be used for authenticating a user.
The distinguished name MUST be formatted according
to
RFC 2253. If this parameter is set to null
or the array is empty,
it is up to the implementation to interact with the user to
select an appropriate certificate that may be used for
authentication.
If an entry in the caNames array is
null, contains an empty String, or
is not properly formatted according to RFC2253
an IllegalArgumentException
is thrown.
If, for a given collection of caNames more than
one certificate
is available, a list of available certificates that are
currently valid (i.e. not expired) MUST be displayed to the
user for selection. The system clock MUST be used to determine
the validity of certificates.securityElementPrompt - guides a 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.
If there are no certificates that can be selected to
complete the operation a
CMSMessageSignatureServiceException is thrown
and the getReason method
MUST return the CRYPTO_NO_CERTIFICATE
error code.
null
if the signature generation was cancelled by the
user before completion
CMSMessageSignatureServiceException - if an
error occurs during signature generation
IllegalArgumentException - if the parameters are not
valid
SecurityException - if the caller is not
authorized to generate authentication messages
UserCredentialManagerException - if a security element
is not found
|
SATSA - JSR177 | ||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||||