This section describes how to use configure Apache WSS4J. This page only applies to WSS4J 2.x, and 1.6.x, a lot of the properties have changed since WSS4J 1.5.x.
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:
${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.
${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.
WSS4J 2.3.0/2.2.6 ${PREFIX}.merlin.keystore.private.caching - Whether to enable caching when loading private keys or not. The default is true for WSS4J 2.3.0 and false for WSS4J 2.2.6. There is a significant performance gain for PKCS12 keys when caching is enabled.
${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().
${PREFIX}.merlin.truststore.provider - WSS4J 2.1.5 The provider used to load truststores. By default it’s the same as the keystore provider. Set to an empty value to force use of the JRE’s default provider.
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:
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. Default is "false".
org.apache.ws.security.saml.callback - The name of the SAML CallbackHandler implementation used to populate the SAML Assertion.
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:
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.
WSS4J 2.3.0 ENCRYPTION (Encryption) - Perform an encryption action. Note that for previous releases, this configuration tag was called ENCRYPT (Encrypt).
TIMESTAMP (Timestamp) - Perform a Timestamp action.
WSS4J 2.0.0 SIGNATURE_DERIVED (SignatureDerived) - Perform a Signature action with derived keys.
WSS4J 2.3.0 ENCRYPTION_DERIVED (EncryptionDerived) - Perform a Encryption action with derived keys. Note that for releases from 2.0.0 → 2.2.x, this configuration tag was called ENCRYPT_DERIVED (EncryptDerived).
WSS4J 2.0.0 SIGNATURE_WITH_KERBEROS_TOKEN (SignatureWithKerberosToken) - Perform a Signature action with a kerberos token. Only for StAX code.
WSS4J 2.3.0 ENCRYPTION_WITH_KERBEROS_TOKEN (EncryptionWithKerberosToken) - Perform a Encryption action with a kerberos token. Only for StAX code. Note that for releases from 2.0.0 → 2.2.x, this configuration tag was called ENCRYPT_WITH_KERBEROS_TOKEN (EncryptWithKerberosToken).
WSS4J 2.0.0 KERBEROS_TOKEN (KerberosToken) - Add a kerberos token. Only for StAX code.
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:
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:
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:
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".
WSS4J 2.0.4/2.1.0 REQUIRE_TIMESTAMP_EXPIRES (requireTimestampExpires) - Set the value of this parameter to true to require that a Timestamp must have an "Expires" Element. The default is "false".
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 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) - (Deprecated in 2.2.0). 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.
WSS4J 2.2.0 EXPAND_XOP_INCLUDE (expandXOPInclude) - Whether to search for and expand xop:Include Elements for encryption and signature (on the outbound side) or for signature verification (on the inbound side). The default is false on the outbound side and true on the inbound side. What this means on the inbound side, is 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:
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 String (separated by the value specified for SIG_CERT_CONSTRAINTS_SEPARATOR) 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.
SIG_ISSUER_CERT_CONSTRAINTS (sigIssuerCertConstraints) - A String (separated by the value specified for SIG_CERT_CONSTRAINTS_SEPARATOR) of regular expressions which will be applied to the issuer DN of the certificate used for signature validation, after trust verification of the certificate chain associated with the certificate.
WSS4J 2.2.3 SIG_CERT_CONSTRAINTS_SEPARATOR (sigCertConstraintsSeparator) - The separator that is used to parse certificate constraints configured in the SIG_SUBJECT_CERT_CONSTRAINTS and SIG_ISSUER_CERT_CONSTRAINTS configuration tags. The default is ",".
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.
DirectReference
IssuerSerial
X509KeyIdentifier
SKIKeyIdentifier
EmbeddedKeyName
Thumbprint
EncryptedKeySHA1
KeyValue
WSS4J 2.0.0 KerberosSHA1