CMSMessageSignatureServicepublic final class CMSMessageSignatureService extends Object | 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.
Example Code
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());
}
}
...
Note regarding UI implementations
The user prompts and notifications should be implemented in such a way that:
-
the UI is distinguishable from a UI generated by external sources
(for example J2ME applications)
-
external sources are not able to modify the data presented to the user.
-
external sources are not able to retrieve the PIN data.
|
| Fields Summary |
|---|
| public static final int | SIG_INCLUDE_CONTENTIncludes the content that was signed in the signature.
If this option is specified and the 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_CERTIFICATEIncludes the user certificate in the signature.
If this option is specified and the certificate is not
available, a
CMSMessageSignatureServiceException
exception MUST be thrown and the
getReason method
MUST return the CRYPTO_NO_CERTIFICATE
error code. | | static int | maskUnassigned option bits. | | private static boolean | certSigIndicates that certificate inclusion is supported
on the platform. |
| Constructors Summary |
|---|
private CMSMessageSignatureService()Constructor for the CMSMessageSignatureService class.
String signprop = Configuration
.getProperty("com.sun.satsa.certsig");
if (signprop != null) {
certSig = signprop.equals("true");
}
|
| Methods Summary |
|---|
| public static final byte[] | authenticate(byte[] byteArrayToAuthenticate, int options, java.lang.String[] caNames, java.lang.String securityElementPrompt)Generates a signature that may be used for
authentication purposes. If the authentication signature is
generated using public key technology, this method may be
tied to key pairs marked for digital signature and
authentication operations. 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.
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.
The signature format returned by this method MUST follow
the CMS
signature format as specified in RFC 2630.
/* Validate the options selected. */
checkOptions(options);
return com.sun.satsa.pki.PKIManager.sign(
com.sun.satsa.pki.PKIManager.AUTHENTICATE_DATA,
byteArrayToAuthenticate, null, options, caNames,
securityElementPrompt);
| | public static final byte[] | authenticate(java.lang.String stringToAuthenticate, int options, java.lang.String[] caNames, java.lang.String securityElementPrompt)Generates a signature that may be used for
authentication purposes. If the authentication signature is
generated using public key technology,
this method may be tied to key pairs
marked for digital signature and authentication operations. 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.
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.
/* Validate the options selected. */
checkOptions(options);
return com.sun.satsa.pki.PKIManager.sign(
com.sun.satsa.pki.PKIManager.AUTHENTICATE_STRING,
null, stringToAuthenticate, options, caNames,
securityElementPrompt);
| | static void | checkOptions(int options)Checks signing option word.
/* Check for valid arguments. */
if ((options & mask) != 0) {
throw new IllegalArgumentException("Invalid signing options ");
}
if ((options & CMSMessageSignatureService. SIG_INCLUDE_CERTIFICATE)
== CMSMessageSignatureService.SIG_INCLUDE_CERTIFICATE) {
if (!CMSMessageSignatureService.certSig) {
throw new CMSMessageSignatureServiceException
(CMSMessageSignatureServiceException.CRYPTO_NO_CERTIFICATE);
}
}
| | public static final byte[] | sign(java.lang.String stringToSign, int options, java.lang.String[] caNames, java.lang.String securityElementPrompt)Generates a CMS signed message.
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.
/* Validate the options selected. */
checkOptions(options);
return com.sun.satsa.pki.PKIManager.sign(
com.sun.satsa.pki.PKIManager.SIGN_STRING,
null, stringToSign, options, caNames,
securityElementPrompt);
|
|
