Chapter 6. Message Protection Abstract The following message protection mechanisms are described in this chapter: protection against eavesdropping (by employing encryption algorithms) and protection against message tampering (by employing message digest algorithms). The protection can be applied at various levels of granularity and to different protocol layers. At the transport layer, you have the option of applying protection to the entire contents of the message; while at the SOAP layer, you have the option of applying protection to various parts of the message (bodies, headers, or attachments). 6.1. Transport Layer Message Protection Overview Transport layer message protection refers to the message protection (encryption and signing) that is provided by the transport layer. For example, HTTPS provides encryption and message signing features using SSL/TLS. In fact, WS-SecurityPolicy does not add much to the HTTPS feature set, because HTTPS is already fully configurable using Blueprint XML configuration (see Chapter 3, Configuring HTTPS ). An advantage of specifying a transport binding policy for HTTPS, however, is that it enables you to embed security requirements in the WSDL contract. Hence, any client that obtains a copy of the WSDL contract can discover what the transport layer security requirements are for the endpoints in the WSDL contract. Warning If you enable SSL/TLS security in the transport layer, you must ensure that you explicitly disable the SSLv3 protocol, in order to safeguard against the Poodle vulnerability (CVE-2014-3566) . For more details, see Disabling SSLv3 in JBoss Fuse 6.x and JBoss A-MQ 6.x . Prerequisites If you use WS-SecurityPolicy to configure the HTTPS transport, you must also configure HTTPS security appropriately in the Blueprint configuration. Example 6.1, "Client HTTPS Configuration in Blueprint" shows how to configure a client to use the HTTPS transport protocol. The sec:keyManagers element specifies the client's own certificate, alice.pfx , and the sec:trustManagers element specifies the trusted CA list. Note how the http:conduit element's name attribute uses wildcards to match the endpoint address. For details of how to configure HTTPS on the client side, see Chapter 3, Configuring HTTPS . Example 6.1. Client HTTPS Configuration in Blueprint Example 6.2, "Server HTTPS Configuration in Blueprint" shows how to configure a server to use the HTTPS transport protocol. The sec:keyManagers element specifies the server's own certificate, bob.pfx , and the sec:trustManagers element specifies the trusted CA list. For details of how to configure HTTPS on the server side, see Chapter 3, Configuring HTTPS . Example 6.2. Server HTTPS Configuration in Blueprint Important You must set secureSocketProtocol to TLSv1 on the server side, in order to protect against the Poodle vulnerability (CVE-2014-3566) Policy subject A transport binding policy must be applied to an endpoint policy subject (see the section called "Endpoint policy subject" ). For example, given the transport binding policy with ID, UserNameOverTransport_IPingService_policy , you could apply the policy to an endpoint binding as follows: Syntax The TransportBinding element has the following syntax: Sample policy Example 6.3, "Example of a Transport Binding" shows an example of a transport binding that requires confidentiality and integrity using the HTTPS transport (specified by the sp:HttpsToken element) and a 256-bit algorithm suite (specified by the sp:Basic256 element). Example 6.3. Example of a Transport Binding sp:TransportToken This element has a two-fold effect: it requires a particular type of security token and it indicates how the transport is secured. For example, by specifying the sp:HttpsToken , you indicate that the connection is secured by the HTTPS protocol and the security tokens are X.509 certificates. sp:AlgorithmSuite This element specifies the suite of cryptographic algorithms to use for signing and encryption. For details of the available algorithm suites, see Section 6.2.7, "Specifying the Algorithm Suite" . sp:Layout This element specifies whether to impose any conditions on the order in which security headers are added to the SOAP message. The sp:Lax element specifies that no conditions are imposed on the order of security headers. The alternatives to sp:Lax are sp:Strict , sp:LaxTimestampFirst , or sp:LaxTimestampLast . sp:IncludeTimestamp If this element is included in the policy, the runtime adds a wsu:Timestamp element to the wsse:Security header. By default, the timestamp is not included. sp:MustSupportRefKeyIdentifier This element specifies that the security runtime must be able to process Key Identifier token references, as specified in the WS-Security 1.0 specification. A key identifier is a mechanism for identifying a key token, which may be used inside signature or encryption elements. Apache CXF requires this feature. sp:MustSupportRefIssuerSerial This element specifies that the security runtime must be able to process Issuer and Serial Number token references, as specified in the WS-Security 1.0 specification. An issuer and serial number is a mechanism for identifying a key token, which may be used inside signature or encryption elements. Apache CXF requires this feature. 6.2. SOAP Message Protection 6.2.1. Introduction to SOAP Message Protection Overview By applying message protection at the SOAP encoding layer, instead of at the transport layer, you have access to a more flexible range of protection policies. In particular, because the SOAP layer is aware of the message structure, you can apply protection at a finer level of granularity-for example, by encrypting and signing only those headers that actually require protection. This feature enables you to support more sophisticated multi-tier architectures. For example, one plaintext header might be aimed at an intermediate tier (located within a secure intranet), while an encrypted header might be aimed at the final destination (reached through an insecure public network). Security bindings As described in the WS-SecurityPolicy specification, one of the following binding types can be used to protect SOAP messages: sp:TransportBinding -the transport binding refers to message protection provided at the transport level (for example, through HTTPS). This binding can be used to secure any message type, not just SOAP, and it is described in detail in the preceding section, Section 6.1, "Transport Layer Message Protection" . sp:AsymmetricBinding -the asymmetric binding refers to message protection provided at the SOAP message encoding layer, where the protection features are implemented using asymmetric cryptography (also known as public key cryptography). sp:SymmetricBinding -the symmetric binding refers to message protection provided at the SOAP message encoding layer, where the protection features are implemented using symmetric cryptography. Examples of symmetric cryptography are the tokens provided by WS-SecureConversation and Kerberos tokens. Message protection The following qualities of protection can be applied to part or all of a message: Encryption. Signing. Signing+encryption (sign before encrypting). Encryption+signing (encrypt before signing). These qualities of protection can be arbitrarily combined in a single message. Thus, some parts of a message can be just encrypted, while other parts of the message are just signed, and other parts of the message can be both signed and encrypted. It is also possible to leave parts of the message unprotected. The most flexible options for applying message protection are available at the SOAP layer ( sp:AsymmetricBinding or sp:SymmetricBinding ). The transport layer ( sp:TransportBinding ) only gives you the option of applying protection to the whole message. Specifying parts of the message to protect Currently, Apache CXF enables you to sign or encrypt the following parts of a SOAP message: Body -sign and/or encrypt the whole of the soap:BODY element in a SOAP message. Header(s) -sign and/or encrypt one or more SOAP message headers. You can specify the quality of protection for each header individually. Attachments -sign and/or encrypt all of the attachments in a SOAP message. Elements -sign and/or encrypt specific XML elements in a SOAP message. Role of configuration Not all of the details required for message protection are specified using policies. The policies are primarily intended to provide a way of specifying the quality of protection required for a service. Supporting details, such as security tokens, passwords, and so on, must be provided using a separate, product-specific mechanism. In practice, this means that in Apache CXF, some supporting configuration details must be provided in Blueprint XML configuration files. For details, see Section 6.2.6, "Providing Encryption Keys and Signing Keys" . 6.2.2. Basic Signing and Encryption Scenario Overview The scenario described here is a client-server application, where an asymmetric binding policy is set up to encrypt and sign the SOAP body of messages that pass back and forth between the client and the server. Example scenario Figure 6.1, "Basic Signing and Encryption Scenario" shows an overview of the basic signing and encryption scenario, which is specified by associating an asymmetric binding policy with an endpoint in the WSDL contract. Figure 6.1. Basic Signing and Encryption Scenario Scenario steps When the client in Figure 6.1, "Basic Signing and Encryption Scenario" invokes a synchronous operation on the recipient's endpoint, the request and reply message are processed as follows: As the outgoing request message passes through the WS-SecurityPolicy handler, the handler processes the message in accordance with the policies specified in the client's asymmetric binding policy. In this example, the handler performs the following processing: Encrypt the SOAP body of the message using Bob's public key. Sign the encrypted SOAP body using Alice's private key. As the incoming request message passes through the server's WS-SecurityPolicy handler, the handler processes the message in accordance with the policies specified in the server's asymmetric binding policy. In this example, the handler performs the following processing: Verify the signature using Alice's public key. Decrypt the SOAP body using Bob's private key. As the outgoing reply message passes back through the server's WS-SecurityPolicy handler, the handler performs the following processing: Encrypt the SOAP body of the message using Alice's public key. Sign the encrypted SOAP body using Bob's private key. As the incoming reply message passes back through the client's WS-SecurityPolicy handler, the handler performs the following processing: Verify the signature using Bob's public key. Decrypt the SOAP body using Alice's private key. 6.2.3. Specifying an AsymmetricBinding Policy Overview The asymmetric binding policy implements SOAP message protection using asymmetric key algorithms (public/private key combinations) and does so at the SOAP layer. The encryption and signing algorithms used by the asymmetric binding are similar to the encryption and signing algorithms used by SSL/TLS. A crucial difference, however, is that SOAP message protection enables you to select particular parts of a message to protect (for example, individual headers, body, or attachments), whereas transport layer security can operate only on the whole message. Policy subject An asymmetric binding policy must be applied to an endpoint policy subject (see the section called "Endpoint policy subject" ). For example, given the asymmetric binding policy with ID, MutualCertificate10SignEncrypt_IPingService_policy , you could apply the policy to an endpoint binding as follows: Syntax The AsymmetricBinding element has the following syntax: Sample policy Example 6.4, "Example of an Asymmetric Binding" shows an example of an asymmetric binding that supports message protection with signatures and encryption, where the signing and encryption is done using pairs of public/private keys (that is, using asymmetric cryptography). This example does not specify which parts of the message should be signed and encrypted, however. For details of how to do that, see Section 6.2.5, "Specifying Parts of Message to Encrypt and Sign" . Example 6.4. Example of an Asymmetric Binding sp:InitiatorToken The initiator token refers to the public/private key-pair owned by the initiator. This token is used as follows: The token's private key signs messages sent from initiator to recipient. The token's public key verifies signatures received by the recipient. The token's public key encrypts messages sent from recipient to initiator. The token's private key decrypts messages received by the initiator. Confusingly, this token is used both by the initiator and by the recipient. However, only the initiator has access to the private key so, in this sense, the token can be said to belong to the initiator. In Section 6.2.2, "Basic Signing and Encryption Scenario" , the initiator token is the certificate, Alice. This element should contain a nested wsp:Policy element and sp:X509Token element as shown. The sp:IncludeToken attribute is set to AlwaysToRecipient , which instructs the runtime to include Alice's public key with every message sent to the recipient. This option is useful, in case the recipient wants to use the initiator's certificate to perform authentication. The most deeply nested element, WssX509V3Token10 is optional. It specifies what specification version the X.509 certificate should conform to. The following alternatives (or none) can be specified here: sp:WssX509V3Token10 This optional element is a policy assertion that indicates that an X509 Version 3 token should be used. sp:WssX509Pkcs7Token10 This optional element is a policy assertion that indicates that an X509 PKCS7 token should be used. sp:WssX509PkiPathV1Token10 This optional element is a policy assertion that indicates that an X509 PKI Path Version 1 token should be used. sp:WssX509V1Token11 This optional element is a policy assertion that indicates that an X509 Version 1 token should be used. sp:WssX509V3Token11 This optional element is a policy assertion that indicates that an X509 Version 3 token should be used. sp:WssX509Pkcs7Token11 This optional element is a policy assertion that indicates that an X509 PKCS7 token should be used. sp:WssX509PkiPathV1Token11 This optional element is a policy assertion that indicates that an X509 PKI Path Version 1 token should be used. sp:RecipientToken The recipient token refers to the public/private key-pair owned by the recipient. This token is used as follows: The token's public key encrypts messages sent from initiator to recipient. The token's private key decrypts messages received by the recipient. The token's private key signs messages sent from recipient to initiator. The token's public key verifies signatures received by the initiator. Confusingly, this token is used both by the recipient and by the initiator. However, only the recipient has access to the private key so, in this sense, the token can be said to belong to the recipient. In Section 6.2.2, "Basic Signing and Encryption Scenario" , the recipient token is the certificate, Bob. This element should contain a nested wsp:Policy element and sp:X509Token element as shown. The sp:IncludeToken attribute is set to Never , because there is no need to include Bob's public key in the reply messages. Note In Apache CXF, there is never a need to send Bob's or Alice's token in a message, because both Bob's certificate and Alice's certificate are provided at both ends of the connection-see Section 6.2.6, "Providing Encryption Keys and Signing Keys" . sp:AlgorithmSuite This element specifies the suite of cryptographic algorithms to use for signing and encryption. For details of the available algorithm suites, see Section 6.2.7, "Specifying the Algorithm Suite" . sp:Layout This element specifies whether to impose any conditions on the order in which security headers are added to the SOAP message. The sp:Lax element specifies that no conditions are imposed on the order of security headers. The alternatives to sp:Lax are sp:Strict , sp:LaxTimestampFirst , or sp:LaxTimestampLast . sp:IncludeTimestamp If this element is included in the policy, the runtime adds a wsu:Timestamp element to the wsse:Security header. By default, the timestamp is not included. sp:EncryptBeforeSigning If a message part is subject to both encryption and signing, it is necessary to specify the order in which these operations are performed. The default order is to sign before encrypting. But if you include this element in your asymmetric policy, the order is changed to encrypt before signing. Note Implicitly, this element also affects the order of the decryption and signature verification operations. For example, if the sender of a message signs before encrypting, the receiver of the message must decrypt before verifying the signature. sp:EncryptSignature This element specifies that the message signature must be encrypted (by the encryption token, specified as described in Section 6.2.6, "Providing Encryption Keys and Signing Keys" ). Default is false. Note The message signature is the signature obtained directly by signing various parts of the message, such as message body, message headers, or individual elements (see Section 6.2.5, "Specifying Parts of Message to Encrypt and Sign" ). Sometimes the message signature is referred to as the primary signature , because the WS-SecurityPolicy specification also supports the concept of an endorsing supporting token, which is used to sign the primary signature. Hence, if an sp:EndorsingSupportingTokens element is applied to an endpoint, you can have a chain of signatures: the primary signature, which signs the message itself, and the secondary signature, which signs the primary signature. For more details about the various kinds of endorsing supporting token, see the section called "SupportingTokens assertions" . sp:ProtectTokens This element specifies that signatures must cover the token used to generate that signature. Default is false. sp:OnlySignEntireHeadersAndBody This element specifies that signatures can be applied only to an entire body or to entire headers, not to sub-elements of the body or sub-elements of a header. When this option is enabled, you are effectively prevented from using the sp:SignedElements assertion (see Section 6.2.5, "Specifying Parts of Message to Encrypt and Sign" ). 6.2.4. Specifying a SymmetricBinding Policy Overview The symmetric binding policy implements SOAP message protection using symmetric key algorithms (shared secret key) and does so at the SOAP layer. Examples of a symmetric binding are the Kerberos protocol and the WS-SecureConversation protocol. Note Currently, Apache CXF supports only WS-SecureConversation tokens in a symmetric binding. Policy subject A symmetric binding policy must be applied to an endpoint policy subject (see the section called "Endpoint policy subject" ). For example, given the symmetric binding policy with ID, SecureConversation_MutualCertificate10SignEncrypt_IPingService_policy , you could apply the policy to an endpoint binding as follows: Syntax The SymmetricBinding element has the following syntax: Sample policy Example 6.5, "Example of a Symmetric Binding" shows an example of a symmetric binding that supports message protection with signatures and encryption, where the signing and encryption is done using a single symmetric key (that is, using symmetric cryptography). This example does not specify which parts of the message should be signed and encrypted, however. For details of how to do that, see Section 6.2.5, "Specifying Parts of Message to Encrypt and Sign" . Example 6.5. Example of a Symmetric Binding sp:ProtectionToken This element specifies a symmetric token to use for both signing and encrypting messages. For example, you could specify a WS-SecureConversation token here. If you want to use distinct tokens for signing and encrypting operations, use the sp:SignatureToken element and the sp:EncryptionToken element in place of this element. sp:SignatureToken This element specifies a symmetric token to use for signing messages. It should be used in combination with the sp:EncryptionToken element. sp:EncryptionToken This element specifies a symmetric token to use for encrypting messages. It should be used in combination with the sp:SignatureToken element. sp:AlgorithmSuite This element specifies the suite of cryptographic algorithms to use for signing and encryption. For details of the available algorithm suites, see Section 6.2.7, "Specifying the Algorithm Suite" . sp:Layout This element specifies whether to impose any conditions on the order in which security headers are added to the SOAP message. The sp:Lax element specifies that no conditions are imposed on the order of security headers. The alternatives to sp:Lax are sp:Strict , sp:LaxTimestampFirst , or sp:LaxTimestampLast . sp:IncludeTimestamp If this element is included in the policy, the runtime adds a wsu:Timestamp element to the wsse:Security header. By default, the timestamp is not included. sp:EncryptBeforeSigning When a message part is subject to both encryption and signing, it is necessary to specify the order in which these operations are performed. The default order is to sign before encrypting. But if you include this element in your symmetric policy, the order is changed to encrypt before signing. Note Implicitly, this element also affects the order of the decryption and signature verification operations. For example, if the sender of a message signs before encrypting, the receiver of the message must decrypt before verifying the signature. sp:EncryptSignature This element specifies that the message signature must be encrypted. Default is false. sp:ProtectTokens This element specifies that signatures must cover the token used to generate that signature. Default is false. sp:OnlySignEntireHeadersAndBody This element specifies that signatures can be applied only to an entire body or to entire headers, not to sub-elements of the body or sub-elements of a header. When this option is enabled, you are effectively prevented from using the sp:SignedElements assertion (see Section 6.2.5, "Specifying Parts of Message to Encrypt and Sign" ). 6.2.5. Specifying Parts of Message to Encrypt and Sign Overview Encryption and signing provide two kinds of protection: confidentiality and integrity, respectively. The WS-SecurityPolicy protection assertions are used to specify which parts of a message are subject to protection. Details of the protection mechanisms, on the other hand, are specified separately in the relevant binding policy (see x Section 6.2.3, "Specifying an AsymmetricBinding Policy" , Section 6.2.4, "Specifying a SymmetricBinding Policy" , and Section 6.1, "Transport Layer Message Protection" ). The protection assertions described here are really intended to be used in combination with SOAP security, because they apply to features of a SOAP message. Nonetheless, these policies can also be satisfied by a transport binding (such as HTTPS), which applies protection to the entire message, rather than to specific parts. Policy subject A protection assertion must be applied to a message policy subject (see the section called "Message policy subject" ). In other words, it must be placed inside a wsdl:input , wsdl:output , or wsdl:fault element in a WSDL binding. For example, given the protection policy with ID, MutualCertificate10SignEncrypt_IPingService_header_Input_policy , you could apply the policy to a wsdl:input message part as follows: Protection assertions The following WS-SecurityPolicy protection assertions are supported by Apache CXF: SignedParts EncryptedParts SignedElements EncryptedElements ContentEncryptedElements RequiredElements RequiredParts Syntax The SignedParts element has the following syntax: The EncryptedParts element has the following syntax: Sample policy Example 6.6, "Integrity and Encryption Policy Assertions" shows a policy that combines two protection assertions: a signed parts assertion and an encrypted parts assertion. When this policy is applied to a message part, the affected message bodies are signed and encrypted. In addition, the message header named CustomHeader is signed. Example 6.6. Integrity and Encryption Policy Assertions sp:Body This element specifies that protection (encryption or signing) is applied to the body of the message. The protection is applied to the entire message body: that is, the soap:Body element, its attributes, and its content. sp:Header This element specifies that protection is applied to the SOAP header specified by the header's local name, using the Name attribute, and namespace, using the Namespace attribute. The protection is applied to the entire message header, including its attributes and its content. sp:Attachments This element specifies that all SOAP with Attachments (SwA) attachments are protected. 6.2.6. Providing Encryption Keys and Signing Keys Overview The standard WS-SecurityPolicy policies are designed to specify security requirements in some detail: for example, security protocols, security algorithms, token types, authentication requirements, and so on, are all described. But the standard policy assertions do not provide any mechanism for specifying associated security data, such as keys and credentials. WS-SecurityPolicy expects that the requisite security data is provided through a proprietary mechanism. In Apache CXF, the associated security data is provided through Blueprint XML configuration. Configuring encryption keys and signing keys You can specify an application's encryption keys and signing keys by setting properties on a client's request context or on an endpoint context (see the section called "Add encryption and signing properties to Blueprint configuration" ). The properties you can set are shown in Table 6.1, "Encryption and Signing Properties" . Table 6.1. Encryption and Signing Properties Property Description security.signature.properties The WSS4J properties file/object that contains the WSS4J properties for configuring the signature keystore (which is also used for decrypting) and Crypto objects. security.signature.username (Optional) The username or alias of the key in the signature keystore to use. If not specified, the alias set in the properties file is used. If that is also not set, and the keystore only contains a single key, that key will be used. security.encryption.properties The WSS4J properties file/object that contains the WSS4J properties for configuring the encryption keystore (which is also used for validating signatures) and Crypto objects. security.encryption.username (Optional) The username or alias of the key in the encryption keystore to use. If not specified, the alias set in the properties file is used. If that is also not set, and the keystore only contains a single key, that key will be used. The names of the preceding properties are not so well chosen, because they do not accurately reflect what they are used for. The key specified by security.signature.properties is actually used both for signing and decrypting. The key specified by security.encryption.properties is actually used both for encrypting and for validating signatures. Add encryption and signing properties to Blueprint configuration Before you can use any WS-Policy policies in a Apache CXF application, you must add the policies feature to the default CXF bus. Add the p:policies element to the CXF bus, as shown in the following Blueprint configuration fragment: The following example shows how to add signature and encryption properties to proxies of the specified service type (where the service name is specified by the name attribute of the jaxws:client element). The properties are stored in WSS4J property files, where alice.properties contains the properties for the signature key and bob.properties contains the properties for the encryption key. In fact, although it is not obvious from the property names, each of these keys is used for two distinct purposes on the client side: alice.properties (that is, the key specified by security.signature.properties ) is used on the client side as follows: For signing outgoing messages. For decrypting incoming messages. bob.properties (that is, the key specified by security.encryption.properties ) is used on the client side as follows: For encrypting outgoing messages. For verifying signatures on incoming messages. If you find this confusing, see Section 6.2.2, "Basic Signing and Encryption Scenario" for a more detailed explanation. The following example shows how to add signature and encryption properties to a JAX-WS endpoint. The properties file, bob.properties , contains the properties for the signature key and the properties file, alice.properties , contains the properties for the encryption key (this is the inverse of the client configuration). Each of these keys is used for two distinct purposes on the server side: bob.properties (that is, the key specified by security.signature.properties ) is used on the server side as follows: For signing outgoing messages. For decrypting incoming messages. alice.properties (that is, the key specified by security.encryption.properties ) is used on the server side as follows: For encrypting outgoing messages. For verifying signatures on incoming messages. Define the WSS4J property files Apache CXF uses WSS4J property files to load the public keys and the private keys needed for encryption and signing. Table 6.2, "WSS4J Keystore Properties" describes the properties that you can set in these files. Table 6.2. WSS4J Keystore Properties Property Description org.apache.ws.security. crypto.provider Specifies an implementation of the Crypto interface (see the section called "WSS4J Crypto interface" ). Normally, you specify the default WSS4J implementation of Crypto , org.apache.ws.security.components.crypto.Merlin . The rest of the properties in this table are specific to the Merlin implementation of the Crypto interface. org.apache.ws.security. crypto.merlin.keystore.provider (Optional) The name of the JSSE keystore provider to use. The default keystore provider is Bouncy Castle . You can switch provider to Sun's JSSE keystore provider by setting this property to SunJSSE . org.apache.ws.security. crypto.merlin.keystore.type The Bouncy Castle keystore provider supports the following types of keystore: JKS and PKCS12 . In addition, Bouncy Castle supports the following proprietary keystore types: BKS and UBER. org.apache.ws.security. crypto.merlin.keystore.file Specifies the location of the keystore file to load, where the location is specified relative to the Classpath. org.apache.ws.security. crypto.merlin.keystore.alias (Optional) If the keystore type is JKS (Java keystore), you can select a specific key from the keystore by specifying its alias. If the keystore contains only one key, there is no need to specify an alias. org.apache.ws.security. crypto.merlin.keystore.password The password specified by this property is used for two purposes: to unlock the keystore (keystore password) and to decrypt a private key that is stored in the keystore (private key password). Hence, the keystore password must be same as the private key password. For example, the etc/alice.properties file contains property settings to load the PKCS#12 file, certs/alice.pfx , as follows: The etc/bob.properties file contains property settings to load the PKCS#12 file, certs/bob.pfx , as follows: Programming encryption keys and signing keys An alternative approach to loading encryption keys and signing keys is to use the properties shown in Table 6.3, "Properties for Specifying Crypto Objects" to specify Crypto objects that load the relevant keys. This requires you to provide your own implementation of the WSS4J Crypto interface, org.apache.ws.security.components.crypto.Crypto . Table 6.3. Properties for Specifying Crypto Objects Property Description security.signature.crypto Specifies an instance of a Crypto object that is responsible for loading the keys for signing and decrypting messages. security.encryption.crypto Specifies an instance of a Crypto object that is responsible for loading the keys for encrypting messages and verifying signatures. WSS4J Crypto interface Example 6.7, "WSS4J Crypto Interface" shows the definition of the Crypto interface that you can implement, if you want to provide encryption keys and signing keys by programming. For more information, see the WSS4J home page . Example 6.7. WSS4J Crypto Interface 6.2.7. Specifying the Algorithm Suite Overview An algorithm suite is a coherent collection of cryptographic algorithms for performing operations such as signing, encryption, generating message digests, and so on. For reference purposes, this section describes the algorithm suites defined by the WS-SecurityPolicy specification. Whether or not a particular algorithm suite is available, however, depends on the underlying security provider. Apache CXF security is based on the pluggable Java Cryptography Extension (JCE) and Java Secure Socket Extension (JSSE) layers. By default, Apache CXF is configured with Sun's JSSE provider, which supports the cipher suites described in Appendix A of Sun's JSSE Reference Guide . Syntax The AlgorithmSuite element has the following syntax: The algorithm suite assertion supports a large number of alternative algorithms (for example, Basic256 ). For a detailed description of the algorithm suite alternatives, see Table 6.4, "Algorithm Suites" . Algorithm suites Table 6.4, "Algorithm Suites" provides a summary of the algorithm suites supported by WS-SecurityPolicy. The column headings refer to different types of cryptographic algorithm, as follows: \[Dig] is the digest algorithm; \[Enc] is the encryption algorithm; \[Sym KW] is the symmetric key-wrap algorithm; \[Asym KW] is the asymmetric key-wrap algorithm; \[Enc KD] is the encryption key derivation algorithm; \[Sig KD] is the signature key derivation algorithm. Table 6.4. Algorithm Suites Algorithm Suite \[Dig] \[Enc] \[Sym KW] \[Asym KW] \[Enc KD] \[Sig KD] Basic256 Sha1 Aes256 KwAes256 KwRsaOaep PSha1L256 PSha1L192 Basic192 Sha1 Aes192 KwAes192 KwRsaOaep PSha1L192 PSha1L192 Basic128 Sha1 Aes128 KwAes128 KwRsaOaep PSha1L128 PSha1L128 TripleDes Sha1 TripleDes KwTripleDes KwRsaOaep PSha1L192 PSha1L192 Basic256Rsa15 Sha1 Aes256 KwAes256 KwRsa15 PSha1L256 PSha1L192 Basic192Rsa15 Sha1 Aes192 KwAes192 KwRsa15 PSha1L192 PSha1L192 Basic128Rsa15 Sha1 Aes128 KwAes128 KwRsa15 PSha1L128 PSha1L128 TripleDesRsa15 Sha1 TripleDes KwTripleDes KwRsa15 PSha1L192 PSha1L192 Basic256Sha256 Sha256 Aes256 KwAes256 KwRsaOaep PSha1L256 PSha1L192 Basic192Sha256 Sha256 Aes192 KwAes192 KwRsaOaep PSha1L192 PSha1L192 Basic128Sha256 Sha256 Aes128 KwAes128 KwRsaOaep PSha1L128 PSha1L128 TripleDesSha256 Sha256 TripleDes KwTripleDes KwRsaOaep PSha1L192 PSha1L192 Basic256Sha256Rsa15 Sha256 Aes256 KwAes256 KwRsa15 PSha1L256 PSha1L192 Basic192Sha256Rsa15 Sha256 Aes192 KwAes192 KwRsa15 PSha1L192 PSha1L192 Basic128Sha256Rsa15 Sha256 Aes128 KwAes128 KwRsa15 PSha1L128 PSha1L128 TripleDesSha256Rsa15 Sha256 TripleDes KwTripleDes KwRsa15 PSha1L192 PSha1L192 Types of cryptographic algorithm The following types of cryptographic algorithm are supported by WS-SecurityPolicy: the section called "Symmetric key signature" the section called "Asymmetric key signature" the section called "Digest" the section called "Encryption" the section called "Symmetric key wrap" the section called "Asymmetric key wrap" the section called "Computed key" the section called "Encryption key derivation" the section called "Signature key derivation" Symmetric key signature The symmetric key signature property, [Sym Sig], specifies the algorithm for generating a signature using a symmetric key. WS-SecurityPolicy specifies that the HmacSha1 algorithm is always used. The HmacSha1 algorithm is identified by the following URI: Asymmetric key signature The asymmetric key signature property, [Asym Sig], specifies the algorithm for generating a signature using an asymmetric key. WS-SecurityPolicy specifies that the RsaSha1 algorithm is always used. The RsaSha1 algorithm is identified by the following URI: Digest The digest property, [Dig], specifies the algorithm used for generating a message digest value. WS-SecurityPolicy supports two alternative digest algorithms: Sha1 and Sha256 . The Sha1 algorithm is identified by the following URI: The Sha256 algorithm is identified by the following URI: Encryption The encryption property, [Enc], specifies the algorithm used for encrypting data. WS-SecurityPolicy supports the following encryption algorithms: Aes256 , Aes192 , Aes128 , TripleDes . The Aes256 algorithm is identified by the following URI: The Aes192 algorithm is identified by the following URI: The Aes128 algorithm is identified by the following URI: The TripleDes algorithm is identified by the following URI: Symmetric key wrap The symmetric key wrap property, [Sym KW], specifies the algorithm used for signing and encrypting symmetric keys. WS-SecurityPolicy supports the following symmetric key wrap algorithms: KwAes256 , KwAes192 , KwAes128 , KwTripleDes . The KwAes256 algorithm is identified by the following URI: The KwAes192 algorithm is identified by the following URI: The KwAes128 algorithm is identified by the following URI: The KwTripleDes algorithm is identified by the following URI: Asymmetric key wrap The asymmetric key wrap property, [Asym KW], specifies the algorithm used for signing and encrypting asymmetric keys. WS-SecurityPolicy supports the following asymmetric key wrap algorithms: KwRsaOaep , KwRsa15 . The KwRsaOaep algorithm is identified by the following URI: The KwRsa15 algorithm is identified by the following URI: Computed key The computed key property, [Comp Key], specifies the algorithm used to compute a derived key. When secure parties communicate with the aid of a shared secret key (for example, when using WS-SecureConversation), it is recommended that a derived key is used instead of the original shared key, in order to avoid exposing too much data for analysis by hostile third parties. WS-SecurityPolicy specifies that the PSha1 algorithm is always used. The PSha1 algorithm is identified by the following URI: Encryption key derivation The encryption key derivation property, [Enc KD], specifies the algorithm used to compute a derived encryption key. WS-SecurityPolicy supports the following encryption key derivation algorithms: PSha1L256 , PSha1L192 , PSha1L128 . The PSha1 algorithm is identified by the following URI (the same algorithm is used for PSha1L256 , PSha1L192 , and PSha1L128 ; just the key lengths differ): Signature key derivation The signature key derivation property, [Sig KD], specifies the algorithm used to compute a derived signature key. WS-SecurityPolicy supports the following signature key derivation algorithms: PSha1L192 , PSha1L128 . Key length properties Table 6.5, "Key Length Properties" shows the minimum and maximum key lengths supported in WS-SecurityPolicy. Table 6.5. Key Length Properties Property Key Length Minimum symmetric key length [Min SKL] 128, 192, 256 Maximum symmetric key length [Max SKL] 256 Minimum asymmetric key length [Min AKL] 1024 Maximum asymmetric key length [Max AKL] 4096 The value of the minimum symmetric key length, [Min SKL], depends on which algorithm suite is selected.

Commands:
<beans xmlns="https://osgi.org/xmlns/blueprint/v1.0.0/" xmlns:http="http://cxf.apache.org/transports/http/configuration" xmlns:sec="http://cxf.apache.org/configuration/security" ... > <http:conduit name="https://.*/UserNameOverTransport.*"> <http:tlsClientParameters disableCNCheck="true"> <sec:keyManagers keyPassword="password"> <sec:keyStore type="pkcs12" password="password" resource="certs/alice.pfx"/> </sec:keyManagers> <sec:trustManagers> <sec:keyStore type="pkcs12" password="password" resource="certs/bob.pfx"/> </sec:trustManagers> </http:tlsClientParameters> </http:conduit> </beans>
<beans xmlns="https://osgi.org/xmlns/blueprint/v1.0.0/" xmlns:httpj="http://cxf.apache.org/transports/http-jetty/configuration" xmlns:sec="http://cxf.apache.org/configuration/security" ... > <httpj:engine-factory id="tls-settings"> <httpj:engine port="9001"> <httpj:tlsServerParameters secureSocketProtocol="TLSv1"> <sec:keyManagers keyPassword="password"> <sec:keyStore type="pkcs12" password="password" resource="certs/bob.pfx"/> </sec:keyManagers> <sec:trustManagers> <sec:keyStore type="pkcs12" password="password" resource="certs/alice.pfx"/> </sec:trustManagers> </httpj:tlsServerParameters> </httpj:engine> </httpj:engine-factory> </beans>
<wsdl:binding name="UserNameOverTransport_IPingService" type="i0:IPingService"> <wsp:PolicyReference URI="#UserNameOverTransport_IPingService_policy"/> </wsdl:binding>
<sp:TransportBinding xmlns:sp="..." ... > <wsp:Policy xmlns:wsp="..."> <sp:TransportToken ... > <wsp:Policy> ... </wsp:Policy> </sp:TransportToken> <sp:AlgorithmSuite ... > ... </sp:AlgorithmSuite> <sp:Layout ... > ... </sp:Layout> ? <sp:IncludeTimestamp ... /> ? </wsp:Policy> </sp:TransportBinding>
<wsp:Policy wsu:Id="UserNameOverTransport_IPingService_policy"> <wsp:ExactlyOne> <wsp:All> <sp:TransportBinding xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy"> <wsp:Policy> <sp:TransportToken> <wsp:Policy> <sp:HttpsToken RequireClientCertificate="false"/> </wsp:Policy> </sp:TransportToken> <sp:AlgorithmSuite> <wsp:Policy> <sp:Basic256/> </wsp:Policy> </sp:AlgorithmSuite> <sp:Layout> <wsp:Policy> <sp:Lax/> </wsp:Policy> </sp:Layout> <sp:IncludeTimestamp/> </wsp:Policy> </sp:TransportBinding> <sp:Wss10 xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy"> <wsp:Policy> <sp:MustSupportRefKeyIdentifier/> <sp:MustSupportRefIssuerSerial/> </wsp:Policy> </sp:Wss10> </wsp:All> </wsp:ExactlyOne> </wsp:Policy>
<wsdl:binding name="MutualCertificate10SignEncrypt_IPingService" type="i0:IPingService"> <wsp: PolicyReference URI="#MutualCertificate10SignEncrypt_IPingService_policy"/> </wsdl:binding>
<sp:AsymmetricBinding xmlns:sp="..." ... > <wsp:Policy xmlns:wsp="..."> ( <sp:InitiatorToken> <wsp:Policy> ... </wsp:Policy> </sp:InitiatorToken> ) | ( <sp:InitiatorSignatureToken> <wsp:Policy> ... </wsp:Policy> </sp:InitiatorSignatureToken> <sp:InitiatorEncryptionToken> <wsp:Policy> ... </wsp:Policy> </sp:InitiatorEncryptionToken> ) ( <sp:RecipientToken> <wsp:Policy> ... </wsp:Policy> </sp:RecipientToken> ) | ( <sp:RecipientSignatureToken> <wsp:Policy> ... </wsp:Policy> </sp:RecipientSignatureToken> <sp:RecipientEncryptionToken> <wsp:Policy> ... </wsp:Policy> </sp:RecipientEncryptionToken> ) <sp:AlgorithmSuite ... > ... </sp:AlgorithmSuite> <sp:Layout ... > ... </sp:Layout> ? <sp:IncludeTimestamp ... /> ? <sp:EncryptBeforeSigning ... /> ? <sp:EncryptSignature ... /> ? <sp:ProtectTokens ... /> ? <sp:OnlySignEntireHeadersAndBody ... /> ? </wsp:Policy> </sp:AsymmetricBinding>
<wsp:Policy wsu:Id="MutualCertificate10SignEncrypt_IPingService_policy"> <wsp:ExactlyOne> <wsp:All> <sp:AsymmetricBinding xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy"> <wsp:Policy> <sp:InitiatorToken> <wsp:Policy> <sp:X509Token sp:IncludeToken="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy/IncludeToken/AlwaysToRecipient"> <wsp:Policy> <sp:WssX509V3Token10/> </wsp:Policy> </sp:X509Token> </wsp:Policy> </sp:InitiatorToken> <sp:RecipientToken> <wsp:Policy> <sp:X509Token sp:IncludeToken="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy/IncludeToken/Never"> <wsp:Policy> <sp:WssX509V3Token10/> </wsp:Policy> </sp:X509Token> </wsp:Policy> </sp:RecipientToken> <sp:AlgorithmSuite> <wsp:Policy> <sp:Basic256/> </wsp:Policy> </sp:AlgorithmSuite> <sp:Layout> <wsp:Policy> <sp:Lax/> </wsp:Policy> </sp:Layout> <sp:IncludeTimestamp/> <sp:EncryptSignature/> <sp:OnlySignEntireHeadersAndBody/> </wsp:Policy> </sp:AsymmetricBinding> <sp:Wss10 xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy"> <wsp:Policy> <sp:MustSupportRefKeyIdentifier/> <sp:MustSupportRefIssuerSerial/> </wsp:Policy> </sp:Wss10> </wsp:All> </wsp:ExactlyOne> </wsp:Policy>
<wsdl:binding name="SecureConversation_MutualCertificate10SignEncrypt_IPingService" type="i0:IPingService"> <wsp: PolicyReference URI="#SecureConversation_MutualCertificate10SignEncrypt_IPingService_policy"/> </wsdl:binding>
<sp:SymmetricBinding xmlns:sp="..." ... > <wsp:Policy xmlns:wsp="..."> ( <sp:EncryptionToken ... > <wsp:Policy> ... </wsp:Policy> </sp:EncryptionToken> <sp:SignatureToken ... > <wsp:Policy> ... </wsp:Policy> </sp:SignatureToken> ) | ( <sp:ProtectionToken ... > <wsp:Policy> ... </wsp:Policy> </sp:ProtectionToken> ) <sp:AlgorithmSuite ... > ... </sp:AlgorithmSuite> <sp:Layout ... > ... </sp:Layout> ? <sp:IncludeTimestamp ... /> ? <sp:EncryptBeforeSigning ... /> ? <sp:EncryptSignature ... /> ? <sp:ProtectTokens ... /> ? <sp:OnlySignEntireHeadersAndBody ... /> ? </wsp:Policy> </sp:SymmetricBinding>
<wsp:Policy wsu:Id="SecureConversation_MutualCertificate10SignEncrypt_IPingService_policy"> <wsp:ExactlyOne> <wsp:All> <sp:SymmetricBinding xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy"> <wsp:Policy> <sp:ProtectionToken> <wsp:Policy> <sp:SecureConversationToken> </sp:SecureConversationToken> </wsp:Policy> </sp:ProtectionToken> <sp:AlgorithmSuite> <wsp:Policy> <sp:Basic256/> </wsp:Policy> </sp:AlgorithmSuite> <sp:Layout> <wsp:Policy> <sp:Lax/> </wsp:Policy> </sp:Layout> <sp:IncludeTimestamp/> <sp:EncryptSignature/> <sp:OnlySignEntireHeadersAndBody/> </wsp:Policy> </sp:SymmetricBinding> <sp:Wss10 xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy"> <wsp:Policy> <sp:MustSupportRefKeyIdentifier/> <sp:MustSupportRefIssuerSerial/> </wsp:Policy> </sp:Wss10> </wsp:All> </wsp:ExactlyOne> </wsp:Policy>
<wsdl:operation name="header"> <soap:operation soapAction="http://InteropBaseAddress/interop/header" style="document"/> <wsdl:input name="headerRequest"> <wsp: PolicyReference URI="#MutualCertificate10SignEncrypt_IPingService_header_Input_policy"/> <soap:header message="i0:headerRequest_Headers" part="CustomHeader" use="literal"/> <soap:body use="literal"/> </wsdl:input> </wsdl:operation>
<sp:SignedParts xmlns:sp="..." ... > <sp:Body />? <sp:Header Name="xs:NCName"? Namespace="xs:anyURI" ... />* <sp:Attachments />? </sp:SignedParts>
<sp:EncryptedParts xmlns:sp="..." ... > <sp:Body/>? <sp:Header Name="xs:NCName"? Namespace="xs:anyURI" ... />* <sp:Attachments />? </sp:EncryptedParts>
<wsp:Policy wsu:Id="MutualCertificate10SignEncrypt_IPingService_header_Input_policy"> <wsp:ExactlyOne> <wsp:All> <sp:SignedParts xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy"> <sp:Body/> <sp:Header Name="CustomHeader" Namespace="http://InteropBaseAddress/interop"/> </sp:SignedParts> <sp:EncryptedParts xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy"> <sp:Body/> </sp:EncryptedParts> </wsp:All> </wsp:ExactlyOne> </wsp:Policy>
<beans xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0" xmlns:jaxws="http://cxf.apache.org/jaxws" xmlns:cxf="http://cxf.apache.org/core" xmlns:p="http://cxf.apache.org/policy" ... > <cxf:bus> <cxf:features> <p:policies/> <cxf:logging/> </cxf:features> </cxf:bus> </beans>
<beans ... > <jaxws:client name="{http://InteropBaseAddress/interop}MutualCertificate10SignEncrypt_IPingService" createdFromAPI="true"> <jaxws:properties> <entry key=" ws-security.signature.properties " value="etc/alice.properties"/> <entry key=" ws-security.encryption.properties " value="etc/bob.properties"/> </jaxws:properties> </jaxws:client> </beans>
<beans ... > <jaxws:endpoint name="{http://InteropBaseAddress/interop}MutualCertificate10SignEncrypt_IPingService" id="MutualCertificate10SignEncrypt" address="http://localhost:9002/MutualCertificate10SignEncrypt" serviceName="interop:PingService10" endpointName="interop:MutualCertificate10SignEncrypt_IPingService" implementor="interop.server.MutualCertificate10SignEncrypt"> <jaxws:properties> <entry key=" security.signature.properties " value="etc/bob.properties"/> <entry key=" security.encryption.properties " value="etc/alice.properties"/> </jaxws:properties> </jaxws:endpoint> </beans>
org.apache.ws.security.crypto.provider=org.apache.ws.security.components.crypto.Merlin org.apache.ws.security.crypto.merlin.keystore.type=PKCS12 org.apache.ws.security.crypto.merlin.keystore.password=password org.apache.ws.security.crypto.merlin.keystore.file=certs/alice.pfx
org.apache.ws.security.crypto.provider=org.apache.ws.security.components.crypto.Merlin org.apache.ws.security.crypto.merlin.keystore.password=password for some reason, bouncycastle has issues with bob.pfx org.apache.ws.security.crypto.merlin.keystore.provider=SunJSSE org.apache.ws.security.crypto.merlin.keystore.type=PKCS12 org.apache.ws.security.crypto.merlin.keystore.file=certs/bob.pfx
// Java package org.apache.ws.security.components.crypto; import org.apache.ws.security.WSSecurityException; import java.io.InputStream; import java.math.BigInteger; import java.security.KeyStore; import java.security.PrivateKey; import java.security.cert.Certificate; import java.security.cert.CertificateFactory; import java.security.cert.X509Certificate; public interface Crypto { X509Certificate loadCertificate(InputStream in) throws WSSecurityException; X509Certificate[] getX509Certificates(byte[] data, boolean reverse) throws WSSecurityException; byte[] getCertificateData(boolean reverse, X509Certificate[] certs) throws WSSecurityException; public PrivateKey getPrivateKey(String alias, String password) throws Exception; public X509Certificate[] getCertificates(String alias) throws WSSecurityException; public String getAliasForX509Cert(Certificate cert) throws WSSecurityException; public String getAliasForX509Cert(String issuer) throws WSSecurityException; public String getAliasForX509Cert(String issuer, BigInteger serialNumber) throws WSSecurityException; public String getAliasForX509Cert(byte[] skiBytes) throws WSSecurityException; public String getDefaultX509Alias(); public byte[] getSKIBytesFromCert(X509Certificate cert) throws WSSecurityException; public String getAliasForX509CertThumb(byte[] thumb) throws WSSecurityException; public KeyStore getKeyStore(); public CertificateFactory getCertificateFactory() throws WSSecurityException; public boolean validateCertPath(X509Certificate[] certs) throws WSSecurityException; public String[] getAliasesForDN(String subjectDN) throws WSSecurityException; }
<sp:AlgorithmSuite xmlns:sp="..." ... > <wsp:Policy xmlns:wsp="..."> (<sp:Basic256 ... /> | <sp:Basic192 ... /> | <sp:Basic128 ... /> | <sp:TripleDes ... /> | <sp:Basic256Rsa15 ... /> | <sp:Basic192Rsa15 ... /> | <sp:Basic128Rsa15 ... /> | <sp:TripleDesRsa15 ... /> | <sp:Basic256Sha256 ... /> | <sp:Basic192Sha256 ... /> | <sp:Basic128Sha256 ... /> | <sp:TripleDesSha256 ... /> | <sp:Basic256Sha256Rsa15 ... /> | <sp:Basic192Sha256Rsa15 ... /> | <sp:Basic128Sha256Rsa15 ... /> | <sp:TripleDesSha256Rsa15 ... /> | ...) <sp:InclusiveC14N ... /> ? <sp:SOAPNormalization10 ... /> ? <sp:STRTransform10 ... /> ? (<sp:XPath10 ... /> | <sp:XPathFilter20 ... /> | <sp:AbsXPath ... /> | ...)? </wsp:Policy> </sp:AlgorithmSuite>
http://www.w3.org/2000/09/xmldsig#hmac-sha1
http://www.w3.org/2000/09/xmldsig#rsa-sha1
http://www.w3.org/2000/09/xmldsig#sha1
http://www.w3.org/2001/04/xmlenc#sha256
http://www.w3.org/2001/04/xmlenc#aes256-cbc
http://www.w3.org/2001/04/xmlenc#aes192-cbc
http://www.w3.org/2001/04/xmlenc#aes128-cbc
http://www.w3.org/2001/04/xmlenc#tripledes-cbc
http://www.w3.org/2001/04/xmlenc#kw-aes256
http://www.w3.org/2001/04/xmlenc#kw-aes192
http://www.w3.org/2001/04/xmlenc#kw-aes128
http://www.w3.org/2001/04/xmlenc#tripledes-cbc
http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p
http://www.w3.org/2001/04/xmlenc#rsa-1_5
http://docs.oasis-open.org/ws-sx/ws-secureconversation/200512/dk/p_sha1
http://docs.oasis-open.org/ws-sx/ws-secureconversation/200512/dk/p_sha1