|  | Home | Documentation | The HTTP-DA plugin updated by Robert van Engelen |

The HTTP-DA plugin

# 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
httpda.h
http_da
SOAP_FMAC1 int SOAP_FMAC2 http_da(struct soap *soap, struct soap_plugin *p, void *arg)
Definition httpda.c:548

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);
http_da_save
SOAP_FMAC1 void SOAP_FMAC2 http_da_save(struct soap *soap, struct http_da_info *info, const char *realm, const char *userid, const char *passwd)
Saves the credentials to the digest store to use repeatedly for authentication.
Definition httpda.c:1098
http_da_release
SOAP_FMAC1 void SOAP_FMAC2 http_da_release(struct soap *soap, struct http_da_info *info)
Releases the digest store and frees memory.
Definition httpda.c:1203
http_da_info
Used to save and restore credentials for client-side invocations to the same authenticated endpoint.
Definition httpda.h:136

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);
http_da_restore
SOAP_FMAC1 void SOAP_FMAC2 http_da_restore(struct soap *soap, struct http_da_info *info)
Retrieves the credentials from the digest store to use for authentication.
Definition httpda.c:1155

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);
http_da_proxy_release
SOAP_FMAC1 void SOAP_FMAC2 http_da_proxy_release(struct soap *soap, struct http_da_info *info)
Releases the digest store for proxy authentication and frees memory.
Definition httpda.c:1265
http_da_proxy_save
SOAP_FMAC1 void SOAP_FMAC2 http_da_proxy_save(struct soap *soap, struct http_da_info *info, const char *realm, const char *userid, const char *passwd)
Saves the credentials to the digest store to use repeatedly for proxy authentication.
Definition httpda.c:1128
http_da_proxy_restore
SOAP_FMAC1 void SOAP_FMAC2 http_da_proxy_restore(struct soap *soap, struct http_da_info *info)
Retrieves the credentials from the digest store to use for proxy authentication.
Definition httpda.c:1179

# 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
http_da_info::authrealm
char * authrealm
Definition httpda.h:137
http_da_info::userid
char * userid
Definition httpda.h:138
http_da_info::passwd
char * passwd
Definition httpda.h:139

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, "<userid>") || strcmp(soap->passwd, "<passwd>"))
return 401; // HTTP authentication required
...
}

HTTP digest authentication is verified differently, because digests are compared, not passwords:

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->authrealm && soap->userid)
{
passwd = ... // database lookup on userid and authrealm to find passwd
if (!strcmp(soap->authrealm, authrealm) && !strcmp(soap->userid, userid))
{
if (!http_da_verify_post(soap, passwd)) // HTTP POST DA verification
{
... // process request and produce response
return SOAP_OK;
}
}
}
soap->authrealm = authrealm; // realm to send to client
return 401; // Not authorized, challenge with digest authentication
http_da_verify_post
SOAP_FMAC1 int SOAP_FMAC2 http_da_verify_post(struct soap *soap, const char *passwd)
Verifies the password credentials at the server side when used in an HTTP POST service operation.
Definition httpda.c:1288

The http_da_verify_post() function checks the HTTP POST credentials by computing and comparing a digest of the password. The HTTP POST method is used for two-way SOAP/XML communications with request and response messages. One-way SOAP/XML messaging may use HTTP POST or HTTP GET. To verify an HTTP GET operation, use http_da_verify_get() instead, for example in the HTTP GET handler implemented with the HTTP GET plugin. Likewise, use http_da_verify_put() for HTTP PUT, http_da_verify_patch() for HTTP PATCH, and http_da_verify_del() for HTTP DELETE. To verify other HTTP methods, use the http_da_verify_method() function with the method as a string argument, for example:

if (!http_da_verify_method(soap, "HEAD", passwd))
{
... // process the request
}
http_da_verify_method
SOAP_FMAC1 int SOAP_FMAC2 http_da_verify_method(struct soap *soap, const char *method, const char *passwd)
Verifies the password credentials at the server side when used in the specified HTTP method.
Definition httpda.c:1369

Server-side operations that handle other methods than HTTP POST and GET, such as PATCH, PUT, and DELETE should be implemented with the HTTP POST plugin. This plugin uses a dispatch table with a handler corresponding to the HTTP method to serve.

RFC7616 recommends SHA2 over MD5. MD5 is not secure. The MD5 algorithm is not allowed in FIPS and SHA-256 or SHA-512-256 are mandatory. This upgraded HTTP digest plugin uses SHA-256 as the default algorithm and reverts to MD5 only if required by a client that does not support RFC7616.

The default SHA-256 digest algorithm is enabled automatically. However, at the server side you can also use a plugin registry option to set a different algorithm as the default:

soap_register_plugin_arg(soap, http_da, <option>);

where <option> is one of:

- http_da_md5() MD5 (not recommended).
- http_da_md5_sess() MD5-sess (not recommended).
- http_da_sha256() SHA-256 (recommended).
- http_da_sha256_sess() SHA-256-sess (recommended).
- http_da_sha512_256() SHA-512-256 (not yet supported).
- http_da_sha512_256_sess() SHA-512-256-sess (not yet supported).

When non-MD5 option is selected, the server will present that digest algorithm together with the MD5 authentication algorithm as challenge to the client. If the client is upgraded to RFC7616 it selects the newer protocol. If the client is not upgraded it will select the older MD5-based protocol.

To revert to RFC2617 use http_da_md5() (not recommended).

# Server example

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) // Basic authentication
{
if (!strcmp(soap->userid, userid) && !strcmp(soap->passwd, passwd))
{
... // can also check soap->authrealm
... // process request and produce response
return SOAP_OK;
}
}
else if (soap->authrealm && soap->userid) // Digest authentication
{
passwd = ... // database lookup on userid and authrealm to find passwd
if (!strcmp(soap->authrealm, authrealm) && !strcmp(soap->userid, userid))
{
if (!http_da_verify_post(soap, passwd)) // HTTP POST DA verification
{
... // process request and produce response
return SOAP_OK;
}
}
}
soap->authrealm = authrealm; // realm to send to client
return 401; // Not authorized, challenge with digest authentication
}

# Limitations

HTTP digest authentication cannot be used with streaming MTOM/MIME/DIME attachments. Non-streaming MTOM/MIME/DIME attachments are handled just fine. MTOM/MIM/DIME attachment streaming is automatically turned off by the plugin and attachment data is buffered rather than streamed.