<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html;charset=utf-8">
<meta http-equiv="cache-control" content="no-cache">
<title>Genivia - The WS-Security plugin</title>
<link href="genivia_tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css">
<link href="genivia_content.css" rel="stylesheet" type="text/css">
</head>
<body>
<div id="top">
<div id="titlearea">
<table height="72px" width="100%" cellspacing="0" cellpadding="0">
<tbody>
<tr>
<td width="10%"> </td>
<td width="175px"><a href="https://www.genivia.com"><img alt="Genivia" src="GeniviaLogo2_trans_noslogan.png"/></a></td>
<td class="tab_home"><a href="https://www.genivia.com">Home</a></td>
<td class="tab_home"><a href="https://www.genivia.com/docs.html">Documentation</a></td>
<td>
<div style="float: right; font-size: 18px; font-weight: bold;">The WS-Security plugin</div>
<br>
<div style="float: right; font-size: 10px;">updated Mon May 14 2018 by Robert van Engelen</div>
</td>
<td width="10%"> </td>
</tr>
</tbody>
</table>
</div>
<!-- Generated by Doxygen 1.8.11 -->
<div id="navrow1" class="tabs">
<ul class="tablist">
<li><a href="index.html"><span>Main Page</span></a></li>
<li class="current"><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="annotated.html"><span>Classes</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
</ul>
</div>
</div><!-- top -->
<div class="header">
<div class="headertitle">
<div class="title">The WS-Security plugin </div> </div>
</div><!--header-->
<div class="contents">
<div class="toc"><h3>Table of Contents</h3>
<ul><li class="level1"><a href="#wsse_5">Security Header</a></li>
<li class="level1"><a href="#wsse_6">Security Tokens</a><ul><li class="level2"><a href="#wsse_6_2">User Name Tokens</a></li>
<li class="level2"><a href="#wsse_6_3">Binary Security Tokens</a></li>
</ul>
</li>
<li class="level1"><a href="#wsse_6_4">SAML and Other Tokens</a></li>
<li class="level1"><a href="#wsse_7">Token References</a></li>
<li class="level1"><a href="#wsse_8">Signatures</a><ul><li class="level2"><a href="#wsse_8_2a">Signing Messages</a></li>
<li class="level2"><a href="#wsse_8_2b">Signing Message Parts</a></li>
<li class="level2"><a href="#wsse_8_3">Signing Security Headers and Tokens</a></li>
<li class="level2"><a href="#wsse_8_4">Signature Validation</a></li>
</ul>
</li>
<li class="level1"><a href="#wsse_9">Encryption</a><ul><li class="level2"><a href="#wsse_9_1">Encrypting Messages</a></li>
<li class="level2"><a href="#wsse_9_2">Decrypting Message Parts</a></li>
<li class="level2"><a href="#wsse_9_3">Example Client and Server</a></li>
</ul>
</li>
<li class="level1"><a href="#wsse_10">Security Timestamps</a></li>
<li class="level1"><a href="#wsse_11">WS-Security and HTTPS</a></li>
<li class="level1"><a href="#wsse_12">Miscellaneous</a></li>
<li class="level1"><a href="#wsse_13">Some Limitations</a></li>
<li class="level1"><a href="#wsse_14">Defending Against Signature Wrapping Attacks</a></li>
<li class="level1"><a href="#wsse_wsc">WS-SecureConversation and WS-Trust</a></li>
</ul>
</div>
<div class="textblock"><h1><a class="anchor" id="wsse_5"></a>
Security Header</h1>
<p>The material in this section relates to the WS-Security specification section 5.</p>
<p>To use the wsse plugin:</p><ol type="1">
<li>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.</li>
<li>Run soapcpp2 on the header file produced by wsdl2h.</li>
<li>(Re-)compile stdsoap2.c/pp, dom.c/pp, <a class="el" href="smdevp_8c.html">smdevp.c</a>, <a class="el" href="mecevp_8c.html">mecevp.c</a>, <a class="el" href="wsseapi_8c.html">wsseapi.c</a> and the generated source files with the <code>-DWITH_DOM</code> and <code>-DWITH_OPENSSL</code> compiler flags set. The <a class="el" href="smdevp_8c.html">smdevp.c</a>, <a class="el" href="mecevp_8c.html">mecevp.c</a>, and <a class="el" href="wsseapi_8c.html">wsseapi.c</a> files are located in the 'plugin' directory.</li>
<li>Use the wsse plugin API functions described below to add and verify Security headers, sign and verify messages, and to encrypt/decrypt messages.</li>
</ol>
<p>An example WS-Security client/server application can be found in gsoap/samples/wsse.</p>
<p>Another example WS-Security client/server application that is designed to interoperate with WCF can be found in gsoap/samples/WCF/Basic/MessageSecurity.</p>
<dl class="section warning"><dt>Warning</dt><dd>The security token handler callback function parameters have changed in 2.8.34 and greater with the addition of KeyIdentifier information <code>keyid</code> and <code>keyidlen</code>. To register your own security token handler function with the plugin, make sure that your functions matches these function parameters: <div class="fragment"><div class="line"><span class="keyword">const</span> <span class="keywordtype">void</span> *security_token_handler(<span class="keyword">struct</span> soap *soap, <span class="keywordtype">int</span> *alg, <span class="keyword">const</span> <span class="keywordtype">char</span> *keyname, <span class="keyword">const</span> <span class="keywordtype">unsigned</span> <span class="keywordtype">char</span> *keyid, <span class="keywordtype">int</span> keyidlen, <span class="keywordtype">int</span> *keylen);</div></div><!-- fragment --></dd></dl>
<p>The wsse engine is thread safe. However, if HTTPS is required then please follow the instructions in Section <a class="el" href="wsse.html#wsse_11">WS-Security and HTTPS</a> to ensure thread-safety of WS-Security with HTTPS.</p>
<p>The wsse API code is implemented in:</p>
<ul>
<li><code><a class="el" href="wsseapi_8h.html">gsoap/plugin/wsseapi.h</a></code> wsse API declarations.</li>
<li><code><a class="el" href="wsseapi_8c.html">gsoap/plugin/wsseapi.c</a></code> wsse API for C and C++.</li>
</ul>
<p>You will also need:</p>
<ul>
<li><code><a class="el" href="smdevp_8c.html">gsoap/plugin/smdevp.c</a></code> compile and link this file (C and C++).</li>
<li><code><a class="el" href="mecevp_8c.html">gsoap/plugin/mecevp.c</a></code> compile and link this file (C and C++).</li>
<li>compile all sources with <code>-DWITH_OPENSSL -DWITH_DOM</code>.</li>
<li>if you have zlib installed, compile all sources also with <code>-DWITH_GZIP</code>.</li>
<li>link with <code>-lssl -lcrypto -lz -gsoapssl++</code> (or <code>-lgsoapssl</code> for C, or compile <code>stdsoap2.cpp</code> for C++ and <code>stdsoap2.c</code> for C).</li>
</ul>
<p>The gSOAP header file (generated with wsdl2h, and containing the data binding interface for soapcpp2) should import <a class="el" href="wsse_8h.html">wsse.h</a> (or the older 2002 version wsse2.h):</p>
<div class="fragment"><div class="line"><span class="preprocessor">#import "<a class="code" href="wsse_8h.html">wsse.h</a>"</span></div></div><!-- fragment --><p>The wsdl2h tool adds the necessary imports to the generated header file if the WSDL declares the use of WS-Security. If not, you may have to add the import manually before running soapcpp2.</p>
<p>The wsse API consists of a set of functions to populate and verify WS-Security headers and message body content. For more details, we refer to the following sections that correspond to the WS-Security specification sections:</p>
<ul>
<li>Section 6 <a class="el" href="wsse.html#wsse_6">Security Tokens</a></li>
<li>Section 7 <a class="el" href="wsse.html#wsse_7">Token References</a></li>
<li>Section 8 <a class="el" href="wsse.html#wsse_8">Signatures</a></li>
<li>Section 9 <a class="el" href="wsse.html#wsse_9">Encryption</a></li>
<li>Section 10 <a class="el" href="wsse.html#wsse_10">Security Timestamps</a></li>
<li><a class="el" href="wsse.html#wsse_11">WS-Security and HTTPS</a></li>
<li><a class="el" href="wsse.html#wsse_12">Miscellaneous</a></li>
<li><a class="el" href="wsse.html#wsse_13">Some Limitations</a></li>
<li><a class="el" href="wsse.html#wsse_wsc">WS-SecureConversation and WS-Trust</a></li>
</ul>
<p>The basic API is introduced below.</p>
<p>To add an empty Security header block to the SOAP header, use:</p>
<div class="fragment"><div class="line"><a class="code" href="wsseapi_8h.html#acdc56c76c1a39c3e6191580d491f9b8e">soap_wsse_add_Security</a>(soap);</div></div><!-- fragment --><p>To delete a Security header, use:</p>
<div class="fragment"><div class="line"><a class="code" href="wsseapi_8h.html#ac06c7021592b2aaca50f73e0de9dec7c">soap_wsse_delete_Security</a>(soap);</div></div><!-- fragment --><p>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.</p>
<dl class="section note"><dt>Note</dt><dd>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.</dd></dl>
<p>To populate the SOAP-ENV:actor or SOAP-ENV:role attribute within the Security header, use:</p>
<div class="fragment"><div class="line"><a class="code" href="wsseapi_8h.html#a16b318c7c4e19d55a07503d72b49e0d7">soap_wsse_add_Security_actor</a>(soap, <span class="stringliteral">"recipient"</span>);</div></div><!-- fragment --><p>To obtain the actor or role value (e.g. after receiving a message), use:</p>
<div class="fragment"><div class="line"><a class="code" href="struct__wsse_____security.html">_wsse__Security</a> *security = <a class="code" href="wsseapi_8h.html#ae7775b49a0cd57c7cf85db7bb18b034d">soap_wsse_Security</a>(soap);</div><div class="line"><span class="keywordflow">if</span> (security)</div><div class="line">{</div><div class="line"> ... = security-><a class="code" href="struct__wsse_____security.html#a1a941d6f69eab871bced7acdb6eb41f3">SOAP_ENV__actor</a>; <span class="comment">// SOAP 1.1</span></div><div class="line"> ... = security-><a class="code" href="struct__wsse_____security.html#a86e02ae8da9bf2f6e1dd6eda8f596012">SOAP_ENV__role</a>; <span class="comment">// SOAP 1.2</span></div></div><!-- fragment --><p>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.</p>
<p>Security header blocks are attached to the soap context, which means that the information will be automatically kept to support multiple invocations.</p>
<h1><a class="anchor" id="wsse_6"></a>
Security Tokens</h1>
<p>The material in this section relates to the WS-Security specification section 6.</p>
<h2><a class="anchor" id="wsse_6_2"></a>
User Name Tokens</h2>
<p>To add a user name token to the Security header block, use:</p>
<div class="fragment"><div class="line"><a class="code" href="wsseapi_8h.html#a37f32e51bceabf2e2823516a1737548f">soap_wsse_add_UsernameTokenText</a>(soap, <span class="stringliteral">"Id"</span>, <span class="stringliteral">"username"</span>, NULL);</div></div><!-- fragment --><p>The <code>Id</code> 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 <code>Id</code>s, 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.</p>
<p>To add a user name token with clear text password, use:</p>
<div class="fragment"><div class="line"><a class="code" href="wsseapi_8h.html#a37f32e51bceabf2e2823516a1737548f">soap_wsse_add_UsernameTokenText</a>(soap, <span class="stringliteral">"Id"</span>, <span class="stringliteral">"username"</span>, <span class="stringliteral">"password"</span>);</div></div><!-- fragment --><p>It is strongly recommended to use <code>soap_wsse_add_UsernameTokenText</code> 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.</p>
<p>To add a user name token with password digest, use:</p>
<div class="fragment"><div class="line"><a class="code" href="wsseapi_8h.html#ac9fe59008bdf12d7a007ac48e6ebb613">soap_wsse_add_UsernameTokenDigest</a>(soap, <span class="stringliteral">"Id"</span>, <span class="stringliteral">"username"</span>, <span class="stringliteral">"password"</span>);</div></div><!-- fragment --><p>Although the password string is passed to this function, it is not rendered in XML or stored in a message log. Only digests are compared on both sides, not the passwords. This authentication method adds a timestamp and nonce to prevent message replay attacks.</p>
<p>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. This is a common approach adopted by Unix for decades.</p>
<p>By setting the <code>Id</code> value to a unique string, the user name token is also digitally signed by the signature engine further preventing tampering with its value.</p>
<p>You must use <code>soap_wsse_add_UsernameTokenDigest</code> 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.</p>
<p>To specify a time stamp for the digest instead of the current time, use:</p>
<div class="fragment"><div class="line">time_t when = ...;</div><div class="line"><a class="code" href="wsseapi_8h.html#a7204edbdd78caf5f1e26f0244e0214ee">soap_wsse_add_UsernameTokenDigest_at</a>(soap, <span class="stringliteral">"Id"</span>, <span class="stringliteral">"username"</span>, <span class="stringliteral">"password"</span>, when);</div></div><!-- fragment --><p>Clear-text passwords and password digests are verified with <code>soap_wsse_verify_Password</code>. To verify a password at the receiving side to authorize a request (e.g. within a Web service operation), use:</p>
<div class="fragment"><div class="line"><span class="keywordtype">int</span> ns__myMethod(<span class="keyword">struct</span> soap *soap, ...)</div><div class="line">{</div><div class="line"> <span class="keyword">const</span> <span class="keywordtype">char</span> *username = <a class="code" href="wsseapi_8h.html#aca3fe6fb7c1e5c103827b33f24292f47">soap_wsse_get_Username</a>(soap);</div><div class="line"> <span class="keyword">const</span> <span class="keywordtype">char</span> *password;</div><div class="line"> <span class="keywordflow">if</span> (!username)</div><div class="line"> {</div><div class="line"> <a class="code" href="wsseapi_8h.html#ac06c7021592b2aaca50f73e0de9dec7c">soap_wsse_delete_Security</a>(soap); <span class="comment">// remove old security headers</span></div><div class="line"> <span class="keywordflow">return</span> soap->error; <span class="comment">// no username: return FailedAuthentication (from soap_wsse_get_Username)</span></div><div class="line"> }</div><div class="line"> password = ...; <span class="comment">// lookup password of username</span></div><div class="line"> <span class="keywordflow">if</span> (<a class="code" href="wsseapi_8h.html#aeb0afd01a5036e4f1314a3cfe8575bd5">soap_wsse_verify_Password</a>(soap, password))</div><div class="line"> {</div><div class="line"> <span class="keywordtype">int</span> err = soap->error;</div><div class="line"> <a class="code" href="wsseapi_8h.html#ac06c7021592b2aaca50f73e0de9dec7c">soap_wsse_delete_Security</a>(soap); <span class="comment">// remove old security headers</span></div><div class="line"> <span class="comment">// if it is required to return signed faults, then add the following six lines here:</span></div><div class="line"> <span class="keywordflow">if</span> (<a class="code" href="wsseapi_8h.html#a53075fb3cec4ec4e70fb11850fecb401">soap_wsse_add_BinarySecurityTokenX509</a>(soap, <span class="stringliteral">"X509Token"</span>, cert)</div><div class="line"> || <a class="code" href="wsseapi_8h.html#a72df80abd1d36cea516feda3a84672cf">soap_wsse_add_KeyInfo_SecurityTokenReferenceX509</a>(soap, <span class="stringliteral">"#X509Token"</span>)</div><div class="line"> || <a class="code" href="wsseapi_8h.html#ab653754f1a287ba06bd808cf89548c38">soap_wsse_sign_body</a>(soap, <a class="code" href="smdevp_8h.html#a8634e2291f274a42107d3e935add3241">SOAP_SMD_SIGN_RSA_SHA256</a>, rsa_private_key, 0)</div><div class="line"> {</div><div class="line"> <a class="code" href="wsseapi_8h.html#ac06c7021592b2aaca50f73e0de9dec7c">soap_wsse_delete_Security</a>(soap); <span class="comment">// remove security headers (failed construction)</span></div><div class="line"> <span class="keywordflow">return</span> soap->error;</div><div class="line"> }</div><div class="line"> <span class="keywordflow">return</span> err; <span class="comment">// password verification failed: return FailedAuthentication</span></div><div class="line"> }</div><div class="line"> ... <span class="comment">// process request, then sign the response message:</span></div><div class="line"> <span class="keywordflow">if</span> (<a class="code" href="wsseapi_8h.html#a53075fb3cec4ec4e70fb11850fecb401">soap_wsse_add_BinarySecurityTokenX509</a>(soap, <span class="stringliteral">"X509Token"</span>, cert)</div><div class="line"> || <a class="code" href="wsseapi_8h.html#a72df80abd1d36cea516feda3a84672cf">soap_wsse_add_KeyInfo_SecurityTokenReferenceX509</a>(soap, <span class="stringliteral">"#X509Token"</span>)</div><div class="line"> || <a class="code" href="wsseapi_8h.html#ab653754f1a287ba06bd808cf89548c38">soap_wsse_sign_body</a>(soap, <a class="code" href="smdevp_8h.html#a8634e2291f274a42107d3e935add3241">SOAP_SMD_SIGN_RSA_SHA256</a>, rsa_private_key, 0)</div><div class="line"> {</div><div class="line"> <a class="code" href="wsseapi_8h.html#ac06c7021592b2aaca50f73e0de9dec7c">soap_wsse_delete_Security</a>(soap); <span class="comment">// remove security headers (failed construction)</span></div><div class="line"> <span class="keywordflow">return</span> soap->error;</div><div class="line"> }</div><div class="line"> <span class="keywordflow">return</span> SOAP_OK;</div><div class="line">}</div></div><!-- fragment --><p>Note that the <code>soap_wsse_get_Username</code> functions sets the wsse:FailedAuthentication fault upon failure. It is common for the wsse plugin functions to return <code>SOAP_OK</code> or a wsse fault that should be passed to the sender by returning soap->error from service operations. The fault is displayed with the <code>soap_print_fault</code> function. To return signed faults back to the client, a signature is constructed as shown in the code snippet above. When the signature construction itself fails, we delete the partially constructed signature and return the fault to the client.</p>
<p>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 <a class="el" href="threads_8h.html">threads.h</a>. 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 <code>SOAP_WSSE_CLKSKEW</code> at the server side.</p>
<h2><a class="anchor" id="wsse_6_3"></a>
Binary Security Tokens</h2>
<p>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.</p>
<p>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:</p>
<div class="fragment"><div class="line">soap->cafile = <span class="stringliteral">"cacerts.pem"</span>; <span class="comment">// use this</span></div><div class="line">soap->capath = <span class="stringliteral">"dir/to/certs"</span>; <span class="comment">// and/or point to CA certs</span></div><div class="line">soap->crlfile = <span class="stringliteral">"revoked.pem"</span>; <span class="comment">// use CRL (optional)</span></div></div><!-- fragment --><p>The <code>soap_wsse_verify_X509</code> 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:</p>
<div class="fragment"><div class="line">X509 *cert = <a class="code" href="wsseapi_8h.html#a2ec22f47b0c66b62ef3c96d8f7b31436">soap_wsse_get_BinarySecurityTokenX509</a>(soap, <span class="stringliteral">"Id"</span>);</div></div><!-- fragment --><p>where <code>Id</code> is the identification string of the binary security token or NULL to get the first found in the Security header.</p>
<p>The X509 certificate returned by this function should be freed with <code>X509_free</code> to deallocate the certificate data:</p>
<div class="fragment"><div class="line"><span class="keywordflow">if</span> (cert)</div><div class="line"> X509_free(cert);</div><div class="line">cert = NULL;</div></div><!-- fragment --><p>The verification is an expensive process that will be optimized in future releases by caching the certificate chain.</p>
<p>To attach a binary security token stored in a PEM file to a Security header block for transmission, use:</p>
<div class="fragment"><div class="line"><a class="code" href="wsseapi_8h.html#ad88d8317bcbbcda4cdc8d1bcfb2e0f18">soap_wsse_add_BinarySecurityTokenPEM</a>(soap, NULL, <span class="stringliteral">"mycert.pem"</span>)</div></div><!-- fragment --><p>A binary security token can be automatically signed by setting its <code>Id</code> attribute:</p>
<div class="fragment"><div class="line"><a class="code" href="wsseapi_8h.html#ad88d8317bcbbcda4cdc8d1bcfb2e0f18">soap_wsse_add_BinarySecurityTokenPEM</a>(soap, <span class="stringliteral">"X509Token"</span>, <span class="stringliteral">"mycert.pem"</span>)</div></div><!-- fragment --><p>Repeatedly loading a certificate from a PEM file is inefficient. To reuse a certificate loaded from a PEM file for multiple invocations, use:</p>
<div class="fragment"><div class="line">FILE *fd = fopen(<span class="stringliteral">"mycert.pem"</span>, <span class="stringliteral">"r"</span>);</div><div class="line">X509 *cert = PEM_read_X509(fd, NULL, NULL, NULL);</div><div class="line">fclose(fd);</div><div class="line"><span class="keywordflow">if</span> (<a class="code" href="wsseapi_8h.html#a53075fb3cec4ec4e70fb11850fecb401">soap_wsse_add_BinarySecurityTokenX509</a>(soap, <span class="stringliteral">"X509Token"</span>, cert))</div><div class="line"> ... <span class="comment">// an error occurred</span></div></div><!-- fragment --><p>Other types of binary security tokens can be added to the Security header block using:</p>
<div class="fragment"><div class="line"><a class="code" href="wsseapi_8h.html#a272ece3d02d7fbb5309cda9d1b252822">soap_wsse_add_BinarySecurityToken</a>(soap, <span class="stringliteral">"Id"</span>, <span class="stringliteral">"valueType"</span>, data, datalen);</div></div><!-- fragment --><h1><a class="anchor" id="wsse_6_4"></a>
SAML and Other Tokens</h1>
<p>The use and processing rules for tokens such as SAML assertions is specific to an application. SAML 1.0 and 2.0 tokens are supported with the following functions to retrieve them from Security header blocks:</p>
<div class="fragment"><div class="line">saml1__AssertionType *assertion1 = soap_wsse_get_saml1(soap);</div></div><!-- fragment --><div class="fragment"><div class="line">saml2__AssertionType *assertion2 = soap_wsse_get_saml2(soap);</div></div><!-- fragment --><p>The pointers returned are non-NULL when these tokens are present. You can verify that a token is signed by the signature of the Security header with:</p>
<div class="fragment"><div class="line">saml2__AssertionType *assertion2 = soap_wsse_get_saml2(soap);</div><div class="line"><span class="keywordflow">if</span> (!assertion2 || <a class="code" href="wsseapi_8h.html#a3fbe81de521579f026dd1ba8e81c59c1">soap_wsse_verify_element</a>(soap, SOAP_NAMESPACE_OF_saml2, <span class="stringliteral">"Assertion"</span>) == 0)</div><div class="line"> ... error <span class="comment">// no Assertion or Assertion not signed by WS-Security signature (zero Assertion elements signed)</span></div></div><!-- fragment --><p>If the SAML token received contains a signature and/or time range conditions then you should verify that the SAML token is valid after receiving it in a Security header block of a WS-Security message:</p>
<div class="fragment"><div class="line"><span class="keywordflow">if</span> (saml2->saml2__Conditions)</div><div class="line">{</div><div class="line"> time_t now = time(NULL);</div><div class="line"> <span class="keywordflow">if</span> (saml2->saml2__Conditions->NotBefore && *saml2->saml2__Conditions->NotBefore > now)</div><div class="line"> ... error <span class="comment">// not valid yet</span></div><div class="line"> <span class="keywordflow">if</span> (saml2->saml2__Conditions->NotOnOrAfter && *saml2->saml2__Conditions->NotOnOrAfter <= now)</div><div class="line"> ... error <span class="comment">// expired</span></div><div class="line">}</div><div class="line"><span class="keywordflow">if</span> (saml2->ds__Signature)</div><div class="line"> <span class="keywordflow">if</span> (<a class="code" href="wsseapi_8h.html#a9683d6e2780bf1d679e191ea18591cbc">soap_wsse_verify_with_signature</a>(soap, saml2->ds__Signature))</div><div class="line"> ... error <span class="comment">// Assertion has signature but token is invalid</span></div></div><!-- fragment --><p>The above assumes that a WS-Security message was received that was signed and decrypted (when applicable).</p>
<dl class="section note"><dt>Note</dt><dd>The resolution of the dateTime values of <code>NotBefore</code> and <code>NotOnOrAfter</code> is determined by the clock resolution of <code>time_t</code>, which is usually seconds. To increase the resolution, edit <code>gsoap/import/saml2.h</code> and add <code>#import "custom/struct_timeval.h"</code>. Then replace <code>time_t</code> in <code>gsoap/import/saml2.h</code> with <code>xsd__dateTime</code> to use <code>struct timeval</code>, which includes the time in seconds <code>tv_sec</code> and a microsecond offset <code>tv_usec</code>.</dd></dl>
<p>To add a SAML token to the WS-Security headers, use <code>soap_wsse_add_saml1(struct soap*, const char *id)</code> or <code>soap_wsse_add_saml2(struct soap*, const char *id)</code>:</p>
<div class="fragment"><div class="line">time_t now = time(NULL);</div><div class="line">saml1__AssertionType *assertion1 = soap_wsse_add_saml1(soap, <span class="stringliteral">"SAML1"</span>);</div><div class="line"><span class="keywordflow">if</span> (!assertion1)</div><div class="line"> ... <span class="comment">// error</span></div><div class="line">assertion1->IssueInstant = now;</div><div class="line">assertion1->Issuer = (<span class="keywordtype">char</span>*)<span class="stringliteral">"MyCompany"</span>;</div><div class="line">assertion1->saml1__Conditions = soap_new_saml1__ConditionsType(soap, -1);</div><div class="line"><span class="keywordflow">if</span> (!assertion1->saml1__Conditions)</div><div class="line"> ... <span class="comment">// error</span></div><div class="line"><span class="comment">// valid from now for up to one hour</span></div><div class="line">assertion1->saml1__Conditions->NotBefore = soap_new_dateTime(soap, -1)</div><div class="line">if (!assertion1->saml1__Conditions->NotBefore)</div><div class="line"> ... <span class="comment">// error</span></div><div class="line">*assertion1->saml1__Conditions->NotBefore = now;</div><div class="line">assertion1->saml1__Conditions->NotOnOrAfter = soap_new_dateTime(soap, -1)</div><div class="line">if (!assertion1->saml1__Conditions->NotOnOrAfter)</div><div class="line"> ... <span class="comment">// error</span></div><div class="line">*assertion1->saml1__Conditions->NotOnOrAfter = now + 3600;</div><div class="line">...</div></div><!-- fragment --><p>and, respectively:</p>
<div class="fragment"><div class="line">time_t now = time(NULL);</div><div class="line">saml2__AssertionType *assertion2 = soap_wsse_add_saml2(soap, <span class="stringliteral">"SAML2"</span>);</div><div class="line"><span class="keywordflow">if</span> (!assertion2)</div><div class="line"> ... <span class="comment">// error</span></div><div class="line">assertion2->IssueInstant = now;</div><div class="line">assertion2->saml2__Issuer = (<span class="keyword">struct </span>saml2__NameIDType*)soap_malloc(soap, <span class="keyword">sizeof</span>(<span class="keyword">struct</span> saml2__NameIDType));</div><div class="line">soap_default_saml2__NameIDType(soap, assertion2->saml2__Issuer);</div><div class="line">assertion2->saml2__Issuer->__item = (<span class="keywordtype">char</span>*)<span class="stringliteral">"MyCompany"</span>;</div><div class="line"><span class="comment">// valid from now for up to one hour</span></div><div class="line">assertion2->saml2__Conditions->NotBefore = soap_new_dateTime(soap, -1)</div><div class="line">if (!assertion2->saml2__Conditions->NotBefore)</div><div class="line"> ... <span class="comment">// error</span></div><div class="line">*assertion2->saml2__Conditions->NotBefore = now;</div><div class="line">assertion2->saml2__Conditions->NotOnOrAfter = soap_new_dateTime(soap, -1)</div><div class="line">if (!assertion2->saml2__Conditions->NotOnOrAfter)</div><div class="line"> ... <span class="comment">// error</span></div><div class="line">*assertion2->saml2__Conditions->NotOnOrAfter = now + 3600;</div><div class="line">...</div></div><!-- fragment --><p>The code shown above adds an empty SAML token to the Security header block after which the SAML assertion issuer, subject, conditions, statements, and attributes should be set. Once these are set, the assertion can be signed with a ds:Signature and X509 certificate added to the assertion to create an enveloped signature:</p>
<div class="fragment"><div class="line">EVP_PKEY *rsa_private_key; <span class="comment">// private key</span></div><div class="line">X509 *cert; <span class="comment">// certificate (e.g. in "cacert.pem")</span></div><div class="line">...</div><div class="line">saml2__AssertionType *assertion2 = soap_wsse_add_saml2(soap, <span class="stringliteral">"SAML2"</span>);</div><div class="line"><span class="keywordflow">if</span> (!assertion2)</div><div class="line"> ... <span class="comment">// error</span></div><div class="line">... <span class="comment">// set SAML issuer, subject, conditions, statements, and attributes</span></div><div class="line"><span class="keywordflow">if</span> (soap_wsse_sign_saml2(soap, assertion2, <a class="code" href="smdevp_8h.html#a8634e2291f274a42107d3e935add3241">SOAP_SMD_SIGN_RSA_SHA256</a>, private_key, 0, cert))</div><div class="line"> ... error <span class="comment">// could not sign and/or add cert to X509Data</span></div><div class="line">soap->cafile = <span class="stringliteral">"cacert.pem"</span>; <span class="comment">// file that contains the public certificate</span></div><div class="line"><span class="keywordflow">if</span> (soap_wsse_verify_saml2(soap, assertion2))</div><div class="line"> ... error <span class="comment">// coult not verify the signature, e.g. invalid key-certificate pair</span></div></div><!-- fragment --><p>It is a good habit to verify a SAML token that was created in memory with <code>int soap_wsse_verify_saml1(struct soap*, saml1__AssertionType *saml1)</code> or <code>int soap_wsse_verify_saml2(struct soap*, saml2__AssertionType *saml2)</code> as shown. This step is optional, but can be useful to detect if the private key and certificate are uncorrelated and should not be used.</p>
<p>The private key and certificate values can be obtained as shown in Section <a class="el" href="wsse.html#wsse_8_2a">Signing Messages</a>.</p>
<p>For implementing other types of tokens, you are encouraged to modify the <a class="el" href="wsse_8h.html">import/wsse.h</a> file to add more tokens to the <code><a class="el" href="struct__wsse_____security.html" title="This element defines the wsse:Security SOAP header element per Section 4. Imported element _wsse__Sec...">_wsse__Security</a></code> header block:</p>
<div class="fragment"><div class="line"><span class="keyword">struct </span>somens__SomeTokenType { @<span class="keywordtype">char</span> *wsu__Id; ... };</div><div class="line"></div><div class="line"><span class="keyword">typedef</span> <span class="keyword">struct </span><a class="code" href="struct__wsse_____security.html">_wsse__Security</a></div><div class="line">{ ...</div><div class="line"> <span class="keyword">struct </span>saml1__AssertionType* saml1__Assertion;</div><div class="line"> <span class="keyword">struct </span>saml2__AssertionType* saml2__Assertion;</div><div class="line"> <span class="keyword">struct </span>somens__SomeTokenType* somens__SomeToken; <span class="comment">// added an optional token</span></div><div class="line"> ... <span class="comment">// add more if needed</span></div><div class="line"> @<span class="keywordtype">char</span>* SOAP_ENV__actor;</div><div class="line"> @<span class="keywordtype">char</span>* SOAP_ENV__role;</div><div class="line">} <a class="code" href="wsse_8h.html#adea0e9370ef38183a230394959186a83">_wsse__Security</a>;</div></div><!-- fragment --><p>The tokens can be set with:</p>
<div class="fragment"><div class="line"><a class="code" href="struct__wsse_____security.html">_wsse__Security</a> *security = <a class="code" href="wsseapi_8h.html#ae7775b49a0cd57c7cf85db7bb18b034d">soap_wsse_Security</a>(soap);</div><div class="line">security->somens__SomeToken = (<span class="keyword">struct </span>somens__SomeTokenType*)soap_malloc(soap, <span class="keyword">sizeof</span>(<span class="keyword">struct</span> somens__SomeTokenType));</div><div class="line">soap_default_somens__SomeTokenType(soap, security->somens__SomeToken);</div><div class="line">security->somens__SomeToken->wsu__Id = <span class="stringliteral">"myToken"</span>; <span class="comment">// allows for auto-signing this element</span></div><div class="line">...</div></div><!-- fragment --><p>For tokens in DOM XML form, use the <code>xsd__anyType</code> DOM element:</p>
<div class="fragment"><div class="line"><span class="keyword">typedef</span> <span class="keyword">struct </span><a class="code" href="struct__wsse_____security.html">_wsse__Security</a></div><div class="line">{ ...</div><div class="line"> xsd__anyType* somens__SomeToken; <span class="comment">// added an optional token in DOM form</span></div><div class="line">} <a class="code" href="wsse_8h.html#adea0e9370ef38183a230394959186a83">_wsse__Security</a>;</div></div><!-- fragment --><p>The token in DOM form can be signed if you set the wsu:Id attribute to a unique value say "MyToken":</p>
<div class="fragment"><div class="line"><a class="code" href="struct__wsse_____security.html">_wsse__Security</a> *security = <a class="code" href="wsseapi_8h.html#ae7775b49a0cd57c7cf85db7bb18b034d">soap_wsse_Security</a>(soap);</div><div class="line">security->somens__SomeToken = (xsd__anyType*)soap_malloc(soap, <span class="keyword">sizeof</span>(xsd__anyType));</div><div class="line"><a class="code" href="wsseapi_8h.html#ac92bae52f1a5a467f3a857ec9f078723">soap_default_xsd__anyType</a>(soap, security->somens__SomeToken);</div><div class="line">soap_att_text(soap_att(soap_add_security->somens__SomeToken, NULL, <span class="stringliteral">"wsu:Id"</span>), <span class="stringliteral">"MyToken"</span>);</div><div class="line">...</div></div><!-- fragment --><p>We recommend to use <a href="http://www.genivia.com/doc/dom/html/index.html">domcpp</a> to generate code to set the token to send messages and get its values after receiving messages.</p>
<p>For tokens in XML "string" text form, use the <code>_XML</code> literal string (a <code>char*</code> type with XML content):</p>
<div class="fragment"><div class="line"><span class="keyword">typedef</span> <span class="keyword">struct </span><a class="code" href="struct__wsse_____security.html">_wsse__Security</a></div><div class="line">{ ...</div><div class="line"> _XML somens__SomeToken; <span class="comment">// added an optional token in string form</span></div><div class="line">} <a class="code" href="wsse_8h.html#adea0e9370ef38183a230394959186a83">_wsse__Security</a>;</div></div><!-- fragment --><p>However, beware that XML text cannot be signed by the signature as a Security header (unless you embed it within a new element in the Security header block and set that element's wsu:Id attribute).</p>
<h1><a class="anchor" id="wsse_7"></a>
Token References</h1>
<p>The material in this section relates to the WS-Security specification section 7.</p>
<p>To use a certificate for signature verification, add a direct security token reference URI for the token to the KeyInfo, for example:</p>
<div class="fragment"><div class="line"><a class="code" href="wsseapi_8h.html#aa1557c59801a0c3e4a77c1cb56cc2d9e">soap_wsse_add_KeyInfo_SecurityTokenReferenceURI</a>(soap, <span class="stringliteral">"URI"</span>, <span class="stringliteral">"valueType"</span>);</div></div><!-- fragment --><p>and:</p>
<div class="fragment"><div class="line"><a class="code" href="wsseapi_8h.html#a72df80abd1d36cea516feda3a84672cf">soap_wsse_add_KeyInfo_SecurityTokenReferenceX509</a>(soap, <span class="stringliteral">"URI"</span>);</div></div><!-- fragment --><p>For X509 certificates we use this to add a binary security token with the certificate and a reference to the local token:</p>
<div class="fragment"><div class="line"><span class="keywordflow">if</span> (<a class="code" href="wsseapi_8h.html#a53075fb3cec4ec4e70fb11850fecb401">soap_wsse_add_BinarySecurityTokenX509</a>(soap, <span class="stringliteral">"X509Token"</span>, cert)</div><div class="line"> || <a class="code" href="wsseapi_8h.html#a72df80abd1d36cea516feda3a84672cf">soap_wsse_add_KeyInfo_SecurityTokenReferenceX509</a>(soap, <span class="stringliteral">"#X509Token"</span>))</div><div class="line"> ... <span class="comment">// an error occurred</span></div></div><!-- fragment --><p>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.</p>
<p>Key identifiers can be used as well:</p>
<div class="fragment"><div class="line"><a class="code" href="wsseapi_8h.html#a83ad7822556d691020209fa12d1c79a7">soap_wsse_add_KeyInfo_SecurityTokenReferenceKeyIdentifier</a>(soap, <span class="stringliteral">"Id"</span>, <span class="stringliteral">"valueType"</span>, data, datalen);</div></div><!-- fragment --><p>Embedded references are added with:</p>
<div class="fragment"><div class="line"><a class="code" href="wsseapi_8h.html#a8fcf5947eb011d73b6a6b1308123a536">soap_wsse_add_KeyInfo_SecurityTokenReferenceEmbedded</a>(soap, <span class="stringliteral">"Id"</span>, <span class="stringliteral">"valueType"</span>);</div></div><!-- fragment --><p>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.</p>
<p>The use of key names is not recommended, but in case they are required they can be added with:</p>
<div class="fragment"><div class="line"><a class="code" href="wsseapi_8h.html#a25240140007f1776479e81dd43457f40">soap_wsse_add_KeyInfo_KeyName</a>(soap, <span class="stringliteral">"name"</span>);</div></div><!-- fragment --><h1><a class="anchor" id="wsse_8"></a>
Signatures</h1>
<p>The material in this section relates to the WS-Security specification section 8.</p>
<p>The wsse plugin must be registered to sign and verify messages:</p>
<div class="fragment"><div class="line">soap_register_plugin(soap, <a class="code" href="wsseapi_8h.html#af15bedb61bffb589683354bc37d20c3a">soap_wsse</a>);</div></div><!-- fragment --><p>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 <code>SOAP_XML_CANONICAL</code> flag:</p>
<div class="fragment"><div class="line"><span class="keyword">struct </span>soap *soap = soap_new1(SOAP_XML_CANONICAL);</div><div class="line">soap_register_plugin(soap, <a class="code" href="wsseapi_8h.html#af15bedb61bffb589683354bc37d20c3a">soap_wsse</a>);</div></div><!-- fragment --><p>To send messages with inclusive canonicalization, in addition to the <code>SOAP_XML_CANONICAL</code> flag also use:</p>
<div class="fragment"><div class="line"><a class="code" href="wsseapi_8h.html#a7a1670c6ee444704c8fb7ac612db37ff">soap_wsse_set_InclusiveNamespaces</a>(soap, <span class="stringliteral">"*"</span>);</div></div><!-- fragment --><p>However, exclusive canonicalization is recommended over inclusive canonicalization, or no canonicalization at all. WS Basic Security profile 1.0 requires exclusive canonicalization.</p>
<p>Flags to consider:</p>
<ul>
<li><code>SOAP_XML_CANONICAL</code> recommended to enable exc-c14n (exclusive canonicalization).</li>
<li><code>SOAP_XML_INDENT</code> optional, to emit more readable XML (see warning below).</li>
<li><code>SOAP_IO_CHUNK</code> efficient HTTP-chunked streaming messages.</li>
<li><code>SOAP_ENC_GZIP</code> for HTTP compression (also enables HTTP chunking).</li>
</ul>
<dl class="section warning"><dt>Warning</dt><dd>Interoperability with WCF WS-Security is not guaranteed when <code>SOAP_XML_INDENT</code> is enabled. Avoid using <code>SOAP_XML_INDENT</code> for interoperability. The implementation of canonicalization in WCF with respect to the normalization of white space between XML tags differs from the protocol standards.</dd></dl>
<p>Next, decide which signature algorithm is appropriate to use:</p>
<ul>
<li>HMAC-SHA uses a secret key (also known as a shared key in symmetric cryptography) to sign the SHA digest of the SignedInfo element.</li>
<li>DSA-SHA uses a DSA private key to sign the SHA digest of the SignedInfo element.</li>
<li>RSA-SHA uses a RSA private key to sign the SHA digest of the SignedInfo element.</li>
<li>ECDSA-SHA uses a Elliptic Curve DSA private key to sign the SHA digest of the SignedInfo element.</li>
</ul>
<p>HMAC-SHA 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-SHA is the speed by which messages are signed and verified.</p>
<p>Algorithms HMAC SHA1, SHA256, and SHA512 are supported:</p>
<ul>
<li><code>SOAP_SMD_HMAC_SHA1</code> <a href="http://www.w3.org/2000/09/xmldsig#hmac-sha1">http://www.w3.org/2000/09/xmldsig#hmac-sha1</a></li>
<li><code>SOAP_SMD_HMAC_SHA224</code> <a href="http://www.w3.org/2001/04/xmldsig-more#hmac-sha224">http://www.w3.org/2001/04/xmldsig-more#hmac-sha224</a></li>
<li><code>SOAP_SMD_HMAC_SHA256</code> <a href="http://www.w3.org/2001/04/xmldsig-more#hmac-sha256">http://www.w3.org/2001/04/xmldsig-more#hmac-sha256</a></li>
<li><code>SOAP_SMD_HMAC_SHA384</code> <a href="http://www.w3.org/2001/04/xmldsig-more#hmac-sha384">http://www.w3.org/2001/04/xmldsig-more#hmac-sha384</a></li>
<li><code>SOAP_SMD_HMAC_SHA512</code> <a href="http://www.w3.org/2001/04/xmldsig-more#hmac-sha512">http://www.w3.org/2001/04/xmldsig-more#hmac-sha512</a></li>
</ul>
<p>DSA-SHA and RSA-SHA 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.</p>
<p>The following DSA, RSA, and ECDSA algorithms are supported:</p>
<ul>
<li><code>SOAP_SMD_SIGN_DSA_SHA1</code> <a href="http://www.w3.org/2000/09/xmldsig#dsa-sha1">http://www.w3.org/2000/09/xmldsig#dsa-sha1</a></li>
<li><code>SOAP_SMD_SIGN_DSA_SHA256</code> <a href="http://www.w3.org/2000/09/xmldsig-more#dsa-sha256">http://www.w3.org/2000/09/xmldsig-more#dsa-sha256</a></li>
<li><code>SOAP_SMD_SIGN_RSA_SHA1</code> <a href="http://www.w3.org/2000/09/xmldsig#rsa-sha1">http://www.w3.org/2000/09/xmldsig#rsa-sha1</a></li>
<li><code>SOAP_SMD_SIGN_RSA_SHA224</code> <a href="http://www.w3.org/2001/04/xmldsig-more#rsa-sha224">http://www.w3.org/2001/04/xmldsig-more#rsa-sha224</a></li>
<li><code>SOAP_SMD_SIGN_RSA_SHA256</code> <a href="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256">http://www.w3.org/2001/04/xmldsig-more#rsa-sha256</a></li>
<li><code>SOAP_SMD_SIGN_RSA_SHA384</code> <a href="http://www.w3.org/2001/04/xmldsig-more#rsa-sha384">http://www.w3.org/2001/04/xmldsig-more#rsa-sha384</a></li>
<li><code>SOAP_SMD_SIGN_RSA_SHA512</code> <a href="http://www.w3.org/2001/04/xmldsig-more#rsa-sha512">http://www.w3.org/2001/04/xmldsig-more#rsa-sha512</a></li>
<li><code>SOAP_SMD_SIGN_ECDSA_SHA1</code> <a href="http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha1">http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha1</a></li>
<li><code>SOAP_SMD_SIGN_ECDSA_SHA224</code> <a href="http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha224">http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha224</a></li>
<li><code>SOAP_SMD_SIGN_ECDSA_SHA256</code> <a href="http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha256">http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha256</a></li>
<li><code>SOAP_SMD_SIGN_ECDSA_SHA384</code> <a href="http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha384">http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha384</a></li>
<li><code>SOAP_SMD_SIGN_ECDSA_SHA512</code> <a href="http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha512">http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha512</a></li>
</ul>
<p>An optional callback function can be passed to the plugin that is responsible for providing a certificate or key to the wsse engine to verify a signed message. For example, when a security token is absent from an DSA-SHA or RSA-SHA signed message then the only mechanism to automatically verify the signature is to let the callback produce a certificate:</p>
<div class="fragment"><div class="line">soap_register_plugin(soap, <a class="code" href="wsseapi_8h.html#af15bedb61bffb589683354bc37d20c3a">soap_wsse</a>);</div><div class="line"><a class="code" href="wsseapi_8h.html#ad6a0b722a052aaa7652cba5245f78b5f">soap_wsse_set_security_token_handler</a>(soap, security_token_handler);</div><div class="line"></div><div class="line"><span class="keyword">const</span> <span class="keywordtype">void</span> *security_token_handler(<span class="keyword">struct</span> soap *soap, <span class="keywordtype">int</span> *alg, <span class="keyword">const</span> <span class="keywordtype">char</span> *keyname, <span class="keyword">const</span> <span class="keywordtype">unsigned</span> <span class="keywordtype">char</span> *keyid, <span class="keywordtype">int</span> keyidlen, <span class="keywordtype">int</span> *keylen)</div><div class="line">{</div><div class="line"> <span class="comment">// Get the user name from UsernameToken in message</span></div><div class="line"> <span class="keyword">const</span> <span class="keywordtype">char</span> *uid = <a class="code" href="wsseapi_8h.html#aca3fe6fb7c1e5c103827b33f24292f47">soap_wsse_get_Username</a>(soap);</div><div class="line"> <span class="keywordflow">switch</span> (*alg)</div><div class="line"> {</div><div class="line"> <span class="keywordflow">case</span> <a class="code" href="smdevp_8h.html#a448c4d5953ca007263ff6a5bd055cfdc">SOAP_SMD_VRFY_DSA_SHA1</a>:</div><div class="line"> <span class="keywordflow">case</span> <a class="code" href="smdevp_8h.html#a5b4e9a64ef8a1de550cc5c5ab889d3c6">SOAP_SMD_VRFY_DSA_SHA256</a>:</div><div class="line"> <span class="keywordflow">case</span> <a class="code" href="smdevp_8h.html#aa395a40932c9c057cd264c03716c9d6e">SOAP_SMD_VRFY_RSA_SHA1</a>:</div><div class="line"> <span class="keywordflow">case</span> <a class="code" href="smdevp_8h.html#aa5d9d36c2db3bbef1dfd66593240cf16">SOAP_SMD_VRFY_RSA_SHA224</a>:</div><div class="line"> <span class="keywordflow">case</span> <a class="code" href="smdevp_8h.html#ac495716c1f8630567900c33cdea08fd1">SOAP_SMD_VRFY_RSA_SHA256</a>:</div><div class="line"> <span class="keywordflow">case</span> <a class="code" href="smdevp_8h.html#afec4c06d2b78ff9a4451a311849d7275">SOAP_SMD_VRFY_RSA_SHA384</a>:</div><div class="line"> <span class="keywordflow">case</span> <a class="code" href="smdevp_8h.html#a16e7c5ef33465656c0d270eebc933021">SOAP_SMD_VRFY_RSA_SHA512</a>:</div><div class="line"> <span class="keywordflow">case</span> <a class="code" href="smdevp_8h.html#a5dba7fc390d7f1056c1315e33003fadb">SOAP_SMD_VRFY_ECDSA_SHA1</a>:</div><div class="line"> <span class="keywordflow">case</span> <a class="code" href="smdevp_8h.html#adf90c93cd7ddcbfdfb4331cd79ec7fed">SOAP_SMD_VRFY_ECDSA_SHA224</a>:</div><div class="line"> <span class="keywordflow">case</span> <a class="code" href="smdevp_8h.html#a302ca7fbeadd43dd57b0cea2c1daf5f3">SOAP_SMD_VRFY_ECDSA_SHA256</a>:</div><div class="line"> <span class="keywordflow">case</span> <a class="code" href="smdevp_8h.html#a1b34145858769663cf7dd9c7cd05d549">SOAP_SMD_VRFY_ECDSA_SHA384</a>:</div><div class="line"> <span class="keywordflow">case</span> <a class="code" href="smdevp_8h.html#ab434218e658d6aa79768e43389cf6871">SOAP_SMD_VRFY_ECDSA_SHA512</a>:</div><div class="line"> <span class="keywordflow">if</span> (uid)</div><div class="line"> {</div><div class="line"> <span class="comment">// Lookup uid to retrieve the X509 certificate to verify the signature</span></div><div class="line"> <span class="keyword">const</span> X509 *cert = ...; </div><div class="line"> <span class="keywordflow">return</span> (<span class="keyword">const</span> <span class="keywordtype">void</span>*)cert;</div><div class="line"> }</div><div class="line"> <span class="keywordflow">return</span> NULL; <span class="comment">// no certificate: fail</span></div><div class="line"> <span class="keywordflow">case</span> <a class="code" href="smdevp_8h.html#a7d00704c43ee044926905cd327a712ef">SOAP_SMD_HMAC_SHA1</a>:</div><div class="line"> <span class="keywordflow">case</span> <a class="code" href="smdevp_8h.html#a0a03fa407c392d53e3e6609032c69a19">SOAP_SMD_HMAC_SHA224</a>:</div><div class="line"> <span class="keywordflow">case</span> <a class="code" href="smdevp_8h.html#a561d6c47f122626acb2f36bdabdc07e6">SOAP_SMD_HMAC_SHA256</a>:</div><div class="line"> <span class="keywordflow">case</span> <a class="code" href="smdevp_8h.html#a5928fa6c9c366857ffb96e70e6e04609">SOAP_SMD_HMAC_SHA384</a>:</div><div class="line"> <span class="keywordflow">case</span> <a class="code" href="smdevp_8h.html#a0eaedca857ff22ca7e2290e3ad67a184">SOAP_SMD_HMAC_SHA512</a>:</div><div class="line"> <span class="keywordflow">if</span> (uid)</div><div class="line"> {</div><div class="line"> <span class="comment">// Lookup uid to retrieve the HMAC SHA key to verify the signature</span></div><div class="line"> <span class="keyword">const</span> <span class="keywordtype">void</span> *key = ...; </div><div class="line"> *alg = ...;</div><div class="line"> *keylen = ...;</div><div class="line"> <span class="keywordflow">return</span> key;</div><div class="line"> }</div><div class="line"> <span class="keywordflow">return</span> NULL; <span class="comment">// no certificate: fail</span></div><div class="line"> <span class="keywordflow">case</span> <a class="code" href="mecevp_8h.html#a533b28fdec1dba756bdd69dea83ad244">SOAP_MEC_ENV_DEC_DES_CBC</a>:</div><div class="line"> <span class="keywordflow">case</span> <a class="code" href="mecevp_8h.html#aa94bbedb3884c463ddcb6dbe3e582913">SOAP_MEC_ENV_DEC_AES128_CBC</a>:</div><div class="line"> <span class="keywordflow">case</span> <a class="code" href="mecevp_8h.html#ad5935be53e1e0d92fcca66f3227d7465">SOAP_MEC_ENV_DEC_AES192_CBC</a>:</div><div class="line"> <span class="keywordflow">case</span> <a class="code" href="mecevp_8h.html#a614a07a8c4fa0aa814e1009033403b84">SOAP_MEC_ENV_DEC_AES256_CBC</a>:</div><div class="line"> <span class="keywordflow">case</span> <a class="code" href="mecevp_8h.html#a54d92e9969643328dbdb10e687ea6a88">SOAP_MEC_ENV_DEC_AES512_CBC</a>: <span class="comment">// reserved for future use</span></div><div class="line"> <span class="keywordflow">case</span> <a class="code" href="mecevp_8h.html#a64d04044822454e1672f5501c67d4a9d">SOAP_MEC_ENV_DEC_AES128_GCM</a>: <span class="comment">// GCM requires OpenSSL 1.0.2 or higher</span></div><div class="line"> <span class="keywordflow">case</span> <a class="code" href="mecevp_8h.html#a8cdb2b051d394a12c7bb7768a95eeb6d">SOAP_MEC_ENV_DEC_AES192_GCM</a>: <span class="comment">// GCM requires OpenSSL 1.0.2 or higher</span></div><div class="line"> <span class="keywordflow">case</span> <a class="code" href="mecevp_8h.html#a86d91a11d9401b4bd0bb86d3b0478fca">SOAP_MEC_ENV_DEC_AES256_GCM</a>: <span class="comment">// GCM requires OpenSSL 1.0.2 or higher</span></div><div class="line"> <span class="keywordflow">case</span> <a class="code" href="mecevp_8h.html#a49ba1d264167026ba86a3a108aad5060">SOAP_MEC_ENV_DEC_AES512_GCM</a>: <span class="comment">// GCM requires OpenSSL 1.0.2 or higher</span></div><div class="line"> <span class="keywordflow">if</span> (keyname)</div><div class="line"> {</div><div class="line"> <span class="comment">// use this to get key or X509 certificate from a key store using the keyname value:</span></div><div class="line"> <span class="comment">// 1. keyname is set to the subject name of the certificate, if a</span></div><div class="line"> <span class="comment">// certificate is present in the SecurityTokenReference/KeyIdentifier</span></div><div class="line"> <span class="comment">// when ValueType is http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3</span></div><div class="line"> <span class="comment">// 2. keyname is set to the string concatenation</span></div><div class="line"> <span class="comment">// "{X509IssuerName}#{X509SerialNumber}" of the X509IssuerName</span></div><div class="line"> <span class="comment">// and X509SerialNumber present in X509Data/X509IssuerSerial</span></div><div class="line"> <span class="comment">// 3. keyname is set to X509Data/X509SubjectName</span></div><div class="line"> <span class="keywordflow">return</span> ...;</div><div class="line"> }</div><div class="line"> <span class="keywordflow">else</span> <span class="keywordflow">if</span> (keyid)</div><div class="line"> {</div><div class="line"> <span class="comment">// use this to get the key from a key store using the keyid[0..keyidlen-1]:</span></div><div class="line"> <span class="comment">// 1. keyid and keyidlen are set to the data in</span></div><div class="line"> <span class="comment">// SecurityTokenReference/KeyIdentifier when the ValueType is</span></div><div class="line"> <span class="comment">// http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509SubjectKeyIdentifier</span></div><div class="line"> <span class="keywordflow">return</span> ...;</div><div class="line"> }</div><div class="line"> <span class="keywordflow">break</span>;</div><div class="line"> <span class="keywordflow">case</span> <a class="code" href="mecevp_8h.html#a9226364c4bf1cd277c417cd4d2706561">SOAP_MEC_DEC_DES_CBC</a>:</div><div class="line"> <span class="keywordflow">case</span> <a class="code" href="mecevp_8h.html#a276b8e0038b3c44235a66467d9056cb1">SOAP_MEC_DEC_AES128_CBC</a>:</div><div class="line"> <span class="keywordflow">case</span> <a class="code" href="mecevp_8h.html#abc989d7ba0703386b786be70f8f23b69">SOAP_MEC_DEC_AES192_CBC</a>:</div><div class="line"> <span class="keywordflow">case</span> <a class="code" href="mecevp_8h.html#a7151041a3f95a45edce0660f0fbcea44">SOAP_MEC_DEC_AES256_CBC</a>:</div><div class="line"> <span class="keywordflow">case</span> <a class="code" href="mecevp_8h.html#a84c17ef148e5a7ab05eea24acf7d4159">SOAP_MEC_DEC_AES512_CBC</a>: <span class="comment">// reserved for future use</span></div><div class="line"> <span class="keywordflow">case</span> <a class="code" href="mecevp_8h.html#ad63c14482c5e9cf3028e96da56d878ad">SOAP_MEC_DEC_AES128_GCM</a>: <span class="comment">// GCM requires OpenSSL 1.0.2 or higher</span></div><div class="line"> <span class="keywordflow">case</span> <a class="code" href="mecevp_8h.html#abeda47e7f8d80130e3675a32b9abcb7e">SOAP_MEC_DEC_AES192_GCM</a>: <span class="comment">// GCM requires OpenSSL 1.0.2 or higher</span></div><div class="line"> <span class="keywordflow">case</span> <a class="code" href="mecevp_8h.html#ab3853c4ab88cd32c4ba6058335f76fdf">SOAP_MEC_DEC_AES256_GCM</a>: <span class="comment">// GCM requires OpenSSL 1.0.2 or higher`</span></div><div class="line"> <span class="keywordflow">case</span> <a class="code" href="mecevp_8h.html#a20016e3054eca51dc31b9eb6c6100d2a">SOAP_MEC_DEC_AES512_GCM</a>: <span class="comment">// GCM requires OpenSSL 1.0.2 or higher</span></div><div class="line"> <span class="keywordflow">if</span> (keyname)</div><div class="line"> {</div><div class="line"> <span class="comment">// use the keyname to get the shared secret key associated for decryption</span></div><div class="line"> *keylen = ... <span class="comment">// length of the shared secret key</span></div><div class="line"> <span class="keywordflow">return</span> ...;</div><div class="line"> }</div><div class="line"> <span class="keywordflow">break</span>;</div><div class="line"> }</div><div class="line"> <span class="keywordflow">return</span> NULL; <span class="comment">// fail</span></div><div class="line">}</div></div><!-- fragment --><dl class="section warning"><dt>Warning</dt><dd>The security token handler callback function parameters have changed in 2.8.34 and greater with the addition of KeyIdentifier information <code>keyid</code> and <code>keyidlen</code>.</dd></dl>
<h2><a class="anchor" id="wsse_8_2a"></a>
Signing Messages</h2>
<p>After the plugin is registered and a signature algorithm selected, the <code>soap_wsse_sign</code> function or the <code>soap_wsse_sign_body</code> function is used to initiate the signature engine to automatically sign outbound messages.</p>
<p>The code to sign the SOAP Body of a message using HMAC-SHA1 is:</p>
<div class="fragment"><div class="line"><span class="keyword">static</span> <span class="keywordtype">char</span> hmac_key[16] =</div><div class="line">{ 0xff, 0xee, 0xdd, 0xcc, 0xbb, 0xaa, 0x99, 0x88,</div><div class="line"> 0x77, 0x66, 0x55, 0x44, 0x33, 0x22, 0x11, 0x00 };</div><div class="line"><span class="keyword">struct </span>soap *soap = soap_new1(SOAP_XML_CANONICAL);</div><div class="line">soap_register_plugin(soap, <a class="code" href="wsseapi_8h.html#af15bedb61bffb589683354bc37d20c3a">soap_wsse</a>);</div><div class="line"><span class="keywordflow">if</span> (<a class="code" href="wsseapi_8h.html#ab653754f1a287ba06bd808cf89548c38">soap_wsse_sign_body</a>(soap, <a class="code" href="smdevp_8h.html#a7d00704c43ee044926905cd327a712ef">SOAP_SMD_HMAC_SHA1</a>, hmac_key, <span class="keyword">sizeof</span>(hmac_key))</div><div class="line"> ... <span class="comment">// an error occurred</span></div><div class="line"><span class="keywordflow">else</span> <span class="keywordflow">if</span> (soap_call_ns__myMethod(soap, ...))</div><div class="line"> ... <span class="comment">// a transmission error occurred</span></div></div><!-- fragment --><p>The <code>hmac_key</code> above is some secret key you generated for the sending side and receiving side (don't use the one shown here). Instead of SHA1 above, you can also use the more secure SHA224, SHA256, SHA384 and SHA512 hashes.</p>
<p>As always, use <code>soap_print_fault</code> to display the error message.</p>
<p>To sign the body of an outbound SOAP message using RSA-SHA (DSA-SHA 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:</p>
<div class="fragment"><div class="line">FILE *fd;</div><div class="line">EVP_PKEY *rsa_private_key;</div><div class="line">X509 *cert;</div><div class="line"><span class="keyword">struct </span>soap *soap = soap_new1(SOAP_XML_CANONICAL);</div><div class="line">soap_register_plugin(soap, <a class="code" href="wsseapi_8h.html#af15bedb61bffb589683354bc37d20c3a">soap_wsse</a>);</div><div class="line">fd = fopen(<span class="stringliteral">"privkey.pem"</span>, <span class="stringliteral">"r"</span>);</div><div class="line">rsa_private_key = PEM_read_PrivateKey(fd, NULL, NULL, <span class="stringliteral">"password"</span>);</div><div class="line">fclose(fd);</div><div class="line">fd = fopen(<span class="stringliteral">"cert.pem"</span>, <span class="stringliteral">"r"</span>);</div><div class="line">X509 *cert = PEM_read_X509(fd, NULL, NULL, NULL);</div><div class="line">fclose(fd);</div><div class="line"><span class="keywordflow">if</span> (<a class="code" href="wsseapi_8h.html#a53075fb3cec4ec4e70fb11850fecb401">soap_wsse_add_BinarySecurityTokenX509</a>(soap, <span class="stringliteral">"X509Token"</span>, cert)</div><div class="line"> || <a class="code" href="wsseapi_8h.html#a72df80abd1d36cea516feda3a84672cf">soap_wsse_add_KeyInfo_SecurityTokenReferenceX509</a>(soap, <span class="stringliteral">"#X509Token"</span>)</div><div class="line"> || <a class="code" href="wsseapi_8h.html#ab653754f1a287ba06bd808cf89548c38">soap_wsse_sign_body</a>(soap, <a class="code" href="smdevp_8h.html#a8634e2291f274a42107d3e935add3241">SOAP_SMD_SIGN_RSA_SHA256</a>, rsa_private_key, 0))</div><div class="line"> ... <span class="comment">// an error occurred</span></div><div class="line"><span class="keywordflow">else</span> <span class="keywordflow">if</span> (soap_call_ns__myMethod(soap, ...))</div><div class="line"> ... <span class="comment">// a transmission error occurred</span></div></div><!-- fragment --><p>The private key and its certificate are often placed in the same file, see e.g. server.pem in the package.</p>
<p>To summarize the signing process:</p><ol type="1">
<li>Register the wsse plugin.</li>
<li>Obtain an HMAC secret key or a DSA/RSA/ECDSA private key.</li>
<li>For DSA or RSA, obtain the X509 certificate with the public key signed by a certificate authority.</li>
<li>Add the X509 certificate as a BinarySecurityToken to the header.</li>
<li>Add a KeyInfo BinarySecurityTokenReference.</li>
<li>Invoke <code>soap_wsse_sign_body</code> and/or <code>soap_wsse_sign</code> with <code>soap_wsse_sign_only</code> to sign the message.</li>
<li>Always check the function return values for errors. You don't want to produce and accept messages with an invalid Security headers.</li>
</ol>
<h2><a class="anchor" id="wsse_8_2b"></a>
Signing Message Parts</h2>
<p>The <code>soap_wsse_sign_body</code> function signs the entire SOAP body but nothing else. If it is desirable to sign individual parts of a message the <code>soap_wsse_sign_only</code> and <code>soap_wsse_sign</code> functions 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 <code>soap_wsse_sign_only</code> function, see <a class="el" href="wsse.html#wsse_8_3">Signing Security Headers and Tokens</a>.</p>
<p>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.</p>
<p>The gSOAP header file includes a myContract declaration:</p>
<div class="fragment"><div class="line"><span class="keyword">struct </span>ns__myContract</div><div class="line">{</div><div class="line"> @<span class="keywordtype">char</span>* wsu__Id = <span class="stringliteral">"Contract"</span>;</div><div class="line"> <span class="keywordtype">char</span>* name;</div><div class="line"> <span class="keywordtype">char</span>* title;</div><div class="line"> <span class="keywordtype">char</span>* terms;</div><div class="line">};</div><div class="line"><span class="keywordtype">int</span> ns__myMethod(<span class="keyword">struct</span> ns__myContract agreement, <span class="keywordtype">bool</span>* accepted);</div></div><!-- fragment --><p>The default value of the wsu:Id is "Contract" so that we can instantiate the struct, automatically sign it, and send it as follows:</p>
<div class="fragment"><div class="line"><span class="keyword">struct </span>ns__myContract contract;</div><div class="line"><span class="keywordtype">bool</span> accept;</div><div class="line">soap_default_ns__myContract(soap, &contract);</div><div class="line">contract.name = ...;</div><div class="line">contract.title = ...;</div><div class="line">contract.terms = ...;</div><div class="line"><span class="keywordflow">if</span> (<a class="code" href="wsseapi_8h.html#a53075fb3cec4ec4e70fb11850fecb401">soap_wsse_add_BinarySecurityTokenX509</a>(soap, <span class="stringliteral">"X509Token"</span>, cert)</div><div class="line"> || <a class="code" href="wsseapi_8h.html#a72df80abd1d36cea516feda3a84672cf">soap_wsse_add_KeyInfo_SecurityTokenReferenceX509</a>(soap, <span class="stringliteral">"#X509Token"</span>)</div><div class="line"> || <a class="code" href="wsseapi_8h.html#aa3ac2afb86a25ec1e1d8e4515133e9ad">soap_wsse_sign</a>(soap, <a class="code" href="smdevp_8h.html#a8634e2291f274a42107d3e935add3241">SOAP_SMD_SIGN_RSA_SHA256</a>, rsa_private_key, 0))</div><div class="line"> ... <span class="comment">// an error occurred</span></div><div class="line"><span class="keywordflow">else</span> <span class="keywordflow">if</span> (soap_call_ns__myMethod(soap, contract, &accept))</div><div class="line"> ... <span class="comment">// a transmission error occurred</span></div></div><!-- fragment --><p>The above example shows a wsu:Id attribute embedded (hardcoded) in a struct. When it is not possible to add the <code>wsu__Id</code> 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 <code>soap_wsse_set_wsu_id(soap, "space-separated string of
element names")</code>. Use it before each call or in the server operation (when returning XML data from a service operation). This lets the engine add wsu:Id="tag" attribute-value pair to the element's tag name. For example:</p>
<div class="fragment"><div class="line"><a class="code" href="wsseapi_8h.html#a9582748dda80d0307e253f1a86c0c454">soap_wsse_set_wsu_id</a>(soap, <span class="stringliteral">"ns:myContract"</span>); <span class="comment">// <ns:myContract wsu:Id="ns:myContract">...</span></div><div class="line"><a class="code" href="wsseapi_8h.html#a7a1670c6ee444704c8fb7ac612db37ff">soap_wsse_set_InclusiveNamespaces</a>(soap, <span class="stringliteral">"ns xsd"</span>); <span class="comment">// QNames have 'ns' and 'xsd' values</span></div><div class="line"><span class="keywordflow">if</span> (<a class="code" href="wsseapi_8h.html#a53075fb3cec4ec4e70fb11850fecb401">soap_wsse_add_BinarySecurityTokenX509</a>(soap, <span class="stringliteral">"X509Token"</span>, cert)</div><div class="line"> || <a class="code" href="wsseapi_8h.html#a72df80abd1d36cea516feda3a84672cf">soap_wsse_add_KeyInfo_SecurityTokenReferenceX509</a>(soap, <span class="stringliteral">"#X509Token"</span>)</div><div class="line"> || <a class="code" href="wsseapi_8h.html#aa3ac2afb86a25ec1e1d8e4515133e9ad">soap_wsse_sign</a>(soap, <a class="code" href="smdevp_8h.html#a8634e2291f274a42107d3e935add3241">SOAP_SMD_SIGN_RSA_SHA256</a>, rsa_private_key, 0))</div><div class="line"> ... <span class="comment">// an error occurred</span></div><div class="line"><a class="code" href="wsseapi_8h.html#a9582748dda80d0307e253f1a86c0c454">soap_wsse_set_wsu_id</a>(soap, NULL); <span class="comment">// reset</span></div><div class="line"><a class="code" href="wsseapi_8h.html#a7a1670c6ee444704c8fb7ac612db37ff">soap_wsse_set_InclusiveNamespaces</a>(soap, NULL); <span class="comment">// reset</span></div></div><!-- fragment --><p>This code adds the wsu:Id="ns-myContract" to the ns:myContract element. Here, the <code>wsu__Id</code> 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.</p>
<dl class="section note"><dt>Note</dt><dd>To reset the automatic wsu:Id attributes addition, pass NULL to <code>soap_wsse_set_wsu_id</code> as shown above. This is automatically performed when a new message is received (but not automatically in a sequence of one-way sends for example).</dd>
<dd>
It is generally known that QName content of elements and attribute values may lead to verification issues with exclusive canonicalization (<code>SOAP_XML_CANONICAL</code>), because XML processors may not recognize prefixes in such QName contexts as visually utilized. With QName content in elements and attributes and <code>SOAP_XML_CANONICAL</code> enabled, we should use <code>soap_wsse_set_InclusiveNamespaces(soap, "prefixlist")</code> to define which namespace prefixes (space-separated in the string) should be considered inclusive. For example, xsi:type attribute values are QNames with xsd types (and perhaps other types), meaning we should add "xsd" to the inclusive namespace prefix list with <code>soap_wsse_set_InclusiveNamespaces(soap, "xsd")</code> to ensure xsi:type="xsd:TYPE" attributes with QName content are properly signed and not susceptible to certain wrapping attacks. A quick way to include all prefixes in the signed contents and thereby thwart signature wrapping attacks is to use <code>soap_wsse_set_InclusiveNamespaces(soap, "+")</code>.</dd>
<dd>
When signing parts of the body as outlined above, use <code>soap_wsse_sign</code> (do NOT use <code>soap_wsse_sign_body</code>).</dd></dl>
<dl class="section warning"><dt>Warning</dt><dd>Do not attempt to sign an element with a wsu:Id that is a subelement of another element with a wsu:Id, that is, do not sign inner nested wsu:Id elements. The element that you will try to sign will not be canonicalized and will lead to a failure of the signature verification. When elements with wsu:Id are nested, sign the outermost element.</dd></dl>
<p>We recommend to sign the entire SOAP Body using <code>soap_wsse_sign_body</code> and reserve the use of <code>soap_wsse_set_wsu_id</code> for SOAP Header elements, such as WS-Addressing elements. For example, to add and sign WS-Addressing 2005 headers (which are activated with an <code>#import "wsa5.h"</code> in the header file for soapcpp2):</p>
<div class="fragment"><div class="line"><span class="preprocessor">#include "wsaapi.h"</span></div><div class="line"><span class="preprocessor">#include "<a class="code" href="wsseapi_8h.html">wsseapi.h</a>"</span></div><div class="line">soap_register_plugin(soap, soap_wsa);</div><div class="line">soap_register_plugin(soap, <a class="code" href="wsseapi_8h.html#af15bedb61bffb589683354bc37d20c3a">soap_wsse</a>);</div><div class="line">...</div><div class="line">soap_wsse_set_wsu_id(soap, <span class="stringliteral">"wsa5:From wsa5:To wsa5:ReplyTo wsa5:FaultTo wsa5:Action wsa5:MessageID"</span>);</div><div class="line"><span class="keywordflow">if</span> (soap_wsa_request(soap, RequestMessageID, ToAddress, RequestAction)</div><div class="line"> || soap_wsa_add_From(soap, FromAddress) <span class="comment">// optional: add a 'From' address</span></div><div class="line"> || soap_wsa_add_FaultTo(soap, FaultToAddress))</div><div class="line"> ... <span class="comment">// error: out of memory</span></div><div class="line"><span class="keywordflow">if</span> (<a class="code" href="wsseapi_8h.html#a53075fb3cec4ec4e70fb11850fecb401">soap_wsse_add_BinarySecurityTokenX509</a>(soap, <span class="stringliteral">"X509Token"</span>, cert)</div><div class="line"> || <a class="code" href="wsseapi_8h.html#a72df80abd1d36cea516feda3a84672cf">soap_wsse_add_KeyInfo_SecurityTokenReferenceX509</a>(soap, <span class="stringliteral">"#X509Token"</span>)</div><div class="line"> || <a class="code" href="wsseapi_8h.html#ab653754f1a287ba06bd808cf89548c38">soap_wsse_sign_body</a>(soap, <a class="code" href="smdevp_8h.html#a8634e2291f274a42107d3e935add3241">SOAP_SMD_SIGN_RSA_SHA256</a>, rsa_private_key, 0))</div><div class="line"> ... <span class="comment">// an error occurred</span></div><div class="line"><span class="keywordflow">else</span> <span class="keywordflow">if</span> (soap_call_ns__myMethod(soap, ...))</div><div class="line"> ... <span class="comment">// a transmission error occurred</span></div><div class="line"><a class="code" href="wsseapi_8h.html#a9582748dda80d0307e253f1a86c0c454">soap_wsse_set_wsu_id</a>(soap, NULL);</div></div><!-- fragment --><p>This code signs the wsa5 header elements that are set with <code>soap_wsa_request</code>, 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 with <code>soap_wsse_set_wsu_id</code> than actually present in the XML payload. The other WS-Addressing headers are not present and are not signed.</p>
<p>If your are using WS-Addressing 2004 (which is activated with an <code>#import "wsa.h"</code> in the header file for soapcpp2) then change one line:</p>
<div class="fragment"><div class="line"><a class="code" href="wsseapi_8h.html#a9582748dda80d0307e253f1a86c0c454">soap_wsse_set_wsu_id</a>(soap, <span class="stringliteral">"wsa:From wsa:To wsa:ReplyTo wsa:FaultTo wsa:Action wsa:MessageID"</span>);</div></div><!-- fragment --><dl class="section note"><dt>Note</dt><dd><code>soap_wsse_set_wsu_id</code> should only be set once for each <code>soap_wsse_sign</code> or <code>soap_wsse_sign_body</code>. Each new call overrides the previous setting.</dd></dl>
<dl class="section warning"><dt>Warning</dt><dd>Never use <code>soap_wsse_set_wsu_id</code> 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.</dd></dl>
<h2><a class="anchor" id="wsse_8_3"></a>
Signing Security Headers and Tokens</h2>
<p>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:</p>
<div class="fragment"><div class="line"><a class="code" href="wsseapi_8h.html#a71fe27aee76db1d0a635afe106d8b109">soap_wsse_add_Timestamp</a>(soap, <span class="stringliteral">"Time"</span>, 600);</div><div class="line"><a class="code" href="wsseapi_8h.html#ac9fe59008bdf12d7a007ac48e6ebb613">soap_wsse_add_UsernameTokenDigest</a>(soap, <span class="stringliteral">"User"</span>, <span class="stringliteral">"username"</span>, <span class="stringliteral">"password"</span>);</div><div class="line">... <span class="comment">// the rest of the signing code</span></div></div><!-- fragment --><p>Note that by default all wsu:Id-attributed elements are signed. To filter a subset of wsu:Id-attributed elements for signatures, use the <code>soap_wsse_sign_only</code> function to specify a subset of the elements that have wsu:Id values as follows:</p>
<div class="fragment"><div class="line"><a class="code" href="wsseapi_8h.html#a71fe27aee76db1d0a635afe106d8b109">soap_wsse_add_Timestamp</a>(soap, <span class="stringliteral">"Time"</span>, 600);</div><div class="line"><a class="code" href="wsseapi_8h.html#ac9fe59008bdf12d7a007ac48e6ebb613">soap_wsse_add_UsernameTokenDigest</a>(soap, <span class="stringliteral">"User"</span>, <span class="stringliteral">"username"</span>, <span class="stringliteral">"password"</span>);</div><div class="line"><a class="code" href="wsseapi_8h.html#a53075fb3cec4ec4e70fb11850fecb401">soap_wsse_add_BinarySecurityTokenX509</a>(soap, <span class="stringliteral">"X509Token"</span>, cert);</div><div class="line"><a class="code" href="wsseapi_8h.html#a72df80abd1d36cea516feda3a84672cf">soap_wsse_add_KeyInfo_SecurityTokenReferenceX509</a>(soap, <span class="stringliteral">"#X509Token"</span>);</div><div class="line"><a class="code" href="wsseapi_8h.html#ab653754f1a287ba06bd808cf89548c38">soap_wsse_sign_body</a>(soap, <a class="code" href="smdevp_8h.html#a8634e2291f274a42107d3e935add3241">SOAP_SMD_SIGN_RSA_SHA256</a>, rsa_private_key, 0);</div><div class="line"><a class="code" href="wsseapi_8h.html#a16e38c1160a47ad2cb60d1b7d5dba777">soap_wsse_sign_only</a>(soap, <span class="stringliteral">"Time User Body"</span>); <span class="comment">// OK to use after soap_wsse_sign_body</span></div></div><!-- fragment --><p>The wsu:Id values are provides with the <code>add</code> functions, such as "User" and "X509Token". The SOAP Body always has a wsu:Id value "Body" when <code>soap_wsse_sign_body</code> is used.</p>
<p>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 <code>soap_wsse_sign_only</code>. The SOAP Body wsu:Id is always "Body" and should be part of the <code>soap_wsse_sign_only</code> set of wsu:Id names to sign.</p>
<p>When using <code>soap_wsse_set_wsu_id</code> we need to use the tag name with <code>soap_wsse_sign_only</code>. For example:</p>
<div class="fragment"><div class="line">soap_wsa_request(soap, RequestMessageID, ToAddress, RequestAction);</div><div class="line"><a class="code" href="wsseapi_8h.html#a9582748dda80d0307e253f1a86c0c454">soap_wsse_set_wsu_id</a>(soap, <span class="stringliteral">"wsa5:To wsa5:From wsa5:ReplyTo wsa5:Action"</span>);</div><div class="line"><a class="code" href="wsseapi_8h.html#ac9fe59008bdf12d7a007ac48e6ebb613">soap_wsse_add_UsernameTokenDigest</a>(soap, <span class="stringliteral">"User"</span>, <span class="stringliteral">"username"</span>, <span class="stringliteral">"password"</span>);</div><div class="line"><a class="code" href="wsseapi_8h.html#a53075fb3cec4ec4e70fb11850fecb401">soap_wsse_add_BinarySecurityTokenX509</a>(soap, <span class="stringliteral">"X509Token"</span>, cert);</div><div class="line"><a class="code" href="wsseapi_8h.html#a72df80abd1d36cea516feda3a84672cf">soap_wsse_add_KeyInfo_SecurityTokenReferenceX509</a>(soap, <span class="stringliteral">"#X509Token"</span>);</div><div class="line"><a class="code" href="wsseapi_8h.html#ab653754f1a287ba06bd808cf89548c38">soap_wsse_sign_body</a>(soap, <a class="code" href="smdevp_8h.html#a8634e2291f274a42107d3e935add3241">SOAP_SMD_SIGN_RSA_SHA256</a>, rsa_private_key, 0);</div><div class="line"><a class="code" href="wsseapi_8h.html#a16e38c1160a47ad2cb60d1b7d5dba777">soap_wsse_sign_only</a>(soap, <span class="stringliteral">"wsa5:To wsa5:From wsa5:ReplyTo wsa5:Action User Body"</span>);</div></div><!-- fragment --><dl class="section note"><dt>Note</dt><dd><code>soap_wsse_sign_only</code> should only be set once for each <code>soap_wsse_sign</code> or <code>soap_wsse_sign_body</code>. Each new call overrides the previous.</dd>
<dd>
To reset the filtering of signed tokens and elements, pass NULL to <code>soap_wsse_sign_only</code>. This is automatically performed when a new message is received (but not automatically in a sequence of one-way sends for example).</dd></dl>
<h2><a class="anchor" id="wsse_8_4"></a>
Signature Validation</h2>
<p>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:</p>
<div class="fragment"><div class="line"><span class="keyword">struct </span>soap *soap = soap_new1(SOAP_XML_CANONICAL);</div><div class="line">soap_register_plugin(soap, <a class="code" href="wsseapi_8h.html#af15bedb61bffb589683354bc37d20c3a">soap_wsse</a>);</div><div class="line"><a class="code" href="wsseapi_8h.html#a7321b451910e1d3887b328f03de92f34">soap_wsse_verify_auto</a>(soap, <a class="code" href="smdevp_8h.html#a011f7d21ad3c8634373fe3d3325fcd75">SOAP_SMD_NONE</a>, NULL, 0);</div><div class="line">soap->cafile = <span class="stringliteral">"cacerts.pem"</span>; <span class="comment">// file with CA certs of peers</span></div><div class="line">soap->capath = <span class="stringliteral">"dir/to/certs"</span>; <span class="comment">// and/or point to CA certs directory</span></div><div class="line">soap->crlfile = <span class="stringliteral">"revoked.pem"</span>; <span class="comment">// use CRL (optional)</span></div><div class="line"></div><div class="line"><span class="comment">// server:</span></div><div class="line"><span class="keywordflow">if</span> (soap_serve(soap))</div><div class="line"> ... <span class="comment">// an error occurred</span></div><div class="line"></div><div class="line"><span class="comment">// client:</span></div><div class="line"><span class="keywordflow">if</span> (soap_call_ns__myMethod(soap, ...))</div><div class="line"> ... <span class="comment">// an error occurred</span></div></div><!-- fragment --><p>All locally referenced and signed elements in the signed message will be verified with <code>soap_wsse_verify_auto</code> using the default settings set with <code>SOAP_SMD_NONE</code>. 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.</p>
<p>For a post-parsing check to verify if an XML element was signed in an inbound message, use:</p>
<div class="fragment"><div class="line"><a class="code" href="wsseapi_8h.html#a7321b451910e1d3887b328f03de92f34">soap_wsse_verify_auto</a>(soap, <a class="code" href="smdevp_8h.html#a011f7d21ad3c8634373fe3d3325fcd75">SOAP_SMD_NONE</a>, NULL, 0);</div><div class="line">soap->cafile = <span class="stringliteral">"cacerts.pem"</span>; <span class="comment">// file with CA certs of peers</span></div><div class="line">soap->capath = <span class="stringliteral">"dir/to/certs"</span>; <span class="comment">// and/or point to CA certs directory</span></div><div class="line">soap->crlfile = <span class="stringliteral">"revoked.pem"</span>; <span class="comment">// use CRL (optional)</span></div><div class="line">... <span class="comment">// client call</span></div><div class="line"><span class="keywordflow">if</span> (<a class="code" href="wsseapi_8h.html#a3fbe81de521579f026dd1ba8e81c59c1">soap_wsse_verify_element</a>(soap, <span class="stringliteral">"namespaceURI"</span>, <span class="stringliteral">"tag"</span>) == 1)</div><div class="line"> ... <span class="comment">// only one element with matching tag and namespace is signed</span></div></div><!-- fragment --><p>The <code>soap_wsse_verify_element</code> function returns the number of matching elements signed.</p>
<p>The signed element nesting rules are obeyed, so if the matching element is a descendent of a signed element, it is signed as well.</p>
<p>Because it is a post check, a client should invoke <code>soap_wsse_verify_element</code> 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.</p>
<p>For example, to check whether the wsu:Timestamp element was signed, e.g. after checking that it is present and message expiration checked with <code>soap_wsse_verify_Timestamp</code>, use:</p>
<div class="fragment"><div class="line"><span class="keywordflow">if</span> (!<a class="code" href="wsseapi_8h.html#a98422cde0e2b7b14d65212f7061101fa">soap_wsse_verify_Timestamp</a>(soap))</div><div class="line">{</div><div class="line"> <a class="code" href="wsseapi_8h.html#ac06c7021592b2aaca50f73e0de9dec7c">soap_wsse_delete_Security</a>(soap);</div><div class="line"> ... <span class="comment">// error</span></div><div class="line">}</div><div class="line"><span class="keywordflow">else</span> <span class="keywordflow">if</span> (<a class="code" href="wsseapi_8h.html#a3fbe81de521579f026dd1ba8e81c59c1">soap_wsse_verify_element</a>(soap, <span class="stringliteral">"http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"</span>, <span class="stringliteral">"Timestamp"</span>) > 0)</div><div class="line"> ... <span class="comment">// timestamp was signed</span></div></div><!-- fragment --><p>To check the SOAP Body (either using SOAP 1.1 or 1.2), simply use <code>soap_wsse_verify_body</code>.</p>
<p>The <code>soap_wsse_verify_auto</code> 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 <code>soap_wsse_verify_done</code>.</p>
<p>There can be two problems with signature verification. First, some WS-Security implementations include SignedInfo/Reference/ without targeting an element, which will produce an error that a Reference URI target does not exist. To ignore these references, use <code>SOAP_WSSE_IGNORE_EXTRA_REFS</code>. Second, certificates provided by the peer are not verifiable unless the signing CA certificate is included in the cafile or capath. To disable peer certificate verification, set the fsslverify callback to return 1 as follows:</p>
<div class="fragment"><div class="line"><span class="keyword">static</span> <span class="keywordtype">int</span> ssl_verify(<span class="keywordtype">int</span> ok, X509_STORE_CTX *store)</div><div class="line">{</div><div class="line"> <span class="comment">// put certificate verification here, return 0 when fails 1 when ok</span></div><div class="line"> <span class="keywordflow">return</span> 1;</div><div class="line">}</div><div class="line">...</div><div class="line">soap_wsse_verify_auto(soap, <a class="code" href="smdevp_8h.html#a011f7d21ad3c8634373fe3d3325fcd75">SOAP_SMD_NONE</a> | <a class="code" href="wsseapi_8h.html#ae6f973cd88cca2187640822dc86fcd9e">SOAP_WSSE_IGNORE_EXTRA_REFS</a>, NULL, 0);</div><div class="line">soap->cafile = <span class="stringliteral">"cacerts.pem"</span>; <span class="comment">// file with CA certs of peers</span></div><div class="line">soap->capath = <span class="stringliteral">"dir/to/certs"</span>; <span class="comment">// and/or point to CA certs directory</span></div><div class="line">soap->crlfile = <span class="stringliteral">"revoked.pem"</span>; <span class="comment">// use CRL (optional)</span></div><div class="line">soap->fsslverify = ssl_verify; <span class="comment">// set certificate verification callback</span></div></div><!-- fragment --><p>To reject peer certificates under all conditions except specific permitted conditions such as self-signed certificates in the chain, use the following code as a guide (see OpenSSL documentation on <code>X509_STORE_CTX_get_error</code>):</p>
<div class="fragment"><div class="line"><span class="keyword">static</span> <span class="keywordtype">int</span> ssl_verify(<span class="keywordtype">int</span> ok, X509_STORE_CTX *store)</div><div class="line">{</div><div class="line"> <span class="keywordflow">if</span> (!ok)</div><div class="line"> {</div><div class="line"> <span class="keywordtype">char</span> buf[1024];</div><div class="line"> <span class="keywordtype">int</span> err = X509_STORE_CTX_get_error(store);</div><div class="line"> X509 *cert = X509_STORE_CTX_get_current_cert(store);</div><div class="line"> <span class="keywordflow">switch</span> (err)</div><div class="line"> {</div><div class="line"> <span class="keywordflow">case</span> X509_V_ERR_CERT_NOT_YET_VALID:</div><div class="line"> <span class="keywordflow">case</span> X509_V_ERR_CERT_HAS_EXPIRED:</div><div class="line"> <span class="keywordflow">case</span> X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT:</div><div class="line"> <span class="keywordflow">case</span> X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN:</div><div class="line"> <span class="keywordflow">case</span> X509_V_ERR_UNABLE_TO_GET_CRL:</div><div class="line"> <span class="keywordflow">case</span> X509_V_ERR_CRL_NOT_YET_VALID:</div><div class="line"> <span class="keywordflow">case</span> X509_V_ERR_CRL_HAS_EXPIRED:</div><div class="line"> X509_STORE_CTX_set_error(store, X509_V_OK);</div><div class="line"> ok = 1;</div><div class="line"> <span class="keywordflow">break</span>;</div><div class="line"> <span class="keywordflow">default</span>:</div><div class="line"> fprintf(stderr, <span class="stringliteral">"SSL verify error %d or warning with certificate at depth %d: %s\n"</span>, err, X509_STORE_CTX_get_error_depth(store), X509_verify_cert_error_string(err));</div><div class="line"> X509_NAME_oneline(X509_get_issuer_name(cert), buf, <span class="keyword">sizeof</span>(buf)-1);</div><div class="line"> fprintf(stderr, <span class="stringliteral">" certificate issuer: %s\n"</span>, buf);</div><div class="line"> X509_NAME_oneline(X509_get_subject_name(cert), buf, <span class="keyword">sizeof</span>(buf)-1);</div><div class="line"> fprintf(stderr, <span class="stringliteral">" certificate subject: %s\n"</span>, buf);</div><div class="line"> }</div><div class="line"> }</div><div class="line"> <span class="keywordflow">return</span> ok;</div><div class="line">}</div><div class="line">...</div><div class="line">soap_wsse_verify_auto(soap, <a class="code" href="smdevp_8h.html#a011f7d21ad3c8634373fe3d3325fcd75">SOAP_SMD_NONE</a> | <a class="code" href="wsseapi_8h.html#ae6f973cd88cca2187640822dc86fcd9e">SOAP_WSSE_IGNORE_EXTRA_REFS</a>, NULL, 0);</div><div class="line">soap->cafile = <span class="stringliteral">"cacerts.pem"</span>; <span class="comment">// file with CA certs of peers</span></div><div class="line">soap->capath = <span class="stringliteral">"dir/to/certs"</span>; <span class="comment">// and/or point to CA certs directory</span></div><div class="line">soap->crlfile = <span class="stringliteral">"revoked.pem"</span>; <span class="comment">// use CRL (optional)</span></div><div class="line">soap->fsslverify = ssl_verify;</div></div><!-- fragment --><p>To verify the HMAC signature of an inbound message, the HMAC key must be supplied:</p>
<div class="fragment"><div class="line"><span class="keyword">static</span> <span class="keywordtype">char</span> hmac_key[16] = <span class="comment">// the same secret key that was used to sign</span></div><div class="line">{ 0xff, 0xee, 0xdd, 0xcc, 0xbb, 0xaa, 0x99, 0x88,</div><div class="line"> 0x77, 0x66, 0x55, 0x44, 0x33, 0x22, 0x11, 0x00 };</div><div class="line"><span class="keyword">struct </span>soap *soap = soap_new1(SOAP_XML_CANONICAL);</div><div class="line">soap_register_plugin(soap, <a class="code" href="wsseapi_8h.html#af15bedb61bffb589683354bc37d20c3a">soap_wsse</a>);</div><div class="line"><a class="code" href="wsseapi_8h.html#a7321b451910e1d3887b328f03de92f34">soap_wsse_verify_auto</a>(soap, <a class="code" href="smdevp_8h.html#a7d00704c43ee044926905cd327a712ef">SOAP_SMD_HMAC_SHA1</a>, hmac_key, <span class="keyword">sizeof</span>(hmac_key));</div><div class="line">soap->cafile = <span class="stringliteral">"cacerts.pem"</span>; <span class="comment">// file with CA certs of peers</span></div><div class="line">soap->capath = <span class="stringliteral">"dir/to/certs"</span>; <span class="comment">// and/or point to CA certs directory</span></div><div class="line">soap->crlfile = <span class="stringliteral">"revoked.pem"</span>; <span class="comment">// use CRL (optional)</span></div><div class="line"></div><div class="line"><span class="comment">// server:</span></div><div class="line"><span class="keywordflow">if</span> (soap_serve(soap))</div><div class="line"> ... <span class="comment">// an error occurred</span></div><div class="line"></div><div class="line"><span class="comment">// client:</span></div><div class="line"><span class="keywordflow">if</span> (soap_call_ns__myMethod(soap, ...))</div><div class="line"> ... <span class="comment">// an error occurred</span></div></div><!-- fragment --><p>To summarize the signature verification process:</p>
<ol type="1">
<li>Register the wsse plugin.</li>
<li>For HMAC, obtain the HMAC secret key</li>
<li>Use <code>soap_wsse_verify_auto</code> to verify inbound messages.</li>
<li>Set the cafile (or capath) to verify certificates of the peers and crlfile (optional)</li>
<li>After receiving a message, the DOM in soap->dom can be traversed for further analysis.</li>
<li>Always check the function return values for errors. You don't want to accept a request or response message with an invalid Security header.</li>
<li>Use <code>soap_wsse_verify_done</code> to terminate verification, e.g. to consume plain messages more efficiently.</li>
</ol>
<h1><a class="anchor" id="wsse_9"></a>
Encryption</h1>
<p>The material in this section relates to the WS-Security specification section 9.</p>
<p>The wsse plugin must be registered:</p>
<div class="fragment"><div class="line"><span class="keyword">struct </span>soap *soap = soap_new1(SOAP_XML_CANONICAL);</div><div class="line">soap_register_plugin(soap, <a class="code" href="wsseapi_8h.html#af15bedb61bffb589683354bc37d20c3a">soap_wsse</a>);</div></div><!-- fragment --><p>To send messages with inclusive canonicalization, in addition to the <code>SOAP_XML_CANONICAL</code> flag also use:</p>
<div class="fragment"><div class="line"><a class="code" href="wsseapi_8h.html#a7a1670c6ee444704c8fb7ac612db37ff">soap_wsse_set_InclusiveNamespaces</a>(soap, <span class="stringliteral">"*"</span>);</div></div><!-- fragment --><p>However, exclusive canonicalization is recommended over inclusive canonicalization, or no canonicalization at all. WS Basic Security profile 1.0 requires exclusive canonicalization.</p>
<p>Flags to consider:</p>
<ul>
<li><code>SOAP_XML_CANONICAL</code> recommended to enable exc-c14n (exclusive canonicalization).</li>
<li><code>SOAP_XML_INDENT</code> optional, to emit more readable XML (see warning).</li>
<li><code>SOAP_IO_CHUNK</code> efficient HTTP-chunked streaming messages.</li>
<li><code>SOAP_ENC_GZIP</code> for HTTP compression (also enables HTTP chunking).</li>
</ul>
<dl class="section warning"><dt>Warning</dt><dd>Interoperability with WCF WS-Security is not guaranteed when <code>SOAP_XML_INDENT</code> is enabled. Avoid using <code>SOAP_XML_INDENT</code> for interoperability. The implementation of C14N in WCF with respect to the normalization of white space between XML tags differs from the protocol standards.</dd></dl>
<h2><a class="anchor" id="wsse_9_1"></a>
Encrypting Messages</h2>
<p>Encryption should be used in combination with signing. A signature ensures message integrity while encryption ensures confidentially. Encrypted messages can be tampered with unless integrity is ensured. Therefore, the reader should be familiar with the material in Section <a class="el" href="wsse.html#wsse_8">Signatures</a> should to sign and verify message content.</p>
<p>Messages are encrypted using either public key cryptography or by using a symmetric secret key. A symmetric secret key should only be shared between the sender and receiver (or any trusted communicating peer).</p>
<p>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 Security header and used for encryption of the SOAP Body as follows:</p>
<div class="fragment"><div class="line">X509 *cert = ...; <span class="comment">//</span></div><div class="line"><span class="keywordflow">if</span> (<a class="code" href="wsseapi_8h.html#a1ba85a8b14587cff0865ebc3e5e9e340">soap_wsse_add_EncryptedKey</a>(soap, <a class="code" href="mecevp_8h.html#a8976847eff9cf2faebc7697e0d596047">SOAP_MEC_ENV_ENC_DES_CBC</a>, <span class="stringliteral">"Cert"</span>, cert, NULL, NULL, NULL))</div><div class="line"> soap_print_fault(soap, stderr);</div></div><!-- fragment --><p><code>SOAP_MEC_ENV_ENC_DES_CBC</code> specifies envelope encoding with triple DES CBC and PKCS1 RSA-1_5. Use <code>(SOAP_MEC_ENV_ENC_AES256_CBC | SOAP_MEC_OAEP)</code> for AES256 CBC with OAEP padding (OAEP is recommended over RSA-1_5 or use GCM).</p>
<p>The envelope encryption options are:</p>
<ul>
<li><code>SOAP_MEC_ENV_ENC_DES_CBC</code> RSA-1_5 envelope encryption with triple DES CBC</li>
<li><code>SOAP_MEC_ENV_ENC_AES256_CBC</code> RSA-1_5 envelope encryption with AES256 CBC</li>
<li><code>SOAP_MEC_ENV_ENC_AES256_GCM</code> envelope authenticated encryption with AES256 GCM</li>
<li><code>SOAP_MEC_ENV_ENC_AES256_CBC | SOAP_MEC_OAEP</code> OAEP envelope encryption with AES256 CBC</li>
</ul>
<p>where, in the above, AES256 can also be replaced with AES128 or AES192.</p>
<p>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.</p>
<p>To include a subject key ID in the Security header instead of the entire public key, specify the subject key ID parameter:</p>
<div class="fragment"><div class="line">X509 *cert = ...; <span class="comment">//</span></div><div class="line"><span class="keywordflow">if</span> (<a class="code" href="wsseapi_8h.html#a1ba85a8b14587cff0865ebc3e5e9e340">soap_wsse_add_EncryptedKey</a>(soap, <a class="code" href="mecevp_8h.html#a8976847eff9cf2faebc7697e0d596047">SOAP_MEC_ENV_ENC_DES_CBC</a>, <span class="stringliteral">"Cert"</span>, cert, <span class="stringliteral">"Subject Key ID"</span>, NULL, NULL))</div><div class="line"> soap_print_fault(soap, stderr);</div></div><!-- fragment --><p>The difference with the previous example where no subject key ID was specified is that the Security header only contains the subject key ID and no longer the public key in base64 format.</p>
<p>To exclude the encrypted key certificate from the message and include a X509Data element with IssuerName and SerialNumber:</p>
<div class="fragment"><div class="line">X509 *cert = ...;</div><div class="line"><span class="keywordflow">if</span> (<a class="code" href="wsseapi_8h.html#a1ba85a8b14587cff0865ebc3e5e9e340">soap_wsse_add_EncryptedKey</a>(soap, <a class="code" href="mecevp_8h.html#a8976847eff9cf2faebc7697e0d596047">SOAP_MEC_ENV_ENC_DES_CBC</a>, <span class="stringliteral">"Cert"</span>, cert, NULL, <span class="stringliteral">"CN=Root Agency"</span>, <span class="stringliteral">"-79441640260855276448009124614332182350"</span>))</div><div class="line"> soap_print_fault(soap, stderr);</div></div><!-- fragment --><p>The issuer name and serial number (must be in decimal for <code>soap_wsse_add_EncryptedKey</code>) of a certificate can be obtained as follows:</p>
<div class="fragment"><div class="line">X509 *cert = ...;</div><div class="line">BIGNUM *bn = BN_new();</div><div class="line"><span class="keywordtype">char</span> issuer[256], *serial;</div><div class="line">X509_NAME_oneline(X509_get_issuer_name(cert), issuer, <span class="keyword">sizeof</span>(issuer)-1);</div><div class="line">ASN1_INTEGER_to_BN(X509_get_serialNumber(cert), bn);</div><div class="line">serial = BN_bn2dec(bn);</div><div class="line">OPENSSL_free(bn);</div><div class="line">...</div><div class="line">if (<a class="code" href="wsseapi_8h.html#a1ba85a8b14587cff0865ebc3e5e9e340">soap_wsse_add_EncryptedKey</a>(soap, <a class="code" href="mecevp_8h.html#a8976847eff9cf2faebc7697e0d596047">SOAP_MEC_ENV_ENC_DES_CBC</a>, <span class="stringliteral">"Cert"</span>, cert, NULL, issuer+1, serial))</div><div class="line"> soap_print_fault(soap, stderr);</div><div class="line">...</div><div class="line">OPENSSL_free(serial);</div></div><!-- fragment --><p>Note that in the above code the leading slash in "/CN=Root Agency" is excluded from the issuer name.</p>
<p>When excluding the encrypted key certificate from the message, the token handler callback must be provided on the receiving end to obtain the certificate that corresponds to the issuer name and serial number.</p>
<p>To encrypt specific elements of the SOAP Body rather than the entire SOAP Body, use <code>soap_wsse_add_EncryptedKey_encrypt_only</code> to specify elements to encrypt in combination with <code>soap_wsse_set_wsu_id</code> to specify these elements again as follows:</p>
<div class="fragment"><div class="line">X509 *cert = ...;</div><div class="line"><span class="comment">// the SOAP Body contains one <ns:myContract> and one <ns:myPIN> (not nested)</span></div><div class="line"><a class="code" href="wsseapi_8h.html#a9582748dda80d0307e253f1a86c0c454">soap_wsse_set_wsu_id</a>(soap, <span class="stringliteral">"ns:myContract ns:myPIN"</span>);</div><div class="line"><span class="keywordflow">if</span> (<a class="code" href="wsseapi_8h.html#adef816d148bd8b1ce1c5a3d023712779">soap_wsse_add_EncryptedKey_encrypt_only</a>(soap, <a class="code" href="mecevp_8h.html#a8976847eff9cf2faebc7697e0d596047">SOAP_MEC_ENV_ENC_DES_CBC</a>, <span class="stringliteral">"Cert"</span>, cert, NULL, NULL, NULL, <span class="stringliteral">"ns:myContract ns:myPIN"</span>))</div><div class="line"> soap_print_fault(soap, stderr);</div></div><!-- fragment --><p>To encrypt the SOAP Body and SOAP Header element(s), such as ds:Signature, use "SOAP-ENV:Body" with <code>soap_wsse_add_EncryptedKey_encrypt_only</code> to specify these elements:</p>
<div class="fragment"><div class="line">X509 *cert = ...;</div><div class="line"><a class="code" href="wsseapi_8h.html#a9582748dda80d0307e253f1a86c0c454">soap_wsse_set_wsu_id</a>(soap, <span class="stringliteral">"ds:Signature"</span>);</div><div class="line"><span class="keywordflow">if</span> (<a class="code" href="wsseapi_8h.html#adef816d148bd8b1ce1c5a3d023712779">soap_wsse_add_EncryptedKey_encrypt_only</a>(soap, <a class="code" href="mecevp_8h.html#a8976847eff9cf2faebc7697e0d596047">SOAP_MEC_ENV_ENC_DES_CBC</a>, <span class="stringliteral">"Cert"</span>, cert, NULL, NULL, NULL, <span class="stringliteral">"ds:Signature SOAP-ENV:Body"</span>))</div><div class="line"> soap_print_fault(soap, stderr);</div></div><!-- fragment --><dl class="section note"><dt>Note</dt><dd>The <code>soap_wsse_set_wsu_id</code> MUST be used to specify all element tag names to encrypt. Additional elements MAY be specified in <code>soap_wsse_set_wsu_id</code> (for example elements to digitally sign). You do not have to use this function to set the wsu:Id of the SOAP Body which always has a wsu:Id with "Body".</dd>
<dd>
The elements identified by the tag names in <code>soap_wsse_set_wsu_id</code> to encrypt MUST occur NO MORE THAN ONCE in the XML message.</dd></dl>
<p>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 <code>soap_wsse_encrypt_body</code> function to encrypt the SOAP Body as follows:</p>
<div class="fragment"><div class="line"><span class="keywordtype">char</span> des_key[20] = ...; <span class="comment">// 20-byte (160-bit) DES shared secret key</span></div><div class="line"><span class="keywordflow">if</span> (<a class="code" href="wsseapi_8h.html#ac12c951db671e4e29810d0f0ae7f1b63">soap_wsse_encrypt_body</a>(soap, <a class="code" href="mecevp_8h.html#ae8f63ce4ee6492f0b07949d301eda7d6">SOAP_MEC_ENC_DES_CBC</a>, des_key, <span class="keyword">sizeof</span>(des_key)))</div><div class="line"> soap_print_fault(soap, stderr);</div></div><!-- fragment --><p>The symmetric encryption options are:</p>
<ul>
<li><code>SOAP_MEC_ENC_DES_CBC</code> symmetric encryption with triple DES CBC</li>
<li><code>SOAP_MEC_ENC_AES256_CBC</code> symmetric encryption with AES256 CBC</li>
<li><code>SOAP_MEC_ENC_AES256_GCM</code> symmetric authenticated encryption with AES256 GCM</li>
</ul>
<p>where, in the above, AES256 can also be replaced with AES128 or AES192.</p>
<p>For example, symmetric encryption with AES256:</p>
<div class="fragment"><div class="line"><span class="keywordtype">char</span> aes256_key[32] = ...; <span class="comment">// 32-byte (256-bit) AES256 shared secret key</span></div><div class="line"><span class="keywordflow">if</span> (<a class="code" href="wsseapi_8h.html#ac12c951db671e4e29810d0f0ae7f1b63">soap_wsse_encrypt_body</a>(soap, <a class="code" href="mecevp_8h.html#aeb9a2bf88cf42f85a4ace0d3cc4a1508">SOAP_MEC_ENC_AES256_CBC</a>, aes256_key, <span class="keyword">sizeof</span>(aes256_key)))</div><div class="line"> soap_print_fault(soap, stderr);</div></div><!-- fragment --><p>To symmetrically encrypt specific elements of the SOAP Body rather than the entire SOAP Body, use <code>soap_wsse_encrypt_only</code> to specify the elements to encrypt in combination with <code>soap_wsse_set_wsu_id</code> to specify these elements again as follows:</p>
<div class="fragment"><div class="line"><span class="keywordtype">char</span> des_key[20] = ...; <span class="comment">// 20-byte (160-bit) secret key</span></div><div class="line"><span class="comment">// the SOAP Body contains one <ns:myContract> and one <ns:myPIN> (not nested)</span></div><div class="line"><a class="code" href="wsseapi_8h.html#a9582748dda80d0307e253f1a86c0c454">soap_wsse_set_wsu_id</a>(soap, <span class="stringliteral">"ns:myContract ns:myPIN"</span>);</div><div class="line"><span class="keywordflow">if</span> (<a class="code" href="wsseapi_8h.html#a3c417c369946561cbf72566349041805">soap_wsse_encrypt_only</a>(soap, <a class="code" href="mecevp_8h.html#ae8f63ce4ee6492f0b07949d301eda7d6">SOAP_MEC_ENC_DES_CBC</a>, des_key, <span class="keyword">sizeof</span>(des_key), <span class="stringliteral">"ns:myContract ns:myPIN"</span>))</div><div class="line"> soap_print_fault(soap, stderr);</div></div><!-- fragment --><dl class="section note"><dt>Note</dt><dd>The <code>soap_wsse_set_wsu_id</code> MUST be used to specify all element tag names to encrypt. Additional elements MAY be specified in <code>soap_wsse_set_wsu_id</code> (for example elements to digitally sign).</dd>
<dd>
The elements identified by the tag names in <code>soap_wsse_set_wsu_id</code> to encrypt MUST occur EXACTLY ONCE in the SOAP Body.</dd></dl>
<h2><a class="anchor" id="wsse_9_2"></a>
Decrypting Message Parts</h2>
<p>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.</p>
<p>An example of a token handler callback:</p>
<div class="fragment"><div class="line">soap_register_plugin_arg(soap, <a class="code" href="wsseapi_8h.html#af15bedb61bffb589683354bc37d20c3a">soap_wsse</a>);</div><div class="line"><a class="code" href="wsseapi_8h.html#ad6a0b722a052aaa7652cba5245f78b5f">soap_wsse_set_security_token_handler</a>(soap, security_token_handler);</div><div class="line"></div><div class="line"><span class="keyword">const</span> <span class="keywordtype">void</span> *security_token_handler(<span class="keyword">struct</span> soap *soap, <span class="keywordtype">int</span> *alg, <span class="keyword">const</span> <span class="keywordtype">char</span> *keyname, <span class="keyword">const</span> <span class="keywordtype">unsigned</span> <span class="keywordtype">char</span> *keyid, <span class="keywordtype">int</span> keyidlen, <span class="keywordtype">int</span> *keylen)</div><div class="line">{</div><div class="line"> <span class="comment">// Get the user name from UsernameToken in message</span></div><div class="line"> <span class="keyword">const</span> <span class="keywordtype">char</span> *uid = <a class="code" href="wsseapi_8h.html#aca3fe6fb7c1e5c103827b33f24292f47">soap_wsse_get_Username</a>(soap);</div><div class="line"> <span class="keywordflow">switch</span> (*alg)</div><div class="line"> {</div><div class="line"> <span class="keywordflow">case</span> <a class="code" href="smdevp_8h.html#a448c4d5953ca007263ff6a5bd055cfdc">SOAP_SMD_VRFY_DSA_SHA1</a>:</div><div class="line"> <span class="keywordflow">case</span> <a class="code" href="smdevp_8h.html#a5b4e9a64ef8a1de550cc5c5ab889d3c6">SOAP_SMD_VRFY_DSA_SHA256</a>:</div><div class="line"> <span class="keywordflow">case</span> <a class="code" href="smdevp_8h.html#aa395a40932c9c057cd264c03716c9d6e">SOAP_SMD_VRFY_RSA_SHA1</a>:</div><div class="line"> <span class="keywordflow">case</span> <a class="code" href="smdevp_8h.html#aa5d9d36c2db3bbef1dfd66593240cf16">SOAP_SMD_VRFY_RSA_SHA224</a>:</div><div class="line"> <span class="keywordflow">case</span> <a class="code" href="smdevp_8h.html#ac495716c1f8630567900c33cdea08fd1">SOAP_SMD_VRFY_RSA_SHA256</a>:</div><div class="line"> <span class="keywordflow">case</span> <a class="code" href="smdevp_8h.html#afec4c06d2b78ff9a4451a311849d7275">SOAP_SMD_VRFY_RSA_SHA384</a>:</div><div class="line"> <span class="keywordflow">case</span> <a class="code" href="smdevp_8h.html#a16e7c5ef33465656c0d270eebc933021">SOAP_SMD_VRFY_RSA_SHA512</a>:</div><div class="line"> <span class="keywordflow">case</span> <a class="code" href="smdevp_8h.html#a5dba7fc390d7f1056c1315e33003fadb">SOAP_SMD_VRFY_ECDSA_SHA1</a>:</div><div class="line"> <span class="keywordflow">case</span> <a class="code" href="smdevp_8h.html#adf90c93cd7ddcbfdfb4331cd79ec7fed">SOAP_SMD_VRFY_ECDSA_SHA224</a>:</div><div class="line"> <span class="keywordflow">case</span> <a class="code" href="smdevp_8h.html#a302ca7fbeadd43dd57b0cea2c1daf5f3">SOAP_SMD_VRFY_ECDSA_SHA256</a>:</div><div class="line"> <span class="keywordflow">case</span> <a class="code" href="smdevp_8h.html#a1b34145858769663cf7dd9c7cd05d549">SOAP_SMD_VRFY_ECDSA_SHA384</a>:</div><div class="line"> <span class="keywordflow">case</span> <a class="code" href="smdevp_8h.html#ab434218e658d6aa79768e43389cf6871">SOAP_SMD_VRFY_ECDSA_SHA512</a>:</div><div class="line"> <span class="keywordflow">if</span> (uid)</div><div class="line"> {</div><div class="line"> <span class="comment">// Lookup uid to retrieve the X509 certificate to verify the signature</span></div><div class="line"> <span class="keyword">const</span> X509 *cert = ...; </div><div class="line"> <span class="keywordflow">return</span> (<span class="keyword">const</span> <span class="keywordtype">void</span>*)cert;</div><div class="line"> }</div><div class="line"> <span class="keywordflow">break</span>;</div><div class="line"> <span class="keywordflow">case</span> <a class="code" href="smdevp_8h.html#a7d00704c43ee044926905cd327a712ef">SOAP_SMD_HMAC_SHA1</a>:</div><div class="line"> <span class="keywordflow">case</span> <a class="code" href="smdevp_8h.html#a0a03fa407c392d53e3e6609032c69a19">SOAP_SMD_HMAC_SHA224</a>:</div><div class="line"> <span class="keywordflow">case</span> <a class="code" href="smdevp_8h.html#a561d6c47f122626acb2f36bdabdc07e6">SOAP_SMD_HMAC_SHA256</a>:</div><div class="line"> <span class="keywordflow">case</span> <a class="code" href="smdevp_8h.html#a5928fa6c9c366857ffb96e70e6e04609">SOAP_SMD_HMAC_SHA384</a>:</div><div class="line"> <span class="keywordflow">case</span> <a class="code" href="smdevp_8h.html#a0eaedca857ff22ca7e2290e3ad67a184">SOAP_SMD_HMAC_SHA512</a>:</div><div class="line"> <span class="keywordflow">if</span> (uid)</div><div class="line"> {</div><div class="line"> <span class="comment">// Lookup uid to retrieve the HMAC SHA key to verify the signature</span></div><div class="line"> <span class="keyword">const</span> <span class="keywordtype">void</span> *key = ...; </div><div class="line"> *alg = ...;</div><div class="line"> *keylen = ...;</div><div class="line"> <span class="keywordflow">return</span> key;</div><div class="line"> }</div><div class="line"> <span class="keywordflow">return</span> NULL; <span class="comment">// no certificate: fail</span></div><div class="line"> <span class="keywordflow">case</span> <a class="code" href="mecevp_8h.html#a533b28fdec1dba756bdd69dea83ad244">SOAP_MEC_ENV_DEC_DES_CBC</a>:</div><div class="line"> <span class="keywordflow">case</span> <a class="code" href="mecevp_8h.html#aa94bbedb3884c463ddcb6dbe3e582913">SOAP_MEC_ENV_DEC_AES128_CBC</a>:</div><div class="line"> <span class="keywordflow">case</span> <a class="code" href="mecevp_8h.html#ad5935be53e1e0d92fcca66f3227d7465">SOAP_MEC_ENV_DEC_AES192_CBC</a>:</div><div class="line"> <span class="keywordflow">case</span> <a class="code" href="mecevp_8h.html#a614a07a8c4fa0aa814e1009033403b84">SOAP_MEC_ENV_DEC_AES256_CBC</a>:</div><div class="line"> <span class="keywordflow">case</span> <a class="code" href="mecevp_8h.html#a54d92e9969643328dbdb10e687ea6a88">SOAP_MEC_ENV_DEC_AES512_CBC</a>: <span class="comment">// reserved for future use</span></div><div class="line"> <span class="keywordflow">case</span> <a class="code" href="mecevp_8h.html#a64d04044822454e1672f5501c67d4a9d">SOAP_MEC_ENV_DEC_AES128_GCM</a>: <span class="comment">// GCM requires OpenSSL 1.0.2 or higher</span></div><div class="line"> <span class="keywordflow">case</span> <a class="code" href="mecevp_8h.html#a8cdb2b051d394a12c7bb7768a95eeb6d">SOAP_MEC_ENV_DEC_AES192_GCM</a>: <span class="comment">// GCM requires OpenSSL 1.0.2 or higher</span></div><div class="line"> <span class="keywordflow">case</span> <a class="code" href="mecevp_8h.html#a86d91a11d9401b4bd0bb86d3b0478fca">SOAP_MEC_ENV_DEC_AES256_GCM</a>: <span class="comment">// GCM requires OpenSSL 1.0.2 or higher</span></div><div class="line"> <span class="keywordflow">case</span> <a class="code" href="mecevp_8h.html#a49ba1d264167026ba86a3a108aad5060">SOAP_MEC_ENV_DEC_AES512_GCM</a>: <span class="comment">// GCM requires OpenSSL 1.0.2 or higher</span></div><div class="line"> <span class="keywordflow">if</span> (keyname)</div><div class="line"> {</div><div class="line"> <span class="comment">// use this to get the key or certificate from a key store using the keyname value:</span></div><div class="line"> <span class="comment">// 1. keyname is set to the subject name of the certificate, if a</span></div><div class="line"> <span class="comment">// certificate is present in the SecurityTokenReference/KeyIdentifier</span></div><div class="line"> <span class="comment">// when ValueType is http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3</span></div><div class="line"> <span class="comment">// 2. keyname is set to the string concatenation</span></div><div class="line"> <span class="comment">// "{X509IssuerName}#{X509SerialNumber}" of the X509IssuerName</span></div><div class="line"> <span class="comment">// and X509SerialNumber present in X509Data/X509IssuerSerial</span></div><div class="line"> <span class="comment">// 3. keyname is set to X509Data/X509SubjectName</span></div><div class="line"> <span class="keywordflow">return</span> ...;</div><div class="line"> }</div><div class="line"> <span class="keywordflow">else</span> <span class="keywordflow">if</span> (keyid)</div><div class="line"> {</div><div class="line"> <span class="comment">// use this to get the key from a key store using the keyid[0..keyidlen-1]:</span></div><div class="line"> <span class="comment">// 1. keyid and keyidlen are set to the data in</span></div><div class="line"> <span class="comment">// SecurityTokenReference/KeyIdentifier when the ValueType is</span></div><div class="line"> <span class="comment">// http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509SubjectKeyIdentifier</span></div><div class="line"> <span class="keywordflow">return</span> ...;</div><div class="line"> }</div><div class="line"> <span class="keywordflow">break</span>;</div><div class="line"> <span class="keywordflow">case</span> <a class="code" href="mecevp_8h.html#a9226364c4bf1cd277c417cd4d2706561">SOAP_MEC_DEC_DES_CBC</a>:</div><div class="line"> <span class="keywordflow">case</span> <a class="code" href="mecevp_8h.html#a276b8e0038b3c44235a66467d9056cb1">SOAP_MEC_DEC_AES128_CBC</a>:</div><div class="line"> <span class="keywordflow">case</span> <a class="code" href="mecevp_8h.html#abc989d7ba0703386b786be70f8f23b69">SOAP_MEC_DEC_AES192_CBC</a>:</div><div class="line"> <span class="keywordflow">case</span> <a class="code" href="mecevp_8h.html#a7151041a3f95a45edce0660f0fbcea44">SOAP_MEC_DEC_AES256_CBC</a>:</div><div class="line"> <span class="keywordflow">case</span> <a class="code" href="mecevp_8h.html#a84c17ef148e5a7ab05eea24acf7d4159">SOAP_MEC_DEC_AES512_CBC</a>: <span class="comment">// reserved for future use</span></div><div class="line"> <span class="keywordflow">case</span> <a class="code" href="mecevp_8h.html#ad63c14482c5e9cf3028e96da56d878ad">SOAP_MEC_DEC_AES128_GCM</a>: <span class="comment">// GCM requires OpenSSL 1.0.2 or higher</span></div><div class="line"> <span class="keywordflow">case</span> <a class="code" href="mecevp_8h.html#abeda47e7f8d80130e3675a32b9abcb7e">SOAP_MEC_DEC_AES192_GCM</a>: <span class="comment">// GCM requires OpenSSL 1.0.2 or higher</span></div><div class="line"> <span class="keywordflow">case</span> <a class="code" href="mecevp_8h.html#ab3853c4ab88cd32c4ba6058335f76fdf">SOAP_MEC_DEC_AES256_GCM</a>: <span class="comment">// GCM requires OpenSSL 1.0.2 or higher`</span></div><div class="line"> <span class="keywordflow">case</span> <a class="code" href="mecevp_8h.html#a20016e3054eca51dc31b9eb6c6100d2a">SOAP_MEC_DEC_AES512_GCM</a>: <span class="comment">// GCM requires OpenSSL 1.0.2 or higher</span></div><div class="line"> <span class="keywordflow">if</span> (keyname)</div><div class="line"> {</div><div class="line"> <span class="comment">// use the keyname to get the shared secret key associated for decryption</span></div><div class="line"> *keylen = ... <span class="comment">// length of the shared secret key</span></div><div class="line"> <span class="keywordflow">return</span> ...;</div><div class="line"> }</div><div class="line"> <span class="keywordflow">break</span>;</div><div class="line"> }</div><div class="line"> <span class="keywordflow">return</span> NULL; <span class="comment">// fail</span></div><div class="line">}</div></div><!-- fragment --><p>The last two case-arms are used to return a 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 <code>soap_wsse_add_EncryptedKey</code> at the sender side.</p>
<dl class="section warning"><dt>Warning</dt><dd>The security token handler callback function parameters have changed in 2.8.34 and greater with the addition of KeyIdentifier information <code>keyid</code> and <code>keyidlen</code>.</dd></dl>
<p>To set the default private key for envelope decryption, use:</p>
<div class="fragment"><div class="line">EVP_PKEY *rsa_private_key = ...;</div><div class="line"><a class="code" href="wsseapi_8h.html#a403569990cf3278a361552aecaf51ffc">soap_wsse_decrypt_auto</a>(soap, <a class="code" href="mecevp_8h.html#a533b28fdec1dba756bdd69dea83ad244">SOAP_MEC_ENV_DEC_DES_CBC</a>, rsa_private_key, 0);</div></div><!-- fragment --><p>The envelope decryption options are:</p>
<ul>
<li><code>SOAP_MEC_ENV_DEC_DES_CBC</code> RSA-1_5 envelope decryption with triple DES CBC</li>
<li><code>SOAP_MEC_ENV_DEC_AES256_CBC</code> RSA-1_5 envelope decryption with AES256 CBC</li>
<li><code>SOAP_MEC_ENV_DEC_AES256_GCM</code> envelope authenticated decryption with AES256 GCM</li>
<li><code>SOAP_MEC_ENV_DEC_AES256_CBC | SOAP_MEC_OAEP</code> OAEP envelope decryption with AES256 CBC</li>
</ul>
<p>where, in the above, AES256 can be replaced with AES128 or AES192.</p>
<p>To set the default shared secret key for symmetric decryption, use:</p>
<div class="fragment"><div class="line"><span class="keywordtype">char</span> des_key[20] = ...; <span class="comment">// 20-byte (160-bit) triple DES key</span></div><div class="line"><a class="code" href="wsseapi_8h.html#a403569990cf3278a361552aecaf51ffc">soap_wsse_decrypt_auto</a>(soap, <a class="code" href="mecevp_8h.html#a9226364c4bf1cd277c417cd4d2706561">SOAP_MEC_DEC_DES_CBC</a>, des_key, <span class="keyword">sizeof</span>(des_key));</div></div><!-- fragment --><p>The symmetric decryption options are:</p>
<ul>
<li><code>SOAP_MEC_DEC_DES_CBC</code> symmetric decryption with triple DES CBC</li>
<li><code>SOAP_MEC_DEC_AES256_CBC</code> symmetric decryption with AES256 CBC</li>
<li><code>SOAP_MEC_DEC_AES256_GCM</code> symmetric authenticated decryption with AES256 GCM</li>
</ul>
<p>where, in the above, AES256 can be replaced with AES128 or AES192.</p>
<p>For example, symmetric decryption with AES256:</p>
<div class="fragment"><div class="line"><span class="keywordtype">char</span> aes256_key[32] = ...; <span class="comment">// 32-byte (256-bit) AES256 key</span></div><div class="line"><a class="code" href="wsseapi_8h.html#a403569990cf3278a361552aecaf51ffc">soap_wsse_decrypt_auto</a>(soap, <a class="code" href="mecevp_8h.html#a7151041a3f95a45edce0660f0fbcea44">SOAP_MEC_DEC_AES256_CBC</a>, aes256_key, <span class="keyword">sizeof</span>(aes256_key));</div></div><!-- fragment --><p>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.</p>
<p>To remove the default key, use:</p>
<div class="fragment"><div class="line"><a class="code" href="wsseapi_8h.html#a403569990cf3278a361552aecaf51ffc">soap_wsse_decrypt_auto</a>(soap, <a class="code" href="mecevp_8h.html#ad5e433363a4d62ada3cf154fb7e5c08e">SOAP_MEC_NONE</a>, NULL, 0);</div></div><!-- fragment --><h2><a class="anchor" id="wsse_9_3"></a>
Example Client and Server</h2>
<p>The code for a client is shown below that uses signatures and encryption:</p>
<div class="fragment"><div class="line">FILE *fd;</div><div class="line">EVP_PKEY *rsa_private_key;</div><div class="line">X509 *cert;</div><div class="line"><span class="comment">// create new context with recommended C14N enabled</span></div><div class="line"><span class="keyword">struct </span>soap *soap = soap_new1(SOAP_XML_CANONICAL);</div><div class="line"><span class="comment">// register the plugin(s)</span></div><div class="line">soap_register_plugin(soap, <a class="code" href="wsseapi_8h.html#af15bedb61bffb589683354bc37d20c3a">soap_wsse</a>);</div><div class="line"><span class="comment">// enable peer certificate verification</span></div><div class="line">soap->cafile = <span class="stringliteral">"cacerts.pem"</span>; <span class="comment">// file with CA certs of peers</span></div><div class="line">soap->capath = <span class="stringliteral">"dir/to/certs"</span>; <span class="comment">// and/or point to CA certs directory</span></div><div class="line">soap->crlfile = <span class="stringliteral">"revoked.pem"</span>; <span class="comment">// use CRL (optional)</span></div><div class="line">soap->fsslverify = ssl_verify; <span class="comment">// optional, a callback to verify peer certificates</span></div><div class="line"><span class="comment">// get the private key for signing and decryption</span></div><div class="line">fd = fopen(<span class="stringliteral">"privkey.pem"</span>, <span class="stringliteral">"r"</span>);</div><div class="line">rsa_private_key = PEM_read_PrivateKey(fd, NULL, NULL, <span class="stringliteral">"password"</span>);</div><div class="line">fclose(fd);</div><div class="line"><span class="comment">// get the certificate to include in the security header</span></div><div class="line">fd = fopen(<span class="stringliteral">"cert.pem"</span>, <span class="stringliteral">"r"</span>);</div><div class="line">X509 *cert = PEM_read_X509(fd, NULL, NULL, NULL);</div><div class="line">fclose(fd);</div><div class="line"><span class="comment">// enable decryption with the private key</span></div><div class="line"><a class="code" href="wsseapi_8h.html#a403569990cf3278a361552aecaf51ffc">soap_wsse_decrypt_auto</a>(soap, <a class="code" href="mecevp_8h.html#a533b28fdec1dba756bdd69dea83ad244">SOAP_MEC_ENV_DEC_DES_CBC</a>, rsa_private_key, 0);</div><div class="line"><span class="comment">// enable signature verification</span></div><div class="line"><a class="code" href="wsseapi_8h.html#a7321b451910e1d3887b328f03de92f34">soap_wsse_verify_auto</a>(soap, <a class="code" href="smdevp_8h.html#a011f7d21ad3c8634373fe3d3325fcd75">SOAP_SMD_NONE</a>, NULL, 0);</div><div class="line"><span class="comment">// add the certificate X509 token and token reference, sign the Body using the private key</span></div><div class="line"><span class="keywordflow">if</span> (<a class="code" href="wsseapi_8h.html#a53075fb3cec4ec4e70fb11850fecb401">soap_wsse_add_BinarySecurityTokenX509</a>(soap, <span class="stringliteral">"X509Token"</span>, cert)</div><div class="line"> || <a class="code" href="wsseapi_8h.html#a72df80abd1d36cea516feda3a84672cf">soap_wsse_add_KeyInfo_SecurityTokenReferenceX509</a>(soap, <span class="stringliteral">"#X509Token"</span>)</div><div class="line"> || <a class="code" href="wsseapi_8h.html#ab653754f1a287ba06bd808cf89548c38">soap_wsse_sign_body</a>(soap, <a class="code" href="smdevp_8h.html#a8634e2291f274a42107d3e935add3241">SOAP_SMD_SIGN_RSA_SHA256</a>, rsa_private_key, 0))</div><div class="line"> ... <span class="comment">// an error occurred</span></div><div class="line"><span class="comment">// encrypt the Body and the signature using the public key in cert (the cert of the peer)</span></div><div class="line"><a class="code" href="wsseapi_8h.html#a9582748dda80d0307e253f1a86c0c454">soap_wsse_set_wsu_id</a>(soap, <span class="stringliteral">"ds:Signature"</span>);</div><div class="line"><span class="keywordflow">if</span> (<a class="code" href="wsseapi_8h.html#adef816d148bd8b1ce1c5a3d023712779">soap_wsse_add_EncryptedKey_encrypt_only</a>(soap, <a class="code" href="mecevp_8h.html#a8976847eff9cf2faebc7697e0d596047">SOAP_MEC_ENV_ENC_DES_CBC</a>, <span class="stringliteral">"Cert"</span>, cert, NULL, NULL, NULL, <span class="stringliteral">"ds:Signature SOAP-ENV:Body"</span>))</div><div class="line"> ... <span class="comment">// an error occurred</span></div><div class="line"><span class="keywordflow">if</span> (soap_call_ns__myMethod(soap, ...))</div><div class="line"> ... <span class="comment">// a transmission error occurred</span></div><div class="line">...</div><div class="line">EVP_PKEY_free(rsa_private_key);</div><div class="line">X509_free(cert);</div></div><!-- fragment --><p>When using HTTPS, the <code>soap->cafile</code>, <code>soap->capath</code> are already set with <code>soap_ssl_client_context()</code>. The explicit assignments shown above are not needed.</p>
<p>See <a class="el" href="wsse.html#wsse_8_4">Signature Validation</a> on how to implement the optional <code>ssl_verify</code> callback to verify peer certificates.</p>
<p>You may want to register a token handler callback if the peer does not include its X509 certificate in the security header. The token handler callback should retrieve the certificate, e.g. given its id and serial number.</p>
<p>The server-side service is implemented as follows:</p>
<div class="fragment"><div class="line">EVP_PKEY *rsa_private_key; <span class="comment">// OK to declare global</span></div><div class="line">X509 *cert; <span class="comment">// OK to declare global</span></div><div class="line">..</div><div class="line">FILE *fd;</div><div class="line"><span class="comment">// create new context with recommended C14N enabled</span></div><div class="line"><span class="keyword">struct </span>soap *soap = soap_new1(SOAP_XML_CANONICAL);</div><div class="line"><span class="comment">// register the plugin(s)</span></div><div class="line">soap_register_plugin(soap, <a class="code" href="wsseapi_8h.html#af15bedb61bffb589683354bc37d20c3a">soap_wsse</a>);</div><div class="line"><span class="comment">// enable peer certificate verification</span></div><div class="line">soap->cafile = <span class="stringliteral">"cacerts.pem"</span>; <span class="comment">// file with CA certs of peers</span></div><div class="line">soap->capath = <span class="stringliteral">"dir/to/certs"</span>; <span class="comment">// and/or point to CA certs directory</span></div><div class="line">soap->crlfile = <span class="stringliteral">"revoked.pem"</span>; <span class="comment">// use CRL (optional)</span></div><div class="line">soap->fsslverify = ssl_verify; <span class="comment">// optional, a callback to verify peer certificates</span></div><div class="line"><span class="comment">// get the private key for signing and decryption</span></div><div class="line">fd = fopen(<span class="stringliteral">"privkey.pem"</span>, <span class="stringliteral">"r"</span>);</div><div class="line">rsa_private_key = PEM_read_PrivateKey(fd, NULL, NULL, <span class="stringliteral">"password"</span>);</div><div class="line">fclose(fd);</div><div class="line"><span class="comment">// get the certificate to include in the security header</span></div><div class="line">fd = fopen(<span class="stringliteral">"cert.pem"</span>, <span class="stringliteral">"r"</span>);</div><div class="line">X509 *cert = PEM_read_X509(fd, NULL, NULL, NULL);</div><div class="line">fclose(fd);</div><div class="line">...</div><div class="line">if (!soap_valid_socket(soap_bind(soap, NULL, port, 100)))</div><div class="line"> ... <span class="comment">// an error occurred</span></div><div class="line"><span class="keywordflow">while</span> (soap_valid_socket(soap_accept(soap)))</div><div class="line">{</div><div class="line"> <span class="comment">// enable signature verification</span></div><div class="line"> <a class="code" href="wsseapi_8h.html#a7321b451910e1d3887b328f03de92f34">soap_wsse_verify_auto</a>(soap, <a class="code" href="smdevp_8h.html#a011f7d21ad3c8634373fe3d3325fcd75">SOAP_SMD_NONE</a>, NULL, 0);</div><div class="line"> <span class="comment">// enable decryption with the private key</span></div><div class="line"> <a class="code" href="wsseapi_8h.html#a403569990cf3278a361552aecaf51ffc">soap_wsse_decrypt_auto</a>(soap, <a class="code" href="mecevp_8h.html#a533b28fdec1dba756bdd69dea83ad244">SOAP_MEC_ENV_DEC_DES_CBC</a>, rsa_private_key, 0);</div><div class="line"> <span class="comment">// serve one request</span></div><div class="line"> <span class="keywordflow">if</span> (soap_serve(soap))</div><div class="line"> {</div><div class="line"> <a class="code" href="wsseapi_8h.html#ac06c7021592b2aaca50f73e0de9dec7c">soap_wsse_delete_Security</a>(soap);</div><div class="line"> soap_print_fault(soap, stderr);</div><div class="line"> }</div><div class="line">}</div><div class="line">...</div><div class="line">EVP_PKEY_free(rsa_private_key);</div><div class="line">X509_free(cert);</div></div><!-- fragment --><p>where an example service operation could be:</p>
<div class="fragment"><div class="line"><span class="keywordtype">int</span> ns__myMethod(<span class="keyword">struct</span> soap *soap, ...)</div><div class="line">{</div><div class="line"> ...</div><div class="line"> <span class="comment">// remove old security headers</span></div><div class="line"> <a class="code" href="wsseapi_8h.html#ac06c7021592b2aaca50f73e0de9dec7c">soap_wsse_delete_Security</a>(soap);</div><div class="line"> <span class="comment">// encrypt the Body and the signature using the public key in cert (the cert of the peer)</span></div><div class="line"> <a class="code" href="wsseapi_8h.html#a9582748dda80d0307e253f1a86c0c454">soap_wsse_set_wsu_id</a>(soap, <span class="stringliteral">"ds:Signature"</span>);</div><div class="line"> <span class="comment">// add the certificate X509 token and token reference, sign the Body using the private key</span></div><div class="line"> <span class="comment">// encrypt the Body and the signature using the public key in cert (the cert of the peer)</span></div><div class="line"> <span class="keywordflow">if</span> (<a class="code" href="wsseapi_8h.html#a53075fb3cec4ec4e70fb11850fecb401">soap_wsse_add_BinarySecurityTokenX509</a>(soap, <span class="stringliteral">"X509Token"</span>, cert)</div><div class="line"> || <a class="code" href="wsseapi_8h.html#a72df80abd1d36cea516feda3a84672cf">soap_wsse_add_KeyInfo_SecurityTokenReferenceX509</a>(soap, <span class="stringliteral">"#X509Token"</span>)</div><div class="line"> || <a class="code" href="wsseapi_8h.html#ab653754f1a287ba06bd808cf89548c38">soap_wsse_sign_body</a>(soap, <a class="code" href="smdevp_8h.html#a8634e2291f274a42107d3e935add3241">SOAP_SMD_SIGN_RSA_SHA256</a>, rsa_private_key, 0)</div><div class="line"> || <a class="code" href="wsseapi_8h.html#adef816d148bd8b1ce1c5a3d023712779">soap_wsse_add_EncryptedKey_encrypt_only</a>(soap, <a class="code" href="mecevp_8h.html#a8976847eff9cf2faebc7697e0d596047">SOAP_MEC_ENV_ENC_DES_CBC</a>, <span class="stringliteral">"Cert"</span>, cert, NULL, NULL, NULL, <span class="stringliteral">"ds:Signature SOAP-ENV:Body"</span>))</div><div class="line"> {</div><div class="line"> <a class="code" href="wsseapi_8h.html#ac06c7021592b2aaca50f73e0de9dec7c">soap_wsse_delete_Security</a>(soap); <span class="comment">// remove incomplete security headers</span></div><div class="line"> <span class="keywordflow">return</span> soap->error;</div><div class="line"> }</div><div class="line"> <span class="keywordflow">return</span> SOAP_OK;</div><div class="line">}</div></div><!-- fragment --><p>The service operation signs the Body using its private key and encrypts the response Body and signature using a public key from the peer's certificate.</p>
<p>To implement a server that supports HTTP keep-alive, a <code>soap->fserveloop</code> callback function should be assigned. This callback is executed in the <code>soap_serve()</code> loop to call <code><a class="el" href="wsseapi_8c.html#aba1ed2878f44b2c4efac24cd89ff30bf" title="Uses the wsse plugin to initiate the automatic verification of the signature and SignedInfo Reference...">soap_wsse_verify_auto()</a></code> and <code><a class="el" href="wsseapi_8c.html#a370bea41564f3a49c1c558e174c4f2c0" title="Start automatic decryption when needed using the specified key. This function should be used just onc...">soap_wsse_decrypt_auto()</a></code> to ensure that the continuous inbound message stream can be verified and decrypted:</p>
<div class="fragment"><div class="line"><span class="keyword">struct </span>soap *soap = soap_new1(SOAP_XML_CANONICAL | SOAP_IO_KEEPALIVE);</div><div class="line">soap_register_plugin(soap, <a class="code" href="wsseapi_8h.html#af15bedb61bffb589683354bc37d20c3a">soap_wsse</a>);</div><div class="line">...</div><div class="line">soap->fserveloop = set_verify_decrypt_auto;</div><div class="line">...</div><div class="line">while (soap_valid_socket(soap_accept(soap)))</div><div class="line">{</div><div class="line"> set_verify_decrypt_auto(soap);</div><div class="line"> <span class="comment">// serve multiple requests (when keep alive)</span></div><div class="line"> <span class="keywordflow">if</span> (soap_serve(soap))</div><div class="line"> {</div><div class="line"> <a class="code" href="wsseapi_8h.html#ac06c7021592b2aaca50f73e0de9dec7c">soap_wsse_delete_Security</a>(soap);</div><div class="line"> soap_print_fault(soap, stderr);</div><div class="line"> }</div><div class="line">}</div><div class="line"></div><div class="line"><span class="keywordtype">int</span> set_verify_decrypt_auto(<span class="keyword">struct</span> soap *soap)</div><div class="line">{</div><div class="line"> <span class="comment">// enable signature verification</span></div><div class="line"> <a class="code" href="wsseapi_8h.html#a7321b451910e1d3887b328f03de92f34">soap_wsse_verify_auto</a>(soap, <a class="code" href="smdevp_8h.html#a011f7d21ad3c8634373fe3d3325fcd75">SOAP_SMD_NONE</a>, NULL, 0);</div><div class="line"> <span class="comment">// enable decryption with the private key</span></div><div class="line"> <a class="code" href="wsseapi_8h.html#a403569990cf3278a361552aecaf51ffc">soap_wsse_decrypt_auto</a>(soap, <a class="code" href="mecevp_8h.html#a533b28fdec1dba756bdd69dea83ad244">SOAP_MEC_ENV_DEC_DES_CBC</a>, rsa_private_key, 0);</div><div class="line"> <span class="keywordflow">return</span> SOAP_OK;</div><div class="line">}</div></div><!-- fragment --><h1><a class="anchor" id="wsse_10"></a>
Security Timestamps</h1>
<p>The material in this section relates to the WS-Security specification section 10.</p>
<p>To add a timestamp with the creation time to the Security header, use:</p>
<div class="fragment"><div class="line"><a class="code" href="wsseapi_8h.html#a71fe27aee76db1d0a635afe106d8b109">soap_wsse_add_Timestamp</a>(soap, NULL, 0); <span class="comment">// 0 means no expiration</span></div></div><!-- fragment --><p>The lifetime of a message (in seconds) is passed as the third argument, which will be displayed as the timestamp expiration time:</p>
<div class="fragment"><div class="line"><a class="code" href="wsseapi_8h.html#a71fe27aee76db1d0a635afe106d8b109">soap_wsse_add_Timestamp</a>(soap, NULL, 10); <span class="comment">// 10 seconds lifetime</span></div></div><!-- fragment --><p>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:</p>
<div class="fragment"><div class="line"><a class="code" href="wsseapi_8h.html#a71fe27aee76db1d0a635afe106d8b109">soap_wsse_add_Timestamp</a>(soap, <span class="stringliteral">"Time"</span>, 10); <span class="comment">// timestamp will be signed</span></div></div><!-- fragment --><p>After receiving a message, the receiver can verify the presence and validity of the timestamp and whether it was signed with:</p>
<div class="fragment"><div class="line"><span class="keywordflow">if</span> (!<a class="code" href="wsseapi_8h.html#a98422cde0e2b7b14d65212f7061101fa">soap_wsse_verify_Timestamp</a>(soap))</div><div class="line">{</div><div class="line"> <a class="code" href="wsseapi_8h.html#ac06c7021592b2aaca50f73e0de9dec7c">soap_wsse_delete_Security</a>(soap);</div><div class="line"> ... <span class="comment">// error, no timestamp or timestamp has expired</span></div><div class="line">}</div><div class="line"><span class="keywordflow">else</span> <span class="keywordflow">if</span> (<a class="code" href="wsseapi_8h.html#a3fbe81de521579f026dd1ba8e81c59c1">soap_wsse_verify_element</a>(soap, <span class="stringliteral">"http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"</span>, <span class="stringliteral">"Timestamp"</span>) > 0)</div><div class="line"> ... <span class="comment">// timestamp was signed</span></div></div><!-- fragment --><h1><a class="anchor" id="wsse_11"></a>
WS-Security and HTTPS</h1>
<p>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:</p>
<div class="fragment"><div class="line"><span class="preprocessor">#include "<a class="code" href="wsseapi_8h.html">wsseapi.h</a>"</span></div><div class="line"><span class="preprocessor">#include "<a class="code" href="threads_8h.html">threads.h</a>"</span></div><div class="line"><span class="keyword">struct </span>soap *soap;</div><div class="line"><span class="keywordflow">if</span> (CRYPTO_thread_setup())</div><div class="line"> ... <span class="comment">// error</span></div><div class="line">soap = soap_new1(SOAP_XML_CANONICAL);</div><div class="line">soap_register_plugin(soap, <a class="code" href="wsseapi_8h.html#af15bedb61bffb589683354bc37d20c3a">soap_wsse</a>);</div><div class="line"><span class="keywordflow">if</span> (soap_ssl_client_context(&soap,</div><div class="line"> SOAP_SSL_DEFAULT, <span class="comment">// requires server authentication</span></div><div class="line"> NULL, <span class="comment">// keyfile for client authentication to server</span></div><div class="line"> NULL, <span class="comment">// the keyfile password</span></div><div class="line"> <span class="stringliteral">"cacerts.pem"</span>, <span class="comment">// cafile CA certificates to authenticate the server</span></div><div class="line"> NULL, <span class="comment">// capath CA directory path to certificates</span></div><div class="line"> NULL</div><div class="line">))</div><div class="line"> ... <span class="comment">// error</span></div><div class="line">soap->cafile = <span class="stringliteral">"cacerts.pem"</span>; <span class="comment">// same as above (or overrides the above)</span></div><div class="line">soap->capath = <span class="stringliteral">"dir/to/certs"</span>; <span class="comment">// and/or point to CA certs</span></div><div class="line">soap->crlfile = <span class="stringliteral">"revoked.pem"</span>; <span class="comment">// use CRL (optional)</span></div><div class="line">... <span class="comment">// set up WS-Security for signatures/encryption etc</span></div><div class="line"><span class="keywordflow">if</span> (soap_call_ns__myMethod(soap, <span class="stringliteral">"https://..."</span>, ...))</div><div class="line"> ... <span class="comment">// error</span></div><div class="line">... <span class="comment">// process response results</span></div><div class="line">soap_destroy(soap);</div><div class="line">soap_end(soap);</div><div class="line">soap_free(soap);</div><div class="line">CRYPTO_thread_cleanup();</div></div><!-- fragment --><p>The CRYPTO threads should be set up before any threads are created.</p>
<p>The <code>soap_ssl_client_context</code> only needs to be set up once. Use the following flags:</p>
<ul>
<li><code>SOAP_SSL_DEFAULT</code> requires server authentication, CA certs should be used</li>
<li><code>SOAP_SSL_NO_AUTHENTICATION</code> disables server authentication</li>
<li><code>SOAP_SSL_SKIP_HOST_CHECK</code> disables server authentication host check</li>
<li><code>SOAP_SSL_ALLOW_EXPIRED_CERTIFICATE</code> to accept self-signed certificates, expired certificates, and certificates without CRL.</li>
</ul>
<p>The server uses the following:</p>
<div class="fragment"><div class="line"><span class="preprocessor">#include "<a class="code" href="wsseapi_8h.html">wsseapi.h</a>"</span></div><div class="line"><span class="preprocessor">#include "<a class="code" href="threads_8h.html">threads.h</a>"</span></div><div class="line">SOAP_SOCKET m, s;</div><div class="line"><span class="keywordtype">int</span> port = 443;</div><div class="line"><span class="keyword">struct </span>soap *soap;</div><div class="line"><span class="keywordflow">if</span> (CRYPTO_thread_setup())</div><div class="line"> ... <span class="comment">// error</span></div><div class="line">soap = soap_new1(SOAP_XML_CANONICAL);</div><div class="line">soap_register_plugin(soap, <a class="code" href="wsseapi_8h.html#af15bedb61bffb589683354bc37d20c3a">soap_wsse</a>);</div><div class="line"><span class="keywordflow">if</span> (soap_ssl_server_context(&soap,</div><div class="line"> SOAP_SSL_DEFAULT, <span class="comment">// requires server to authenticate, but not the client</span></div><div class="line"> server.pem, <span class="comment">// keyfile for authentication to client</span></div><div class="line"> <span class="stringliteral">"password"</span>, <span class="comment">// the keyfile password</span></div><div class="line"> NULL, <span class="comment">// CA certificates to authenticate the client</span></div><div class="line"> NULL, <span class="comment">// CA directory path to certificates</span></div><div class="line"> NULL, <span class="comment">// use RSA 2048 bits (or give file name with DH param)</span></div><div class="line"> NULL,</div><div class="line"> NULL</div><div class="line">))</div><div class="line"> ... <span class="comment">// error</span></div><div class="line"><span class="keywordflow">if</span> (!soap_valid_socket(m = soap_bind(soap, NULL, port, 100))</div><div class="line"> ... <span class="comment">// error</span></div><div class="line"><span class="keywordflow">for</span> (;;)</div><div class="line">{</div><div class="line"> <span class="keywordflow">if</span> (!soap_valid_socket(s = soap_accept(soap)))</div><div class="line"> ... <span class="comment">// error</span></div><div class="line"> <span class="keywordflow">else</span></div><div class="line"> {</div><div class="line"> <span class="keyword">struct </span>soap *tsoap = soap_copy(soap);</div><div class="line"> <span class="keywordflow">while</span> (THREAD_CREATE(&tid, (<span class="keywordtype">void</span>*(*)(<span class="keywordtype">void</span>*))&process_request, (<span class="keywordtype">void</span>*)tsoap))</div><div class="line"> sleep(1);</div><div class="line"> }</div><div class="line">}</div><div class="line">soap_destroy(soap);</div><div class="line">soap_end(soap);</div><div class="line">soap_free(soap);</div><div class="line">CRYPTO_thread_cleanup();</div></div><!-- fragment --><p>where we define a <code>process_request()</code> function that is executed by the thread to process the request (on a copy of the soap context struct):</p>
<div class="fragment"><div class="line"> <span class="keywordtype">void</span> *process_request(<span class="keyword">struct</span> soap *soap)</div><div class="line"> {</div><div class="line"> ... <span class="comment">// set up WS-Security for signatures/encryption etc</span></div><div class="line"> <span class="keywordflow">if</span> (soap_ssl_accept(soap)</div><div class="line"> || soap_serve(soap))</div><div class="line"> ... <span class="comment">// error</span></div><div class="line"> soap_destroy(soap);</div><div class="line"> soap_end(soap);</div><div class="line"> soap_free(soap);</div><div class="line">}</div></div><!-- fragment --><p>The <code>soap_ssl_server_context</code> only needs to be set up once. Use the following flags:</p>
<ul>
<li><code>SOAP_SSL_DEFAULT</code> requires server authentication, but no client authentication</li>
<li><code>SOAP_SSL_REQUIRE_CLIENT_AUTHENTICATION</code> requires client authentication</li>
</ul>
<p>We also should implement the mutex setup and cleanup operations as follows:</p>
<div class="fragment"><div class="line"><span class="keyword">struct </span>CRYPTO_dynlock_value</div><div class="line">{</div><div class="line"> MUTEX_TYPE mutex;</div><div class="line">};</div><div class="line"></div><div class="line"><span class="keyword">static</span> MUTEX_TYPE *mutex_buf;</div><div class="line"></div><div class="line"><span class="keyword">static</span> <span class="keyword">struct </span>CRYPTO_dynlock_value *dyn_create_function(<span class="keyword">const</span> <span class="keywordtype">char</span> *file, <span class="keywordtype">int</span> line)</div><div class="line">{</div><div class="line"> <span class="keyword">struct </span>CRYPTO_dynlock_value *value;</div><div class="line"> value = (<span class="keyword">struct </span>CRYPTO_dynlock_value*)malloc(<span class="keyword">sizeof</span>(<span class="keyword">struct</span> CRYPTO_dynlock_value));</div><div class="line"> <span class="keywordflow">if</span> (value)</div><div class="line"> MUTEX_SETUP(value->mutex);</div><div class="line"> <span class="keywordflow">return</span> value;</div><div class="line">}</div><div class="line"></div><div class="line"><span class="keyword">static</span> <span class="keywordtype">void</span> dyn_lock_function(<span class="keywordtype">int</span> mode, <span class="keyword">struct</span> CRYPTO_dynlock_value *l, <span class="keyword">const</span> <span class="keywordtype">char</span> *file, <span class="keywordtype">int</span> line)</div><div class="line">{</div><div class="line"> <span class="keywordflow">if</span> (mode & CRYPTO_LOCK)</div><div class="line"> MUTEX_LOCK(l->mutex);</div><div class="line"> <span class="keywordflow">else</span></div><div class="line"> MUTEX_UNLOCK(l->mutex);</div><div class="line">}</div><div class="line"></div><div class="line"><span class="keyword">static</span> <span class="keywordtype">void</span> dyn_destroy_function(<span class="keyword">struct</span> CRYPTO_dynlock_value *l, <span class="keyword">const</span> <span class="keywordtype">char</span> *file, <span class="keywordtype">int</span> line)</div><div class="line">{</div><div class="line"> MUTEX_CLEANUP(l->mutex);</div><div class="line"> free(l);</div><div class="line">}</div><div class="line"></div><div class="line"><span class="keywordtype">void</span> locking_function(<span class="keywordtype">int</span> mode, <span class="keywordtype">int</span> n, <span class="keyword">const</span> <span class="keywordtype">char</span> *file, <span class="keywordtype">int</span> line)</div><div class="line">{</div><div class="line"> <span class="keywordflow">if</span> (mode & CRYPTO_LOCK)</div><div class="line"> MUTEX_LOCK(mutex_buf[n]);</div><div class="line"> <span class="keywordflow">else</span></div><div class="line"> MUTEX_UNLOCK(mutex_buf[n]);</div><div class="line">}</div><div class="line"></div><div class="line"><span class="keywordtype">unsigned</span> <span class="keywordtype">long</span> id_function()</div><div class="line">{</div><div class="line"> <span class="keywordflow">return</span> (<span class="keywordtype">unsigned</span> <span class="keywordtype">long</span>)THREAD_ID;</div><div class="line">}</div><div class="line"></div><div class="line"><span class="keywordtype">int</span> CRYPTO_thread_setup()</div><div class="line">{</div><div class="line"> <span class="keywordtype">int</span> i;</div><div class="line"> mutex_buf = (MUTEX_TYPE*)malloc(CRYPTO_num_locks() * <span class="keyword">sizeof</span>(pthread_mutex_t));</div><div class="line"> <span class="keywordflow">if</span> (!mutex_buf)</div><div class="line"> <span class="keywordflow">return</span> SOAP_EOM;</div><div class="line"> <span class="keywordflow">for</span> (i = 0; i < CRYPTO_num_locks(); i++)</div><div class="line"> MUTEX_SETUP(mutex_buf[i]);</div><div class="line"> CRYPTO_set_id_callback(id_function);</div><div class="line"> CRYPTO_set_locking_callback(locking_function);</div><div class="line"> CRYPTO_set_dynlock_create_callback(dyn_create_function);</div><div class="line"> CRYPTO_set_dynlock_lock_callback(dyn_lock_function);</div><div class="line"> CRYPTO_set_dynlock_destroy_callback(dyn_destroy_function);</div><div class="line"> <span class="keywordflow">return</span> SOAP_OK;</div><div class="line">}</div><div class="line"></div><div class="line"><span class="keywordtype">void</span> CRYPTO_thread_cleanup()</div><div class="line">{</div><div class="line"> <span class="keywordtype">int</span> i;</div><div class="line"> <span class="keywordflow">if</span> (!mutex_buf)</div><div class="line"> <span class="keywordflow">return</span>;</div><div class="line"> CRYPTO_set_id_callback(NULL);</div><div class="line"> CRYPTO_set_locking_callback(NULL);</div><div class="line"> CRYPTO_set_dynlock_create_callback(NULL);</div><div class="line"> CRYPTO_set_dynlock_lock_callback(NULL);</div><div class="line"> CRYPTO_set_dynlock_destroy_callback(NULL);</div><div class="line"> <span class="keywordflow">for</span> (i = 0; i < CRYPTO_num_locks(); i++)</div><div class="line"> MUTEX_CLEANUP(mutex_buf[i]);</div><div class="line"> free(mutex_buf);</div><div class="line"> mutex_buf = NULL;</div><div class="line">}</div></div><!-- fragment --><p>For additional details and examples, see the user guide and examples in the gSOAP package directory gsoap/samples/ssl.</p>
<h1><a class="anchor" id="wsse_12"></a>
Miscellaneous</h1>
<p>The Security header block was generated from the WS-Security schema with the wsdl2h tool and WS/WS-typemap.dat: </p><pre class="fragment">wsdl2h -cegxy -o wsse.h -t WS/WS-typemap.dat WS/wsse.xsd
</pre><p>The same process was used to generate the header file <a class="el" href="ds_8h.html">ds.h</a> from the XML digital signatures core schema, and the <a class="el" href="xenc_8h.html">xenc.h</a> encryption schema: </p><pre class="fragment">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
</pre><p>The <a class="el" href="wsse_8h.html">import/wsse.h</a> file has the following definition for the Security header block:</p>
<div class="fragment"><div class="line"><span class="keyword">typedef</span> <span class="keyword">struct </span><a class="code" href="struct__wsse_____security.html">_wsse__Security</a></div><div class="line">{ <span class="keyword">struct </span><a class="code" href="struct__wsu_____timestamp.html">_wsu__Timestamp</a>* <a class="code" href="struct__wsse_____security.html#a583fa6d2bb116663adab85ecae3a21e2">wsu__Timestamp</a>;</div><div class="line"> <span class="keyword">struct </span><a class="code" href="struct__wsse_____username_token.html">_wsse__UsernameToken</a>* <a class="code" href="struct__wsse_____security.html#a7ad164fa611e885fdc48d869f54bcda2">UsernameToken</a>;</div><div class="line"> <span class="keyword">struct </span><a class="code" href="struct__wsse_____binary_security_token.html">_wsse__BinarySecurityToken</a>* <a class="code" href="struct__wsse_____security.html#ae1a14c1c9cb302b6e155eec932b4f342">BinarySecurityToken</a>;</div><div class="line"> <span class="keyword">struct </span><a class="code" href="structxenc_____encrypted_key_type.html">xenc__EncryptedKeyType</a>* <a class="code" href="struct__wsse_____security.html#af12916fe6b69cc8cf4414408548ff91e">xenc__EncryptedKey</a>;</div><div class="line"> <span class="keyword">struct </span><a class="code" href="struct__xenc_____reference_list.html">_xenc__ReferenceList</a>* <a class="code" href="struct__wsse_____security.html#ad44f259af51a51596f636a0c9097cdb2">xenc__ReferenceList</a>;</div><div class="line"> <span class="keyword">struct </span><a class="code" href="structds_____signature_type.html">ds__SignatureType</a>* <a class="code" href="struct__wsse_____security.html#a9a97955540b1b810aeeda13a1341dba0">ds__Signature</a>;</div><div class="line"> @<span class="keywordtype">char</span>* <a class="code" href="struct__wsse_____security.html#a1a941d6f69eab871bced7acdb6eb41f3">SOAP_ENV__actor</a>;</div><div class="line"> @<span class="keywordtype">char</span>* <a class="code" href="struct__wsse_____security.html#a86e02ae8da9bf2f6e1dd6eda8f596012">SOAP_ENV__role</a>;</div><div class="line">} <a class="code" href="wsse_8h.html#adea0e9370ef38183a230394959186a83">_wsse__Security</a>;</div></div><!-- fragment --><p>The <code><a class="el" href="struct__wsse_____security.html" title="This element defines the wsse:Security SOAP header element per Section 4. Imported element _wsse__Sec...">_wsse__Security</a></code> header is modified by a WS/WS-typemap.dat mapping rule to include additional details.</p>
<h1><a class="anchor" id="wsse_13"></a>
Some Limitations</h1>
<ul>
<li>Encryption of simple content (CDATA content) directly with <code>soap_wsse_add_EncryptedKey_encrypt_only</code> is not supported. You can encrypt elements with complex content (complexType and complexContent elements that have sub elements). Decryption is not limited to elements with complex content.</li>
<li>Encryption is performed after signing (likewise, signatures are verified after decryption). Signing after encryption is not supported in the current plugin release. It is generally known that it is safer to perform encryption after signing as the WSSE plugin performs, and not vice versa.</li>
<li>Signing and encrypting XML containing QName content may lead to verification issues, because the W3C C14N exclusive canonicalization protocol has known limitations with QName content normalization. In fact, not signing the prefix bindings as in C14N exclusive canonicalization is a security risk, because the prefix-URI binding can be modified when placed at an ancestor node that is not included in the signed XML content. Use <code>soap_wsse_set_InclusiveNamespaces(soap, "prefixlist")</code> to define all namespace prefixes (space-separated in the string) that should be considered inclusive. All prefixes used in QName content should be listed to mitigate the security risks outlined. The WSSE engine recognizes xsi:type, SOAP-ENC:arrayType, SOAP-ENC:itemType attribute QNames. Therefore, soapcpp2 option <code>-t</code> is always safe to use, but a non-gSOAP receiver may still fail.</li>
</ul>
<h1><a class="anchor" id="wsse_14"></a>
Defending Against Signature Wrapping Attacks</h1>
<p>Signature wrapping attacks exploit a vulnerability in the XML DSig standard by tricking the signature verifier to verify the signature of the signed content but when this content is moved to a different place in the XML document, for example where the content is ignored. In this attack, a signed XML element identified with an <code>id</code> attribute is moved in the document and replaced with an unsigned replacement element with aribitrary content that the attacker created and the receiver will use instead. We refer to online articles and publications on signature wrapping attacks for more details.</p>
<p>To defend against signature wrapping attacks, we recommend to sign the SOAP Body instead of individual elements of the SOAP Body. A receiver must verify that the SOAP Body received is indeed signed and verify that other parts of the message such as critical SOAP Headers are signed. You can do this on the receiving end by calling <code>soap_wsse_verify_body(soap)</code> and check that the return value is nonzero. This prevents signature wrapping attacks on the SOAP Body. If individual element(s) of the SOAP Body must be signed instead of the body itself, then make sure to use call <code>soap_wsse_verify_element(soap, "namespaceURI", "tag")</code> on the receiving end and check that the return value is nonzero to verify that all elements matching the namespaceURI and tag are signed.</p>
<p>If SOAP Headers are signed such as the timestamp and username token then make sure to verify that the timestamp was indeed signed by calling <code>soap_wsse_verify_element(soap, "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd", "Timestamp")</code> and check that the return value is nonzero. Likewise, to verify that the usernameToken authentication credentials are signed, call <code>soap_wsse_verify_element(soap, "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd", "UsernameToken")</code> and check that the return value is nonzero.</p>
<p>To prevent signature wrapping attacks on XML namespace prefixes used in QNames, which are vulnerable when the prefix is bound to a namespace URI in an ancester node to the signed content, use <code>soap_wsse_set_InclusiveNamespaces(soap, "prefixlist")</code>. This makes the namespace prefixes in the list (space-separated in the string) inclusive. Use <code>soap_wsse_set_InclusiveNamespaces(soap, "+")</code> to automatically add all prefixes defined in the namespace table (i.e. the .nsmap file) to the inclusive namespace list (this requires gSOAP 2.8.64 or greater).</p>
<h1><a class="anchor" id="wsse_wsc"></a>
WS-SecureConversation and WS-Trust</h1>
<p>To use a WS-SecureConversation security context token (SCT) with WS-Security:</p>
<div class="fragment"><div class="line"><span class="keyword">const</span> <span class="keywordtype">char</span> *identifier = <span class="stringliteral">"..."</span>;</div><div class="line"><a class="code" href="wsseapi_8h.html#a4941ccab15e473e979ff4b3a926c04bb">soap_wsse_add_SecurityContextToken</a>(soap, <span class="stringliteral">"SCT"</span>, identifier);</div></div><!-- fragment --><p>In this example a context has been established and the secret that is identified by the 'identifier' string is known to both parties. This secret is used to sign the message body. The "SCT" is a wsu:Id, which is used as a reference to sign the token.</p>
<p>To compute PSHA1 with base64 input strings <code>client_secret_base64</code> and <code>server_secret_base64</code> to output a base64-encoded <code>psha1[0..psha1len-1]</code> string <code>psha1_base64</code>:</p>
<div class="fragment"><div class="line"><span class="keywordtype">int</span> psha1len = 32; <span class="comment">// or greater</span></div><div class="line"><span class="keywordtype">int</span> n, m;</div><div class="line"><span class="keyword">const</span> <span class="keywordtype">char</span> *client_secret = soap_base642s(soap, client_secret_base64, NULL, 0, &n);</div><div class="line"><span class="keyword">const</span> <span class="keywordtype">char</span> *server_secret = soap_base642s(soap, server_secret_base64, NULL, 0, &m);</div><div class="line"><span class="keywordtype">char</span> psha1[psha1len];</div><div class="line"><span class="keywordtype">char</span> *psha1_base64;</div><div class="line"><span class="keywordflow">if</span> (n != 16)</div><div class="line"> .. error <span class="comment">// HMAC key is 16 bytes</span></div><div class="line"><span class="keywordflow">if</span> (<a class="code" href="wsseapi_8h.html#ac50a99453ce725c252c8d5efb89438c6">soap_psha1</a>(soap, client_secret, server_secret, m, psha1, psha1len))</div><div class="line"> .. error <span class="comment">// insufficient memory</span></div><div class="line">psha1_base64 = soap_s2base64(soap, (<span class="keywordtype">unsigned</span> <span class="keywordtype">char</span>*)psha1, NULL, psha1len);</div></div><!-- fragment --> </div></div><!-- contents -->
<hr class="footer">
<address class="footer">
Copyright (C) 2018, Robert van Engelen, Genivia Inc., All Rights Reserved.
</address>
<address class="footer"><small>
Converted on Mon May 14 2018 21:30:25 by <a target="_blank" href="http://www.doxygen.org/index.html">Doxygen</a> 1.8.11</small></address>
<br>
<div style="height: 246px; background: #DBDBDB;">
</body>
</html>
distrib
>
Mageia
>
7
>
armv7hl
>
media
>
core-updates
>
by-pkgid
>
7481cee7c2fa9882f50c7e675767c075
>
files
>
2909
