Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

7.21.2.6. X509 Certificate TokenJBOSSCC-50

By using X509v3 certificates, you can both sign and encrypt messages.
Encryption

To configure encryption, you must specify the items in Example 7.5, “X509 Encryption Configuration”. The configuration is the same for clients and servers.

Example 7.5. X509 Encryption Configuration

<jboss-ws-security xmlns="http://www.jboss.com/ws-security/config"
                   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                   xsi:schemaLocation="http://www.jboss.com/ws-security/config
                   http://www.jboss.com/ws-security/schema/jboss-ws-security_1_0.xsd">
(1) <key-store-file>WEB-INF/bob-sign_enc.jks</key-store-file>
    <key-store-password>password</key-store-password>
    <key-store-type>jks</key-store-type>
    <trust-store-file>WEB-INF/wsse10.truststore</trust-store-file>
    <trust-store-password>password</trust-store-password>

    <config>
     <timestamp ttl="300"/>
(2)     <sign type="x509v3" alias="1" includeTimestamp="true"/>
(3)     <encrypt type="x509v3"
              alias="alice"
              algorithm="aes-256"
              keyWrapAlgorithm="rsa_oaep"
              tokenReference="keyIdentifier" />
(4)         <requires>
            <signature/>
              <encryption/>      
            </requires>
    </config>
</jboss-ws-security>
The server configuration includes the following encryption information:
  1. Keystore and Truststore information: location of each store, the password, and type of store.
  2. Signature configuration: you must provide the certificate and key pair aliases to use. includeTimestamp specifies whether the timestamp is signed to prevent tampering.
  3. Encryption configuration: you must provide the certificate and key pair aliases to use. Refer to Algorithms for more information.
  4. Optional security requirements: incoming messages must be both signed, and encrypted.
Dynamic Encryption

When replying to multiple clients, a service provider must encrypt a message according to its destination using the correct public key. The JBossWS native implementation of WS-Security obtains the correct key to use from the signature received (and verified) in the incoming message.

Example 7.6. Dynamic Encryption Configuration

To configure dynamic encryption, do not specify any encryption alias on the server side (1), and declare that a signature is required (2). 
<jboss-ws-security xmlns="http://www.jboss.com/ws-security/config"
                   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                   xsi:schemaLocation="http://www.jboss.com/ws-security/config
                   http://www.jboss.com/ws-security/schema/jboss-ws-security_1_0.xsd">
    <key-store-file>WEB-INF/bob-sign_enc.jks</key-store-file>
    <key-store-password>password</key-store-password>
    <key-store-type>jks</key-store-type>
    <trust-store-file>WEB-INF/wsse10.truststore</trust-store-file>
    <trust-store-password>password</trust-store-password>

    <config>
     <timestamp ttl="300"/>
        <sign type="x509v3" alias="1" includeTimestamp="true"/>
(1)     <encrypt type="x509v3"
              algorithm="aes-256"
              keyWrapAlgorithm="rsa_oaep"
               tokenReference="keyIdentifier" />
            <requires>
(2)         <signature/>
              <encryption/>      
           </requires>
    </config>
</jboss-ws-security>
Algorithms

Asymmetric and symmetric encryption is performed whenever the <encrypt> element is declared. Message data are encrypted using a generated symmetric secured key. This key is written in the SOAP header after being encrypted (wrapped) with the receiver public key. You can set both the encryption and key wrap algorithms.

The supported encryption algorithms include:
  • AES 128 (aes-128) (default)
  • AES 192 (aes-192)
  • AES 256 (aes-256)
  • Triple DES (triple-des)
The supported key-wrap algorithms include:
  • RSA v1.5 (rsa_15) (default)
  • RSA OAEP (rsa_oaep)

Note

The Unlimited Strength Java(TM) Cryptography Extension installation might be required to run some strong algorithms (for example, aes-256). Your country may impose limitations on the allowed cryptographic strength in applications. It is your responsibility to select the encryption level suitable for your jurisdiction.
Encryption Token Reference

For interoperability reasons, you may need to configure the type of reference to encryption token to be used. For example, Microsoft Indigo does not support direct reference to local binary security tokens which are the default reference type used by JBossWS.

To configure this reference, you specify the tokenReference attribute in the <encrypt> element. The values for the tokenReference attribute are:
  • directReference (default)
  • keyIdentifier - specifies the token data by means of an X509 SubjectKeyIdentifier reference.
  • x509IssuerSerial - uniquely identifies an end entity certificate by its X509 Issuer and Serial Number

Note

Complete information about X509 Token Profiles are available in the WSS X501 Certificate Token Profile 1.0 document, which can be obtained from the Oasis.org docs portal.
Targets Configuration

JBossWS gives you precise control over elements that must be signed or encrypted. This allows you to encrypt important data only (such as credit card numbers) instead of other, security-trivial, information exchanged by the same service (email addresses, for example). To configure this, you must specify the Qualified Name (qname) of the SOAP elements to encrypt. The default behavior is to encrypt the whole SOAP body. 

<encrypt type="x509v3" alias="alice">
  <targets>
    <target type="qname">{http://www.my-company.com/cc}CardNumber</target>
    <target type="qname">{http://www.my-company.com/cc}CardExpiration</target>
    <target type="qname" contentOnly="true">{http://www.my-company.com/cc}CustomerData</target>
  </targets>
</encrypt>
Payload Carriage Returns

Signature verification errors can occur in signed message payloads that contain carriage returns (\r) due to the way the special character is parsed by XML parsers. To prevent this issue, you can choose to implement custom encoding before sending the payload. Users can either encrypt the message, or force JBossWS to perform canonical normalization of messages.

The org.jboss.ws.DOMContentCanonicalNormalization property can normalize the payload if set to true in the MessageContext. The property must be set just before the invocation on the client side and in the endpoint implementation.
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2026 Red HatBack to top