Protecting message authenticity by validating the consumer token

Validating the consumer token to protect message authenticity

The token consumer information is used on the consumer side to incorporate and validate the security token. The Username token, X509 tokens, and LTPA tokens by default are used for message authenticity.

The token processing and pluggable token architecture in the Web Services Security run time reuses the same security token interface and Java Authentication and Authorization Service (JAAS) Login Module from the Web Services Security APIs (WSS API). The same implementation of token creation and validation can be used in both the WSS API and the WSS SPI in the Web Services Security run time.
Restriction: The com.ibm.wsspi.wssecurity.token.TokenConsumingComponent interface is not used with JAX-WS web services. If we are using JAX-RPC web services, this interface is still valid.
Note that the key name (KeyName) element is not supported because there is no KeyName policy assertion defined in the current OASIS Web Services Security draft specification.

The JAAS callback handler (CallbackHandler) and the JAAS login module (LoginModule) are responsible for creating the security token on the generator side and validating (authenticating) the security token on the consumer side.
For example, on the generator side, the Username token is created by the JAAS LoginModule and using the JAAS CallbackHandler to pass the authentication data. The JAAS LoginModule creates the Username SecurityToken object and passes it to the Web Services Security run time.
Then, on the consumer side, the Username Token XML format is passed to the JAAS LoginModule for validation or authentication and the JAAS CallbackHandler is used to pass authentication data from the Web Services Security run time to the LoginModule. After the token is authenticated, a Username SecurityToken object is created and passed it to the Web Services Security run time.
WAS does not support a stackable login module with the WAS default login module implementation, meaning adding the login module before or after the WAS login module implementation. To stack the login module implementations, you must develop the required login modules because there is no default implementation.
The com.ibm.websphere.wssecurity.wssapi.token package provided by WebSphere Application Server includes support for these classes:

Security token (SecurityTokenImpl)

Binary security token (BinarySecurityTokenImpl)

In addition, WebSphere Application Server provides the following pre-configured sub-interfaces for security tokens:

Derived key token

Security context token (SCT)

Username token

LTPA token propagation

LTPA token

X509PKCS7 token

X509PKIPath token

X509v3 token

Kerberos v5 token

The Username token, the X.509 tokens, and the LTPA tokens are used by default for message authenticity. The derived key token and the X.509 tokens are used by default for signing and encryption.
The WSS API and WSS SPI are only supported on the client. To specify the security token type on the consumer side, we can also configure policy sets using the console. We can also use the WSS APIs or policy sets for matching generator security tokens.
The default Login Module and Callback implementations are designed to be used as a pair, meaning both a generator and a consumer part. To use the default implementations, select the appropriate generator and consumer security token in a pair. For example, select system.wss.generate.x509 in the token generator and system.wss.consume.x509 in the token consumer when the X.509 token is required.
To configure the consumer-side security token, use the appropriate pre-configured token consumer interface from the WSS APIs to complete the following token configuration process steps:

Generate the wssFactory instance.

Generate the wssConsumingContext instance.
The WSSConsumingContext interface stores the components for consuming Web Services Security (WS-Security), such as verification, decryption, the security token, and the time stamp. When the validate() method is called, all of these components are validated.

Create the consumer-side components, such as the WSSVerification and the WSSDecryption objects.

Specify a JAAS configuration by specifying the name of the JAAS login configuration. The JAAS configuration specifies the name of the JAAS configuration. The JAAS configuration specifies how the token logs in on the consumer side. Do not remove the predefined system or application login configurations. However, within these configurations, we can add module class names and specify the order in which WebSphere Application Server loads each module.

Specify a token consumer class name. The token consumer class name specifies the required information to validate the SecurityToken. The Username token, the X.509 tokens, and the LTPA tokens are used by default for message authenticity.

Specify the settings for the callback handler by specifying a callback handler class name and also specifies the callback handler keys. This class name is the name of the callback handler implementation class used for the plug-in to the security token framework.
WebSphere Application Server provides the following default callback handler implementations for the consumer side:

com.ibm.websphere.wssecurity.callbackhandler.PropertyCallback

This class is a callback for handling the name-value pair in elements in the Web Services Security (WS-Security) configuration XMI files.

ccom.ibm.websphere.wssecurity.callbackhandler.UNTConsumeCallbackHandler

This class is a callback handler for the Username token on the consumer side. This instance is used to set into WSSConsumingContext object to validate a Username token. Use this implementation for a Java EE application client only.

com.ibm.websphere.wssecurity.callbackhandler.X509ConsumeCallbackHandler

This class is a callback handler used to validate the X.509 certificate that is inserted in the Web Services Security header within the SOAP message as a binary security token on the consumer side. This instance is used to generate the WSSVerification object and WSSDecryption objects, set the objects into WSSConsumingContext object to validate the X.509 binary security tokens. A keystore and a key definition are required for this callback handler. If we use this implementation, a key store password, path, and type must have been provided on the generator side.

com.ibm.websphere.wssecurity.callbackhandler.LTPAConsumeCallbackHandler

This class is a callback handler for the Lightweight Third Party Authentication (LTPA) tokens on the consumer side. This instance is used to generate the WSSVerification and WSSDecryption objects to validate an LTPA token.
This callback handler is used to validate the LTPA security token inserted in the Web Services Security header within the SOAP message as a binary security token. However, if the user name and password are specified, WebSphere Application Server authenticates the user name and password to obtain the LTPA security token rather than obtaining it from the Run As Subject. Use this callback handler only when the web service is acting as a client on the application server. IBM recommends that we do not use this callback handler on a Java EE application client. If we use this implementation, a basic authentication user ID and password must have been provided on the generator side.

com.ibm.websphere.wssecurity.callbackhandler.KRBTokenConsumeCallbackHandler

This class is a callback handler for the Kerberos v5 token on the consumer side. This instance is used to set the WSSConsumingContext object to consume the Kerberos v5 AP-REQ as a binary security token. The instance is also used to generate the WSSVerification and WSSDecryption objects to use the Kerberos session key or derived key in the SOAP message verification and decryption.

If a X.509 token is specified, additional token information is also specified.

for the X.509 token. Use the X.509 token to authenticate
Token Information Description
keyStoreRef The reference name of the keystore used for the key locator.
keyStorePath The keystore file path from which the keystore is loaded, if needed. IBM recommends that you use the ${USER_INSTALL_ROOT} in the path name as this variable expands to the WAS path on the machine. This path is required when you use the X.509 tokens callback handler implementations.
keyStorePassword The password used to check the integrity of the keystore, or the keystore password used to unlock the keystore and to access the keystore file. The keystore and its configuration are used for some of the default callback handler implementations provided by WebSphere Application Server.
keyStoreType The keystore type of keystore used for the key locator. This selection indicates the format used by the keystore file. The following values are available for selection:

JKS

Use this option if the keystore uses the Java Keystore (JKS) format.

JCEKS

Use this option if the Java Cryptography Extension is configured in the SDK. The default IBM JCE is configured in WebSphere Application Server. This option provides stronger protection for stored private keys by using Triple DES encryption.

JCERACFKS

Use JCERACFKS if the certificates are stored in a SAF key ring (z/OS only).

PKCS11KS (PKCS11)

Use this format if the keystore uses the PKCS#11 file format. Keystores using this format might contain RSA keys on cryptographic hardware or might contain encrypt keys that use cryptographic hardware to ensure protection.

PKCS12KS (PKCS12)

Use this option if the keystore uses the PKCS#12 file format.

alias The key alias name. The key alias is used by the key locator to find the key within the keystore file.
keyPassword The key password used for recovering the key. This password is needed to access the key object within the keystore file.
keyName The name of the key. For digital signatures, the key name is used by the request generator or response consumer signing information to determine which key is used to digitally sign the message. For encryption, the key name is used to determine the key used for encryption. The key name must be a fully qualified, distinguished name (DN). For example, CN=Bob,O=IBM,C=US.
trustAnchorPath The file path from which the trust anchor is loaded.
trustAnchorType The type of trust anchor.
trustAnchorPassword The password used to check the integrity of the trust anchor or the password used to unlock the keystore.
certStores A list of certificate stores. A collection certificate store includes a list of untrusted, intermediary certificates and certificate revocation lists (CRLs). The collection certificate store is used to validate the certificate path of the incoming X.509-formatted security tokens.
provider The security provider.

The following can be specified for a X.509 token:

Without any keystore.

With a trust anchor. A trust anchor specifies a list of keystore configurations containing trusted root certificates. These configurations are used to validate the certificate path of incoming X.509-formatted security tokens. For example, when you select the trust anchor or the certificate store of a trusted certificate, configure the trust anchor and the certificate store before setting the certificate path.

With a keystore used for the key locator.
First, you must have created the keystore file, by using a key tool utility, for example. The keystore is used to retrieve the X.509 certificate. This entry specifies the password used to access the keystore file. Keystore objects within trust anchors contain trusted root certificates used by the CertPath API to validate the trustworthiness of a certificate chain. The names of the trust anchor and the collection certificate store are created in the certificate path under the token consumer.

With a keystore used for the key locator and the trust anchor.

With a map that includes key-value pairs. For example, you might specify the value type name and the value type Uniform Resource Identifier (URI). The value type specifies the namespace URI of the value type for the consumer token, and represents the token type of this class:

ValueType: http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3

Specifies an X.509 certificate token.

ValueType: http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509PKIPathv1

Specifies X.509 certificates in a public key infrastructure (PKI) path. This callback handler is used to create X.509 certificates encoded with the PkiPath format. The certificate is inserted in the Web Services Security header within the SOAP message as a binary security token. A keystore is required for this callback handler. A CRL is not supported by the callback handler; therefore, the collection certificate store is not required or used. If we use this implementation, you must provide a key store password, path, and type on this panel.

ValueType: http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#PKCS7

List of X.509 certificates and certificate revocation lists in a PKCS#7 format. This callback handler is used to create X.509 certificates encoded with the PKCS#7 format. The certificate is inserted in the Web Services Security header in the SOAP message as a binary security token. A keystore is required for this callback handler. We can specify a certificate revocation list (CRL) in the collection certificate store. The CRL is encoded with the X.509 certificate in the PKCS#7 format. If we use this implementation, provide a key store password, path, and type.

For some tokens, WebSphere Application Server provides a predefined local name for the value type. When specified the following local name, we do not need to specify a value type URI:

ValueType: http://www.ibm.com/websphere/appserver/tokentype/5.0.2

For an LTPA token, we can use LTPA for the value type local name. This local name causes http://www.ibm.com/websphere/appserver/tokentype/5.0.2 to be specified for the value type Uniform Resource Identifier (URI).

ValueType: http://www.ibm.com/websphere/appserver/tokentype/5.0.2

For LTPA token propagation, we can use LTPA_PROPAGATION for the value type local name. This local name causeshttp://www.ibm.com/websphere/appserver/tokentype to be specified for the value type Uniform Resource Identifier (URI).

If the Username token is specified as the token consumer class name, the following token information can be specified:

Whether to specify the nonce.
This option indicates whether a Nonce is included for the token consumer. Nonce is a unique, cryptographic number embedded in a message to help stop repeat, unauthorized attacks of Username tokens. Nonce is valid only when the validating token type is a Username token, and it is available only for the response consumer binding.

Keyword of the time stamp. This option indicates whether to verify a time stamp in the Username token. The time stamp is valid only when the incorporated token type is a Username token.

Specifies a map that includes key-value pairs. For example, you might specify the value type name and the value type Uniform Resource Identifier (URI). The value type specifies the namespace URI of the value type for the consumer token, and represents the token type of this class:

URI value type: http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#UsernameToken

Specifies a Username token.

If a Kerberos v5 token is specified as the token generator class name, the following token information can be specified:

Token Information Description Default Value
tokenValueType Kerberos token value type in QName defined by Oasis Kerberos Token Profile v1.1 specification. http://docs.oasis-open.org/wss/oasis-wss-kerberos-token-profile-1.1#GSS_Kerberosv5_AP_REQ
requireDKT A boolean value to require a derived key for message protection. false
clabel The client label for the derived key. WS-SecureConversation
Specify null to use the default value.
slabel The service label for the derived key. WS-SecureConversation
Specify null to use the default value.
keylen The length of the derived key. 16
Specify zero to use the default value
supportTokenRequireSHA1 A boolean value to require a SHA1 key used in subsequent request messages when the Kerberos token is used as a supporting token. false
SHA1 key is consumed only if the supporting Kerberos token is protected. If set to true, the SHA1 key is always consumed.
decComponent An instance of WSSDecryption . Set decComponent and verComponent to null to initialize this first for either the decryption or verification component. Then, use the initialized component only in the callback handler constructor for the second component.
verComponent An instance of WSSVerfication. Set decComponent and verComponent to null to initialize this first for either the decryption or verification component. Then, use the initialized component only in the callback handler constructor for the second component.

Additional token value types are defined in the OASIS Kerberos Token Profile v1.1 specification. Specify the token value type as the local name. It is not necessary to specify the value type URI for the Kerberos v5 token.

http://docs.oasis-open.org/wss/oasis-wss-kerberos-token-profile-1.1#Kerberosv5_AP_REQ

http://docs.oasis-open.org/wss/oasis-wss-kerberos-token-profile-1.1#Kerberosv5_AP_REQ1510

http://docs.oasis-open.org/wss/oasis-wss-kerberos-token-profile-1.1#GSS_Kerberosv5_AP_REQ1510

http://docs.oasis-open.org/wss/oasis-wss-kerberos-token-profile-1.1#Kerberosv5_AP_REQ4120

http://docs.oasis-open.org/wss/oasis-wss-kerberos-token-profile-1.1#GSS_Kerberosv5_AP_REQ4120

If secure conversation is used for message protection, then the following information must be specified:

Information Description
EncryptionAlgorithm This determines the key size.
cLabel The client label used when creating the derived key.
sLabel The server label used when creating the derived key.

Set the components into the wssConsumingContext object.

Invoke the wssConsumingContext.process() method.

Results
Use the WSS APIs, we have configured the token consumer.

What to do next
Specify a similar token generator configuration, if not already completed.

Subtopics

Configure the consumer security tokens using the WSS API
We can secure the SOAP messages, without using policy sets, using the Web Services Security APIs. To configure the token on the consumer side, use the Web Services Security APIs (WSS API). The consumer security tokens are part of the com.ibm.websphere.wssecurity.wssapi.token interface package.

Related concepts

Derived key token
Security context token
Binary security token
Security token
Username token
XML token

Related tasks

Attaching the generator token using WSS APIs to protect message authenticity

Token Information	Description
keyStoreRef	The reference name of the keystore used for the key locator.
keyStorePath	The keystore file path from which the keystore is loaded, if needed. IBM recommends that you use the ${USER_INSTALL_ROOT} in the path name as this variable expands to the WAS path on the machine. This path is required when you use the X.509 tokens callback handler implementations.
keyStorePassword	The password used to check the integrity of the keystore, or the keystore password used to unlock the keystore and to access the keystore file. The keystore and its configuration are used for some of the default callback handler implementations provided by WebSphere Application Server.
keyStoreType	The keystore type of keystore used for the key locator. This selection indicates the format used by the keystore file. The following values are available for selection: JKS Use this option if the keystore uses the Java Keystore (JKS) format. JCEKS Use this option if the Java Cryptography Extension is configured in the SDK. The default IBM JCE is configured in WebSphere Application Server. This option provides stronger protection for stored private keys by using Triple DES encryption. JCERACFKS Use JCERACFKS if the certificates are stored in a SAF key ring (z/OS only). PKCS11KS (PKCS11) Use this format if the keystore uses the PKCS#11 file format. Keystores using this format might contain RSA keys on cryptographic hardware or might contain encrypt keys that use cryptographic hardware to ensure protection. PKCS12KS (PKCS12) Use this option if the keystore uses the PKCS#12 file format.
alias	The key alias name. The key alias is used by the key locator to find the key within the keystore file.
keyPassword	The key password used for recovering the key. This password is needed to access the key object within the keystore file.
keyName	The name of the key. For digital signatures, the key name is used by the request generator or response consumer signing information to determine which key is used to digitally sign the message. For encryption, the key name is used to determine the key used for encryption. The key name must be a fully qualified, distinguished name (DN). For example, CN=Bob,O=IBM,C=US.
trustAnchorPath	The file path from which the trust anchor is loaded.
trustAnchorType	The type of trust anchor.
trustAnchorPassword	The password used to check the integrity of the trust anchor or the password used to unlock the keystore.
certStores	A list of certificate stores. A collection certificate store includes a list of untrusted, intermediary certificates and certificate revocation lists (CRLs). The collection certificate store is used to validate the certificate path of the incoming X.509-formatted security tokens.
provider	The security provider.

Token Information	Description	Default Value
tokenValueType	Kerberos token value type in QName defined by Oasis Kerberos Token Profile v1.1 specification.	http://docs.oasis-open.org/wss/oasis-wss-kerberos-token-profile-1.1#GSS_Kerberosv5_AP_REQ
requireDKT	A boolean value to require a derived key for message protection.	false
clabel	The client label for the derived key.	WS-SecureConversation Specify null to use the default value.
slabel	The service label for the derived key.	WS-SecureConversation Specify null to use the default value.
keylen	The length of the derived key.	16 Specify zero to use the default value
supportTokenRequireSHA1	A boolean value to require a SHA1 key used in subsequent request messages when the Kerberos token is used as a supporting token.	false SHA1 key is consumed only if the supporting Kerberos token is protected. If set to true, the SHA1 key is always consumed.
decComponent	An instance of WSSDecryption .	Set decComponent and verComponent to null to initialize this first for either the decryption or verification component. Then, use the initialized component only in the callback handler constructor for the second component.
verComponent	An instance of WSSVerfication.	Set decComponent and verComponent to null to initialize this first for either the decryption or verification component. Then, use the initialized component only in the callback handler constructor for the second component.

Information	Description
EncryptionAlgorithm	This determines the key size.
cLabel	The client label used when creating the derived key.
sLabel	The server label used when creating the derived key.