references with XML Encryption, adding an xenc:EncryptedKey to the wsse:Security header and replacing each target with an xenc:EncryptedData. A single freshly generated content encryption key protects every reference of this part; that key is itself encrypted for the recipient, whose certificate is taken from the enclosing wsSecurity element's truststore under recipientAlias.Order relative to signature is meaningful and not fixed. Listed after a signature this produces sign-then-encrypt, and the receiver has to decrypt before it verifies; listed before one it produces encrypt-then-sign, and the receiver has to verify first. Whichever is chosen, the receiver's validate list has to mirror it.
Encryption provides confidentiality only — it says nothing about who sent the message, since the recipient's certificate is public. Combine it with a signature when the sender has to be authenticated.
AES-GCM and RSA-OAEP are the defaults. dataEncryptionAlgorithm and keyTransportAlgorithm also accept the legacy AES-CBC and RSA-1.5 algorithms for a recipient that supports nothing else; both are vulnerable to padding-oracle attacks and log a warning at startup. Configuring one here does not make it acceptable inbound — a validate/decrypt needs its own allowedLegacyAlgorithms for that. See distribution/tutorials/web-services-security/70-Encrypt-And-Decrypt-Body.yaml.
Example Configuration
- wsSecurity:
truststore:
location: backend.p12
password: secret
secure:
- encrypt:
recipientAlias: backend
references:
- by: BODY
- wsSecurity:
truststore:
location: backend.p12
password: secret
secure:
- encrypt:
recipientAlias: backend
references:
- by: BODY
Syntax
encrypt:
dataEncryptionAlgorithm: <string>
keyIdentifier: {}
keyTransportAlgorithm: <string>
recipientAlias: <string>
references:
- <wsSecurity-encrypt-reference>
requireKeyEncipherment: <boolean>
encrypt:
dataEncryptionAlgorithm: <string>
keyIdentifier: {}
keyTransportAlgorithm: <string>
recipientAlias: <string>
references:
- <wsSecurity-encrypt-reference>
requireKeyEncipherment: <boolean>
Attributes
| Name | Required | Default | Description | Examples |
|---|---|---|---|---|
| dataEncryptionAlgorithm | false | http://www.w3.org/2009/xmlenc11#aes256-gcm | The XML Encryption algorithm URI protecting the referenced elements. The authenticated AES-GCM modes — http://www.w3.org/2009/xmlenc11#aes128-gcm and http://www.w3.org/2009/xmlenc11#aes256-gcm — are the ones to use.The unauthenticated CBC modes | - |
| keyTransportAlgorithm | false | http://www.w3.org/2009/xmlenc11#rsa-oaep | The algorithm URI encrypting the content encryption key for the recipient. http://www.w3.org/2009/xmlenc11#rsa-oaep, which this gateway emits with SHA-256 and MGF1-SHA-256, is the one to use. The older rsa-oaep-mgf1p URI is not available, because it cannot express a SHA-256 mask generation function.
| - |
| recipientAlias | false | - | The alias of the recipient's certificate in the enclosing wsSecurity element's truststore. Its public key encrypts the content encryption key, so only the holder of the matching private key can read the message. Required: there is no default, because picking a certificate automatically would mean encrypting for an arbitrary recipient. A PEM truststore exposes its entries as cert-0, cert-1, and so on. | backend |
| requireKeyEncipherment | false | false | Whether the recipient certificate's keyUsage must permit keyEncipherment. RFC 5280 reserves keyEncipherment for exactly what this part does with the certificate — encrypting a symmetric content encryption key — and dataEncipherment for directly encrypting user data, which nothing here does. By default a certificate with dataEncipherment but not keyEncipherment is still accepted, for compatibility with certificates issued that way, and logs a warning at startup naming the mismatch. Set this to true to reject such a certificate instead. A certificate with neither bit set, or with no keyUsage extension at all, is unaffected either way. | true |
Child Structure
| Element | Cardinality | Description |
|---|---|---|
| keyIdentifier | 0..1 | Names the recipient by a wsse:SecurityTokenReference/wsse:KeyIdentifier, which is what the xenc:EncryptedKey carries whether or not this element is present: omitted, it names the certificate by its SHA-1 thumbprint. Configure it explicitly only to select valueType=X509_V3, which embeds the certificate itself — the one reason being a recipient that cannot look a thumbprint up in a store of its own. Unlike under signature, there is no x509Data alternative here, because the two would produce the same ds:KeyInfo. |
| wsSecurity-encrypt-reference | 0..* | The elements to encrypt. Each becomes one xenc:EncryptedData, named by one xenc:DataReference in this part's xenc:EncryptedKey — except an XPATH reference matching more than one element, which becomes one xenc:EncryptedData per matched element. |