gSOAP WS-Security: The wsse WS-Security plugin
Main Page | Class List | File List | Class Members | File Members | Related Pages

The wsse WS-Security plugin

Security Header

The material in this section relates to the WS-Security specification section 5.

To use the wsse plugin:

  1. Run wsdl2h -t typemap.dat on a WSDL of a service that requires WS-Security headers. The typemap.dat file is used to recognize and translate Security header blocks for XML signature and encryption.
  2. Run soapcpp2 on the header file produced by wsdl2h.
  3. (Re-)compile stdsoap2.c/pp, dom.c/pp, smdevp.c, mecevp.c, wsseapi.c and the generated source files with the -DWITH_DOM and -DWITH_OPENSSL compile flags set. The smdevp.c, mecevp.c, and wsseapi.c files are located in the 'plugin' directory.
  4. Use the wsse plugin API functions described below to add and verify Security headers, sign and verify messages, and to encrypt/decrypt messages.

An example wsse client/server application can be found in gsoap/samples/wsse.

The wsse engine is thread safe. However, if HTTPS is required please follow the instructions in Section WS-Security and HTTPS to ensure thread-safety of WS-Security with HTTPS.

The wsse plugin API consists of a set of functions to populate and verify WS-Security headers and message body content. For more details, we refer to tbe following sections:

The basic API is introduced below.

To add an empty Security header block to the SOAP header, use:

    soap_wsse_add_Security(soap);

To delete a Security header, use:

    soap_wsse_delete_Security(soap);

Adding an empty Security header block is not very useful. In the following, we present the higher-level functions of the wsse plugin to populate and verify Security header content.

Note: The soap context includes an actor value soap.actor that is populated and rendered as the SOAP-ENV:actor (SOAP 1.1) or SOAP-ENV:role (SOAP 1.2) attribute in XML within the generic SOAP Header. The attribute is optional, but should be used to target a recipient such as an intermediate node to process the SOAP header. In contrast, actor or role attributes within Security header blocks target specific recipients to process the Security header block. The gSOAP implementation does not automate this feature and application should set and check the actor/role attribute when necessary. In addition, the current implementation supports the inclusion of a single Security header block in the SOAP header.

To populate the SOAP-ENV:actor or SOAP-ENV:role attribute within the Security header, use:

    soap_wsse_add_Security_actor(soap, "recipient");

To obtain the actor or role value (e.g. after receiving a message), use:

    _wsse__Security *security = soap_wsse_Security(soap);
    if (security)
    { ... = security->SOAP_ENV__actor; // SOAP 1.1
      ... = security->SOAP_ENV__role;  // SOAP 1.2

The SOAP-ENV:mustUnderstand attribute is automatically added and checked by the gSOAP engine. A gSOAP application compiled without Security support will reject Security headers.

Security header blocks are attached to the soap context, which means that the information will be automatically kept to support multiple invocations.

Security Tokens

The material in this section relates to the WS-Security specification section 6.

User Name Token

To add a user name token to the Security header block, use:

    soap_wsse_add_UsernameTokenText(soap, "Id", "username", NULL);

The Id value is optional. When non-NULL the user name token is included in the digital signature to protect its integrity. It is common for the wsse plugin functions to accept such Ids, which are serialized as wsu:Id identifiers for cross-referencing XML elements. The signature engine of the wsse plugin is designed to automatically sign all wsu:Id attributed elements to simplify the code you need to write to implement the signing process.

To add a user name token with clear text password, use:

    soap_wsse_add_UsernameTokenText(soap, "Id", "username", "password");

It is strongly recommended to use soap_wsse_add_UsernameTokenText only in combination with HTTPS encrypted transmission or not at all. A better alternative is to use password digests. With password digest authentication, the digest value of a password (with message creation time and a random nonce) is compared on both sides, thus eliminating the need to exchange a password over the wire.

To add a user name token with password digest, use:

    soap_wsse_add_UsernameTokenDigest(soap, "Id", "username", "password");

Although the password string is passed to this function, it is not rendered in XML or stored in a message log. It has been argued that this approach adopted by the WS-Security protocol is still vulnerable since the application retrieves the password in text form requiring a database to store passwords in clear text. However, a digest algorithm can be used to hash the passwords and store their digests instead, which eliminates the need to store clear-text passwords. Note that this is a common approach adopted by Unix for decades.

By setting the Id value to a unique string, the user name token is also digitally signed by the signature engine further preventing tampering with its value.

You must use soap_wsse_add_UsernameTokenDigest for each message exchange to refresh the password digest even when the user name and password are not changed. Otherwise, the receiver might flag the message as a replay attack.

Clear-text passwords and password digests are verified with soap_wsse_verify_Password. To verify a password at the receiving side to authorize a request (e.g. within a Web service operation), use:

    int ns__myMethod(struct soap *soap, ...)
    { const char *username = soap_wsse_get_Username(soap);
      const char *password;
      if (!username)
        return soap->error; // no username: return FailedAuthentication
      password = ...; // lookup password of username
      if (soap_wsse_verify_Password(soap, password))
        return soap->error; // password verification failed: return FailedAuthentication
      ... // process request, then sign the response message:
      if (soap_wsse_add_BinarySecurityTokenX509(soap, "X509Token", cert)
       || soap_wsse_add_KeyInfo_SecurityTokenReferenceX509(soap, "#X509Token")
       || soap_wsse_sign_body(soap, SOAP_SMD_SIGN_RSA_SHA1, rsa_private_key, 0)
        return soap->error;
      return SOAP_OK;
    }

Note that the soap_wsse_get_Username functions sets the wsse:FailedAuthentication fault. It is common for the wsse plugin functions to return SOAP_OK or a wsse fault that should be passed to the sender by returning soap->error from service operations. The fault is displayed with the soap_print_fault() function.

Password digest authentication prevents message replay attacks. The wsse plugin keeps a database of password digests to thwart replay attacks. This is the only part in the plugin code that requires mutex provided by threads.h. Of course, this only works correctly if the server is persistent, such as a stand-alone service. Note that CGI-based services do not keep state. Machine clocks must be synchronized and clock skew should not exceed SOAP_WSSE_CLKSKEW at the server side.

Binary Security Tokens

X509 certificates are commonly included in Security header blocks as binary security tokens. A certificate is used to verify the digital signature of a digitally signed message using the public key embedded within the certificate. The certificate itself is signed by a certificate authority (CA) that vouches for the authenticity of the certificate, i.e. to prove the identify of the message originator. This verification process is important, because digital signatures are useless without verification: an attacker could simply replace the message, sign it, and replace the certificate.

Certificates are automatically verified by the wsse plugin signature engine when received and accessed, which means that the certificates of the CAs must be made accessible to the wsse plugin as follows:

    soap->cafile = "cacerts.pem";  // use this
    soap->capath = "dir/to/certs"; // and/or point to CA certs
    soap->crlfile = "revoked.pem"; // use CRL (optional)

The soap_wsse_verify_X509 function checks the validity of a certificate. The check is automatically performed. The check is also performed when retrieving the certificate from a Security header block, either automatically by the wsse plugin's signature verification engine or manually as follows:

    X509 *cert = soap_wsse_get_BinarySecurityTokenX509(soap, "Id");

where Id is the identification string of the binary security token or NULL.

The verification is an expensive process that will be optimized in future releases by caching the certificate chain.

To attach a binary security token stored in a PEM file to a Security header block for transmission, use:

    soap_wsse_add_BinarySecurityTokenPEM(soap, NULL, "mycert.pem")

A binary security token can be automatically signed by setting its Id attribute:

    soap_wsse_add_BinarySecurityTokenPEM(soap, "X509Token", "mycert.pem")

Repeatedly loading a certificate from a PEM file is inefficient. To reuse a certificate loaded from a PEM file for multiple invocations, use:

    FILE *fd = fopen("mycert.pem", "r");
    X509 *cert = PEM_read_X509(fd, NULL, NULL, NULL);
    fclose(fd);
    if (soap_wsse_add_BinarySecurityTokenX509(soap, "X509Token", cert))
      ... // an error occurred

Other types of binary security tokens can be added to the Security header block using:

    soap_wsse_add_BinarySecurityToken(soap, "Id", "valueType", data, datalen);

XML Tokens

The use and processing rules for XML tokens such as SAML assertions is specific to an application. The wsse plugin does not automate the use of XML tokens. The developer is encouraged to generate code for the SAML schema with wsdl2h and add the necessary assertions to the Security header block:

typedef struct _wsse__Security
{       struct _wsu__Timestamp*                 wsu__Timestamp;
        struct _wsse__UsernameToken*            UsernameToken;
        struct _wsse__BinarySecurityToken*      BinarySecurityToken;
        struct _saml__Assertion*                saml__Assertion; // added
        struct xenc__EncryptedKeyType*          xenc__EncryptedKey;
        struct ds__SignatureType*               ds__Signature;
        @char*                                  SOAP_ENV__actor;
        @char*                                  SOAP_ENV__role;
} _wsse__Security;

Alternatively, a DOM can be used to store and retrieve XML tokens:

#import "dom.h"
typedef struct _wsse__Security
{       struct _wsu__Timestamp*                 wsu__Timestamp;
        struct _wsse__UsernameToken*            UsernameToken;
        struct _wsse__BinarySecurityToken*      BinarySecurityToken;
        struct xenc__EncryptedKeyType*          xenc__EncryptedKey;
        struct ds__SignatureType*               ds__Signature;
        int                                     __size;
        xsd__anyType*                           any;
        @char*                                  SOAP_ENV__actor;
        @char*                                  SOAP_ENV__role;
} _wsse__Security;

Token References

The material in this section relates to the WS-Security specification section 7.

To use a certificate for signature verification, add a direct security token reference URI for the token to the KeyInfo, for example:

    soap_wsse_add_KeyInfo_SecurityTokenReferenceURI(soap, "URI", "valueType");

and:

    soap_wsse_add_KeyInfo_SecurityTokenReferenceX509(soap, "URI");

For X509 certificates we use this to add a binary security token with the certificate and a reference to the local token:

    if (soap_wsse_add_BinarySecurityTokenX509(soap, "X509Token", cert)
     || soap_wsse_add_KeyInfo_SecurityTokenReferenceX509(soap, "#X509Token"))
      ... // an error occurred

This follows the recommended practice to place Security token references in the KeyInfo element of a Signature. The KeyInfo is used to verify the validity of a signature value.

Key identifiers can be used as well:

    soap_wsse_add_KeyInfo_SecurityTokenReferenceKeyIdentifier(soap, "Id", "valueType", data, datalen);

Embedded references are added with:

    soap_wsse_add_KeyInfo_SecurityTokenReferenceEmbedded(soap, "Id", "valueType");

Full support for embedded references requires coding to add tokens and assertions, as well as to consume embedded references at the receiving side. There is no automated mechanism to take the embedded references and process them accordingly.

The use of key names is not recommended, but in case they are required they can be added with:

    soap_wsse_add_KeyInfo_KeyName(soap, "name");

Signatures

The material in this section relates to the WS-Security specification section 8.

The wsse plugin must be registered to sign and verify messages:

    soap_register_plugin(soap, soap_wsse);

XML signatures are usually computed over normalized XML (to ensure the XML processors of intermediate nodes can accurately reproduce the XML). To this end, the exclusive canonical XML standard (exc-c14n) is required, which is set using the SOAP_XML_CANONICAL flag:

    struct soap *soap = soap_new1(SOAP_XML_CANONICAL);
    soap_register_plugin(soap, soap_wsse);

If you prefer XML indentation, use:

    struct soap *soap = soap_new1(SOAP_XML_CANONICAL | SOAP_XML_INDENT);
    soap_register_plugin(soap, soap_wsse);

Other flags to consider:

Next, we decide which signature algorithm is appropriate to use:

HMAC-SHA1 is the simplest method, but relies on the fact that you have to make absolutely sure the key is kept secret on both the sending and receiving side. As long as the secret key is confidential, messages are securely signed. However, this is virtually impossible when exchanging messages with untrusted disparate parties. The advantage of HMAC-SHA1 is the speed by which messages are signed and verified.

DSA-SHA1 and RSA-SHA1 rely on public key cryptography. In simplified terms, a message is signed using the (confidential!) private key. The public key is used to verify the signature. Since only the originating party could have used its private key to sign the message, the integrity of the message is guaranteed. Of course, we must trust the public key came from the originator (it is often included as an X509 certificate in the message). To this end, a trusted certificate authority should have signed the public key, thereby creating a X509 certificate that contains the public key and the identity of the message originator.

An optional callback function can be passed to the plugin that is responsible for providing a certificate to the wsse engine to verify a signed message. For example, when a security token is absent from an DSA-SHA1 or RSA-SHA1 signed message then the only mechanism to automatically verify the signature is to let the callback produce a certificate:

    soap_register_plugin_arg(soap, soap_wsse, security_token_handler);

    const void *security_token_handler(struct soap *soap, int alg, const char *keyname, int *keylen)
    { // Note: 'keyname' argument is only used with shared secret key decryption
      // Get the user name from UsernameToken in message
      const char *uid = soap_wsse_get_Username(soap);
      switch (alg)
      { case SOAP_SMD_VRFY_DSA_SHA1:
        case SOAP_SMD_VRFY_RSA_SHA1:
          if (uid)
          { // Lookup uid to retrieve the X509 certificate to verify the signature
            const X509 *cert = ...; 
            return (const void*)cert;
          }
          return NULL; // no certificate: fail
        case SOAP_SMD_HMAC_SHA1:
          if (uid)
          { // Lookup uid to retrieve the HMAC key to verify the signature
            const void *key = ...; 
            *keylen = ...;
            return key;
          }
          return NULL; // no certificate: fail
        case SOAP_MEC_ENV_DEC_DES_CBC
          // return decryption private key associated with keyname
        case SOAP_MEC_DEC_DES_CBC
          // *keylen = ...
          // return decryption shared secret key associated with keyname
      }
      return NULL; // fail
    }

Signing Messages

After the plugin is registered and a signature algorithm selected, the soap_wsse_sign function or the soap_wsse_sign_body function is used to initiate the signature engine to automatically sign outbound messages.

The code to sign the SOAP Body of a message using HMAC-SHA1 is:

    static char hmac_key[16] =
    { 0xff, 0xee, 0xdd, 0xcc, 0xbb, 0xaa, 0x99, 0x88,
      0x77, 0x66, 0x55, 0x44, 0x33, 0x22, 0x11, 0x00 };
    struct soap *soap = soap_new1(SOAP_XML_CANONICAL | SOAP_XML_INDENT);
    soap_register_plugin(soap, soap_wsse);
    if (soap_wsse_sign_body(soap, SOAP_SMD_HMAC_SHA1, hmac_key, sizeof(hmac_key))
      ... // an error occurred
    else if (soap_call_ns__myMethod(soap, ...))
      ... // a transmission error occurred

The hmac_key is some secret key you generated for the sending side and receiving side (don't use the one shown here).

As always, use soap_print_fault() to display the error message.

To sign the body of an outbound SOAP message using RSA-SHA1 (DSA-SHA1 is similar), we include the X509 certificate with the public key as a BinarySecurityToken in the header and a KeyInfo reference to the token to let receivers use the public key in the certificate to verify the authenticity of the message:

    FILE *fd;
    EVP_PKEY *rsa_private_key;
    X509 *cert;
    struct soap *soap = soap_new1(SOAP_XML_CANONICAL | SOAP_XML_INDENT);
    soap_register_plugin(soap, soap_wsse);
    fd = fopen("privkey.pem", "r");
    rsa_private_key = PEM_read_PrivateKey(fd, NULL, NULL, "password");
    fclose(fd);
    fd = fopen("cert.pem", "r");
    X509 *cert = PEM_read_X509(fd, NULL, NULL, NULL);
    fclose(fd);
    if (soap_wsse_add_BinarySecurityTokenX509(soap, "X509Token", cert)
     || soap_wsse_add_KeyInfo_SecurityTokenReferenceX509(soap, "#X509Token")
     || soap_wsse_sign_body(soap, SOAP_SMD_SIGN_RSA_SHA1, rsa_private_key, 0))
      ... // an error occurred
    else if (soap_call_ns__myMethod(soap, ...))
      ... // a transmission error occurred

The private key and its certificate are often placed in the same file, see e.g. server.pem in the package.

To summarize the signing process:

  1. Register the wsse plugin.
  2. Obtain an HMAC secret key or a DSA or RSA private key.
  3. For DSA or RSA, obtain the X509 certificate with the public key signed by a certificate authority.
  4. Add the X509 certificate as a BinarySecurityToken to the header.
  5. Add a KeyInfo BinarySecurityTokenReference.
  6. Invoke soap_wsse_sign or soap_wsse_sign_body to sign the message.
  7. Always check the function return values for errors. You don't want to produce and accept messages with an invalid Security headers.

Signing Message Parts

The soap_wsse_sign_body function signs the entire SOAP body. If it is desirable to sign individual parts of a message the soap_wsse_sign function should be used. All message parts with wsu:Id attributes are signed. These message parts should not be nested (nested elements will not be separately signed). By default, all and only those XML elements with wsu:Id attributes are signed. Therefore, the wsu:Id attribute values used in a message must be unique within the message. Although usually not required, the default signing rule can be overridden with the soap_wsse_sign_only function, see Signing Tokens.

For example, consider a transaction in which we only want to sign a contract in the SOAP Body. This allows us to modify the rest of the message or extract the contract in XML and pass it on with the signature.

The gSOAP header file includes a myContract declaration:

    struct ns__myContract
    { @char* wsu__Id = "Contract";
      char* name;
      char* title;
      char* terms;
    };
    int ns__myMethod(struct ns__myContract agreement, bool* accepted);

The default value of the wsu:Id is "Contract" so that we can instantiate the struct, automatically sign it, and send it as follows:

    struct ns__myContract contract;
    bool accept;
    soap_default_ns__myContract(soap, &contract);
    contract.name = ...;
    contract.title = ...;
    contract.terms = ...;
    if (soap_wsse_add_BinarySecurityTokenX509(soap, "X509Token", cert)
     || soap_wsse_add_KeyInfo_SecurityTokenReferenceX509(soap, "#X509Token")
     || soap_wsse_sign(soap, SOAP_SMD_SIGN_RSA_SHA1, rsa_private_key, 0))
      ... // an error occurred
    else if (soap_call_ns__myMethod(soap, contract, &accept))
      ... // a transmission error occurred

The above example shows a wsu:Id attribute embedded (hardcoded) in a struct. When it is not possible to add the wsu__Id member, for example when the type is a string instead of a struct, it is suggested to specify the XML element to be signed with the soap_wsse_set_wsu_id(soap, "space-separated string of element names") function, to be used before each call or when returning from a service operation. This lets the engine add wsu:Id="tag" attribute-value pair to the element's tag name. For example:

    soap_wsse_set_wsu_id(soap, "ns:myContract"); // <ns:myContract wsu:Id="ns:myContract">...
    if (soap_wsse_add_BinarySecurityTokenX509(soap, "X509Token", cert)
     || soap_wsse_add_KeyInfo_SecurityTokenReferenceX509(soap, "#X509Token")
     || soap_wsse_sign(soap, SOAP_SMD_SIGN_RSA_SHA1, rsa_private_key, 0))
      ... // an error occurred
    soap_wsse_set_wsu_id(soap, NULL);
This adds the wsu:Id="ns-myContract" to the ns:myContract element. Here, the wsu__Id value in the struct MUST NOT be set. Otherwise, two wsu:Id attributes are present which is invalid. Also, the element signed must be unique in the message. That is, there cannot be more than one matching element, otherwise the resulting signature is invalid.

We recommend to sign the entire SOAP Body using soap_wsse_sign_body and reserve the use of soap_wsse_set_wsu_id for SOAP Header elements, such as WS-Addressing elements. For example:

    #include "wsaapi.h"
    ...
    soap_wsa_request(soap, RequestMessageID, ToAddress, RequestAction);
    soap_wsse_set_wsu_id(soap, "wsa5:To wsa5:From wsa5:ReplyTo wsa5:Action");
    if (soap_wsse_add_BinarySecurityTokenX509(soap, "X509Token", cert)
     || soap_wsse_add_KeyInfo_SecurityTokenReferenceX509(soap, "#X509Token")
     || soap_wsse_sign_body(soap, SOAP_SMD_SIGN_RSA_SHA1, rsa_private_key, 0))
      ... // an error occurred
    else if (soap_call_ns__myMethod(soap, ...))
      ... // a transmission error occurred
    soap_wsse_set_wsu_id(soap, NULL);
This signs the wsa5:To and wsa5:Action SOAP header elements (set with soap_wsa_request, see the WS-Addressing "wsa" API in the gSOAP documentation for more information on the use of WS-Addressing). It is fine to specify more elements than present in the XML payload. The other WS-Addressing headers are not present and are not signed.

Note: soap_wsse_set_wsu_id should only be set once for each soap_wsse_sign or soap_wsse_sign_body. Each new call overrides the previous.

Note: to reset the automatic wsu:Id attributes addition, pass NULL to soap_wsse_set_wsu_id. This is automatically performed when a new message is received (but not automatically in a sequence of one-way sends for example).

Note: never use soap_wsse_set_wsu_id to set the wsu:Id for an element that occurs more than once in the payload, since each will have the same wsu:Id attribute that may lead to a WS-Signature failure.

Signing Tokens

To sign security tokens such as user names, passwords, and binary security tokens, just assign their Id values with a unique string, such as "Time" for timestamps and "User" for user names. For example:

    soap_wsse_add_Timestamp(soap, "Time", 600);
    soap_wsse_add_UsernameTokenDigest(soap, "User", "username", "password");
    ... // the rest of the signing code

Note that by default all wsu:Id-attributed elements are signed. To filter a subset of wsu:Id-attributed elements for signatures, use the soap_wsse_sign_only function as follows:

    soap_wsse_add_UsernameTokenDigest(soap, "User", "username", "password");
    soap_wsse_add_BinarySecurityTokenX509(soap, "X509Token", cert);
    soap_wsse_add_KeyInfo_SecurityTokenReferenceX509(soap, "#X509Token");
    soap_wsse_sign_body(soap, SOAP_SMD_SIGN_RSA_SHA1, rsa_private_key, 0);
    soap_wsse_sign_only(soap, "User Body");

Note that in the above we MUST set the X509Token name for cross-referencing with a wsu:Id, which normally results in automatically signing that token unless filtered out with soap_wsse_sign_only. The SOAP Body wsu:Id is always "Body" and should be part of the soap_wsse_sign_only set of wsu:Id names to sign.

When using soap_wsse_set_wsu_id we need to use the tag name with soap_wsse_sign_only. For example:

    soap_wsa_request(soap, RequestMessageID, ToAddress, RequestAction);
    soap_wsse_set_wsu_id(soap, "wsa5:To wsa5:From wsa5:ReplyTo wsa5:Action");
    soap_wsse_add_UsernameTokenDigest(soap, "User", "username", "password");
    soap_wsse_add_BinarySecurityTokenX509(soap, "X509Token", cert);
    soap_wsse_add_KeyInfo_SecurityTokenReferenceX509(soap, "#X509Token");
    soap_wsse_sign_body(soap, SOAP_SMD_SIGN_RSA_SHA1, rsa_private_key, 0);
    soap_wsse_sign_only(soap, "wsa5:To wsa5:From wsa5:ReplyTo wsa5:Action User Body");

Note: soap_wsse_sign_only should only be set once for each soap_wsse_sign or soap_wsse_sign_body. Each new call overrides the previous.

Note: to reset the filtering of signed tokens and elements, pass NULL to soap_wsse_sign_only. This is automatically performed when a new message is received (but not automatically in a sequence of one-way sends for example).

Signature Validation

To automatically verify the signature of an inbound message signed with DSA or RSA algorithms, assuming the message contains the X509 certificate as a binary security token, use:

    struct soap *soap = soap_new1(SOAP_XML_CANONICAL | SOAP_XML_INDENT);
    soap_register_plugin(soap, soap_wsse);
    soap_wsse_verify_auto(soap, SOAP_SMD_NONE, NULL, 0);
    soap->cafile = "cacerts.pem";  // file with CA certs of peers
    soap->capath = "dir/to/certs"; // and/or point to CA certs
    soap->crlfile = "revoked.pem"; // use CRL (optional)

    // server:
    if (soap_serve(soap))
      ... // an error occurred

    // client:
    if (soap_call_ns__myMethod(soap, ...))
      ... // an error occurred

All locally referenced and signed elements in the signed message will be verified. Elements that are not signed cannot be verified. Also elements referenced with absolute URIs that are not part of the message are not automatically verified. The received message is stored in a DOM accessible with soap->dom. This enables further analysis of the message content.

For a post-parsing check to verify if an XML element was signed in an inbound message, use: 

    soap_wsse_verify_auto(soap, SOAP_SMD_NONE, NULL, 0);
    ... // client call
    if (soap_wsse_verify_element(soap, "namespaceURI", "tag") > 0)
      ... // at least one element with matching tag and namespace is signed
The signed element nesting rules are obeyed, so if the matching element is a descendent of a signed element, it is signed as well.

Because it is a post check, a client should invoke soap_wsse_verify_element after the call completed. A service should invoke this function within the service operation routine, i.e. when the message request is accepted and about to be processed.

For example, to check whether the wsu:Timestamp element was signed (assuming it is present and message expiration checked with soap_wsse_verify_Timestamp), use soap_wsse_verify_element(soap, "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd", "Timestamp").

To check the SOAP Body (either using SOAP 1.1 or 1.2), use the shorthand soap_wsse_verify_body(soap).

The soap_wsse_verify_auto function keeps processing signed (and unsigned) messages as they arrive. For unsigned messages this can be expensive and the verification engine should be shut down using soap_wsse_verify_done.

To verify the HMAC signature of an inbound message, the HMAC key must be supplied:

    static char hmac_key[16] = // the same secret key that was used to sign
    { 0xff, 0xee, 0xdd, 0xcc, 0xbb, 0xaa, 0x99, 0x88,
      0x77, 0x66, 0x55, 0x44, 0x33, 0x22, 0x11, 0x00 };
    struct soap *soap = soap_new1(SOAP_XML_CANONICAL | SOAP_XML_INDENT);
    soap_register_plugin(soap, soap_wsse);
    soap_wsse_verify_auto(soap, SOAP_SMD_HMAC_SHA1, hmac_key, sizeof(hmac_key));

    // server:
    if (soap_serve(soap))
      ... // an error occurred

    // client:
    if (soap_call_ns__myMethod(soap, ...))
      ... // an error occurred

To summarize the signature verification process:

  1. Register the wsse plugin.
  2. For HMAC, obtain the HMAC secret key
  3. Use soap_wsse_verify_auto to verify inbound messages.
  4. Set the cafile (or capath) to verify certificates of the peers and crlfile (optional)
  5. After receiving a message, the DOM in soap->dom can be traversed for further analysis.
  6. Always check the function return values for errors. You don't want to accept a request or response message with an invalid Security header.
  7. Use soap_wsse_verify_done to terminate verification, e.g. to consume plain messages more efficiently.

Encryption

The material in this section relates to the WS-Security specification section 9.

The wsse plugin must be registered:

    struct soap *soap = soap_new1(SOAP_XML_CANONICAL | SOAP_XML_INDENT);
    soap_register_plugin(soap, soap_wsse);

Other flags to consider:

Encrypting Messages

Encryption should be used in combination with signing. A signature ensures message integrity while encryption ensures confidentially. However, encrypted messages can be tampered with unless integrity is ensured. Therefore, Section Signatures should be followed to sign and verify message content.

Messages are encrypted using either public key cryptography or a symmetric secret key that is only shared between the sender and receiver.

Encryption with public key cryptography uses an "envelope" process, where the public key of the recipient is used to encrypt a temporary (ephemeral) secret key that is sent together with the secret key-encrypted message to the recipient. The recipient decrypts the ephemeral key and uses it to decrypt the message. The public key is usually part of a X509 certificate. The public key (containing the subject information) is added to the WS-Security header and used for encryption of the SOAP Body as follows:

    X509 *cert = ...; //
    if (soap_wsse_add_EncryptedKey(soap, "Cert", cert, NULL))
      soap_print_fault(soap, stderr);

The "Cert" parameter is a unique URI to reference the key from the encrypted SOAP Body. The above enables the encryption engine for the next message to be sent, either at the client or server side. The server should use this withing a server operation (before returning) to enable the service operation response to be encrypted.

To include a subject key ID in the WS-Security header instead of the entire public key, specify the subject key ID parameter:

    X509 *cert = ...; //
    if (soap_wsse_add_EncryptedKey(soap, "Cert", cert, "Subject Key ID"))
      soap_print_fault(soap, stderr);

The difference with the previous example where no subject key ID was specified is that the WS-Security header only contains the subject key ID and no longer the public key in base64 format.

For symmetric encryption with a shared secret key, generate a 160-bit triple DES key and make sure both the sender and reciever can use the key without it being shared by any other party (key exchange problem). Then use the soap_wsse_encrypt_body function to encrypt the SOAP Body as follows:

    char des_key[20] = ...; // 20-byte (160-bit) secret key
    if (soap_wsse_encrypt_body(soap, SOAP_MEC_ENC_DES_CBC, des_key, sizeof(des_key)))
      soap_print_fault(soap, stderr);

Decrypting Message Parts

The wsse engine automatically decrypts message parts, but requires a private key or secret shared key to do so. A default key can be given to enable decryption, but it will fail if a non-compatible key was used for encryption. In that case a token handler callback should be defined by the user to select a proper decryption key based on the available subject key name or identifier embedded in the encrypted message.

Here is an example of a token handler callback:

    soap_register_plugin_arg(soap, soap_wsse, security_token_handler);

    const void *security_token_handler(struct soap *soap, int alg, const char *keyname, int *keylen)
    { // Note: 'keyname' argument is only used with shared secret key decryption
      // Get the user name from UsernameToken in message
      const char *uid = soap_wsse_get_Username(soap);
      switch (alg)
      { case SOAP_SMD_VRFY_DSA_SHA1:
        case SOAP_SMD_VRFY_RSA_SHA1:
          if (uid)
          { // Lookup uid to retrieve the X509 certificate to verify the signature
            const X509 *cert = ...; 
            return (const void*)cert;
          }
          return NULL; // no certificate: fail
        case SOAP_SMD_HMAC_SHA1:
          if (uid)
          { // Lookup uid to retrieve the HMAC key to verify the signature
            const void *key = ...; 
            *keylen = ...;
            return key;
          }
          return NULL; // no certificate: fail
        case SOAP_MEC_ENV_DEC_DES_CBC
          // return decryption private key associated with keyname
        case SOAP_MEC_DEC_DES_CBC
          // *keylen = ...
          // return decryption shared secret key associated with keyname
      }
      return NULL; // fail
    }

The last two arms are used to return a private key associated with the keyname paramater, which is a string that contains the subject key id from the public key information in an encrypted message or the subject key ID string that was set with soap_wsse_add_EncryptedKey at the sender side.

To set the default private key for envelope decryption, use:

    EVP_PKEY *rsa_private_key = ...;
    soap_wsse_decrypt_auto(soap, SOAP_MEC_ENV_DEC_DES_CBC, rsa_private_key, 0);

Or to set the default shared secret key for symmetric decryption, use:

    char des_key[20] = ...; // 20-byte (160-bit) triple DES key
    soap_wsse_decrypt_auto(soap, SOAP_MEC_DEC_DES_CBC, des_key, sizeof(des_key));

If a default key is not set, the token handler callback should be used as discussed above in this section. Do NOT set a default key if a token handler is used to handle multiple different keys. The default key mechanism is simpler to use when only one decryption key is used to decrypt all encrypted messages.

To remove the default key, use:

    soap_wsse_decrypt_auto(soap, SOAP_MEC_NONE, NULL, 0);

Example Combining Signing with Encryption/Decryption

Here is an client-side example to use signatures and encryption for the outbound service request message and verification and decryption of the inbound response message:

    FILE *fd;
    EVP_PKEY *rsa_private_key;
    X509 *cert;
    struct soap *soap = soap_new1(SOAP_XML_CANONICAL | SOAP_XML_INDENT);
    soap_register_plugin(soap, soap_wsse);
    soap_wsse_verify_auto(soap, SOAP_SMD_NONE, NULL, 0);
    fd = fopen("privkey.pem", "r");
    rsa_private_key = PEM_read_PrivateKey(fd, NULL, NULL, "password");
    fclose(fd);
    soap_wsse_decrypt_auto(soap, SOAP_MEC_ENV_DEC_DES_CBC, rsa_private_key, 0);
    fd = fopen("cert.pem", "r");
    X509 *cert = PEM_read_X509(fd, NULL, NULL, NULL);
    fclose(fd);
    if (soap_wsse_add_BinarySecurityTokenX509(soap, "X509Token", cert)
     || soap_wsse_add_KeyInfo_SecurityTokenReferenceX509(soap, "#X509Token")
     || soap_wsse_add_EncryptedKey(soap, "Cert", cert, NULL)
     || soap_wsse_sign_body(soap, SOAP_SMD_SIGN_RSA_SHA1, rsa_private_key, 0)
      ... // an error occurred
    else if (soap_call_ns__myMethod(soap, ...))
      ... // a transmission error occurred
    ...
    EVP_PKEY_free(rsa_private_key);
    X509_free(cert);

The server-side service operation is as follows:

    FILE *fd;
    EVP_PKEY *rsa_private_key;
    X509 *cert;
    struct soap *soap = soap_new1(SOAP_XML_CANONICAL | SOAP_XML_INDENT);
    soap_register_plugin(soap, soap_wsse);
    soap_wsse_verify_auto(soap, SOAP_SMD_NONE, NULL, 0);
    fd = fopen("privkey.pem", "r");
    rsa_private_key = PEM_read_PrivateKey(fd, NULL, NULL, "password");
    fclose(fd);
    soap_wsse_decrypt_auto(soap, SOAP_MEC_ENV_DEC_DES_CBC, rsa_private_key, 0);
    fd = fopen("cert.pem", "r");
    X509 *cert = PEM_read_X509(fd, NULL, NULL, NULL);
    fclose(fd);
    ...
    if (soap_serve(soap))
    { soap_wsse_delete_Security(soap);
      soap_print_fault(soap, stderr);
    }
    ...
    EVP_PKEY_free(rsa_private_key);
    X509_free(cert);

where an example service operation could be:

    int ns__myMethod(struct soap *soap, ...)
    { ...
      soap_wsse_delete_Security(soap);
      if (soap_wsse_add_BinarySecurityTokenX509(soap, "X509Token", cert)
       || soap_wsse_add_KeyInfo_SecurityTokenReferenceX509(soap, "#X509Token")
       || soap_wsse_add_EncryptedKey(soap, "Cert", cert, NULL)
       || soap_wsse_sign_body(soap, SOAP_SMD_SIGN_RSA_SHA1, rsa_private_key, 0)
        return soap->error;
      return SOAP_OK;
    }

The service operation signs the message using a private key and encrypts the response message using a public key (from the certificate).

Security Timestamps

The material in this section relates to the WS-Security specification section 10.

To add a timestamp with the creation time to the Security header, use:

    soap_wsse_add_Timestamp(soap, NULL, 0); // no expiration

The lifetime of a message (in seconds) is passed as the third argument, which will be displayed as the timestamp expiration time:

    soap_wsse_add_Timestamp(soap, NULL, 10); // 10 seconds lifetime

Timestamps, like other header elements, are not automatically secured with a digital signature. To secure a timestamp, we add an identifier (wsu:Id) to each element we want the WS-Security plugin to sign thereby making it impossible for someone to tamper with that part of the message. To do this for the timestamp, we simply pass a unique identification string as the second argument:

    soap_wsse_add_Timestamp(soap, "Time", 10); // timestamp will be signed

WS-Security and HTTPS

HTTPS is used at the client side with the usual "https:" URL addressing, shown here with the registration of the wsse plugin and setting up locks for thread-safe use of SSL for HTTPS:

    #include "wsseapi.h"
    #include "threads.h"
    struct soap *soap;
    if (CRYPTO_thread_setup())
      ... // error
    soap = soap_new1(SOAP_XML_CANONICAL | SOAP_XML_INDENT);
    soap_register_plugin(soap, soap_wsse);
    if (soap_ssl_client_context(&soap,
      SOAP_SSL_DEFAULT, // requires server authentication
      NULL,             // keyfile for client authentication to server
      NULL,             // the keyfile password
      "cacerts.pem",    // cafile CA certificates to authenticate the server
      NULL,             // capath CA directory path to certificates
      NULL
    ))
      ... // error
    soap->cafile = "cacerts.pem";  // same as above (or overrides the above)
    soap->capath = "dir/to/certs"; // and/or point to CA certs
    soap->crlfile = "revoked.pem"; // use CRL (optional)
    ... // set up WS-Security for signatures/encryption etc
    if (soap_call_ns__myMethod(soap, "https://...", ...))
      ... // error
    ... // process response results
    soap_destroy(soap);
    soap_end(soap);
    soap_free(soap);
    CRYPTO_thread_cleanup();

The CRYPTO threads should be set up before any threads are created.

The soap_ssl_client_context only needs to be set up once. Use the following flags:

The server uses the following:

    #include "wsseapi.h"
    #include "threads.h"
    SOAP_SOCKET m, s;
    int port = 443;
    struct soap *soap;
    if (CRYPTO_thread_setup())
      ... // error
    soap = soap_new1(SOAP_XML_CANONICAL | SOAP_XML_INDENT);
    soap_register_plugin(soap, soap_wsse);
    if (soap_ssl_server_context(&soap,
      SOAP_SSL_DEFAULT, // requires server to authenticate, but not the client
      server.pem,       // keyfile for authentication to client
      "password",       // the keyfile password
      NULL,             // CA certificates to authenticate the client
      NULL,             // CA directory path to certificates
      NULL,             // use RSA 2048 bits (or give file name with DH param)
      NULL,
      NULL
    ))
      ... // error
    if (!soap_valid_socket(m = soap_bind(soap, NULL, port, 100))
      ... // error
    for (;;)
    { if (!soap_valid_socket(s = soap_accept(soap)))
        ... // error
      THREAD_CREATE(&tid, (void*(*)(void*))&process_request, soap_copy(soap));
    }
    soap_destroy(soap);
    soap_end(soap);
    soap_free(soap);
    CRYPTO_thread_cleanup();

where we define a process_request function that is executed by the thread to process the request (on a copy of the soap context struct):

  void *process_request(struct soap *soap)
  { ... // set up WS-Security for signatures/encryption etc
    if (soap_ssl_accept(soap)
     || soap_serve(soap))
      ... // error
    soap_destroy(soap);
    soap_end(soap);
    soap_free(soap);
  }

The soap_ssl_server_context only needs to be set up once. Use the following flags:

We need to define the thread set up and clean up operations as follows:

  struct CRYPTO_dynlock_value
  { MUTEX_TYPE mutex;
  };

  static MUTEX_TYPE *mutex_buf;

  static struct CRYPTO_dynlock_value *dyn_create_function(const char *file, int line)
  { struct CRYPTO_dynlock_value *value;
    value = (struct CRYPTO_dynlock_value*)malloc(sizeof(struct CRYPTO_dynlock_value));
    if (value)
      MUTEX_SETUP(value->mutex);
    return value;
  }

  static void dyn_lock_function(int mode, struct CRYPTO_dynlock_value *l, const char *file, int line)
  { if (mode & CRYPTO_LOCK)
      MUTEX_LOCK(l->mutex);
    else
      MUTEX_UNLOCK(l->mutex);
  }

  static void dyn_destroy_function(struct CRYPTO_dynlock_value *l, const char *file, int line)
  { MUTEX_CLEANUP(l->mutex);
    free(l);
  }

  void locking_function(int mode, int n, const char *file, int line)
  { if (mode & CRYPTO_LOCK)
      MUTEX_LOCK(mutex_buf[n]);
    else
      MUTEX_UNLOCK(mutex_buf[n]);
  }

  unsigned long id_function()
  { return (unsigned long)THREAD_ID;
  }

  int CRYPTO_thread_setup()
  { int i;
    mutex_buf = (MUTEX_TYPE*)malloc(CRYPTO_num_locks() * sizeof(pthread_mutex_t));
    if (!mutex_buf)
      return SOAP_EOM;
    for (i = 0; i < CRYPTO_num_locks(); i++)
      MUTEX_SETUP(mutex_buf[i]);
    CRYPTO_set_id_callback(id_function);
    CRYPTO_set_locking_callback(locking_function);
    CRYPTO_set_dynlock_create_callback(dyn_create_function);
    CRYPTO_set_dynlock_lock_callback(dyn_lock_function);
    CRYPTO_set_dynlock_destroy_callback(dyn_destroy_function);
    return SOAP_OK;
  }

  void CRYPTO_thread_cleanup()
  { int i;
    if (!mutex_buf)
      return;
    CRYPTO_set_id_callback(NULL);
    CRYPTO_set_locking_callback(NULL);
    CRYPTO_set_dynlock_create_callback(NULL);
    CRYPTO_set_dynlock_lock_callback(NULL);
    CRYPTO_set_dynlock_destroy_callback(NULL);
    for (i = 0; i < CRYPTO_num_locks(); i++)
      MUTEX_CLEANUP(mutex_buf[i]);
    free(mutex_buf);
    mutex_buf = NULL;
  }

For additional details and examples, see the user guide and examples in the gSOAP package directory gsoap/samples/ssl.

Miscellaneous

The Security header block was generated from the WS-Security schema with the wsdl2h tool and WS/WS-typemap.dat:

    > wsdl2h -cegxy -o wsse.h -t WS/WS-typemap.dat WS/wsse.xsd

The same process was used to generate the header file ds.h from the XML digital signatures core schema, and the xenc.h encryption schema:

    > wsdl2h -cuxy -o ds.h -t WS/WS-typemap.dat WS/ds.xsd
    > wsdl2h -cuxy -o xenc.h -t WS/WS-typemap.dat WS/xenc.xsd

The import/wsse.h file has the following definition for the Security header block:

typedef struct _wsse__Security
{       struct _wsu__Timestamp*                 wsu__Timestamp;
        struct _wsse__UsernameToken*            UsernameToken;
        struct _wsse__BinarySecurityToken*      BinarySecurityToken;
        struct xenc__EncryptedKeyType*          xenc__EncryptedKey;
        struct _xenc__ReferenceList*            xenc__ReferenceList;
        struct ds__SignatureType*               ds__Signature;
        @char*                                  SOAP_ENV__actor;
        @char*                                  SOAP_ENV__role;
} _wsse__Security;

The _wsse__Security header is modified by a WS/WS-typemap.dat mapping rule to include additional details.

Generated on Fri Jan 14 09:45:25 2011 for gSOAP WS-Security by doxygen 1.3.8