Apache WSS4J

Project Documentation

WSS4J configuration

This page describes how to use configure Apache WSS4J. This page only applies
to WSS4J 2.1.x, 2.0.x and 1.6.x, a lot of the properties have changed since
WSS4J 1.5.x.

Crypto properties

Apache WSS4J uses the Crypto interface to get keys and certificates for
encryption/decryption and for signature creation/verification. WSS4J ships
with three implementations:

Merlin: The standard implementation, based around two JDK keystores for
key/cert retrieval, and trust verification.

CertificateStore: Holds an array of X509 Certificates. Can only be used
for encryption and signature verification.

MerlinDevice: Based on Merlin, allows loading of keystores using a null
InputStream - for example on a smart-card device.

For more information on the Crypto implementations see the
Special
Topics page. It is possible to instantiate a Crypto implementation
directly, but it can also be loaded via a properties file. For Apache WSS4J
2.0.0 onwards, the property names ${PREFIX} below is "org.apache.wss4j.crypto".
For Apache WSS4J 1.6.x, the property names ${PREFIX} below is
"org.apache.ws.security.crypto". WSS4J 2.0.0 onwards will also accept the older
${PREFIX} value. The property values for the standard Merlin implementation
are as follows:

SAML properties

WSS4J 1.6.x only Apache WSS4J 1.6.x uses the SAMLIssuer interface to
configure the creation and signing of a SAML Assertion. In Apache WSS4J 2.0.0,
the SAMLIssuer functionality has been moved to the SAMLCallback, so that the
CallbackHandler used to create a SAML Assertion is responsible for all of the
signing configuration as well.

WSS4J 1.6.x ships with a default "SAMLIssuerImpl" implementation. It is
possible to instantiate a SAMLIssuer implementation directly, but it can also
be loaded via a properties file. The property values are as follows:

The crypto properties file corresponding to the issuer crypto instance, if the assertion is to
be signed.

org.apache.ws.security.saml.issuer.key.name

The KeyStore alias for the issuer key.

org.apache.ws.security.saml.issuer.key.password

The KeyStore password for the issuer key.

org.apache.ws.security.saml.issuer

The issuer name

org.apache.ws.security.saml.issuer.sendKeyValue

Whether to send the key value or the X509Certificate. Default is "false".

org.apache.ws.security.saml.issuer.signAssertion

Whether the SAMLIssuer implementation will sign the assertion or not. Defaults is
"false".

org.apache.ws.security.saml.callback

The name of the SAML CallbackHandler implementation used to populate the SAML Assertion.

Configuration tags

Apache WSS4J provides a set of configuration tags that can be used to configure
both the DOM-based and StAX-based (WSS4J 2.0.0 onwards) outbound and inbound
processing. As both DOM and StAX code are very similar, both approaches share
a set of common configuration tags given in ConfigurationConstants. Note
that the WSS4J 1.6.x configuration class (WSHandlerConstants) extends this
class in WSS4J 2.0.0, so there is no need to change any configuration code
when upgrading.

The configuration tags for Actions are as follows:

Tag name

Tag value

Tag meaning

ACTION

action

The action to perform, e.g. ConfigurationConstants.TIMESTAMP

NO_SECURITY

NoSecurity

Do not perform any action, do nothing. Only applies to DOM code.

WSS4J 2.0.0 USERNAME_TOKEN_SIGNATURE

UsernameTokenSignature

Perform a UsernameTokenSignature action.

USERNAME_TOKEN

UsernameToken

Perform a UsernameToken action.

USERNAME_TOKEN_NO_PASSWORD

UsernameTokenNoPassword

Used on the receiving side to specify a UsernameToken with no password

SAML_TOKEN_UNSIGNED

SAMLTokenUnsigned

Perform an unsigned SAML Token action.

SAML_TOKEN_SIGNED

SAMLTokenSigned

Perform a signed SAML Token action.

SIGNATURE

Signature

Perform a signature action.

ENCRYPT

Encrypt

Perform an encryption action.

TIMESTAMP

Timestamp

Perform a Timestamp action.

WSS4J 2.0.0 SIGNATURE_DERIVED

SignatureDerived

Perform a Signature action with derived keys.

WSS4J 2.0.0 ENCRYPT_DERIVED

EncryptDerived

Perform a Encryption action with derived keys.

WSS4J 2.0.0 SIGNATURE_WITH_KERBEROS_TOKEN

SignatureWithKerberosToken

Perform a Signature action with a kerberos token. Only for StAX code.

WSS4J 2.0.0 ENCRYPT_WITH_KERBEROS_TOKEN

EncryptWithKerberosToken

Perform a Encryption action with a kerberos token. Only for StAX code.

WSS4J 2.0.0 KERBEROS_TOKEN

KerberosToken

Add a kerberos token.

WSS4J 2.0.0 CUSTOM_TOKEN

CustomToken

Add a "Custom" token from a CallbackHandler

WSS4J 1.6.x only SIGN_WITH_UT_KEY

UsernameTokenSignature

Perform a .NET specific signature using a Username Token action.

The configuration tags for WSHandler user properties are as follows:

Tag name

Tag value

Tag meaning

ACTOR

"actor"

The actor or role name of the wsse:Security header.

USER

"user"

The user's name. Consult the Javadoc for an explanation of this property.

ENCRYPTION_USER

"encryptionUser"

The user's name for encryption. Consult the Javadoc for an explanation of
this property.

SIGNATURE_USER

"signatureUser"

The user's name for signature. Consult the Javadoc for an explanation of
this property.

USE_REQ_SIG_CERT

"useReqSigCert"

A special value for ENCRYPTION_USER. Consult the Javadoc for an
explanation of this property.

The configuration tags for callback class and property file configuration are
summarised here:

Tag name

Tag value

Tag meaning

PW_CALLBACK_CLASS

passwordCallbackClass

The CallbackHandler implementation class used to obtain passwords.

PW_CALLBACK_REF

passwordCallbackRef

The CallbackHandler implementation object used to obtain passwords.

SAML_CALLBACK_CLASS

samlCallbackClass

The CallbackHandler implementation class used to construct SAML Assertions.

SAML_CALLBACK_REF

samlCallbackRef

The CallbackHandler implementation object used to construct SAML Assertions.

WSS4J 1.6.x only ENC_CALLBACK_CLASS

embeddedKeyCallbackClass

The CallbackHandler implementation class used to get the key associated
with a key name.

WSS4J 1.6.x only ENC_CALLBACK_REF

embeddedKeyCallbackRef

The CallbackHandler implementation object used to get the key associated
with a key name.

SIG_PROP_FILE

signaturePropFile

The path of the crypto property file to use for Signature.

SIG_PROP_REF_ID

signaturePropRefId

The String ID that is used to store a reference to the Crypto object or
the Crypto Properties object for Signature.

WSS4J 2.0.0 SIG_VER_PROP_FILE

signatureVerificationPropFile

The path of the crypto property file to use for Signature verification.

WSS4J 2.0.0 SIG_VER_PROP_REF_ID

signatureVerificationPropRefId

The String ID that is used to store a reference to the Crypto object or
the Crypto Properties object for Signature verification.

DEC_PROP_FILE

decryptionPropFile

The path of the crypto property file to use for Decryption.

DEC_PROP_REF_ID

decryptionPropRefId

The String ID that is used to store a reference to the Crypto object or
the Crypto Properties object for decryption.

ENC_PROP_FILE

encryptionPropFile

The path of the crypto property file to use for encryption.

ENC_PROP_REF_ID

encryptionPropRefId

The String ID that is used to store a reference to the Crypto object or
the Crypto Properties object for encryption.

SAML_PROP_FILE

samlPropFile

The path of the property file to use for creating SAML Assertions.

The configuration tags for properties that are configured via a boolean
parameter (i.e. "true" or "false") are as follows:

Tag name

Tag value

Tag meaning

ENABLE_SIGNATURE_CONFIRMATION

enableSignatureConfirmation

Whether to enable signature confirmation or not. Default is "false".

MUST_UNDERSTAND

mustUnderstand

Set the outbound MustUnderstand flag or not. Default is "true".

IS_BSP_COMPLIANT

isBSPCompliant

Whether or not to ensure compliance with the BSP 1.1 spec. Default is
"true".

WSS4J 2.0.0 ADD_INCLUSIVE_PREFIXES

addInclusivePrefixes

Whether to add an InclusiveNamespaces PrefixList as a
CanonicalizationMethod child when generating Signatures using
WSConstants.C14N_EXCL_OMIT_COMMENTS. Default is "true".

WSS4J 2.0.0 ADD_USERNAMETOKEN_NONCE

addUsernameTokenNonce

Whether to add a Nonce Element to a UsernameToken (for plaintext). Default
is "false"

WSS4J 2.0.0 ADD_USERNAMETOKEN_CREATED

addUsernameTokenCreated

Whether to add a Created Element to a UsernameToken (for plaintext).
Default is "false"

HANDLE_CUSTOM_PASSWORD_TYPES

handleCustomPasswordTypes

Whether to allow non-standard password types in a UsernameToken. Default
is "false".

Whether to validate the SubjectConfirmation requirements of a received
SAML Token (sender-vouches or holder-of-key). Default is "true".

WSS4J 2.0.0 INCLUDE_SIGNATURE_TOKEN

includeSignatureToken

Whether to include the Signature Token in the security header as well or
not (for IssuerSerial, Thumbprint, SKI cases). Default is "false"

WSS4J 2.0.0 INCLUDE_ENCRYPTION_TOKEN

includeEncryptionToken

Whether to include the Encryption Token in the security header as well or
not (for IssuerSerial, Thumbprint, SKI cases). Default is "false"

WSS4J 2.0.0 ENABLE_NONCE_CACHE

enableNonceCache

Whether to cache UsernameToken nonces. Default is "true"

WSS4J 2.0.0 ENABLE_TIMESTAMP_CACHE

enableTimestampCache

Whether to cache Timestamp Created Strings (these are only cached in
conjunction with a message Signature). Default is "true"

WSS4J 2.0.0 ENABLE_SAML_ONE_TIME_USE_CACHE

enableSamlOneTimeUseCache

Whether to cache SAML2 Token Identifiers, if the token contains a
"OneTimeUse" Condition. Default is "true".

WSS4J 2.0.0 USE_2005_12_NAMESPACE

use200512Namespace

Whether to use the 2005/12 namespace for SecureConveration + DerivedKeys,
or the older namespace. The default is "true"

WSS4J 2.1.2/2.0.5 GET_SECRET_KEY_FROM_CALLBACK_HANDLER

getSecretKeyFromCallbackHandler

Whether to get a secret key from a CallbackHandler or not for encryption
only. The default is false. If set to true WSS4J attempts to get the secret
key from the CallbackHandler instead of generating a random key internally.

WSS4J 2.1.2/2.0.5 STORE_BYTES_IN_ATTACHMENT

storeBytesInAttachment

Whether to store bytes (CipherData or BinarySecurityToken) in an
attachment. The default is false, meaning that bytes are BASE-64 encoded and
"inlined" in the message. Setting this to true is more efficient, as it means
that the BASE-64 encoding step can be skipped. For this to work, a
CallbackHandler must be set on RequestData that can handle attachments.

WSS4J 2.1.2/2.0.5 EXPAND_XOP_INCLUDE_FOR_SIGNATURE

expandXOPIncludeForSignature

Whether to expand xop:Include Elements encountered when verifying a
Signature. The default is true, meaning that the relevant attachment bytes are
BASE-64 encoded and inserted into the Element. This ensures that the actual
bytes are signed, and not just the reference.

The configuration tags for properties that are configured via a non-boolean
parameter are as follows:

Tag name

Tag value

Tag meaning

PASSWORD_TYPE

passwordType

The encoding of the password for a Username Token. The default is
WSConstants.PW_DIGEST.

WSS4J 1.6.x only ENC_KEY_NAME

embeddedKeyName

The text of the key name to be sent in the KeyInfo for encryption

WSS4J 1.6.x only ADD_UT_ELEMENTS

addUTElements

Additional elements to add to a Username Token, i.e. "nonce" and "created".

SIG_KEY_ID

signatureKeyIdentifier

The key identifier type to use for signature. The default is "IssuerSerial".

SIG_ALGO

signatureAlgorithm

The signature algorithm to use. The default is set by the data in the
certificate.

The length of the secret (derived) key to use for the WSE UT_SIGN
functionality.

SIGNATURE_PARTS

signatureParts

Parameter to define which parts of the request shall be signed. The SOAP
body is signed by default.

WSS4J 2.0.0 OPTIONAL_SIGNATURE_PARTS

optionalSignatureParts

Parameter to define which parts of the request shall be signed, if they
exist in the request.

DERIVED_KEY_ITERATIONS

derivedKeyIterations

The number of iterations to use when deriving a key from a Username Token.
The default is 1000.

ENC_KEY_ID

encryptionKeyIdentifier

The key identifier type to use for encryption. The default is
"IssuerSerial".

ENC_SYM_ALGO

encryptionSymAlgorithm

The symmetric encryption algorithm to use. The default is AES-128.

ENC_KEY_TRANSPORT

encryptionKeyTransportAlgorithm

The algorithm to use to encrypt the generated symmetric key. The default is RSA-OAEP.

ENC_DIGEST_ALGO

encryptionDigestAlgorithm

The encryption digest algorithm to use with the RSA-OAEP key transport
algorithm. The default is SHA-1.

ENCRYPTION_PARTS

encryptionParts

Parameter to define which parts of the request shall be encrypted. The
SOAP body is encrypted in "Content" mode by default.

WSS4J 2.0.0 OPTIONAL_ENCRYPTION_PARTS

optionalEncryptionParts

Parameter to define which parts of the request shall be encrypted, if they
exist in the request.

WSS4J 2.0.0 ENC_MGF_ALGO

encryptionMGFAlgorithm

Defines which encryption mgf algorithm to use with the RSA OAEP Key
Transport algorithm for encryption. The default is mgfsha1.

TTL_TIMESTAMP

timeToLive

The time difference between creation and expiry time in seconds in the WSS
Timestamp. The default is "300".

TTL_FUTURE_TIMESTAMP

futureTimeToLive

The time in seconds in the future within which the Created time of an
incoming Timestamp is valid. The default is "60".

TTL_USERNAMETOKEN

utTimeToLive

The time difference between creation and expiry time in seconds in the WSS
UsernameToken created element. The default is "300".

TTL_FUTURE_USERNAMETOKEN

utFutureTimeToLive

The time in seconds in the future within which the Created time of an
incoming UsernameToken is valid. The default is "60".

SIG_SUBJECT_CERT_CONSTRAINTS

sigSubjectCertConstraints

A comma separated String of regular expressions which will be applied to
the subject DN of the certificate used for signature validation, after trust
verification of the certificate chain associated with the certificate.

WSS4J 2.0.0 VALIDATOR_MAP

validatorMap

A map of QName, Object (Validator) instances to be used to validate
tokens identified by their QName.

WSS4J 2.0.0 NONCE_CACHE_INSTANCE

nonceCacheInstance

A ReplayCache instance used to cache UsernameToken nonces. The default
instance that is used is the EHCacheReplayCache.

WSS4J 2.0.0 TIMESTAMP_CACHE_INSTANCE

timestampCacheInstance

A ReplayCache instance used to cache Timestamp Created Strings. The default
instance that is used is the EHCacheReplayCache.

WSS4J 2.0.0 SAML_ONE_TIME_USE_CACHE_INSTANCE

samlOneTimeUseCacheInstance

A ReplayCache instance used to cache SAML2 Token Identifier Strings (if
the token contains a OneTimeUse Condition). The default instance that is used
is the EHCacheReplayCache.

WSS4J 2.0.0 PASSWORD_ENCRYPTOR_INSTANCE

passwordEncryptorInstance

A PasswordEncryptor instance used to decrypt encrypted passwords in Crypto
properties files. The default is the JasyptPasswordEncryptor.

WSS4J 2.0.0 DERIVED_TOKEN_REFERENCE

derivedTokenReference

This controls how deriving tokens are referenced.

WSS4J 2.0.0 DERIVED_TOKEN_KEY_ID

derivedTokenKeyIdentifier

This controls the key identifier of Derived Tokens.

WSS4J 2.0.0 DERIVED_SIGNATURE_KEY_LENGTH

derivedSignatureKeyLength

The length to use (in bytes) when deriving a key for Signature.

WSS4J 2.0.0 DERIVED_ENCRYPTION_KEY_LENGTH

derivedEncryptionKeyLength

The length to use (in bytes) when deriving a key for Encryption.

The configuration values for setting the KeyIdentifiers for signature or
encryption are shown below. For an in depth explanation
with examples, see this blog entry.