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". |
| 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. |
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 |