| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> | |
| <html><head><meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1"> | |
| <title>gSOAP WS-Security: The wsse plugin</title> | |
| <link href="doxygen.css" rel="stylesheet" type="text/css"> | |
| </head><body> | |
| <!-- Generated by Doxygen 1.3.8 --> | |
| <div class="qindex"><a class="qindex" href="index.html">Main Page</a> | <a class="qindex" href="annotated.html">Class List</a> | <a class="qindex" href="files.html">File List</a> | <a class="qindex" href="functions.html">Class Members</a> | <a class="qindex" href="globals.html">File Members</a> | <a class="qindex" href="pages.html">Related Pages</a></div> | |
| <h1><a class="anchor" name="wsse">The wsse plugin</a></h1><h2><a class="anchor" name="wsse_5"> | |
| Security Header</a></h2> | |
| The material in this section relates to the WS-Security specification section 5.<p> | |
| To use the wsse plugin:<ol> | |
| <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.</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="wsseapi_8c.html">wsseapi.c</a> and the generated source files with the -DWITH_DOM and -DWITH_OPENSSL compile flags set. The <a class="el" href="smdevp_8c.html">smdevp.c</a> and wssapi.c files are located in the 'plugin' directory.</li><li>Use the wsse plugin API functions described below to add and verify Security headers.</li></ol> | |
| <p> | |
| An example wsse client/server application can be found in samples/wsse.<p> | |
| The Security header block was generated from the WS-Security schema with the wsdl2h tool and WS/WS-typemap.dat:<p> | |
| <div class="fragment"><pre> $ wsdl2h -cegxy -o wsse.h -t WS/WS-typemap.dat WS/wsse.xsd | |
| </pre></div><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.<p> | |
| The import/wsse.h file has the following definition for the Security header block:<p> | |
| <div class="fragment"><pre><span class="keyword">typedef</span> <span class="keyword">struct </span><a class="code" href="struct__wsse_____security.html">_wsse__Security</a> | |
| { <span class="keyword">struct </span><a class="code" href="struct__wsu_____timestamp.html">_wsu__Timestamp</a>* wsu__Timestamp; | |
| <span class="keyword">struct </span><a class="code" href="struct__wsse_____username_token.html">_wsse__UsernameToken</a>* UsernameToken; | |
| <span class="keyword">struct </span><a class="code" href="struct__wsse_____binary_security_token.html">_wsse__BinarySecurityToken</a>* BinarySecurityToken; | |
| <span class="keyword">struct </span><a class="code" href="structds_____signature_type.html">ds__SignatureType</a>* ds__Signature; | |
| @<span class="keywordtype">char</span>* SOAP_ENV__actor; | |
| @<span class="keywordtype">char</span>* SOAP_ENV__role; | |
| } <a class="code" href="struct__wsse_____security.html">_wsse__Security</a>; | |
| </pre></div><p> | |
| To add an empty Security header block to the SOAP header, use:<p> | |
| <div class="fragment"><pre> <a class="code" href="wsseapi_8c.html#a31">soap_wsse_add_Security</a>(soap); | |
| </pre></div><p> | |
| To delete a Security header, use:<p> | |
| <div class="fragment"><pre> <a class="code" href="wsseapi_8c.html#a33">soap_wsse_delete_Security</a>(soap); | |
| </pre></div><p> | |
| Adding an empty Security header block is not very useful. We will mainly make use of the higher-level functions of the wsse plugin to populate and verify Security header content.<p> | |
| Note: The soap context includes an actor value soap.actor that is populated and rendered as the SOAP-ENV:actor (SOAP 1.1) or SOAP-ENV:role (SOAP 1.2) attribute in XML within the generic SOAP Header. The attribute is optional, but should be used to target a recipient such as an intermediate node to process the SOAP header. In contrast, actor or role attributes within Security header blocks target specific recipients to process the Security header block. The gSOAP implementation does not automate this feature and application should set and check the actor/role attribute when necessary. In addition, the current implementation supports the inclusion of a single Security header block in the SOAP header.<p> | |
| To populate the SOAP-ENV:actor or SOAP-ENV:role attribute within the Security header, use:<p> | |
| <div class="fragment"><pre> <a class="code" href="wsseapi_8c.html#a32">soap_wsse_add_Security_actor</a>(soap, <span class="stringliteral">"recipient"</span>); | |
| </pre></div><p> | |
| To obtain the actor or role value (e.g. after receiving a message), use:<p> | |
| <div class="fragment"><pre> <a class="code" href="struct__wsse_____security.html">_wsse__Security</a> *security = <a class="code" href="wsseapi_8c.html#a34">soap_wsse_Security</a>(soap); | |
| <span class="keywordflow">if</span> (security) | |
| { ... = security-><a class="code" href="struct__wsse_____security.html#o4">SOAP_ENV__actor</a>; <span class="comment">// SOAP 1.1</span> | |
| ... = security-><a class="code" href="struct__wsse_____security.html#o5">SOAP_ENV__role</a>; <span class="comment">// SOAP 1.2</span> | |
| </pre></div><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> | |
| Security header blocks are attached to the soap context, which means that the information will be automatically kept to support multiple invocations.<h2><a class="anchor" name="wsse_6"> | |
| Security Tokens</a></h2> | |
| The material in this section relates to the WS-Security specification section 6.<h3><a class="anchor" name="wsse_6_2"> | |
| User Name Token</a></h3> | |
| To add a user name token to the Security header block, use:<p> | |
| <div class="fragment"><pre> <a class="code" href="wsseapi_8c.html#a41">soap_wsse_add_UsernameTokenText</a>(soap, <span class="stringliteral">"Id"</span>, <span class="stringliteral">"username"</span>, NULL); | |
| </pre></div><p> | |
| The Id value is optional. When non-NULL the user name token is included in the digital signature to protect its integrity. It is common for the wsse plugin functions to accept such Ids, which are serialized as wsu:Id identifiers for cross-referencing XML elements. The signature engine of the wsse plugin is designed to automatically sign all wsu:Id attributed elements to simplify the code you need to write to implement the signing process.<p> | |
| To add a user name token with clear text password, use:<p> | |
| <div class="fragment"><pre> <a class="code" href="wsseapi_8c.html#a41">soap_wsse_add_UsernameTokenText</a>(soap, <span class="stringliteral">"Id"</span>, <span class="stringliteral">"username"</span>, <span class="stringliteral">"password"</span>); | |
| </pre></div><p> | |
| It is strongly recommended to use <a class="el" href="wsseapi_8h.html#a24">soap_wsse_add_UsernameTokenText</a> 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> | |
| To add a user name token with password digest, use:<p> | |
| <div class="fragment"><pre> <a class="code" href="wsseapi_8c.html#a42">soap_wsse_add_UsernameTokenDigest</a>(soap, <span class="stringliteral">"Id"</span>, <span class="stringliteral">"username"</span>, <span class="stringliteral">"password"</span>); | |
| </pre></div><p> | |
| Although the password string is passed to this function, it is not rendered in XML or stored in a message log. It has been argued that this approach adopted by the WS-Security protocol is still vulnerable since the application retrieves the password in text form requiring a database to store passwords in clear text. However, a digest algorithm can be used to hash the passwords and store their digests instead, which eliminates the need to store clear-text passwords. Note that this is a common approach adopted by Unix for decades.<p> | |
| By setting the Id value to a unique string, the user name token is also digitally signed by the signature engine further preventing tampering with its value.<p> | |
| You must use <a class="el" href="wsseapi_8h.html#a25">soap_wsse_add_UsernameTokenDigest</a> 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> | |
| Clear-text passwords and password digests are verified with <a class="el" href="wsseapi_8h.html#a28">soap_wsse_verify_Password</a>. To verify a password at the receiving side to authorize a request (e.g. within a Web service operation), use:<p> | |
| <div class="fragment"><pre> <span class="keywordtype">int</span> ns__myMethod(<span class="keyword">struct</span> soap *soap, ...) | |
| { <span class="keyword">const</span> <span class="keywordtype">char</span> *username = <a class="code" href="wsseapi_8c.html#a44">soap_wsse_get_Username</a>(soap); | |
| <span class="keyword">const</span> <span class="keywordtype">char</span> *password; | |
| <span class="keywordflow">if</span> (!username) | |
| <span class="keywordflow">return</span> soap->error; <span class="comment">// no username: return FailedAuthentication</span> | |
| password = ...; <span class="comment">// lookup password of username</span> | |
| <span class="keywordflow">if</span> (<a class="code" href="wsseapi_8c.html#a45">soap_wsse_verify_Password</a>(soap, password)) | |
| <span class="keywordflow">return</span> soap->error; <span class="comment">// password verification failed: return FailedAuthentication</span> | |
| ... <span class="comment">// process request</span> | |
| <span class="keywordflow">return</span> SOAP_OK; | |
| } | |
| </pre></div><p> | |
| Note that the <a class="el" href="wsseapi_8h.html#a27">soap_wsse_get_Username</a> functions sets the wsse:FailedAuthentication fault. It is common for the wsse plugin functions to return SOAP_OK or a wsse fault that should be passed to the sender by returning soap->error from service operations. The fault is displayed with the soap_print_fault function.<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 threads.h. Of course, this only works correctly if the server is persistent, such as a stand-alone service. Note that CGI-based services do not keep state. Machine clocks must be synchronized and clock skew should not exceed <a class="el" href="wsseapi_8c.html#a1">SOAP_WSSE_CLKSKEW</a> at the server side.<h3><a class="anchor" name="wsse_6_3"> | |
| Binary Security Tokens</a></h3> | |
| 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> | |
| 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"><pre> soap->cafile = <span class="stringliteral">"cacerts.pem"</span>; <span class="comment">// use this</span> | |
| soap->capath = <span class="stringliteral">"dir/to/certs"</span>; <span class="comment">// and/or point to CA certs</span> | |
| soap->crlfile = <span class="stringliteral">"revoked.pem"</span>; <span class="comment">// use CRL (optional)</span> | |
| </pre></div><p> | |
| The <a class="el" href="wsseapi_8h.html#a35">soap_wsse_verify_X509</a> 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"><pre> X509 *cert = <a class="code" href="wsseapi_8c.html#a51">soap_wsse_get_BinarySecurityTokenX509</a>(soap, <span class="stringliteral">"Id"</span>); | |
| </pre></div><p> | |
| where Id is the identification string of the binary security token or NULL.<p> | |
| The verification is an expensive process that will be optimized in future releases by caching the certificate chain.<p> | |
| To attach a binary security token stored in a PEM file to a Security header block for transmission, use:<p> | |
| <div class="fragment"><pre> <a class="code" href="wsseapi_8c.html#a48">soap_wsse_add_BinarySecurityTokenPEM</a>(soap, NULL, <span class="stringliteral">"mycert.pem"</span>) | |
| </pre></div><p> | |
| A binary security token can be automatically signed by setting its Id attribute:<p> | |
| <div class="fragment"><pre> <a class="code" href="wsseapi_8c.html#a48">soap_wsse_add_BinarySecurityTokenPEM</a>(soap, <span class="stringliteral">"X509Token"</span>, <span class="stringliteral">"mycert.pem"</span>) | |
| </pre></div><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"><pre> FILE *fd = fopen(<span class="stringliteral">"mycert.pem"</span>, <span class="stringliteral">"r"</span>); | |
| X509 *cert = PEM_read_X509(fd, NULL, NULL, NULL); | |
| fclose(fd); | |
| <span class="keywordflow">if</span> (<a class="code" href="wsseapi_8c.html#a47">soap_wsse_add_BinarySecurityTokenX509</a>(soap, <span class="stringliteral">"X509Token"</span>, cert)) | |
| ... <span class="comment">// an error occurred</span> | |
| </pre></div><p> | |
| Other types of binary security tokens can be added to the Security header block using:<p> | |
| <div class="fragment"><pre> <a class="code" href="wsseapi_8c.html#a46">soap_wsse_add_BinarySecurityToken</a>(soap, <span class="stringliteral">"Id"</span>, <span class="stringliteral">"valueType"</span>, data, datalen); | |
| </pre></div><h2><a class="anchor" name="wsse_6_4"> | |
| XML Tokens</a></h2> | |
| The use and processing rules for XML tokens such as SAML assertions is specific to an application. The wsse plugin does not automate the use of XML tokens. The developer is encouraged to generate code for the SAML schema with wsdl2h and add the necessary assertions to the Security header block:<p> | |
| <div class="fragment"><pre><span class="keyword">typedef</span> <span class="keyword">struct </span><a class="code" href="struct__wsse_____security.html">_wsse__Security</a> | |
| { <span class="keyword">struct </span><a class="code" href="struct__wsu_____timestamp.html">_wsu__Timestamp</a>* wsu__Timestamp; | |
| <span class="keyword">struct </span><a class="code" href="struct__wsse_____username_token.html">_wsse__UsernameToken</a>* UsernameToken; | |
| <span class="keyword">struct </span><a class="code" href="struct__wsse_____binary_security_token.html">_wsse__BinarySecurityToken</a>* BinarySecurityToken; | |
| <span class="keyword">struct </span>_saml__Assertion* saml__Assertion; <span class="comment">// added</span> | |
| <span class="keyword">struct </span><a class="code" href="structds_____signature_type.html">ds__SignatureType</a>* ds__Signature; | |
| @<span class="keywordtype">char</span>* SOAP_ENV__actor; | |
| @<span class="keywordtype">char</span>* SOAP_ENV__role; | |
| } <a class="code" href="struct__wsse_____security.html">_wsse__Security</a>; | |
| </pre></div><p> | |
| Alternatively, a DOM can be used to store and retrieve XML tokens:<p> | |
| <div class="fragment"><pre><span class="preprocessor">#import "dom.h"</span> | |
| <span class="keyword">typedef</span> <span class="keyword">struct </span><a class="code" href="struct__wsse_____security.html">_wsse__Security</a> | |
| { <span class="keyword">struct </span><a class="code" href="struct__wsu_____timestamp.html">_wsu__Timestamp</a>* wsu__Timestamp; | |
| <span class="keyword">struct </span><a class="code" href="struct__wsse_____username_token.html">_wsse__UsernameToken</a>* UsernameToken; | |
| <span class="keyword">struct </span><a class="code" href="struct__wsse_____binary_security_token.html">_wsse__BinarySecurityToken</a>* BinarySecurityToken; | |
| <span class="keyword">struct </span><a class="code" href="structds_____signature_type.html">ds__SignatureType</a>* ds__Signature; | |
| <span class="keywordtype">int</span> __size; | |
| xsd__anyType* any; | |
| @<span class="keywordtype">char</span>* SOAP_ENV__actor; | |
| @<span class="keywordtype">char</span>* SOAP_ENV__role; | |
| } <a class="code" href="struct__wsse_____security.html">_wsse__Security</a>; | |
| </pre></div><h2><a class="anchor" name="wsse_7"> | |
| Token References</a></h2> | |
| The material in this section relates to the WS-Security specification section 7.<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"><pre> <a class="code" href="wsseapi_8c.html#a66">soap_wsse_add_KeyInfo_SecurityTokenReferenceURI</a>(soap, <span class="stringliteral">"URI"</span>, <span class="stringliteral">"valueType"</span>); | |
| </pre></div><p> | |
| and:<p> | |
| <div class="fragment"><pre> <a class="code" href="wsseapi_8c.html#a67">soap_wsse_add_KeyInfo_SecurityTokenReferenceX509</a>(soap, <span class="stringliteral">"URI"</span>); | |
| </pre></div><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"><pre> <span class="keywordflow">if</span> (<a class="code" href="wsseapi_8c.html#a47">soap_wsse_add_BinarySecurityTokenX509</a>(soap, <span class="stringliteral">"X509Token"</span>, cert) | |
| || <a class="code" href="wsseapi_8c.html#a67">soap_wsse_add_KeyInfo_SecurityTokenReferenceX509</a>(soap, <span class="stringliteral">"#X509Token"</span>)) | |
| ... <span class="comment">// an error occurred</span> | |
| </pre></div><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> | |
| Key identifiers can be used as well:<p> | |
| <div class="fragment"><pre> <a class="code" href="wsseapi_8c.html#a70">soap_wsse_add_KeyInfo_SecurityTokenReferenceKeyIdentifier</a>(soap, <span class="stringliteral">"Id"</span>, <span class="stringliteral">"valueType"</span>, data, datalen); | |
| </pre></div><p> | |
| Embedded references are added with:<p> | |
| <div class="fragment"><pre> <a class="code" href="wsseapi_8c.html#a73">soap_wsse_add_KeyInfo_SecurityTokenReferenceEmbedded</a>(soap, <span class="stringliteral">"Id"</span>, <span class="stringliteral">"valueType"</span>); | |
| </pre></div><p> | |
| TODO item: full support for embedded reference is currently under construction.<p> | |
| The use of key names is not recommended, but in case they are required they can be added with:<p> | |
| <div class="fragment"><pre> <a class="code" href="wsseapi_8c.html#a64">soap_wsse_add_KeyInfo_KeyName</a>(soap, <span class="stringliteral">"name"</span>); | |
| </pre></div><h2><a class="anchor" name="wsse_8"> | |
| Signatures</a></h2> | |
| The material in this section relates to the WS-Security specification section 8.<p> | |
| The wsse plugin must be registered to sign and verify messages:<p> | |
| <div class="fragment"><pre> soap_register_plugin(soap, soap_wsse); | |
| </pre></div><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 SOAP_XML_CANONICAL flag:<p> | |
| <div class="fragment"><pre> <span class="keyword">struct </span>soap *soap = soap_new1(SOAP_XML_CANONICAL); | |
| soap_register_plugin(soap, soap_wsse); | |
| </pre></div><p> | |
| If you prefer XML indentation, use:<p> | |
| <div class="fragment"><pre> <span class="keyword">struct </span>soap *soap = soap_new1(SOAP_XML_CANONICAL | SOAP_XML_INDENT); | |
| soap_register_plugin(soap, soap_wsse); | |
| </pre></div><p> | |
| Next, we decide which signature algorithm is appropriate to use:<ul> | |
| <li>HMAC-SHA1 uses a secret key (also known as a shared key in symmetric cryptography) to sign the SHA1 digest of the SignedInfo element.</li><li>DSA-SHA1 uses a DSA private key to sign the SHA1 digest of the SignedInfo element.</li><li>RSA-SHA1 uses a RSA private key to sign the SHA1 digest of the SignedInfo element.</li></ul> | |
| <p> | |
| HMAC-SHA1 is the simplest method, but relies on the fact that you have to make absolutely sure the key is kept secret on both the sending and receiving side. As long as the secret key is confidential, messages are securely signed. However, this is virtually impossible when exchanging messages with untrusted disparate parties. The advantage of HMAC-SHA1 is the speed by which messages are signed and verified.<p> | |
| DSA-SHA1 and RSA-SHA1 rely on public key cryptography. In simplified terms, a message is signed using the (confidential!) private key. The public key is used to verify the signature. Since only the originating party could have used its private key to sign the message, the integrity of the message is guaranteed. Of course, we must trust the public key came from the originator (it is often included as an X509 certificate in the message). To this end, a trusted certificate authority should have signed the public key, thereby creating a X509 certificate that contains the public key and the identity of the message originator.<h3><a class="anchor" name="wsse_8_2a"> | |
| Signing Messages</a></h3> | |
| After the plugin is registered and a signature algorithm selected, the <a class="el" href="wsseapi_8h.html#a59">soap_wsse_sign</a> function or the <a class="el" href="wsseapi_8h.html#a60">soap_wsse_sign_body</a> function is used to initiate the signature engine to automatically sign outbound messages.<p> | |
| The code to sign the SOAP Body of a message using HMAC-SHA1 is:<p> | |
| <div class="fragment"><pre> <span class="keyword">static</span> <span class="keywordtype">char</span> hmac_key[16] = | |
| { 0xff, 0xee, 0xdd, 0xcc, 0xbb, 0xaa, 0x99, 0x88, | |
| 0x77, 0x66, 0x55, 0x44, 0x33, 0x22, 0x11, 0x00 }; | |
| <span class="keyword">struct </span>soap *soap = soap_new1(SOAP_XML_CANONICAL | SOAP_XML_INDENT); | |
| soap_register_plugin(soap, soap_wsse); | |
| <span class="keywordflow">if</span> (<a class="code" href="wsseapi_8c.html#a77">soap_wsse_sign_body</a>(soap, SOAP_SMD_HMAC_SHA1, hmac_key, <span class="keyword">sizeof</span>(hmac_key)) | |
| ... <span class="comment">// an error occurred</span> | |
| <span class="keywordflow">else</span> <span class="keywordflow">if</span> (soap_call_ns__myMethod(soap, ...)) | |
| ... <span class="comment">// a transmission error occurred</span> | |
| </pre></div><p> | |
| The hmac_key is some secret key you generated for the sending side and receiving side (don't use the one shown here).<p> | |
| As always, use soap_print_fault to display the error message.<p> | |
| To sign the body of an outbound SOAP message using RSA-SHA1 (DSA-SHA1 is similar), we include the X509 certificate with the public key as a BinarySecurityToken in the header and a KeyInfo reference to the token to let receivers use the public key in the certificate to verify the authenticity of the message:<p> | |
| <div class="fragment"><pre> FILE *fd; | |
| EVP_PKEY *rsa_private_key; | |
| X509 *cert; | |
| <span class="keyword">struct </span>soap *soap = soap_new1(SOAP_XML_CANONICAL | SOAP_XML_INDENT); | |
| soap_register_plugin(soap, soap_wsse); | |
| fd = fopen(<span class="stringliteral">"privkey.pem"</span>, <span class="stringliteral">"r"</span>); | |
| rsa_private_key = PEM_read_PrivateKey(fd, NULL, NULL, <span class="stringliteral">"password"</span>); | |
| fclose(fd); | |
| fd = fopen(<span class="stringliteral">"cert.pem"</span>, <span class="stringliteral">"r"</span>); | |
| X509 *cert = PEM_read_X509(fd, NULL, NULL, NULL); | |
| fclose(fd); | |
| <span class="keywordflow">if</span> (<a class="code" href="wsseapi_8c.html#a47">soap_wsse_add_BinarySecurityTokenX509</a>(soap, <span class="stringliteral">"X509Token"</span>, cert) | |
| || <a class="code" href="wsseapi_8c.html#a67">soap_wsse_add_KeyInfo_SecurityTokenReferenceX509</a>(soap, <span class="stringliteral">"#X509Token"</span>) | |
| || <a class="code" href="wsseapi_8c.html#a77">soap_wsse_sign_body</a>(soap, SOAP_SMD_SIGN_RSA_SHA1, rsa_private_key, 0)) | |
| ... <span class="comment">// an error occurred</span> | |
| <span class="keywordflow">else</span> <span class="keywordflow">if</span> (soap_call_ns__myMethod(soap, ...)) | |
| ... <span class="comment">// a transmission error occurred</span> | |
| </pre></div><p> | |
| The private key and its certificate are often placed in the same file, see e.g. server.pem in the package.<p> | |
| To summarize the signing process:<ol> | |
| <li>Register the wsse plugin.</li><li>Obtain an HMAC secret key or a DSA or RSA 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 <a class="el" href="wsseapi_8h.html#a59">soap_wsse_sign</a> or <a class="el" href="wsseapi_8h.html#a60">soap_wsse_sign_body</a> 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> | |
| <h3><a class="anchor" name="wsse_8_2b"> | |
| Signing Message Parts</a></h3> | |
| The <a class="el" href="wsseapi_8h.html#a60">soap_wsse_sign_body</a> function signs the entire SOAP body. If it is desirable to sign individual parts of a message the <a class="el" href="wsseapi_8h.html#a59">soap_wsse_sign</a> function should be used. Message parts with wsu:Id attributes are signed. These message parts should not be nested (nested elements will not be separately signed).<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> | |
| The gSOAP header file includes a myContract declaration:<p> | |
| <div class="fragment"><pre> <span class="keyword">struct </span>ns__myContract | |
| { @<span class="keywordtype">char</span>* wsu_Id = <span class="stringliteral">"Contract"</span>; | |
| <span class="keywordtype">char</span>* name; | |
| <span class="keywordtype">char</span>* title; | |
| <span class="keywordtype">char</span>* terms; | |
| }; | |
| <span class="keywordtype">int</span> ns__myMethod(<span class="keyword">struct</span> ns__myContract agreement, <span class="keywordtype">bool</span>* accepted); | |
| </pre></div><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"><pre> <span class="keyword">struct </span>ns__myContract contract; | |
| <span class="keywordtype">bool</span> accept; | |
| soap_default_ns__myContract(soap, &contract); | |
| contract.name = ...; | |
| contract.title = ...; | |
| contract.terms = ...; | |
| <span class="keywordflow">if</span> (<a class="code" href="wsseapi_8c.html#a47">soap_wsse_add_BinarySecurityTokenX509</a>(soap, <span class="stringliteral">"X509Token"</span>, cert) | |
| || <a class="code" href="wsseapi_8c.html#a67">soap_wsse_add_KeyInfo_SecurityTokenReferenceX509</a>(soap, <span class="stringliteral">"#X509Token"</span>) | |
| || <a class="code" href="wsseapi_8c.html#a76">soap_wsse_sign</a>(soap, SOAP_SMD_SIGN_RSA_SHA1, rsa_private_key, 0)) | |
| ... <span class="comment">// an error occurred</span> | |
| <span class="keywordflow">else</span> <span class="keywordflow">if</span> (soap_call_ns__myMethod(soap, contract, &accept)) | |
| ... <span class="comment">// a transmission error occurred</span> | |
| </pre></div><h3><a class="anchor" name="wsse_8_3"> | |
| Signing Tokens</a></h3> | |
| 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"><pre> <a class="code" href="wsseapi_8c.html#a38">soap_wsse_add_Timestamp</a>(soap, <span class="stringliteral">"Time"</span>, 600); | |
| <a class="code" href="wsseapi_8c.html#a42">soap_wsse_add_UsernameTokenDigest</a>(soap, <span class="stringliteral">"User"</span>, <span class="stringliteral">"username"</span>, <span class="stringliteral">"password"</span>); | |
| ... <span class="comment">// the rest of the signing code</span> | |
| </pre></div><h3><a class="anchor" name="wsse_8_4"> | |
| Signature Validation</a></h3> | |
| 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"><pre> <span class="keyword">struct </span>soap *soap = soap_new1(SOAP_XML_CANONICAL | SOAP_XML_INDENT); | |
| soap_register_plugin(soap, soap_wsse); | |
| <a class="code" href="wsseapi_8c.html#a79">soap_wsse_verify_auto</a>(soap, SOAP_SMD_NONE, NULL, 0); | |
| <span class="comment">// server:</span> | |
| <span class="keywordflow">if</span> (soap_serve(soap)) | |
| ... <span class="comment">// an error occurred</span> | |
| <span class="comment">// client:</span> | |
| <span class="keywordflow">if</span> (soap_call_ns__myMethod(soap, ...)) | |
| ... <span class="comment">// an error occurred</span> | |
| </pre></div><p> | |
| All locally referenced elements in the signed message will be verified. Elements referenced with absolute URIs 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> | |
| The <a class="el" href="wsseapi_8h.html#a62">soap_wsse_verify_auto</a> 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 <a class="el" href="wsseapi_8h.html#a63">soap_wsse_verify_done</a>.<p> | |
| To verify the HMAC signature of an inbound message, the HMAC key must be supplied:<p> | |
| <div class="fragment"><pre> <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> | |
| { 0xff, 0xee, 0xdd, 0xcc, 0xbb, 0xaa, 0x99, 0x88, | |
| 0x77, 0x66, 0x55, 0x44, 0x33, 0x22, 0x11, 0x00 }; | |
| <span class="keyword">struct </span>soap *soap = soap_new1(SOAP_XML_CANONICAL | SOAP_XML_INDENT); | |
| soap_register_plugin(soap, soap_wsse); | |
| <a class="code" href="wsseapi_8c.html#a79">soap_wsse_verify_auto</a>(soap, SOAP_SMD_HMAC_SHA1, hmac_key, <span class="keyword">sizeof</span>(hmac_key)); | |
| <span class="comment">// server:</span> | |
| <span class="keywordflow">if</span> (soap_serve(soap)) | |
| ... <span class="comment">// an error occurred</span> | |
| <span class="comment">// client:</span> | |
| <span class="keywordflow">if</span> (soap_call_ns__myMethod(soap, ...)) | |
| ... <span class="comment">// an error occurred</span> | |
| </pre></div><p> | |
| To summarize the signature verification process:<ol> | |
| <li>Register the wsse plugin.</li><li>For HMAC, obtain the HMAC secret key</li><li>Use <a class="el" href="wsseapi_8h.html#a62">soap_wsse_verify_auto</a> to verify inbound messages.</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 <a class="el" href="wsseapi_8h.html#a63">soap_wsse_verify_done</a> to terminate verification, e.g. to consume plain messages more efficiently.</li></ol> | |
| <h2><a class="anchor" name="wsse_9"> | |
| Encryption</a></h2> | |
| The material in this section relates to the WS-Security specification section 9.<p> | |
| TODO item: encryption support is under construction.<h2><a class="anchor" name="wsse_10"> | |
| Security Timestamps</a></h2> | |
| The material in this section relates to the WS-Security specification section 10.<p> | |
| To add a timestamp with the creation time to the Security header, use:<p> | |
| <div class="fragment"><pre> <a class="code" href="wsseapi_8c.html#a38">soap_wsse_add_Timestamp</a>(soap, NULL, 0); <span class="comment">// no expiration</span> | |
| </pre></div><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"><pre> <a class="code" href="wsseapi_8c.html#a38">soap_wsse_add_Timestamp</a>(soap, NULL, 10); <span class="comment">// 10 seconds lifetime</span> | |
| </pre></div><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"><pre> <a class="code" href="wsseapi_8c.html#a38">soap_wsse_add_Timestamp</a>(soap, <span class="stringliteral">"Time"</span>, 10); <span class="comment">// timestamp will be signed</span> | |
| </pre></div><hr size="1"><address style="align: right;"><small>Generated on Fri Aug 19 10:41:46 2005 for gSOAP WS-Security by | |
| <a href="http://www.doxygen.org/index.html"> | |
| <img src="doxygen.png" alt="doxygen" align="middle" border=0 ></a> 1.3.8 </small></address> | |
| </body> | |
| </html> |