Batch processing in the Apache CXF STS

A previous blog entry covered the ability to renew SAML Tokens in the Security Token Service (STS) in Apache CXF 2.6.0. In this post, we will look at another major new feature in the STS in CXF 2.6.0, namely the addition of batch processing. Batch processing gives the ability to issue, validate, renew or cancel multiple tokens at the same time.

1) Batch Processing in the STS Provider framework

The STS implementation in CXF is based on the STS Provider framework in the security runtime, which is essentially an API that can be used to create your own STS implementation. The SEI (Service Endpoint Implementation) contains the following method that can be used for batch processing:

• RequestSecurityTokenResponseCollectionType requestCollection(RequestSecurityTokenCollectionType requestCollection)

This method can be used to execute batch processing for any of the core operations (issue/validate/renew/cancel). To do this it is necessary to implement the RequestCollectionOperation interface, and to install it in the STS Provider.

2) Batch Processing in the STS implementation

The STS ships with an implementation of the RequestCollectionOperation interface described above that can be used to perform batch processing. The TokenRequestCollectionOperation is essentially a wrapper for the other operations, and does no processing itself. It iterates through the request collection that was received, and checks that each request has the same RequestType. If not then an exception is thrown. It then dispatches each request to the appropriate operation. To support bulk processing for each individual operation, it is necessary to set the appropriate implementation for that operation on the TokenRequestCollectionOperation, otherwise an exception will be thrown.

3) Batch Processing example

Take a look at the following test to see how batch processing works in practice. In this test, the client requests two tokens via the (batch) issue binding, a SAML 1.1 and a SAML 2.0 token. The client then validates both tokens at the same time using the batch validate binding. The STSClient class used by the WS-Security runtime in CXF does not currently support bulk processing. Therefore, the test uses a custom STSClient implementation for this purpose.

The WSDL the STS uses two separate bindings for issue and validate, to cater for the fact that two separate SOAP Actions must be used for bulk issue and validate for the same operation. The STS configuration is available here. Note that the TokenRequestCollectionOperation is composed with the TokenIssueOperation and TokenValidateOperation, to be able to bulk issue and validate security tokens:

<bean class="org.apache.cxf.sts.operation.TokenRequestCollectionOperation" 
  id="transportRequestCollectionDelegate">
  <property name="issueSingleOperation" ref="transportIssueDelegate">
  <property name="validateOperation" ref="transportValidateDelegate>
</bean>

Security Token Caching in Apache CXF 2.6 - part II

This post is the second in a two-part series on how security tokens are cached in Apache CXF 2.6. Part I covered how UsernameToken nonces and Timestamps are cached to prevent replay attacks, using a default caching implementation based on EhCache. In this post I will cover how security tokens are cached in the CXF WS-Security runtime and also in the STS.

1) CXF WS-Security runtime token caching

CXF caches tokens in the security runtime in the following circumstances:

• When the IssuedTokenInterceptorProvider is invoked to obtain an Issued token from an STS.
• When the STSTokenValidator is used to validate a received UsernameToken, BinarySecurityToken or SAML Assertion to an STS.
• When the SecureConversation protocol is used.
• When the WS-Trust SPNEGO protocol is used.
• When tokens are obtained from a Kerberos KDC.

In each of these use-cases, the retrieved token is cached to prevent repeated remote calls to obtain the desired security token. There is no built-in support as yet to cache tokens in the WS-Security layer to prevent repeat validation. Of course this could be easily done by wrapping the existing validators with a custom caching solution.

1.1) SecurityTokens

CXF defines a SecurityToken class which encapsulates all relevant information about a successful authentication event in the security runtime (as defined above). In particular, it contains the following items (amongst others):

• A String identifier of the token. This could be a SAML Assertion Id, the Identifier element of a SecurityContextToken, or the wsu:Id of a UsernameToken, etc.
• The DOM Element that represents that security token.
• Attached and Unattached reference elements for that token that might have been retrieved from an STS.
• A byte[] secret associated with the token.
• An expiration date after which the token is not valid.
• A String TokenType that categorizes the token.
• An X.509 Certificate associated with the token.
• The principal associated with the token.
• A hashcode that represents the security token (normally the hashcode of the underlying WSS4J object).
• An identifier of another SecurityToken that represents a transformed version of this token.

 1.2) TokenStores

CXF defines a TokenStore interface for caching SecurityTokens in the WS-Security runtime module. Prior to CXF 2.6, a simple default HashMap based approach was used to cache security tokens. In CXF 2.6, Ehcache is used to provide a suitable default TokenStore implementation to cache security tokens. Tokens are stored until the expiry date of the token if it exists, provided it does not exceed the maximum storage time of 12 hours. If it exceeds this, or if there is no expiry date provided in the security token, it is cached for the default storage time of 1 hour. If the token is expired then it is not cached. This default storage time is configurable. Note that while Ehcache is a compile time dependency of the WS-Security module in CXF, it can be safely excluded in which case CXF will fall back to use the simple HashMap based cache, unless the user specifically wants to implement an alternative TokenStore implementation and configure this instead.

Apache CXF 2.6 provides support for configuring caching via the following JAX-WS properties:

• "org.apache.cxf.ws.security.tokenstore.TokenStore" - The TokenStore instance to use to cache security tokens. By default this uses the EHCacheTokenStore if Ehcache is available. Otherwise it uses the MemoryTokenStore.
• "ws-security.cache.config.file" - Set this property to point to a configuration file for the underlying caching implementation. By default the cxf-ehcache.xml file in the CXF rt-ws-security module is used.

2) CXF STS token caching

Token caching in the CXF STS has been previously (briefly) covered in the STS documentation. Prior to CXF 2.6, the STS shipped an interface called "STSTokenStore" that contained some additional functionality related to storing SecurityTokens specific to the STS. In CXF 2.6, this interface has been removed, and instead the same TokenStore interface is used as in the security runtime. A TokenStore instance can be set on any of the STS operations (see AbstractOperation), and it will be used for caching in the token providers, validators, etc. The STS ships with two TokenStore implementations, a DefaultInMemoryTokenStore which just wraps the EHCacheTokenStore discussed above, and an implementation based on HazelCast.

Token caching works in different ways depending on where it is used. Both token providers (SAML and SecurityContextTokens) that ship with the STS cache a successfully generated token. When a SAML or SecurityContextToken (or UsernameToken) is received by the STS for validation, it will first check to see whether the token is stored in the cache. If it is then validation is skipped. If it is not, then the TokenValidator will re-validate the token, and store it in the cache if validation is successful. A slight caveat to this behaviour for SAML Tokens is that token validation is only skipped if the token that is stored in the cache originally was signed, as this signature value is used to check to see if the two SAML Tokens are equal. The TokenCanceller implementation for cancelling SecurityContextTokens in the STS removes the token from the cache, if the token is stored in the cache and proof-of-possession passes.

Finally, two significant changes in CXF 2.6.0 concerning caching in the STS relate to the length of time tokens are valid for. Prior to CXF 2.6.0, SecurityContextTokens and SAML Tokens issued by the STS were valid for a default (configurable) value of 5 minutes. In CXF 2.6.0, both tokens are now issued for a default value of 30 minutes, and are stored in the cache for this length of time as a result.

Note on CVE-2011-1096

A new attack on the XML Encryption standard has recently emerged and is described by the security advisory CVE-2011-1096:

Tibor Jager, Juraj Somorovsky, Meiko Jensen, and Jorg Schwenk
described an attack technique against W3C XML Encryption Standard,
when the block ciphers were used in cipher-block chaining (CBC)
mode of operation. A remote attacker, aware of a cryptographic
weakness of the CBC mode could use this flaw to conduct
chosen-ciphertext attacks, leading to the recovery of the entire
plaintext of a particular cryptogram by examining of the differences
between SOAP responses, sent from JBossWS, J2EE Web Services server.

There is no (immediate) security "fix" for this issue, as it is an attack on the standard itself. However, the attack can be prevented by using a symmetric algorithm such as AES-128 or AES-256 with GCM. Support for GCM algorithms is available in Apache Santuario 1.5.0 and Apache WSS4J 1.6.5 (see here).

One problem with using a GCM algorithm via WS-SecurityPolicy is that no AlgorithmSuite policy is defined in the WS-SecurityPolicy 1.3 specification that uses GCM. Until the WS-SecurityPolicy specification is updated to support GCM, Apache CXF has defined its own AlgorithmSuite policies to use GCM algorithms. These AlgorithmSuites are called "Basic128GCM", "Basic192GCM" and "Basic256GCM" in the namespace "http://cxf.apache.org/custom/security-policy", and are exactly the same as the corresponding standard "Basic(128|192|256)" policies, except that GCM is used instead of CBC. For example, to use the AES-128 Algorithm with GCM mode, one would use a policy like:

<sp:AlgorithmSuite>
    <wsp:Policy>
        <sp-cxf:Basic128GCM xmlns:sp-cxf="http://cxf.apache.org/custom/security-policy"/>
    </wsp:Policy>
</sp:AlgorithmSuite>

CXF contains a number of system tests that show how to use these new AlgorithmSuites. The WSDL containing the embedded policies is here, and the test itself is here. This functionality is available from Apache CXF 2.4.7, 2.5.3, and 2.6.0.

In addition to this, the CXF JAX-RS XML Security functionality has been updated so that GCM algorithms can be used for encryption and decryption via the BouncyCastle JCE provider. A test is available here. For more information on the CXF JAX-RS XML Security functionality, checkout Sergey's blog or the CXF wiki page.

Renewing SAML Tokens in the Apache CXF STS

Apache CXF 2.6.0 sees a number of improvements to the functionality of the SecurityTokenService (STS). These include relatively minor tasks such as supporting SymmetricKeys for Entropy and BinarySecret Elements, supporting SecurityTokenReferences in UseKey Elements, and supporting KeyInfo/KeyValue Elements in UseKey Elements. However, the STS also includes two major new features. The first of these new features, the ability to renew (SAML) tokens, is covered in this blog entry.

1) The TokenRenewer interface

Security tokens are renewed in the STS via the TokenRenewer interface. It has the following methods:

• void setVerifyProofOfPossession(boolean verifyProofOfPossession) - A boolean switch to enable or disable the proof of possession requirement.
• void setAllowRenewalAfterExpiry(boolean allowRenewalAfterExpiry) - A switch to enable or disable the ability to renew tokens after they have expired.
• boolean canHandleToken(ReceivedToken renewTarget) - Whether this TokenRenewer implementation can renew the given token.
• boolean canHandleToken(ReceivedToken renewTarget, String realm) - Whether this TokenRenewer implementation can renew the given token in the given realm.
• TokenRenewerResponse renewToken(TokenRenewerParameters tokenParameters) - Renew the token using the given parameters

A client can request that the STS renew a security token by invoking the "renew" operation and supplying a token under the "RenewTarget" Element. Assuming that the client request is authenticated and well-formed, the STS will first iterate through a list of TokenValidator implementations to see if they can "handle" the received token. If they can, then the implementation is used to validate the received security token. If no TokenValidator is found that can handle the RenewTarget that was received, then an exception is thrown. Note that this means that for token renewal, it is necessary to configure both a TokenValidator and TokenRenewer implementation that can handle the given token.

After the successful validation of a token, the state of the token is checked. If the state is not valid or expired, then an exception is thrown. The STS then iterates through the configured list of TokenRenewer implementations to see which can renew the given (validated) token. The token is then renewed and returned to the client.

The TokenRenewerParameters class is nothing more than a collection of configuration properties to use in renewing the token, which are populated by the STS operations using information collated from the request, or static configuration, etc. The TokenRenewerResponse class holds the results from the (successful) token renewal, including the DOM representation of the renewed token, the token Id, the new lifetime of the renewed token, and references to the renewed token. 

2) The SAMLTokenRenewer

The SAMLTokenRenewer can renew valid or expired SAML 1.1 and SAML 2.0 tokens. The following properties can be configured on the SAMLTokenRenewer directly:

• boolean signToken - Whether to sign the renewed token or not. The default is true.
• ConditionsProvider conditionsProvider - An object used to add a Conditions statement to the token.
• Map<String, SAMLRealm> realmMap - A map of realms to SAMLRealm objects. See here for an explanation of realms in the SAMLTokenProvider.
• long maxExpiry - how long a token is allowed to be expired (in seconds) before renewal. The default is 30 minutes.

The SAMLTokenRenewer first checks that the token it extracts from the TokenRenewerParameters is in an expired or valid state, if not it throws an exception. It then retrieves the cached token that corresponds to the token to be renewed. A cache must be configured to use the SAMLTokenRenewer, and the token to be renewed must be in the cache before renewal takes place, for reasons that will become clear in the next section.

2.1) Token validation

Before the received SAML token can be renewed, a number of validation steps (that are specific to renewing SAML tokens) takes place. Two boolean properties are retrieved from the properties of the cached token:

• org.apache.cxf.sts.token.renewing.allow - Whether the token is allowed to be renewed or not.
• org.apache.cxf.sts.token.renewing.allow.after.expiry - Whether the token is allowed to be renewed or not after it has expired.

These two properties are set in the SAMLTokenProvider based on a received "<wst:Renewing/>" element when the user is requesting a SAML token via the issue binding. If a user omits a "<wst:Renewing/>" element, or sends "<wst:Renewing/>" or "<wst:Renewing Allow="true"/>", then the token is allowed to be renewed. However, only if the user sends <wst:Renewing OK=True"/>", will the token be allowed to be renewed after expiry. This explains why a TokenStore is required for token renewal, as without access to these two properties it is impossible for the SAMLTokenRenewer to figure out whether the issuer of the token intended for the token to be renewed (after expiry) or not.

If the state of the token is expired, and if the token is allowed to be renewed after expiry, a final check is done against the boolean set via the "setAllowRenewalAfterExpiry" method of TokenRenewer. If this is set to false (the default), then an exception is thrown. So to support token renewal after expiry, you must explicitly define this behaviour on the TokenRenewer implementation. Finally, a check is done on how long ago the SAML Token expired. If it is greater than the value configured in the "maxExpiry" property (30 minutes by default), then an exception is thrown.

The next validation step is to check proof of possession, if this is enabled (true by default). The Subject KeyInfo of the Assertion must contain a PublicKey or X509Certificate that corresponds to either the client certificate if TLS is used, or to the private key that was used to sign some part of the request. Finally, if an "AppliesTo" URI is sent as part of the request, the SAMLTokenRenewer checks that the received Assertion contains at least one AudienceRestrictionURI that matches that address, otherwise it throws an Exception.

2.2) Renewing the SAML Assertion

After the validation steps outlined above have passed, the token is renewed in the following way:

• A new ID is generated for the token.
• A new "IssueInstant" is set on the token.
• A new Conditions Element replaces the old Conditions Element of the token, using the configured ConditionsProvider.
• The Assertion is (re)-signed if the "signToken" property is true.

The old token is removed from the cache, and the new token is added. Finally, the token is set on the TokenRenewerResponse, along with the token Id, and Lifetime.

3) SAML Token Renewal in action

Finally, let's take a look at a system test in CXF that shows how to renew a SAML Token issued by an STS. The wsdl of the service provider defines a number of endpoints which use the transport binding, with a (endorsing) supporting token requirement which has an IssuedToken policy that requires a SAML token. In other words, the client must request a SAML token from an STS and send it to the service provider over TLS, and optionally use the secret associated with the SAML token to sign the message Timestamp (if an EndorsingSupportingToken policy is specified in the wsdl).

The STS spring configuration is available here. The SAMLTokenRenewer is configured with proof-of-possession enabled, and tokens are allowed to be renewed after they have expired. Let's look at the test code and client configuration. All of the tests follow the same pattern. The client requests a SAML Token from the STS (as per the IssuedToken policy), with a TTL (time-to-live) value of 8 seconds. The client then uses this issued token to make a successful request to the service provider. The test code then sleeps for 8 seconds to expire the token, and tries to invoke on the service provider again. The IssuedTokenInterceptorProvider in the WS-Security runtime in CXF recognises that the token has expired, and sends it to the STS for renewal. The returned (renewed) token is then sent to the service provider.

Security Token Caching in Apache CXF 2.6 - part I

This post is the first of a two-part series on how security tokens are cached in Apache CXF 2.6.0, which has just been released. In this particular post I will examine how Apache CXF provides detection against replay attacks on the WS-Security protocol. Apache WSS4J 1.6.5 provides support for detecting and preventing replay attacks.

1) Replay attacks on the WS-Security protocol

A replay attack in this context is when an adversary intercepts a WS-Security enabled message and sends it again to the original intended target of the message. As the message is a direct copy of the original (presumably valid) message, the normal security processing steps should pass without error. Therefore, some additional steps are required on both the initiator and recipient side to protect against these attacks.

2) Message initiator requirements

The initiator should take either or both of the following steps:

• If the initiator is including a UsernameToken in the message, the initiator should include a nonce in the UsernameToken. A nonce is a random String that can serve as an identifier for the message. The recipient can then cache this value for a certain time period and reject any subsequent message containing this nonce.
• The initiator should include a Timestamp in the security header of the message. This step alone provides a certain protection against a replay attack if it includes an Expires element, which the recipient should reject if it contains a value prior to the time the message was received at. The Created value of the Timestamp can also serve as the basis of a unique identifier to store in a replay cache.

3) Message recipient requirements

A service provider that uses WS-SecurityPolicy can enforce the message requirements defined above on the client by doing the following:

• Use a <sp:HashPassword/> OR a <sp13:Nonce/> policy in the UsernameToken policy.
• Add a <sp:IncludeTimestamp/> to the binding policy.

In addition to this, the recipient must provide a cache to store the UsernameToken nonce values and Timestamp Created values. Note that Timestamp Created values do not provide enough "uniqueness" on their own, as the recipient could receive two valid messages from different clients that were created at the same millisecond in time. Therefore, WSS4J combines the Timestamp Created value with a message Signature value to form a unique identifier. If no message signature is included in the message, then no replay caching is done for Timestamps. However, note that CXF already enforces that a Timestamp must be signed for the Symmetric and Asymmetric WS-SecurityPolicy bindings.

4) Replay caching support in WSS4J

Apache WSS4J 1.6.5 provides support for detecting and preventing replay attacks by introducing the ReplayCache interface. A seperate ReplayCache instance is used to cache UsernameToken nonces and Timestamp Created / Signature Value Strings. WSS4J ships with a sample HashSet based implementation, which is not intended for production use. The default caching time for this implementation is 5 minutes - Timestamps are cached until their expiry time (if it exists), otherwise for 5 minutes.

The ReplayCache implementations to use can be configured via RequestData. No ReplayCache implementation is used by default for backwards compatibility reasons - to enable it you must implement the ReplayCache interface, and set the appropriate methods on RequestData. 

5) Replay caching support in CXF.

Apache CXF 2.6 uses Ehcache to provide a suitable ReplayCache implementation to detect replay attacks. The default cache time for the Ehcache implementation is 60 minutes. No configuration is required for out-of-the-box support for replay attack detection on the message recipient side. Caching is not enabled by default on the inbound initiator side for efficiency reasons. Note that this functionality is available in Apache CXF 2.4.7 and 2.5.3, but is not enabled by default at all for backwards-compatibility reasons. Ehcache is an optional provided dependency for these releases, meaning that you will have to include it as a dependency and enable caching to get replay caching to work. If caching is enabled and Ehcache is not available, then CXF will fall back to using the default HashSet based implementation that ships with WSS4J. Note that this is not intended for production use and will entail performance penalties.

Apache CXF 2.6 provides support for configuring replay caching via the following JAX-WS properties:

• "ws-security.enable.nonce.cache" - The default value is "true" for message recipients, and "false" for message initiators. Set it to true to cache for both cases.
• "ws-security.enable.timestamp.cache" - This uses the same logic as above.
• "ws-security.nonce.cache.instance" - This holds a reference to a ReplayCache instance used to cache UsernameToken nonces. The default instance that is used is the EHCacheReplayCache.
• "ws-security.timestamp.cache.instance" - This uses the same logic as above.
• "ws-security.cache.config.file" - Set this property to point to a configuration file for the underlying caching implementation. By default the cxf-ehcache.xml file in the CXF rt-ws-security module is used.