WAS v8.5 > Develop applications > Develop web services - Security (WS-Security) > Develop applications that use Web Services Security > Develop message-level security for JAX-WS web services > Secure web services applications using the WSS APIs at the message level > Secure messages at the response consumer using WSS APIs > Configure decryption methods to protect message confidentiality using the WSS APIs

Choose decryption methods for the consumer binding

To configure the client for response decryption for the consumer binding, specify which data and transform algorithm methods to use when the client decrypts the SOAP messages.

Prior to completing these steps, read the XML encryption information to become familiar with encrypting and decrypting SOAP messages.

To complete decryption configuration to secure SOAP messages, you must complete the following tasks:

We can configure the decryption methods using the WSSDecryption and WSSDecryptPart APIs. Or we can also configure policy sets using the dmgr console to configure the decryption methods. Some of the encryption-related definitions are based on the XML-Encryption specification. The following information defines some data encryption-related terms:

Data encryption method algorithm

Data encryption algorithms specify the algorithm uniform resource identifier (URI) of the data encryption method. This algorithm encrypts and decrypts data in fixed size, multiple octet blocks.

By default, the Java Cryptography Extension (JCE) is shipped with restricted or limited strength ciphers. To use 192-bit and 256-bit Advanced Encryption Standard (AES) encryption algorithms, you must apply unlimited jurisdiction policy files.

For the AES256-cbc and the AES192-cbc algorithms, download the unrestricted Java™ Cryptography Extension (JCE) policy files from the following website: http://www.ibm.com/developerworks/java/jdk/security/index.html.

Key encryption method algorithm

Key encryption algorithms specify the algorithm uniform resource identifier (URI) of the key encryption method. The algorithm represents public key encryption algorithms specified for encrypting and decrypting keys.

By default, the RSA_OAEP algorithm uses the SHA1 message digest algorithm to compute a message digest as part of the encryption operation. Optionally, we can use the SHA256 or SHA512 message digest algorithm by specifying a key encryption algorithm property. The property name is: com.ibm.wsspi.wssecurity.enc.rsaoaep.DigestMethod. The property value is one of the following URIs of the digest method:

  • http://www.w3.org/2001/04/xmlenc#sha256
  • http://www.w3.org/2001/04/xmlenc#sha512

By default, the RSA_OAEP algorithm uses a null string for the optional encoding octet string for the OAEPParams. We can provide an explicit encoding octet string by specifying a key encryption algorithm property. For the property name, we can specify com.ibm.wsspi.wssecurity.enc.rsaoaep.OAEPparams. The property value is the base 64-encoded value of the octet string.

We can set these digest method and OAEPParams properties on the generator side only. On the consumer side, these properties are read from the incoming SOAP message.

For the KW_AES256 and the KW_AES192 key encryption algorithms, download the unrestricted JCE policy files from the following website: http://www.ibm.com/developerworks/java/jdk/security/index.html.

Your country of origin might have restrictions on the import, possession, use, or re-export to another country, of encryption software. Before downloading or using the unrestricted policy files, check the laws of your country, its regulations, and its policies concerning the import, possession, use, and re-export of encryption software, to determine if it is permitted.

To complete the decryption configuration, specify the algorithm uniform resource identifier (URI) and its usage type. If the URI is used for multiple usage types, then you must define the URI to each usage type. WebSphere Application Server supports the following decryption usage types:

Decryption usage types. These decryption types are supported by WAS.

Usage types Description
Data encryption Algorithm URI used for both encrypting and decrypting data. Encrypts and decrypts data in fixed size, multiple octet blocks.
Key encryption Algorithm URI used for encrypting and decrypting the encryption key.

To configure the decryption and decrypted part algorithms, use the WSSDecryption and WSSDecryptPart APIs, or configure policy sets using the dmgr console.

Policy sets do not support symmetric key encryption. If we are using the WSS API for symmetric key encryption, you will not be able to interoperate with web services endpoints that use policy sets.

If we are using the WSS APIs, the WSSDecryption and WSSDecryptPart APIs specify which algorithm methods are used when the client decrypts the SOAP messages.

The WSS API process completes the following high-level steps to specify which decryption and decrypted part algorithm methods to use when configuring the client for response decryption:

  1. Using the WSSDecryption API, adds the required data encryption algorithm. The data encryption algorithm is used for encrypting or decrypting parts of a SOAP message. Data decryption algorithms specify the algorithm uniform resource identifier (URI) of the data encryption method.

    The default data encryption algorithm is AES 128. The data encryption name is AES128, and the URI of the data encryption algorithm, is http://www.w3.org/2001/04/xmlenc#aes128-cbc. WAS supports the following pre-configured data decryption algorithms:

    • AES128: http://www.w3.org/2001/04/xmlenc#aes128-cbc

      The AES 128 algorithm is the default data algorithm method.

    • AES256: http://www.w3.org/2001/04/xmlenc#aes256-cbc

      To use this AES 256-cbc algorithm, download the unrestricted Java Cryptography Extension (JCE) policy file from the following website: http://www.ibm.com/developerworks/java/jdk/security/index.html.

    • AES192: http://www.w3.org/2001/04/xmlenc#aes192-cbc

      Do not use the 192-bit key encryption algorithm if we want our configured application to be in compliance with the Basic Security Profile (BSP).

      To use this AES 192-cbc algorithm, download the unrestricted Java Cryptography Extension (JCE) policy file from the following website: http://www.ibm.com/developerworks/java/jdk/security/index.html.

    • TRIPLE_DES: http://www.w3.org/2001/04/xmlenc#tripledes-cbc

  2. As needed, changes the WSSEncryption API method to specify another data encryption algorithm. For example, you might add the following code to change from the default AES 128 algorithm to the Triple DES algorithm:

      dec.addAllowedKeyEncryptionMethod(WSSDecryption.TRIPLE_DES);
  3. Using the WSSDecryption API, adds the required key encryption algorithm. The key encryption algorithm is used for encrypting the key used for encrypting the message parts within the SOAP message. If no key for encrypting the data is needed, then specify WSSDecryption.encryptKey(false).

    The key encryption algorithm that you select for the consumer side must match the key encryption method that you select for the generator side.

    The default key encryption algorithm value is key wrap RSA_OAEP. The key encryption name is KW_RSA_OAEP, and the URI of the key encryption algorithm is http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p. WAS supports the following pre-configured key encryption algorithms:

    • KW_AES128: http://www.w3.org/2001/04/xmlenc#kw-aes128
    • KW_AES192: http://www.w3.org/2001/04/xmlenc#kw-aes192

      To use this key wrap AES 192 algorithm, download the unrestricted Java Cryptography Extension (JCE) policy file from the following website: http://www.ibm.com/developerworks/java/jdk/security/index.html.

      Restriction: Do not use the 192-bit key encryption algorithm if we want our configured application to be in compliance with the Basic Security Profile (BSP).

    • KW_AES256: http://www.w3.org/2001/04/xmlenc#kw-aes256

      To use this key wrap AES 256-cbc algorithm, download the unrestricted Java Cryptography Extension (JCE) policy file from the following website: http://www.ibm.com/developerworks/java/jdk/security/index.html.

    • KW_RSA_OAEP: http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p.

      The KW_RSA_OAEP algorithm is the default key algorithm method.

      When running with SDK v1.4, the list of supported key transport algorithms does not include this algorithm. This algorithm appears in the list of supported key transport algorithms when running with SDK v1.5. See more information at http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p

    • KW_RSA_15: http://www.w3.org/2001/04/xmlenc#rsa-1_5
    • KW_TRIPLE_DES: http://www.w3.org/2001/04/xmlenc#kw-tripledes

    For Web Services Secure Conversation, the WSSEncryption API might specify addition key-related information, such as the:

    • algorithmName
    • keyLength

  4. As needed, uses the WSSDecryption API method to change to other key encryption algorithms. For example, you might add the following code to change from the default key encryption algorithm KW_RSA_OAEP to the TRIPLE_DES algorithm:

      dec.addAllowedKeyEncryptionMethod(WSSDecryption.KW_TRIPLE_DES);
  5. Using the WSSDecryptPart API, adds a transform algorithm, as needed. There is no default transform algorithm. However, WAS provides a pre-configured decrypted part, WSSDecryptPart.TRANSFORM_ATTACHMENT_CIPHERTEXT, that can be added.


Results

If there is an error condition, a WSSException is provided. If successful, the API calls the WSSConsumerContext.process() method, the WS-Security header is validated, and the SOAP message is now secured using Web Services Security.


Example

The following example provides sample WSS API code for decrypting the body content as well as changing the data encryption and key encryption algorithms from the default values: 

// Get the message context    Object msgcontext = getMessageContext();

// Generate the WSSFactory instance 
   WSSFactory factory = WSSFactory.getInstance();

// Generate the WSSConsumingContext instance 
   WSSConsumingContext gencont = factory.newWSSConsumingContext();

// Generate the callback handler    X509ConsumeCallbackHandler callbackHandler = new 
      X509ConsumeCallbackHandler(
                                 "",
                                 "enc-sender.jceks",
                                 "jceks", 
                                 "storepass".toCharArray(), 
                                 "alice", 
                                 "keypass".toCharArray(), 
                                 "CN=Alice, O=IBM, C=US");

// Generate WSSDecryption instance 
   WSSDecryption dec = factory.newWSSDecryption(X509Token.class, 
                                                callbackHandler);

// Set the candidates for the data encryption method // DEFAULT : WSSDecryption.AES128
   dec.addAllowedEncryptionMethod(WSSDecryption.AES128);
   dec.addAllowedEncryptionMethod(WSSDecryption.AES192);

// Set the candidates for the key encryption method // DEFAULT : WSSDecryption.KW_RSA_OAEP
   dec.addAllowedKeyEncryptionMethod(WSSDecryption.KW_TRIPLE_DES);

// Add the WSSDecryption to WSSConsumingContext 
   concont.add(dec);

// Validate the WS-Security header
concont.process(msgcontext);


Related concepts:

XML encryption


Related


Decrypting SOAP messages using the WSSDecryption API
Configure the consumer security tokens using the WSS API
Encrypting the SOAP message using the WSSEncryption API
Choose encryption methods for generator bindings


Reference:

Decryption methods


Related information:

XML Encryption Syntax and Processing W3C Recommendation 10 December 2002


+

Search Tips   |   Advanced Search