Genivia - The WS-Addressing Plugin

|  | Home | Documentation | The WS-Addressing Plugin updated Thu Mar 21 2024 by Robert van Engelen |

- Main Page
- Related Pages
- Classes
- Files

The WS-Addressing Plugin

# WS-Addressing Setup

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

To use the wsa plugin:

1. Run wsdl2h -t typemap.dat on a WSDL of a service that requires WS-Addressing headers. The typemap.dat file included in the gSOAP package is used to recognize and translate Addressing header blocks.
2. Run soapcpp2 -a on the header file produced by wsdl2h. To enable addressing-based service operation selection, you MUST use soapcpp2 option -a. This allows the service to dispatch methods based on the WS-Addressing action information header value (when the wsa plugin is registered).
3. (Re-)compile and link stdsoap2.c/pp or libgsoap, (dom.c/pp when needed), wsaapi.c and the soapcpp2-generated source files.
4. Use the wsa plugin API functions described below.

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

A gSOAP service definitions header file with a `#import "wsa.h"` to support WS-Addressing is automatically generated by wsdl2h for a set of WSDLs that use WS-Addressing. The wsdl2h-generated header file should be further processed by soapcpp2 to generate the binding code. The wsaapi.h and wsaapi.c implement the WS-Addressing API described in this document.

A wsdl2h-generated service definitions header file might include the following imports:

#import "soap12.h"
#import "wsa.h" // or wsa3.h (2003/03), wsa4.h (2004/03), wsa5.h (2005/03)

The wsa.h header file is imported from import/wsa.h when soapcpp2 is run on this file. The wsa.h import can be manually added to enable WS-Addressing when needed. The gSOAP service definitions header file is processed with soapcpp2 to generate the client-side and/or server-side binding code.

Note that the wsa.h, wsa3.h, wsa4.h, and wsa5.h header files are located in the import directory of the gSOAP package. These files define the WS-Addressing information header elements and types. The soap12.h header file enables SOAP 1.2 messaging.

For developers: the WS-Addressing header blocks in wsa.h (and others) were generated from the WS-Addressing schema with the wsdl2h tool and WS/WS-typemap.dat as follows:

    wsdl2h -cegy -o wsa.h -t WS/WS-typemap.dat WS/WS-Addressing.xsd

Refer to wsa.h for more details.

# Client-side Usage

## Constructing WS-Addressing Information Headers

To associate WS-Addressing information headers with service operations, the SOAP Header struct `SOAP_ENV__Header` must have been defined and for each service operation that uses WS-Addressing method-header-part directives should be used in the gSOAP service definitions header file as follows:

#import "wsa.h"
//gsoap ns service method-header-part: example wsa__MessageID
//gsoap ns service method-header-part: example wsa__RelatesTo
//gsoap ns service method-header-part: example wsa__From
//gsoap ns service method-header-part: example wsa__ReplyTo
//gsoap ns service method-header-part: example wsa__FaultTo
//gsoap ns service method-header-part: example wsa__To
//gsoap ns service method-header-part: example wsa__Action
//gsoap ns service method-action: example urn:example/examplePort/example
int ns__example(char *in, struct ns__exampleResponse *out);

Note that the use of wsa versions determines the wsa prefix, e.g. use `wsa5` for the latest WS-Addressing as in `wsa5__MessageID`.

In the client-side code, the WS-Addressing information headers are set with `soap_wsa_request` by passing an optional message UUID string, a mandatory destination address URI string, and a mandatory request action URI string. The wsa plugin should be registered with the current soap struct context. An optional source address information header can be added with `soap_wsa_add_From` (must be invoked after the `soap_wsa_request` call).

For example:

#include "wsaapi.h"
soap_register_plugin(soap, soap_wsa);
if (soap_wsa_request(soap, RequestMessageID, ToAddress, RequestAction))
|| soap_wsa_add_From(soap, FromAddress)) // optional: add a 'From' address
... // error: out of memory
if (soap_call_ns__example(soap, ToAddress, NULL, ...))
soap_print_fault(soap, stderr); // an error occurred
else
// process the response

To generate a UUID for the RequestMessageID, use:

const char *RequestMessageID = soap_wsa_rand_uuid(soap);

## Information Headers for Relaying Server Responses

To relay the response to another destination, the WS-Addressing ReplyTo information header is added with `soap_wsa_add_ReplyTo` by passing a reply address URI string. The service returns "HTTP 200 OK" or "HTTP 202 ACCEPTED" to the client when the response message relay was successful.

For example:

#include "wsaapi.h"
soap_register_plugin(soap, soap_wsa);
if (soap_wsa_request(soap, RequestMessageID, ToAddress, RequestAction)
|| soap_wsa_add_From(soap, FromAddress) // optional: add a 'From' address
|| soap_wsa_add_ReplyTo(soap, ReplyToAddress))
... // error: out of memory
if (soap_call_ns__example(soap, ToAddress, NULL, ...))
{
if (soap->error == 200 || soap->error == 202) // HTTP OK or ACCEPTED
printf("Request was accepted and results were forwarded\n");
else
soap_print_fault(soap, stderr); // an error occurred
}
else
// unexpected OK: for some reason the response was not relayed

Note: the response message will be relayed when the From address is absent or different than the ReplyTo address

## Information Headers for Relaying Server Faults

To relay a server fault message to another destination, the WS-Addressing FaultTo information header is added with `soap_wsa_add_FaultTo` by passing a relay address URI string. The service returns "HTTP 200 OK" or "HTTP 202 ACCEPTED" to the client when the fault was relayed.

For example:

#include "wsaapi.h"
soap_register_plugin(soap, soap_wsa);
if (soap_wsa_request(soap, RequestMessageID, ToAddress, RequestAction)
|| soap_wsa_add_From(soap, FromAddress) // optional: add a 'From' address
|| soap_wsa_add_FaultTo(soap, FaultToAddress))
... // error: out of memory
if (soap_call_ns__example(soap, ToAddress, NULL, ...))
{
if (soap->error == 200 || soap->error == 202) // HTTP OK or ACCEPTED
printf("A fault occurred and the fault details were forwarded\n");
else
soap_print_fault(soap, stderr); // a connection error occurred
}
else
... // process response

Note that the call can still return a fault, such as a connection error when the service is not responding. In addition to the fault relay, the responses can be relayed with `soap_wsa_add_ReplyTo`.

## Error Handling

SOAP and HTTP errors set the soap->error attribute, as shown in this example:

if (soap_call_ns__example(soap, ToAddress, NULL, ...))
{
if (soap->error == 200 || soap->error == 202) // HTTP OK or ACCEPTED
printf("A fault occurred and the fault details were forwarded\n");
else
soap_print_fault(soap, stderr); // a connection error occurred
}
else
... // process response

When a WS-Addressing error occurred, the wsa error code is stored in the SOAP Fault Subcode field. This information can be retrieved with:

wsa__FaultSubcodeValues fault;
if (soap_wsa_check_fault(soap, &fault))
{
switch (fault)
{
case wsa__InvalidMessageInformationHeader: ...
case wsa__MessageInformationHeaderRequired: ...
case wsa__DestinationUreachable: ...
case wsa__ActionNotSupported: ...
case wsa__EndpointUnavailable: ...
}
}

When using wsa5.h, please refer to the standards and fault codes for this implementation. For the wsa5.h 2005/03 standard, several faults have an additional parameter (SOAP Fault detail):

wsa5__FaultCodesType fault;
char *info;
if (soap_wsa_check_fault(soap, &fault, &info))
{
switch (fault)
{
case wsa5__InvalidAddressingHeader:
if (info)
printf("The invalid addressing header element is %s\n", info);
...
}
}

## Combining WS-Addressing with WS-Security

WS-Security can be combined with WS-Addressing. To sign WS-Addressing header blocks, use the `soap_wsse_set_wsu_id` WSSE-plugin call to set the wsu:Id attribute and signing of these attributed elements. For example, suppose we use WS-Addressing 2005 headers (which are activated with an `#import "wsa5.h"` in the header file for soapcpp2):

#include "wsaapi.h"
#include "wsseapi.h"
soap_register_plugin(soap, soap_wsa);
soap_register_plugin(soap, soap_wsse);
soap_wsse_set_wsu_id(soap, "wsa5:From wsa5:To wsa5:ReplyTo wsa5:FaultTo wsa5:Action wsa5:MessageID");
if (soap_wsa_request(soap, RequestMessageID, ToAddress, RequestAction)
|| soap_wsa_add_From(soap, FromAddress) // optional: add a 'From' address
|| soap_wsa_add_FaultTo(soap, FaultToAddress))
... // error: out of memory
if (soap_call_ns__example(soap, ToAddress, NULL, ...))
... // error

If your are using WS-Addressing 2004 (which is activated with an `#import "wsa.h"` in the header file for soapcpp2) then change one line:

soap_wsse_set_wsu_id(soap, "wsa:From wsa:To wsa:ReplyTo wsa:FaultTo wsa:Action wsa:MessageID");

Note: `soap_wsse_set_wsu_id` should only be set once. Each new call overrides the previous.

For more details on WS-Security, please see the WS-Security plugin documentation.

# Server-side Usage

The wsa plugin should be registered with:

soap_register_plugin(soap, soap_wsa);

Once the plugin is registered, the `soap_bind`, `soap_accept`, and `soap_serve` functions can be called to process requests and semi-automatically handle the WS-Addressing header blocks.

Important: to dispatch service operations based on the WS-Addressing wsa:Action information header, you must use soapcpp2 option `-a`. The generates a new dispatcher (in soapServer.c) based on the action value.

A service operation implementation should use `soap_wsa_check` at the start of its execution to verify the validity of the WS-Addressing information headers in the SOAP request message. To allow response message to be automatically relayed based on the ReplyTo information header, the service operation should return `soap_wsa_reply` with an optional message UUID string and a mandatory response action string. The response action string is documented in the wsdl2h-generated .h file for this service operation.

For example:

int ns__example(struct soap *soap, char *in, struct ns__exampleResponse *out)
{
if (soap_wsa_check(soap))
return soap->error;
// ... service logic
return soap_wsa_reply(soap, ResponseMessageID, ResponseAction);
}

To return a SOAP fault that is automatically relayed to a fault service based on the FaultTo information header, the `soap_wsa_sender_fault`, `soap_wsa_receiver_fault`, `soap_wsa_sender_fault_subcode`, and `soap_wsa_receiver_fault_subcode` functions should be used instead of the usual `soap_sender_fault`, `soap_receiver_fault`, `soap_sender_fault_subcode`, and `soap_receiver_fault_subcode`, respectively:

In case a Action must be associated with a SOAP Fault, use the `soap_wsa_sender_fault_subcode_action` and `soap_wsa_receiver_fault_subcode_action` functions to set the WS-Addressing Action (and HTTP SOAP Action header as well).

For example, the following service operation illustrates the use of `soap_wsa_check` to verify and process WS-Addressing header blocks and `soap_wsa_reply` to enable responses to be relayed as per ReplyTo address in the WS-Addressing header:

int ns__example(struct soap *soap, char *in, struct ns__exampleResponse *out)
{
if (soap_wsa_check(soap))
return soap->error;
// ... service logic
// ... an error occurred, need to return fault possibly to fault service:
return soap_wsa_sender_fault(soap, "Exception in service operation", NULL);
// ... normal execution continues
return soap_wsa_reply(soap, ResponseMessageID, ResponseAction);
}

# HTTPS Server-side Usage

To enable HTTPS (SSL/TSL) servers, compile the sources with -DWITH_OPENSSL (and link with libgsoapssl, libssl, and libcrypto). Because WS-Addressing may relay messages over HTTPS as a sender (client), you must initialize the SSL context for server and client uses. Therefore, the context must have access to all the certificates need to verify the authenticity of the ReplyTo and FaultTo HTTPS servers. To do so, use the following SSL initialization before `soap_bind`:

struct soap *soap = soap_new();
if (soap_ssl_server_context(soap,
SOAP_SSL_DEFAULT,
"server.pem", // the keyfile (server should authenticate)
"password", // password to read the key file
"cacert.pem", // cacert file to store trusted certificates (role as client)
NULL, // optional capath
NULL, // DH file name or DH param key len bits, when NULL use RSA
NULL, // file with random data to seed randomness
"myserver" // unique server identification for SSL session cache
))
{
soap_print_fault(soap, stderr);
...
}
soap->bind_flags = SO_REUSEADDR;
if (!soap_valid_socket(soap_bind(soap, NULL, port, 100)))
{
soap_print_fault(soap, stderr);
...
}

# Implementing a Server for Handling ReplyTo Response Messages

To implement a separate server for handling relayed SOAP response messages based on the ReplyTo information header in the request message, the gSOAP header file should include a one-way service operation for the response message. These one-way response service operations are automatically generated with wsdl2h option `-b`.

For example, suppose a service operation returns an exampleResponse message. We declare the one-way exampleResponse operation as follows:

#import "wsa.h"
//gsoap ns service method-header-part: exampleResult wsa__MessageID
//gsoap ns service method-header-part: exampleResult wsa__RelatesTo
//gsoap ns service method-header-part: exampleResult wsa__From
//gsoap ns service method-header-part: exampleResult wsa__ReplyTo
//gsoap ns service method-header-part: exampleResult wsa__FaultTo
//gsoap ns service method-header-part: exampleResult wsa__To
//gsoap ns service method-header-part: exampleResult wsa__Action
//gsoap ns service method-action: exampleResult urn:example/examplePort/exampleResponse
int ns__exampleResponse(char *out, void);

Note that the action information is important, because it is used by the service dispatcher (assuming soapcpp2 option `-a` is used).

The implementation in the server code uses soap_wsa_check() to check the presense and validity of the WS-Addressing information header in the message. The `soap_send_empty_response` function should be used to return an acknowledgment HTTP header with "HTTP 202 ACCEPTED" to the sender:

int ns__exampleResponse(struct soap *soap, char *out)
{
if (soap_wsa_check(soap))
return soap_send_empty_response(soap, 500); // HTTP 500 Internal Server Error
// ... service logic
return soap_send_empty_response(soap, SOAP_OK); // HTTP 202 ACCEPTED
}

# Implementing a Server for Handling FaultTo Fault Messages

To implement a separate server for handling relayed SOAP fault messages based on the FaultTo information header in the request message, the gSOAP header file for soapcpp2 should include a SOAP fault service operation. This operation accepts fault messages that are relayed by other services.

Basically, we use a trick to generate the SOAP-ENV:Fault struct via a one-way service operation. This allows us both to implement a one-way service operation that accepts faults and to automatically generate the fault struct for fault data storage and manipulation.

The fault operation in the WS-Addressing files (wsa5.h etc.) is declared as follows (here shown for the 2004/08 standard):

//gsoap SOAP_ENV service method-action: Fault http://schemas.xmlsoap.org/ws/2004/08/addressing/fault
int SOAP_ENV__Fault
(
_QName faultcode, // SOAP 1.1
char *faultstring, // SOAP 1.1
char *faultactor, // SOAP 1.1
struct SOAP_ENV__Detail *detail, // SOAP 1.1
struct SOAP_ENV__Code *SOAP_ENV__Code, // SOAP 1.2
struct SOAP_ENV__Reason *SOAP_ENV__Reason, // SOAP 1.2
char *SOAP_ENV__Node, // SOAP 1.2
char *SOAP_ENV__Role, // SOAP 1.2
struct SOAP_ENV__Detail *SOAP_ENV__Detail, // SOAP 1.2
void
);

Because each service operation has a struct to hold its input parameters, we automatically generate the (original) `SOAP_ENV__Fault` struct on the fly!

It is important to associate the wsa fault action with this operation as shown above.

The implementation of the Fault service operation in your server code should be similar to:

int SOAP_ENV__Fault(struct soap *soap, char *faultcode, char *faultstring, char *faultactor, struct SOAP_ENV__Detail *detail, struct SOAP_ENV__Code *SOAP_ENV__Code, struct SOAP_ENV__Reason *SOAP_ENV__Reason, char *SOAP_ENV__Node, char *SOAP_ENV__Role, struct SOAP_ENV__Detail *SOAP_ENV__Detail)
{
... = faultcode; // SOAP 1.1 fault code string (QName)
... = faultstring; // SOAP 1.1 fault string
... = faultactor; // SOAP 1.1 fault actor string
... = detail; // SOAP 1.1 fault detail struct
... = SOAP_ENV__Code; // SOAP 1.2 fault code struct
... = SOAP_ENV__Reason; // SOAP 1.2 reason struct
... = SOAP_ENV__Node; // SOAP 1.2 node string
... = SOAP_ENV__Role; // SOAP 1.2 role string
... = SOAP_ENV__Detail; // SOAP 1.2 detail struct
return SOAP_OK;
}

Note that SOAP 1.1 or SOAP 1.2 parameters are set based on the 1.1/1.2 messaging requirements.

# Using the WS-Addressing plugin with the Apache gSOAP module

The WS-Addressing plugin may be used with the Apache `mod_gsoap` module. The server-side logic is the same. However, registering the WS-Addressing plugin requires a parameter `SOAP_WSA_NEW_TRANSFER`:

#include "plugin/wsaapi.h"
#include "apache_gsoap.h"
void mod_gsoap_init(struct soap *soap, request_rec *r)
{
soap_register_plugin_arg(soap, http_wsa, SOAP_WSA_NEW_TRANSFER)
}
IMPLEMENT_GSOAP_SERVER_INIT(mod_gsoap_init)