WSS4J configuration

This page describes how to use configure Apache WSS4J. This page only applies to WSS4J 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 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 will also accept the older ${PREFIX} value. The property values for the standard Merlin implementation are as follows:

General properties:

Property name Property value
${PREFIX}.provider WSS4J specific provider used to create Crypto instances. Defaults to "org.apache.wss4j.common.crypto.Merlin".
${PREFIX}.merlin.x509crl.file The location of an (X509) CRL file to use.

Keystore properties:

Property name Property value
${PREFIX}.merlin.keystore.provider The provider used to load keystores. Defaults to installed provider.
${PREFIX}.merlin.cert.provider The provider used to load certificates. Defaults to keystore provider.
${PREFIX}.merlin.keystore.file The location of the keystore
${PREFIX}.merlin.keystore.password The password used to load the keystore. Default value is "security".
${PREFIX}.merlin.keystore.type Type of keystore. Defaults to: java.security.KeyStore.getDefaultType())
${PREFIX}.merlin.keystore.alias The default keystore alias to use, if none is specified.
${PREFIX}.merlin.keystore.private.password The default password used to load the private key.

TrustStore properties:

Property name Property value
${PREFIX}.merlin.load.cacerts Whether or not to load the CA certs in ${java.home}/lib/security/cacerts (default is false)
${PREFIX}.merlin.truststore.file The location of the truststore
${PREFIX}.merlin.truststore.password The truststore password. Defaults to "changeit".
${PREFIX}.merlin.truststore.type The truststore type. Defaults to: java.security.KeyStore.getDefaultType().

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:

Property name Property value
org.apache.ws.security.saml.issuerClass The SAML Issuer implementation (defaults to "org.apache.ws.security.saml.SAMLIssuerImpl").
org.apache.ws.security.saml.issuer.cryptoProp.file 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".
WSS4J 1.6.X only PASSWORD_TYPE_STRICT passwordTypeStrict Whether to enable strict Username Token password type handling. Default is "false".
WSS4J 2.0.0 ALLOW_USERNAMETOKEN_NOPASSWORD allowUsernameTokenNoPassword Whether a UsernameToken with no password element is allowed. Default is "false".
REQUIRE_SIGNED_ENCRYPTED_DATA_ELEMENTS requireSignedEncryptedDataElements Whether the engine needs to enforce EncryptedData elements are in a signed subtree of the document. Default is "false".
WSS4J 1.6.X only USE_DERIVED_KEY useDerivedKey Whether to use the standard UsernameToken Key Derivation algorithm. Default is "true".
ALLOW_NAMESPACE_QUALIFIED_PASSWORD_TYPES allowNamespaceQualifiedPasswordTypes Whether (wsse) namespace qualified password types are accepted when processing UsernameTokens. Default is "false".
ENABLE_REVOCATION enableRevocation Whether to enable Certificate Revocation List (CRL) checking when verifying trust in a certificate. Default is "false".
USE_ENCODED_PASSWORDS useEncodedPasswords Set whether to treat passwords as binary values for Username Tokens. Default is "false". DOM code only.
USE_SINGLE_CERTIFICATE useSingleCertificate Whether to use a single certificate or a whole certificate chain to construct a BinarySecurityToken. Default is "true".
USE_DERIVED_KEY_FOR_MAC useDerivedKeyForMAC Whether to use the Username Token derived key for a MAC. Default is "true".
TIMESTAMP_PRECISION precisionInMilliseconds Set whether outbound timestamps have precision in milliseconds. Default is "true".
TIMESTAMP_STRICT timestampStrict Set whether to enable strict Timestamp handling, i.e. throw an exception if the current receiver time is past the Expires time of the Timestamp. Default is "true".
ENC_SYM_ENC_KEY encryptSymmetricEncryptionKey Set whether to encrypt the symmetric encryption key or not. Default is "true".
WSS4J 2.0.0 ALLOW_RSA15_KEY_TRANSPORT_ALGORITHM allowRSA15KeyTransportAlgorithm Whether to allow the RSA v1.5 Key Transport Algorithm or not. Default is "false".
WSS4J 2.0.0 VALIDATE_SAML_SUBJECT_CONFIRMATION validateSamlSubjectConfirmation 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"

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.
SIG_DIGEST_ALGO signatureDigestAlgorithm The signature digest algorithm to use. The default is SHA-1.
SIG_C14N_ALGO signatureC14nAlgorithm Defines which signature c14n (canonicalization) algorithm to use. The default is: "http://www.w3.org/2001/10/xml-exc-c14n#".
WSS4J 1.6.X only WSE_SECRET_KEY_LENGTH wseSecretKeyLength 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.

Value
DirectReference
IssuerSerial
X509KeyIdentifier
SKIKeyIdentifier
EmbeddedKeyName
Thumbprint
EncryptedKeySHA1
KeyValue
WSS4J 2.0.0 KerberosSHA1