Web Service Security
[cSOAP]

Modules
	XML-security errors
Defines
#define	SOAP_SECURITY_NAMESPACE   "http://schemas.xmlsoap.org/soap/security/2000-12"
#define	SOAP_SECURITY_PREFIX   "SOAP-SEC"
#define	CSOAP_ENABLE_XMLSEC   "-CSOAPxmlsec"
#define	CSOAP_XMLSEC_KEYFILE   "-CSOAPkeyfile"
#define	CSOAP_XMLSEC_PASSWORD   "-CSOAPpassword"
#define	CSOAP_XMLSEC_CERTFILE   "-CSOAPcertfile"
Functions
herror_t	soap_xmlsec_server_init_args (int argc, char **argv)
herror_t	soap_xmlsec_client_init_args (int argc, char **argv)
herror_t	soap_xmlsec_sign (struct SoapCtx *context)
herror_t	soap_xmlsec_verify (struct SoapCtx *context)
herror_t	soap_xmlsec_encrypt (struct SoapCtx *context)
herror_t	soap_xmlsec_decrypt (struct SoapCtx *context)
void	soap_xmlsec_destroy (void)

---

Detailed Description

Web Services Security

This module is implemented using the xmlsec1 library.

Author:

H. Ronsdorf

Version:

Revision

1.10

See also:

http://www.w3.org/TR/SOAP-dsig/

http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=wss

http://www.aleksey.com/xmlsec/

---

Define Documentation

#define CSOAP_ENABLE_XMLSEC   "-CSOAPxmlsec"

Commandline argument to enable WS-Security.

#define CSOAP_XMLSEC_CERTFILE   "-CSOAPcertfile"

Commandline argument to set a file of certificates.

#define CSOAP_XMLSEC_KEYFILE   "-CSOAPkeyfile"

Commandline argument to set the keyfile. If this argument is not specified, a random key will be used.

#define CSOAP_XMLSEC_PASSWORD   "-CSOAPpassword"

Commandline argument to set the password of the key.

#define SOAP_SECURITY_NAMESPACE   "http://schemas.xmlsoap.org/soap/security/2000-12"

#define SOAP_SECURITY_PREFIX   "SOAP-SEC"

---

Function Documentation

herror_t soap_xmlsec_client_init_args	(	int	argc,
		char **	argv
	)

This function initializes the WS-Security subsystem for a SOAP client.

Parameters:

	argc	commandline arg count
	argv	commandline arg vector

Returns:

H_OK on success.

See also:

soap_xmlsec_destroy()

herror_t soap_xmlsec_decrypt

(

struct SoapCtx *

context

)

This function decrypts an XML document contained in a SOAP envelope.

Parameters:

context

The SOAP context to be decrypted.

Returns:

H_OK on success.

void soap_xmlsec_destroy

(

void

)

This function frees the resources needed by the XML security subsystem.

See also:

soap_xmlsec_init()

herror_t soap_xmlsec_encrypt

(

struct SoapCtx *

context

)

This function encrypts an XML document contained in a SOAP envelope.

Parameters:

context

The SOAP context to be encrypted.

Returns:

H_OK on success.

herror_t soap_xmlsec_server_init_args	(	int	argc,
		char **	argv
	)

This function initializes the WS-Security subsystem for a SOAP server.

Parameters:

	argc	commandline arg count
	argv	commandline arg vector

Returns:

H_OK on success.

See also:

soap_xmlsec_destroy()

herror_t soap_xmlsec_sign

(

struct SoapCtx *

context

)

This function signs an XML document contained in a SOAP Envelope with the key specified on the commandline. Our way to create a <SOAP-SEC:Signature> header entry is as follows:

• Prepare the target SOAP Envelope with the body and necessary headers.
• Create a template of a <ds:Signature> element. The template is assumed to contain empty contents for <ds:DigestValue> or <ds:SignatureValue> elements, but contains appropriate values for the elements such as <ds:SignatureMethod> and <ds:Reference> required to calculate them.
• Create a new header entry <SOAP-SEC:Signature> and add the template to this entry.
• Add the header entry <SOAP-SEC:Signature> to the SOAP Header.
• Add the SOAP "actor" and "mustUnderstand" attributes to the entry, if necessary.
• Calculate the <ds:DigestValue> and <ds:SignatureValue> elements according to the core generation of the XML-Signature specification.

XPath filtering can be used to specify objects to be signed, as described in the XML-Signature specification. However, since the SOAP message exchange model allows intermediate applications to modify the Envelope (add or delete a header entry, for example), XPath filtering does not always result in the same objects after message delivery. Care should be taken in using XPath filtering so that there is no subsequent validation failure due to such modifications.

The transform http://www.w3.org/2000/09/xmldsig#enveloped-signature defined in the XML-Signature specification may be useful when signing the entire Envelope including other header entries, if any.

Parameters:

context

The SOAP context to be signed.

Returns:

H_OK on success.

See also:

http://www.w3.org/TR/SOAP-dsig/

http://www.w3.org/TR/xmldsig-core/

herror_t soap_xmlsec_verify

(

struct SoapCtx *

context

)

This function verifies an XML documents signature contained in a SOAP Envelope. The validation of a <SOAP-SEC:Signature> header entry fails if:

• The syntax of the content of the header entry does not conform to SOAP Security Extensions: Digital Signature specification, or
• the validation of the signature contained in the header entry fails according to the core validation of the XML-Signature specification, or
• the receiving application program rejects the signature for some reason (e.g., the signature is created by an untrusted key).

If the validation of the signature header entry fails, applications MAY report the failure to the sender. It is out of the scope of this library how to deal with it.

Parameters:

context

The SOAP context to be verified.

Returns:

H_OK on success.

See also:

http://www.w3.org/TR/SOAP-dsig/

http://www.w3.org/TR/xmldsig-core/