Attaching the generator token using WSS APIs to protect message authenticity

Attaching the generator token using WSS APIs to protect message authenticity

When specified the token generator, the information is used on the generator side to generate the security token.

The token processing and pluggable token architecture in the Web Services Security run time reuses the same security token interface and 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.TokenGeneratorComponent 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 in the application server 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, we 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 generator side, we can also configure policy sets using the console. We can also use the WSS APIs or policy sets for matching consumer 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 generator-side security token, use the appropriate pre-configured token generator interface from the WSS APIs to complete the following token configuration process steps:

Generate the wssFactory instance.

Generate the wssGenerationContext instance.
The WSSGenerationContext interface stores the components for generating Web Services Security (WS-Security), such as the signing and encryption information, the security token, and the time stamp. When the generate() method is called, all of these components are generated.

Create the generator-side components, such as the WSSSignature and the WSSEncryption 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.

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

Specifiy 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.
The callback handler implementation obtains the required security token and passes it to the token generator. The token generator inserts the security token in the Web Services Security header within the SOAP message. Also, the token generator is a plug-in point for the pluggable security token framework. Service providers can provide their own implementation, but the implementation must use the WSSGenerationContext interface.
WebSphere Application Server provides the following default callback handler implementations for the generator 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.

com.ibm.websphere.wssecurity.callbackhandler.UNTGUIPromptCallbackHandler

This class is a callback handler for the Username token with the GUI prompt on the generator side. This instance is used to set the WSSGenerationContext object to generate a Username token.

com.ibm.websphere.wssecurity.callbackhandler.UNTGenerateCallbackHandler

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

com.ibm.websphere.wssecurity.callbackhandler.X509GenerateCallbackHandler

This class is a callback handler used to generate the X.509 certificate that is inserted in the Web Services Security header within the SOAP message as a binary security token on the generator side. This instance is used to generate the WSSSignature and WSSEncryption objects, set the objects into the WSSGenerationContext object to generate 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 be provided on the generator side.

com.ibm.websphere.wssecurity.callbackhandler.LTPAGenerateCallbackHandler

This class is a callback handler for the Lightweight Third Party Authentication (LTPA) tokens on the generator side. This instance is used to generate WSSSignature object and WSSEncryption object to generate a 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 generator side. This instance is used to set the WSSGenerationContext object to generate the Kerberos v5 AP-REQ as a binary security token. The instance is also used to generate the WSSSignature and WSSEncryption objects to use the Kerberos session key or derived key in the SOAP message signature and encryption.

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

Token Information Description
storeRef The reference name of the keystore.
storePath 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 using the X.509 tokens callback handler implementations.
storePassword 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.
storeType 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 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 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.
certStores A list of certificate stores. A collection certificate store includes a list of untrusted, intermediary certificates and certificate revocation lists (CRLs). This step configures a collection certificate store and certificate revocation lists for the generator bindings.
identityAssertion Whether identity assertion is used. Selects this item if identity assertion is defined. This option indicates that only the identity of the initial sender is required and inserted into the Web Services Security header within the SOAP message. For an X.509 token generator, the application server sends the original signer certification only.
requestorCertificate Whether the certificate of the requestor is used.

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, we must have created the keystore file, 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.

With 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 generated 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, we 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 causes http://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 generator class name, the following token information can be specified:

Whether to use IdentityAssertion option. This option is selected if identity assertion is defined. This option indicates that only the identity of the initial sender is required and inserted into the Web Services Security header within the SOAP message. For example, WebSphere Application Server sends only the user name of the original caller for a Username token generator.

Whether to use RunAsSubject identity option. This option is used if an identity assertion is defined and to use the Run As identity instead of the initial caller identity for identity assertion in a downstream call. This option is valid only if you have configured the Username token as the token generator.

Whether to use sendRealm.

Whether to specify the nonce.
This option indicates whether a Nonce is included for the token generator. 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 generated token type is a Username token, and it is available only for the request generator 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 generated 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 the Kerberos v5 token is specified as the token generator class name, the following token information can be specified:

Token Information Description Default Value
name Kerberos client principal name

password Kerberos client password

realm Kerberos realm associated with the Kerberos client Default realm name in Kerberos configuration file.
Specify null to use the default value.
targetService Kerberos service name associated with the target web services.

targetHost Kerberos realm name associated with the Kerberos service name.

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
targetRealm Kerberos realm name associated with the Kerberos service name. Default realm name in the Kerberos configuration file
prompt A boolean value to enable the login prompt. false
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 true, the SHA1 key is always consumed.
alwaysAPREQ A boolean value to indicate that the client should always send the Kerberos AP_REQ token in the request messages. false
The SHA1 key is used instead in the subsequent messages. If true, the Kerberos AP_REQ token is always used.
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
noncelen The length of the nonce. 16
Specify zero to use the default value
encComponent An instance of WSSEncryption. Set encComponent and sigComponent to null to initialize this first for either the encryption or signature component. Then, use the initialized component only in the callback handler constructor for the second component.
sigComponent An instance of WSSSignature. Set encComponent and sigComponent to null to initialize this first for either the encryption or signature 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. 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, the following information must be specified:

Information Description
bootstrapWSSGenerationContext The bootstrap configuration used to secure the RequestSecurityToken (RST) token.
bootstrapWSSConmingContext The bootstrap configuration used for consuming a secured RequestSecurityTokenResponse (RSTR).
ENDPOINT_URL The service end point URL.
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 wssGenerationContext object.

Invoke the wssGenerationContext.process() method.

Results
Use the Web Services Security API (WSS API) process, we can configured the token generator.

What to do next
Next, specify a similar token consumer configuration.

Subtopics

Configure generator 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 generator side, use the Web Services Security APIs (WSS API). The generator 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

Validating the consumer token to protect message authenticity

Token Information	Description
storeRef	The reference name of the keystore.
storePath	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 using the X.509 tokens callback handler implementations.
storePassword	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.
storeType	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 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 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.
certStores	A list of certificate stores. A collection certificate store includes a list of untrusted, intermediary certificates and certificate revocation lists (CRLs). This step configures a collection certificate store and certificate revocation lists for the generator bindings.
identityAssertion	Whether identity assertion is used. Selects this item if identity assertion is defined. This option indicates that only the identity of the initial sender is required and inserted into the Web Services Security header within the SOAP message. For an X.509 token generator, the application server sends the original signer certification only.
requestorCertificate	Whether the certificate of the requestor is used.

Token Information	Description	Default Value
name	Kerberos client principal name
password	Kerberos client password
realm	Kerberos realm associated with the Kerberos client	Default realm name in Kerberos configuration file. Specify null to use the default value.
targetService	Kerberos service name associated with the target web services.
targetHost	Kerberos realm name associated with the Kerberos service name.
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
targetRealm	Kerberos realm name associated with the Kerberos service name.	Default realm name in the Kerberos configuration file
prompt	A boolean value to enable the login prompt.	false
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 true, the SHA1 key is always consumed.
alwaysAPREQ	A boolean value to indicate that the client should always send the Kerberos AP_REQ token in the request messages.	false The SHA1 key is used instead in the subsequent messages. If true, the Kerberos AP_REQ token is always used.
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
noncelen	The length of the nonce.	16 Specify zero to use the default value
encComponent	An instance of WSSEncryption.	Set encComponent and sigComponent to null to initialize this first for either the encryption or signature component. Then, use the initialized component only in the callback handler constructor for the second component.
sigComponent	An instance of WSSSignature.	Set encComponent and sigComponent to null to initialize this first for either the encryption or signature component. Then, use the initialized component only in the callback handler constructor for the second component.

Information	Description
bootstrapWSSGenerationContext	The bootstrap configuration used to secure the RequestSecurityToken (RST) token.
bootstrapWSSConmingContext	The bootstrap configuration used for consuming a secured RequestSecurityTokenResponse (RSTR).
ENDPOINT_URL	The service end point URL.
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.