The HTTP-DA plugin

Table of Contents

• Introduction
• Client-side usage
• Client example
• Server-side usage
• Server example
• Limitations

Introduction

The upgraded HTTP digest authentication plugin for gSOAP adds support for the RFC7616 draft that is backwards compatible with RFC2617. The new plugin adds SHA-256 (and SHA-512/256 when OpenSSL supports it) algorithms, including the -sess variants. To maintain backwards compatibility with RFC2617 the MD5 algorithm is still supported but not recommended.

HTTP digest authentication does not transmit the user id and password for authentication. Instead, a server negotiates credentials (username and/or password) with a client using cryptographic hashing algorithms with nonce values to prevent replay attacks.

By contrast, HTTP basic authentication is not safe over unencrypted channels because the password is transmitted to the server unencrypted. Therefore, this mechanism provides no confidentiality protection for the transmitted credentials. HTTPS is typically preferred over or used in conjunction with HTTP basic authentication.

To support HTTP digest authentication in favor of HTTP basic authentication, you will need to install OpenSSL and follow these steps to build your projects:

• Compile your project that uses gSOAP source code with -DWITH_OPENSSL.
• Link libgsoapssl (libgsoapssl++), or use the stdsoap2.c[pp] source.
• Compile and link your code together with plugin/httpda.c, plugin/smdevp.c, and plugin/threads.c

The plugin is MT-safe by means of internal mutex locks. Mutex ensures exclusive access and updates of the shared session store with nonces to prevent replay attacks.

Client-side usage

HTTP basic authentication is the default authentication mechanism supported by gSOAP. You can set the basic authentication credentials at the client-side with:

soap.userid = "<userid>";
soap.passed = "<passwd>";
if (soap_call_ns__method(&soap, ...))
  ... // error

or if you use a proxy object generated with saopcpp2 option -j:

Proxy proxy(...);
proxy.soap->userid = "<userid>";
proxy.soap->passed = "<passwd>";
if (proxy.method(...))
  ... // error

HTTP basic authentication should never be used over plain HTTP, because the credentials (the ID and password) are transmitted in the clear in base64 encoded form which is easily reversible. This mechanism is safer to use over HTTPS, because the HTTP headers and body are encrypted.

This upgraded HTTP digest authentication plugin supports RFC7616 and RFC2617. RFC7616 adds SHA2 and is backwards compatible to clients that use MD5. The MD5 algorithm is not allowed in FIPS making SHA-256 or SHA-512-256 digest algorithms mandatory. The client-side of the plugin handles both RFCs automatically.

To use HTTP digest authentication with gSOAP, register the http_da plugin as follows:

#include "httpda.h"
struct soap *soap = soap_new();
soap_register_plugin(soap, http_da);
...
soap_destroy(soap); // deallocate data
soap_end(soap);     // deallocate temp data
soap_free(soap);    // deregister plugin and deallocate context

or if you use a proxy object generated with saopcpp2 option -j:

#include "httpda.h"
Proxy proxy(...);
soap_register_plugin(proxy.soap, http_da);
...
proxy.destroy(); // deallocate data and temps

To make a client-side service call you will need to create a digest store http_da_info. The store holds the digest information locally on your machine to manage repeated authentication challenges from all servers you connect to. Use http_da_save() to add credentials to the store and release the store with http_da_release() when you no longer need the credentials.

The http_da_info store is intended for one thread to issue a sequence of calls that are all authenticated without requiring (re)negotiation. You should not share the http_da_info store with multiple threads, unless you use mutex locks.

Here is an example:

struct soap *soap = soap_new();
soap_register_plugin(soap, http_da);
struct http_da_info info;

if (soap_call_ns__method(soap, ...)) // make a call without authentication
{
  if (soap.error == 401) // HTTP authentication is required
  {
    http_da_save(soap, &info, "<authrealm>", "<userid>", "<passwd>");
    if (soap_call_ns__method(soap, ...)) // make a call with authentication
      ... // error
    http_da_release(soap, &info); // release if auth is no longer needed
  }
  else
    ... // other error
}

soap_destroy(soap);
soap_end(soap);
soap_free(soap);

Again, if you use a proxy object then replace the soap_call_ns__method with the proxy method invocation, as was shown earlier.

The <authrealm> string is the protected realm of the server that requires authorization. This string can be obtained with the soap.authrealm string after an unsuccessful non-authenticated call so you can use it to save credentials to the digest store:

struct soap *soap = soap_new();
soap_register_plugin(soap, http_da);
struct http_da_info info;

if (soap_call_ns__method(soap, ...)) // make a call without authentication
{
  if (soap.error == 401) // HTTP authentication is required
  {
    const char *realm = soap.authrealm;
    http_da_save(soap, &info, realm, "<userid>", "<passwd>");
    if (soap_call_ns__method(soap, ...)) // make a call with authentication
      ... // error
    ...
    http_da_release(soap, &info); // deallocate authentication info if auth is no longer needed
  }
  else
    ... // error
}

soap_destroy(soap);
soap_end(soap);
soap_free(soap);

Before a second call is made to the same endpoint that requires authentication, you must restore the authentication state with http_da_restore(), then use it, and finally release it with http_da_release():

struct soap *soap = soap_new();
soap_register_plugin(soap, http_da);
struct http_da_info info;
bool auth = false;

if (soap_call_ns__method(soap, ...)) // make a call without authentication
{
  if (soap.error == 401) // HTTP authentication is required
  {
    http_da_save(soap, &info, "<authrealm>", "<userid>", "<passwd>");
    auth = true;
  }
  else
    ... // other error
}

if (auth)
  http_da_restore(soap, &info);
if (soap_call_ns__method(soap, ...)) // make a call with authentication
  ... // error

soap_destroy(soap); // okay to dealloc data
soap_end(soap);     // okay to dealloc data

if (auth)
  http_da_restore(soap, &info);
if (soap_call_ns__method(soap, ...)) // make a call with authentication
  ... // error

if (auth)
  http_da_release(soap, &info); // deallocate authentication info

soap_destroy(soap);
soap_end(soap);
soap_free(soap);

For HTTP proxies requiring HTTP digest authenticaiton, use the 'proxy' functions of the plugin:

struct soap *soap = soap_new();
soap_register_plugin(soap, http_da);
struct http_da_info info;

if (soap_call_ns__method(soap, ...)) // make a call without authentication
{
  if (soap.error == 407) // HTTP proxy authentication is required
  {
    http_da_proxy_save(soap, &info, "<authrealm>", "<userid>", "<passwd>");
    auth = true;
  }
  else
    ... // error
}

if (auth)
  http_da_proxy_restore(soap, &info);
if (soap_call_ns__method(soap, ...))
  ... // error

http_da_proxy_release(soap, &info); // deallocate authentication info

soap_destroy(soap);
soap_end(soap);
soap_free(soap);

Client example

A client authenticating against a server:

struct soap *soap = soap_new();
soap_register_plugin(soap, http_da);

if (soap_call_ns__method(soap, ...)) // make a call without authentication
{
  if (soap.error == 401) // HTTP authentication is required
  {
    if (!strcmp(soap.authrealm, authrealm)) // check authentication realm
    {
      struct http_da_info info; // to store userid and passwd
      http_da_save(soap, &info, authrealm, userid, passwd);
      // call again, now with credentials
      if (soap_call_ns__method(soap, ...) == SOAP_OK)
      {
        ... // process response data
        soap_end(soap);
        ... // userid and passwd were deallocated (!)
        http_da_restore(soap, &info); // get userid and passwd after soap_end()
        if (!soap_call_ns__method(soap, ...) == SOAP_OK)
          ... // error
        http_da_release(soap, &info); // deallocate authentication info

A client authenticating against a proxy:

struct soap *soap = soap_new();
soap_register_plugin(soap, http_da);

if (soap_call_ns__method(soap, ...))  // make a call without authentication
{
  if (soap.error == 407) // HTTP authentication is required
  {
    if (!strcmp(soap.authrealm, authrealm)) // check authentication realm
    {
      struct http_da_info info; // to store userid and passwd
      http_da_proxy_save(soap, &info, authrealm, userid, passwd);
      // call again, now with credentials
      if (soap_call_ns__method(soap, ...) == SOAP_OK)
      {
        ... // process response data
        soap_end(soap);
        ... // userid and passwd were deallocated (!)
        http_da_proxy_restore(soap, &info); // get userid and passwd after soap_end()
        if (!soap_call_ns__method(soap, ...) == SOAP_OK)
          ... // error
        http_da_proxy_release(soap, &info); // deallocate authentication info

Server-side usage

As explained in the gSOAP user guid, server-side HTTP basic authentication is enforced by simply checking the soap.userid and soap.passwd values in a service method that requires client authentication:

struct soap *soap = soap_new();
soap_register_plugin(soap, http_da);
...
soap_serve(soap); // see gSOAP documentation and examples on how to serve requests
...

int ns__method(struct soap *soap, ...)
{
  if (!soap->userid || !soap->passwd || strcmp(soap->userid,