This page describes how to use configure Apache WSS4J. This page only applies to WSS4J 1.6, 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 two implementations, the standard "Merlin" implementation, which is based around two JDK keystores for key retrieval and trust verification, as well as a CertificateStore, which is based around a set of X509Certificates (presently supporting encryption/signature verification only). 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. The property values are as follows:
General properties:
| Property name | Property value |
|---|---|
| org.apache.ws.security.crypto.provider | WSS4J specific provider used to create Crypto instances. Defaults to "org.apache.ws.security.components.crypto.Merlin". |
| org.apache.ws.security.crypto.merlin.keystore.provider | The provider used to load keystores. Defaults to installed provider. |
| org.apache.ws.security.crypto.merlin.cert.provider | The provider used to load certificates. Defaults to keystore provider. |
| org.apache.ws.security.crypto.merlin.x509crl.file | The location of an (X509) CRL file to use. |
Keystore properties:
| Property name | Property value |
|---|---|
| org.apache.ws.security.crypto.merlin.keystore.file | The location of the keystore |
| org.apache.ws.security.crypto.merlin.keystore.password | The password used to load the keystore. Default value is "security". |
| org.apache.ws.security.crypto.merlin.keystore.type | Type of keystore. Defaults to: java.security.KeyStore.getDefaultType()) |
| org.apache.ws.security.crypto.merlin.keystore.alias | The default keystore alias to use, if none is specified. |
| org.apache.ws.security.crypto.merlin.keystore.private.password | The default password used to load the private key. |
TrustStore properties:
| Property name | Property value |
|---|---|
| org.apache.ws.security.crypto.merlin.load.cacerts | Whether or not to load the CA certs in ${java.home}/lib/security/cacerts (default is false) |
| org.apache.ws.security.crypto.merlin.truststore.file | The location of the truststore |
| org.apache.ws.security.crypto.merlin.truststore.password | The truststore password. Defaults to "changeit". |
| org.apache.ws.security.crypto.merlin.truststore.type | The truststore type. Defaults to: java.security.KeyStore.getDefaultType(). |
Apache WSS4J uses the SAMLIssuer interface to configure the creation and signing of a SAML Assertion. WSS4J 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. |
Apache WSS4J provides a set of configuration tags for the WSHandler object used for the creation and processing of WS-Security enabled messages. For more information see the WSHandlerConstants Javadoc.
The configuration tags for WSHandler Actions are as follows:
| Tag name | Tag value | Tag meaning |
|---|---|---|
| ACTION | action | The action to perform, e.g. WSHandlerConstants.TIMESTAMP |
| NO_SECURITY | NoSecurity | Do not perform any action, do nothing. |
| 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. |
| 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 WSHandler 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. |
| ENC_CALLBACK_CLASS | embeddedKeyCallbackClass | The CallbackHandler implementation class used to get the key associated with a key name. |
| 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. |
| 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 WSHandler 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". |
| HANDLE_CUSTOM_PASSWORD_TYPES | handleCustomPasswordTypes | Whether to allow non-standard password types in a UsernameToken. Default is "false". |
| PASSWORD_TYPE_STRICT | passwordTypeStrict | Whether to enable strict Username Token password type handling. 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". |
| 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". |
| 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 | useDerivedKey | Whether to use the standard UsernameToken Key Derivation algorithm. 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. Default is "true". |
| ENC_SYM_ENC_KEY | encryptSymmetricEncryptionKey | Set whether to encrypt the symmetric encryption key or not. Default is "true". |
The configuration tags for WSHandler properties that are configured via a non-boolean parameter are as follows:
| Tag name | Tag value | Tag meaning |
|---|---|---|
| ENC_KEY_NAME | embeddedKeyName | The text of the key name to be sent in the KeyInfo for encryption |
| PASSWORD_TYPE | passwordType | The encoding of the password for a Username Token. The default is WSConstants.PW_DIGEST. |
| 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. |
| SIGNATURE_PARTS | signatureParts | Parameter to define which parts of the request shall be signed. The SOAP body is signed by default. |
| WSE_SECRET_KEY_LENGTH | wseSecretKeyLength | The length of the secret (derived) key to use for the WSE UT_SIGN functionality. |
| 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-15. |
| ENCRYPTION_PARTS | encryptionParts | Parameter to define which parts of the request shall be encrypted. The SOAP body is encrypted in "Content" mode by default. |
| 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". |
The configuration values for setting the KeyIdentifiers for signature or encryption are shown below. See the Javadoc for SIG_KEY_ID and ENC_KEY_ID for more details:
| Value |
|---|
| DirectReference |
| IssuerSerial |
| X509KeyIdentifier |
| SKIKeyIdentifier |
| EmbeddedKeyName |
| Thumbprint |
| EncryptedKeySHA1 |