A SOAP digital signature is a value attached to a SOAP request that proves two things: the request came from a trusted sender, and the content was not changed after it was sent. In Unqork, SOAP digital signatures are configured in Services Administration on SOAP-compatible service types.
How SOAP Digital Signatures Work
A digital signature uses two related keys: a private key and a public key. The sender uses the private key to create the signature. The receiver uses the public key to check it. The private key is kept secret and never shared.
When Unqork sends a SOAP request with a digital signature, it:
- Takes the content of the request.
- Runs it through a hash function to produce a short, fixed-length value called a digest.
- Signs the digest using the private key to produce the digital signature.
- Embeds the signature in the SOAP message header before sending the request.
The receiving service uses the public key included in the signature to run the same check. If the signature matches, the receiver knows two things:
- Integrity: The request content was not changed after it was signed.
- Authenticity: The sender holds the correct private key.
If the content was changed after signing, the check fails and the request is rejected.
Message-Level vs. Transport-Level Security
SOAP digital signatures protect the message itself. The signature travels inside the SOAP request and remains valid regardless of how the request is delivered.
Transport-level security, like Mutual TLS, protects the connection between the two systems. It secures the channel, not the message content.
These two methods can be used together. A service can require both a signed message and a verified client connection.
Algorithm Settings
Three algorithm settings control how the signature is computed. Each is specified as a URI from the W3C XML Signature specification.
| Algorithm | Role |
|---|---|
| Signing Algorithm | The cryptographic method used to produce the signature from the digest. |
| Digest Algorithm | The hash function applied to the request content before signing. Produces a fixed-length value that represents the full content. |
| Canonicalization Algorithm | Normalizes the XML formatting before signing. This makes sure the same content always produces the same bytes, even if spacing or namespace order differs. |
See the W3C XML Signature algorithm reference for a list of valid URIs for each setting.
SOAP Digital Signature Settings in Unqork
SOAP digital signatures are configured in Services Administration. The certificate used for signing is stored in PFX format and managed in Certificate Management.
| Setting | Description |
|---|---|
| Enable SOAP Digital Signature | Enables digital signing for SOAP requests. When checked, the fields below appear. |
| PFX or PKCS12 Encoded Private key and Certificate Chain | The private key and certificate chain in PFX or PKCS12 format, hex encoded. |
| PFX Passphrase | The passphrase for the PFX file, if one was set when the certificate was created. |
| Signing Algorithm | The XML digital signature signing algorithm URI. |
| Digest Algorithm | The XML digital signature digest algorithm URI. |
| Canonicalization Algorithm | The XML canonicalization algorithm URI. |
All SOAP Digital Signature processing runs server-side. This service type cannot be called directly from the browser.
See Service Types for the complete field reference.
How Unqork Uses SOAP Digital Signatures
When a request goes to a SOAP Digital Signature-enabled service, Unqork:
- Processes authentication for the service first.
- Loads the stored PFX certificate and extracts the private key and X.509 certificate.
- Computes the digital signature using the configured signing, digest, and canonicalization algorithms.
- Wraps the signature and embeds it in the SOAP message header.
- If the request includes file attachments, those are included in the signature scope as well.
- Sends the signed request to the external service.
The receiver uses the public key included in the signature to check the request. If the check passes, the request is accepted. If anything in the message was changed after signing, the check fails.
The private key is stored encrypted at rest. Unqork never sends the private key as part of outbound requests.
Supported Authentication Types
SOAP Digital Signature is available on the following service authentication types:
| Authentication Type | SOAP Digital Signature Support |
|---|---|
| No Authentication | Supported |
| WSSE Username Token Profile | Supported |
| Custom SOAP Header | Supported |
All other authentication types, including Basic Auth, Bearer Token, and OAuth, do not support SOAP Digital Signature.
SOAP Digital Signature and Mutual TLS can be used together on supported types. SOAP Digital Signature signs the message content. Mutual TLS secures the connection. See Mutual TLS Concepts for more detail.
When to Use SOAP Digital Signatures
Use SOAP digital signatures when integrating with SOAP services that:
- Require signed requests as part of their security policy.
- Need to confirm the identity of the calling system at the message level, not just the connection level.
- Follow WS-Security standards for message integrity and authentication.
If the external service only requires an encrypted connection instead of a signed message, Mutual TLS might be sufficient. Check the external service documentation to confirm which method is required.
SOAP Digital Signature Terminology
| Term | Definition |
|---|---|
| SOAP | Simple Object Access Protocol. A messaging format that uses XML to exchange data between systems. Many enterprise and government services use SOAP. |
| XML | Extensible Markup Language. A text format that uses tags to structure data, similar to HTML. SOAP messages are written in XML. |
| Digital Signature | A value computed from a message and a private key. It lets the receiver confirm who sent the message and that the content was not changed. |
| Private Key | A secret key held only by the sender. Used to compute the digital signature. Never shared or included in requests. |
| Public Key | A key paired with the private key. Included in the signature so the receiver can check it. Does not need to be kept secret. |
| X.509 Certificate | A standard format for a digital certificate. It contains the public key and information about the key holder. Unqork uses an X.509 certificate stored in PFX format. |
| PFX / PKCS#12 | A file format that bundles a private key and certificate into a single file. Unqork requires this format for SOAP Digital Signature. |
| Signing Algorithm | The cryptographic method used to produce the signature. Specified as a URI from the W3C XML Signature specification. |
| Digest Algorithm | A hash function applied to the request content before signing. Produces a short, fixed-length value that represents the full content. |
| Canonicalization Algorithm | A step that standardizes XML formatting before signing. This makes sure that the same content always produces the same bytes, regardless of how the XML was formatted. |
| SOAP Header | The section of a SOAP message that carries metadata and control information. Unqork embeds the digital signature in the SOAP Header, not the message body. |
| WS-Security | A set of standards for adding security to SOAP messages, including digital signatures and authentication tokens. |
| WSSE | Web Services Security Extensions. The namespace and standards that define security headers for SOAP, including WSSE Username Token Profile. |
| Enveloped Signature | A signature style where the signature is embedded inside the signed document. The signature element itself is excluded from the signed content so it does not break its own check. |
Changelog
| Date | Change |
|---|---|
| 2026-05-12 | Expanded with algorithm background, full settings table, runtime behavior, supported authentication types, and terminology glossary. |
| — | Initial publication. |