The material in this section relates to the WS-Security specification section 5.
To use the wsse lite API:
If HTTPS is required with OpenSSL then please follow the instructions in Section WS-Security and HTTPS to ensure thread-safety of WS-Security with HTTPS.
The wsse lite API is located in:
You will also need:
gsoap/custom/struct_timeval.ccompile and link this file (C and C++).
-DWITH_OPENSSLto enable HTTPS.
-lssl -lcrypto -lz -gsoapssl++(or
-lgsoapsslfor C, or compile
stdsoap2.cppfor C++ and
The gSOAP header file for soapcpp2 should import wsse.h (or the older 2002 version wsse2.h):
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.
The wsse lite 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:
The basic API is introduced below.
To add an empty Security header block to the SOAP header, use:
To delete a Security header, use:
Adding an empty Security header block is not very useful. In the following, we present the higher-level functions of the wsse lite API to populate and verify Security header content.
To populate the SOAP-ENV:actor or SOAP-ENV:role attribute within the Security header, use:
To obtain the actor or role value (e.g. after receiving a message), use:
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.
Security header blocks are attached to the soap context, which means that the information will be automatically kept to support multiple invocations.
The material in this section relates to the WS-Security specification section 6.
To add a user name token to the Security header block, use:
Id value is optional and not used in the wsse lite API. These
Ids are serialized as wsu:Id identifiers for cross-referencing XML elements.
To add a user name token with clear text password, use:
It is strongly recommended to use
soap_wsse_add_UsernameTokenText only in combination with HTTPS encrypted transmission or not at all. A better alternative is to use password digests (not supported in this wsse lite API).
Clear-text passwords are verified with
soap_wsse_verify_Password. To verify a password at the receiving side to authorize a request (e.g. within a Web service operation), use:
Note that the
soap_wsse_get_Username functions sets the wsse:FailedAuthentication fault upon failure. It is common for the API functions 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
The material in this section relates to the WS-Security specification section 10.
To add a timestamp with the creation time to the Security header, use:
The lifetime of a message (in seconds) is passed as the third argument, which will be displayed as the timestamp expiration time:
HTTPS is used at the client side with the usual "https:" URL addressing, shown here:
With OpenSSL, the CRYPTO threads should be set up before any threads are created.
soap_ssl_client_context only needs to be set up once. Use the following flags:
SOAP_SSL_DEFAULTrequires server authentication, CA certs should be used
SOAP_SSL_NO_AUTHENTICATIONdisables server authentication
SOAP_SSL_SKIP_HOST_CHECKdisables server authentication host check
SOAP_SSL_ALLOW_EXPIRED_CERTIFICATEto accept self-signed certificates, expired certificates, and certificates without CRL.
The server uses the following:
where we define a process_request function that is executed by the thread to process the request (on a copy of the soap context struct):
soap_ssl_server_context only needs to be set up once. Use the following flags:
SOAP_SSL_DEFAULTrequires server authentication, but no client authentication
SOAP_SSL_REQUIRE_CLIENT_AUTHENTICATIONrequires client authentication
With OpenSSL, we need to define the thread set up and clean up operations as follows:
For additional details and examples, see the user guide and examples in the gSOAP package directory