Use is subject to License Terms. Your use of this web site or any of its contents or software indicates your agreement to be bound by these License Terms.

Copyright © 2006 Sun Microsystems, Inc. All rights reserved.

JSR 177

javax.microedition.securityservice
Class CMSMessageSignatureService

java.lang.Object
  extended by javax.microedition.securityservice.CMSMessageSignatureService

public final class CMSMessageSignatureService
extends java.lang.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:


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, java.lang.String[] caNames, java.lang.String securityElementPrompt)
          Generates a signature that may be used for authentication purposes.
static 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.
static byte[] sign(java.lang.String stringToSign, int options, java.lang.String[] caNames, java.lang.String securityElementPrompt)
          Generates a CMS signed message.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

SIG_INCLUDE_CONTENT

public static final int SIG_INCLUDE_CONTENT
Includes 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.

See Also:
Constant Field Values

SIG_INCLUDE_CERTIFICATE

public static final int SIG_INCLUDE_CERTIFICATE
Includes 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.

See Also:
Constant Field Values
Method Detail

sign

public static final byte[] sign(java.lang.String stringToSign,
                                int options,
                                java.lang.String[] caNames,
                                java.lang.String securityElementPrompt)
                         throws CMSMessageSignatureServiceException,
                                UserCredentialManagerException
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.

Parameters:
stringToSign - the string that is to be signed
options - 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.
Returns:
the DER encoded signature, null if the signature generation was cancelled by the user before completion
Throws:
CMSMessageSignatureServiceException - if an error occurs during signature generation
java.lang.IllegalArgumentException - if the parameters are not valid
java.lang.SecurityException - if the caller is not authorized to sign messages
UserCredentialManagerException - if a security element is not found

authenticate

public static final byte[] authenticate(byte[] byteArrayToAuthenticate,
                                        int options,
                                        java.lang.String[] caNames,
                                        java.lang.String securityElementPrompt)
                                 throws CMSMessageSignatureServiceException,
                                        UserCredentialManagerException
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 2.0.

The signature format returned by this method MUST follow the CMS signature format as specified in RFC 2630.

Parameters:
byteArrayToAuthenticate - the byte array that is to be signed
options - 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.
Returns:
the DER encoded signature, null if the signature generation was cancelled by the user before completion
Throws:
CMSMessageSignatureServiceException - if an error occurs during signature generation
java.lang.IllegalArgumentException - if the parameters are not valid
java.lang.SecurityException - if the caller is not authorized to generate authentication messages
UserCredentialManagerException - if a security element is not found

authenticate

public static final byte[] authenticate(java.lang.String stringToAuthenticate,
                                        int options,
                                        java.lang.String[] caNames,
                                        java.lang.String securityElementPrompt)
                                 throws CMSMessageSignatureServiceException,
                                        UserCredentialManagerException
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.

Parameters:
stringToAuthenticate - the string that is to be signed
options - 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.
Returns:
the DER encoded signature, null if the signature generation was cancelled by the user before completion
Throws:
CMSMessageSignatureServiceException - if an error occurs during signature generation
java.lang.IllegalArgumentException - if the parameters are not valid
java.lang.SecurityException - if the caller is not authorized to generate authentication messages
UserCredentialManagerException - if a security element is not found

JSR 177

Copyright © 2006 Sun Microsystems, Inc. All rights reserved. Use is subject to License Terms. Your use of this web site or any of its content or software indicates your agreement to be bound by these License Terms.

For more information, please consult the JSR 177 specification.