gSOAP WS-Security: /Users/engelen/Projects/gsoap/plugin/wsseapi.h File Reference

/Users/engelen/Projects/gsoap/plugin/wsseapi.h File Reference

#include "soapH.h"
#include "smdevp.h"
#include "mecevp.h"

Include dependency graph for wsseapi.h:

This graph shows which files directly or indirectly include this file:


Classes
struct	soap_wsse_data
	wsseapi plugin data More...
struct	soap_wsse_digest
	Digest dictionary: linked list of ID-hash pairs. More...
Defines
#define	SOAP_WSSE_ID "SOAP-WSSE-1.2"
Functions
_wsse__Security *	soap_wsse_add_Security (struct soap *soap)
	Adds Security header element.
_wsse__Security *	soap_wsse_add_Security_actor (struct soap soap, const char actor)
	Adds Security header element with actor or role attribute.
void	soap_wsse_delete_Security (struct soap *soap)
	Deletes Security header element.
_wsse__Security *	soap_wsse_Security (struct soap *soap)
	Returns Security header element if present.
ds__SignatureType *	soap_wsse_add_Signature (struct soap *soap)
	Adds Signature header element.
void	soap_wsse_delete_Signature (struct soap *soap)
	Deletes Signature header element.
ds__SignatureType *	soap_wsse_Signature (struct soap *soap)
	Returns Signature header element if present.
int	soap_wsse_add_Timestamp (struct soap soap, const char id, time_t lifetime)
	Adds Timestamp element with optional expiration date+time (lifetime).
_wsu__Timestamp *	soap_wsse_Timestamp (struct soap *soap)
	Returns Timestamp element if present.
int	soap_wsse_verify_Timestamp (struct soap *soap)
	Verifies the Timestamp/Expires element against the current time.
int	soap_wsse_add_UsernameTokenText (struct soap soap, const char id, const char username, const char password)
	Adds UsernameToken element with optional clear-text password.
int	soap_wsse_add_UsernameTokenDigest (struct soap soap, const char id, const char username, const char password)
	Adds UsernameToken element for digest authentication.
_wsse__UsernameToken *	soap_wsse_UsernameToken (struct soap soap, const char id)
	Returns UsernameToken element if present.
const char *	soap_wsse_get_Username (struct soap *soap)
	Returns UsernameToken/username string or wsse:FailedAuthentication fault.
int	soap_wsse_verify_Password (struct soap soap, const char password)
	Verifies the supplied password or sets wsse:FailedAuthentication fault.
int	soap_wsse_add_BinarySecurityToken (struct soap soap, const char id, const char valueType, const unsigned char data, int size)
	Adds BinarySecurityToken element.
int	soap_wsse_add_BinarySecurityTokenX509 (struct soap soap, const char id, X509 *cert)
	Adds BinarySecurityToken element with X509 certificate.
int	soap_wsse_add_BinarySecurityTokenPEM (struct soap soap, const char id, const char *filename)
	Adds BinarySecurityToken element from a PEM file.
_wsse__BinarySecurityToken *	soap_wsse_BinarySecurityToken (struct soap soap, const char id)
	Returns BinarySecurityToken element if present.
int	soap_wsse_get_BinarySecurityToken (struct soap soap, const char id, char valueType, unsigned char data, int *size)
	Get wsse:BinarySecurityToken element token data in binary form.
X509 *	soap_wsse_get_BinarySecurityTokenX509 (struct soap soap, const char id)
	Get X509 wsse:BinarySecurityToken certificate and verify its content.
int	soap_wsse_verify_X509 (struct soap soap, X509 cert)
	Verifies X509 certificate against soap->cafile, soap->capath, and soap->crlfile.
ds__SignedInfoType *	soap_wsse_add_SignedInfo (struct soap *soap)
	Adds SignedInfo element.
int	soap_wsse_add_SignedInfo_Reference (struct soap soap, const char URI, const char transform, const char inclusiveNamespaces, const char *HA)
	Adds SignedInfo element with Reference URI, transform algorithm used, and digest value.
int	soap_wsse_add_SignedInfo_SignatureMethod (struct soap soap, const char method, int canonical)
	Adds SignedInfo element with SignatureMethod.
ds__SignedInfoType *	soap_wsse_SignedInfo (struct soap *soap)
	Returns SignedInfo element if present.
int	soap_wsse_get_SignedInfo_SignatureMethod (struct soap soap, int alg)
	Get SignatureMethod algorithm.
int	soap_wsse_add_SignatureValue (struct soap soap, int alg, const void key, int keylen)
	Adds SignedInfo/SignatureMethod element, signs the SignedInfo element, and adds the resulting SignatureValue element.
int	soap_wsse_verify_SignatureValue (struct soap soap, int alg, const void key, int keylen)
	Verifies the SignatureValue of a SignedInfo element.
int	soap_wsse_verify_SignedInfo (struct soap *soap)
	Verifies the digest values of the XML elements referenced by the SignedInfo References.
int	soap_wsse_verify_digest (struct soap soap, int alg, int canonical, const char id, unsigned char hash[SOAP_SMD_MAX_SIZE])
	Verifies the digest value of an XML element referenced by id against the hash.
ds__KeyInfoType *	soap_wsse_add_KeyInfo (struct soap *soap)
	Adds KeyInfo element.
ds__KeyInfoType *	soap_wsse_KeyInfo (struct soap *soap)
	Returns KeyInfo element if present.
int	soap_wsse_add_KeyInfo_KeyName (struct soap soap, const char name)
	Adds KeyName element.
const char *	soap_wsse_get_KeyInfo_KeyName (struct soap *soap)
	Returns KeyName element if present.
int	soap_wsse_add_KeyInfo_SecurityTokenReferenceURI (struct soap soap, const char URI, const char *valueType)
	Adds KeyInfo element with SecurityTokenReference URI.
int	soap_wsse_add_KeyInfo_SecurityTokenReferenceX509 (struct soap soap, const char URI)
	Adds KeyInfo element with SecurityTokenReference URI to an X509 cert.
const char *	soap_wsse_get_KeyInfo_SecurityTokenReferenceURI (struct soap *soap)
	Returns a SecurityTokenReference URI if present.
const char *	soap_wsse_get_KeyInfo_SecurityTokenReferenceValueType (struct soap *soap)
	Returns a SecurityTokenReference ValueType if present.
X509 *	soap_wsse_get_KeyInfo_SecurityTokenReferenceX509 (struct soap *soap)
	Returns a X509 certificate if present as a BinarySecurity token.
int	soap_wsse_add_KeyInfo_SecurityTokenReferenceKeyIdentifier (struct soap soap, const char id, const char valueType, unsigned char data, int size)
	Adds KeyInfo element with SecurityTokenReference/KeyIdentifier binary data.
const char *	soap_wsse_get_KeyInfo_SecurityTokenReferenceKeyIdentifierValueType (struct soap *soap)
	Returns KeyInfo/SecurityTokenReference/KeyIdentifier/ValueType if present.
const unsigned char *	soap_wsse_get_KeyInfo_SecurityTokenReferenceKeyIdentifier (struct soap soap, int size)
	Returns KeyInfo/SecurityTokenReference/KeyIdentifier binary data.
int	soap_wsse_add_KeyInfo_SecurityTokenReferenceEmbedded (struct soap soap, const char id, const char *valueType)
	Adds KeyInfo element with Embedded SecurityTokenReference.
int	soap_wsse_sender_fault_subcode (struct soap soap, const char faultsubcode, const char faultstring, const char faultdetail)
	Sets sender SOAP Fault (sub)code for server fault response.
int	soap_wsse_receiver_fault_subcode (struct soap soap, const char faultsubcode, const char faultstring, const char faultdetail)
	Sets receiver SOAP Fault (sub)code for server fault response.
int	soap_wsse_sender_fault (struct soap soap, const char faultstring, const char *faultdetail)
	Sets sender SOAP Fault for server fault response.
int	soap_wsse_receiver_fault (struct soap soap, const char faultstring, const char *faultdetail)
	Sets receiver SOAP Fault for server fault response.
int	soap_wsse_fault (struct soap soap, enum wsse__FaultcodeEnum fault, const char detail)
int	soap_wsse (struct soap soap, struct soap_plugin p, void *arg)
	Plugin registry function, used with soap_register_plugin.
int	soap_wsse_sign (struct soap soap, int alg, const void key, int keylen)
	Uses the wsse plugin to sign all wsu:Id attributed elements.
int	soap_wsse_sign_body (struct soap soap, int alg, const void key, int keylen)
	Uses the wsse plugin to sign all wsu:Id attributed elements, including the SOAP Body (by adding a wsu:Id="Body" attribute).
int	soap_wsse_verify_init (struct soap *soap)
	Uses the wsse plugin to initiate the verification of the signature and SignedInfo Reference digests.
int	soap_wsse_verify_auto (struct soap soap, int alg, const void key, size_t keylen)
	Uses the wsse plugin to initiate the automatic verification of the signature and SignedInfo Reference digests.
int	soap_wsse_verify_done (struct soap *soap)
	Terminates the automatic verification of signatures.
size_t	soap_wsse_verify_element (struct soap soap, const char URI, const char *tag)
	Post-checks the presence of signed element(s). Does not verify the signature of these elements, which is done with soap_wsse_verify_auto.
int	soap_wsse_verify_body (struct soap *soap)
	Post-checks the presence of signed SOAP Body. Does not verify the signature of the Body, which is done with soap_wsse_verify_auto.
int	soap_wsse_set_wsu_id (struct soap soap, const char tags)
	Sets the elements that are to be extended with wsu:Id attributes. The wsu:Id attribute values are set to the string value of the tag's QName by replacing colons with hyphens to produce an xsd:ID value.
int	soap_wsse_sign_only (struct soap soap, const char ids)
	Filters only the specified wsu:Id names for signing. Can be used with soap_wsse_set_wsu_id() and if so should use the element tag names.
int	soap_wsse_encrypt_only (struct soap soap, const char ids)
int	soap_wsse_add_EncryptedKey (struct soap soap, const char URI, X509 cert, const char subjectkeyid)
	Adds EncryptedKey header element.
int	soap_wsse_verify_EncryptedKey (struct soap *soap)
	Verifies the EncryptedKey header information (certificate validity requires soap->cacert to be set). Retrieves the decryption key from the token handler callback to decrypt the decryption key.
void	soap_wsse_delete_EncryptedKey (struct soap *soap)
	Deletes EncryptedKey header element.
xenc__EncryptedKeyType *	soap_wsse_EncryptedKey (struct soap *soap)
	Returns EncryptedKey header element if present.
int	soap_wsse_add_EncryptedKey_DataReferenceURI (struct soap soap, const char URI)
	Adds a DataReference URI to the EncryptedKey header element.
int	soap_wsse_add_DataReferenceURI (struct soap soap, const char URI)
	Adds a DataReference URI to the WS-Security header element.
int	soap_wsse_encrypt_body (struct soap soap, int alg, const void key, int keylen)
	Initiates the encryption of the SOAP Body. The algorithm should be SOAP_MEC_ENC_DES_CBC for symmetric encryption. Use soap_wsse_add_EncryptedKey for public key encryption.
int	soap_wsse_encrypt (struct soap soap, int alg, const void key, int keylen)
	Start encryption. This function is supposed to be used internally only. The algorithm should be SOAP_MEC_ENC_DES_CBC for symmetric encryption. Use soap_wsse_add_EncryptedKey for public key encryption.
int	soap_wsse_decrypt_auto (struct soap soap, int alg, const void key, int keylen)
	Start automatic decryption when needed using the specified key. This function should be used just once. The algorithm should be SOAP_MEC_ENV_DEC_DES_CBC for public key encryption/decryption and SOAP_MEC_DEC_DES_CBC for symmetric shared secret keys.
int	soap_wsse_encrypt_begin (struct soap soap, const char id, const char URI, const char keyname, const unsigned char *key)
	Emit XML encryption tags and start encryption of the XML element content.
int	soap_wsse_encrypt_end (struct soap *soap)
	Emit XML encryption end tags and stop encryption of the XML element content.
int	soap_wsse_decrypt_begin (struct soap soap, const unsigned char key)
	Check for XML encryption tags and start decryption of the XML element content. If the KeyInfo element is present, the security_token_handler callback will be used to obtain a decryption key based on the key name. Otherwise the current decryption key will be used.
int	soap_wsse_decrypt_end (struct soap *soap)
	Check for XML encryption ending tags and stop decryption of the XML element content.
SOAP_FMAC1 void SOAP_FMAC2	soap_default_xsd__anyType (struct soap , struct soap_dom_element node)
SOAP_FMAC1 int SOAP_FMAC2	soap_out_xsd__anyType (struct soap soap, const char tag, int id, const struct soap_dom_element node, const char type)
SOAP_FMAC1 struct soap_dom_element *SOAP_FMAC2	soap_in_xsd__anyType (struct soap soap, const char tag, struct soap_dom_element node, const char type)
Variables
const char	soap_wsse_id []
const char *	wsse_PasswordTextURI
const char *	wsse_PasswordDigestURI
const char *	wsse_Base64BinaryURI
const char *	wsse_X509v3URI
const char *	wsse_X509v3SubjectKeyIdentifierURI
const char *	ds_sha1URI
const char *	ds_hmac_sha1URI
const char *	ds_dsa_sha1URI
const char *	ds_rsa_sha1URI
const char *	ds_URI
const char *	c14n_URI
const char *	wsu_URI

Define Documentation

#define SOAP_WSSE_ID "SOAP-WSSE-1.2"

plugin identification for plugin registry

Function Documentation

SOAP_FMAC1 void SOAP_FMAC2 soap_default_xsd__anyType ( struct soap * ,

struct soap_dom_element * node

)

SOAP_FMAC1 struct soap_dom_element* SOAP_FMAC2 soap_in_xsd__anyType ( struct soap * soap,

const char * tag,

struct soap_dom_element * node,

const char * type

)

SOAP_FMAC1 int SOAP_FMAC2 soap_out_xsd__anyType ( struct soap * soap,

const char * tag,

int id,

const struct soap_dom_element * node,

const char * type

)

int soap_wsse ( struct soap * soap,

struct soap_plugin * p,

void * arg

)

Plugin registry function, used with soap_register_plugin.

Parameters:

soap context

[in,out] p plugin created in registry

[in] arg passed from soap_register_plugin_arg is an optional security token handler callback

Returns:
SOAP_OK

int soap_wsse_add_BinarySecurityToken ( struct soap * soap,

const char * id,

const char * valueType,

const unsigned char * data,

int size

)

Adds BinarySecurityToken element.

Parameters:

soap context

[in] id string for signature referencing or NULL

[in] valueType string

[in] data points to binary token data

[in] size is length of binary token

Returns:
SOAP_OK

int soap_wsse_add_BinarySecurityTokenPEM ( struct soap * soap,

const char * id,

const char * filename

)

Adds BinarySecurityToken element from a PEM file.

Parameters:

soap context

[in] id string for signature reference

[in] filename

Returns:
SOAP_OK or SOAP_FAULT with wsse__InvalidSecurity fault when file cannot be read or does not contain a valid certificate
This function uses PEM_read_X509 from the the OpenSSL library to read a certificate from a PEM formatted file.

int soap_wsse_add_BinarySecurityTokenX509 ( struct soap * soap,

const char * id,

X509 * cert

)

Adds BinarySecurityToken element with X509 certificate.

Parameters:

soap context

[in] id string for signature reference

[in] cert points to the X509 certificate

Returns:
SOAP_OK or SOAP_EOM
This function uses i2d_X509 from the the OpenSSL library to convert an X509 object to binary DER format.

int soap_wsse_add_DataReferenceURI ( struct soap * soap,

const char * URI

)

Adds a DataReference URI to the WS-Security header element.

Parameters:

soap context

[in] URI value of the URI ID

Returns:
SOAP_OK or error code

xenc__EncryptedKeyType * soap_wsse_add_EncryptedKey ( struct soap * soap,

const char * URI,

X509 * cert,

const char * subjectkeyid

)

Adds EncryptedKey header element.

Parameters:

soap context

[in] URI a unique identifier for the key, required for interoperability

[in] cert the X509 certificate with public key or NULL

[in] subjectkeyid string identification of the subject which when set to non-NULL is used instead of embedding the public key in the message

Returns:
xenc__EncryptedKeyType object
This function adds the encrypted key or subject key ID to the WS-Security header and initiates encryption of the SOAP Body. An X509 certificate must be provided. The certificate is embedded in the WS-Security EncryptedKey header. If the subjectkeyid string is non-NULL the subject key ID is used in the EncryptedKey header instead of the X509 certificate content.

int soap_wsse_add_EncryptedKey_DataReferenceURI ( struct soap * soap,

const char * URI

)

Adds a DataReference URI to the EncryptedKey header element.

Parameters:

soap context

[in] URI value of the URI ID

Returns:
SOAP_OK or error code

ds__KeyInfoType * soap_wsse_add_KeyInfo ( struct soap * soap )

Adds KeyInfo element.

Parameters:

soap context

Returns:
ds__KeyInfo object

int soap_wsse_add_KeyInfo_KeyName ( struct soap * soap,

const char * name

)

Adds KeyName element.

Parameters:

soap context

[in] name string of the KeyName

Returns:
SOAP_OK
Note: the recommended method to add Key information is to utilize KeyIdentifier instead of KeyName. A KeyName is useful mainly for internal use.

int soap_wsse_add_KeyInfo_SecurityTokenReferenceEmbedded ( struct soap * soap,

const char * id,

const char * valueType

)

Adds KeyInfo element with Embedded SecurityTokenReference.

Parameters:

soap context

[in] id string for signature reference

[in] valueType string

Returns:
SOAP_OK
Note: this function does not add embedded tokens automatically. See code for comments.

int soap_wsse_add_KeyInfo_SecurityTokenReferenceKeyIdentifier ( struct soap * soap,

const char * id,

const char * valueType,

unsigned char * data,

int size

)

Adds KeyInfo element with SecurityTokenReference/KeyIdentifier binary data.

Parameters:

soap context

[in] id string for signature reference

[in] valueType string

[in] data binary data

[in] size of binary data

Returns:
SOAP_OK

int soap_wsse_add_KeyInfo_SecurityTokenReferenceURI ( struct soap * soap,

const char * URI,

const char * valueType

)

Adds KeyInfo element with SecurityTokenReference URI.

Parameters:

soap context

[in] URI string referencing a security token

[in] valueType string or NULL

Returns:
SOAP_OK

int soap_wsse_add_KeyInfo_SecurityTokenReferenceX509 ( struct soap * soap,

const char * URI

)

Adds KeyInfo element with SecurityTokenReference URI to an X509 cert.

Parameters:

soap context

[in] URI string referencing an X509 certificate

Returns:
SOAP_OK

_wsse__Security * soap_wsse_add_Security ( struct soap * soap )

Adds Security header element.

Parameters:

soap context

Returns:
_wsse__Security object

_wsse__Security * soap_wsse_add_Security_actor ( struct soap * soap,

const char * actor

)

Adds Security header element with actor or role attribute.

Parameters:

soap context

actor string

Returns:
_wsse__Security object

ds__SignatureType * soap_wsse_add_Signature ( struct soap * soap )

Adds Signature header element.

Parameters:

soap context

Returns:
ds__SignatureType object

int soap_wsse_add_SignatureValue ( struct soap * soap,

int alg,

const void * key,

int keylen

)

Adds SignedInfo/SignatureMethod element, signs the SignedInfo element, and adds the resulting SignatureValue element.

Parameters:

soap context

[in] alg is SOAP_SMD_HMAC_SHA1, SOAP_SMD_SIGN_DSA_SHA1, or SOAP_SMD_SIGN_RSA_SHA1

[in] key to use to sign (HMAC or EVP_PKEY)

[in] keylen length of HMAC key

Returns:
SOAP_OK, SOAP_EOM, or fault
To sign the SignedInfo element with this function, populate SignedInfo with Reference elements first using soap_wsse_add_SignedInfo_Reference. The SignedInfo element must not be modified after signing.
The SOAP_XML_INDENT and SOAP_XML_CANONICAL flags are used to serialize the SignedInfo to compute the signature.

ds__SignedInfoType * soap_wsse_add_SignedInfo ( struct soap * soap )

Adds SignedInfo element.

Parameters:

soap context

Returns:
ds__SignedInfoType object

int soap_wsse_add_SignedInfo_Reference ( struct soap * soap,

const char * URI,

const char * transform,

const char * inclusiveNamespaces,

const char * HA

)

Adds SignedInfo element with Reference URI, transform algorithm used, and digest value.

Parameters:

soap context

[in] URI reference

[in] transform string should be c14n_URI for exc-c14n or NULL

[in] inclusiveNamespaces used by the exc-c14n transform or NULL

[in] HA is the SHA1 digest in binary form (length=SOAP_SMD_SHA1_SIZE)

Returns:
SOAP_OK or SOAP_EOM when references exceed SOAP_WSSE_MAX_REF
This function can be called to add more references to the wsse:SignedInfo element. A maximum number of SOAP_WSSE_MAX_REF references can be added. The digest method is always SHA1. Note: XPath transforms cannot be specified in this release.

int soap_wsse_add_SignedInfo_SignatureMethod ( struct soap * soap,

const char * method,

int canonical

)

Adds SignedInfo element with SignatureMethod.

Parameters:

soap context

[in] method is the URI of the signature algorithm (e.g. ds_rsa_sha1)

[in] canonical flag indicating that SignedInfo is signed in exc-c14n form

Returns:
SOAP_OK
Note: the c14n:InclusiveNamespaces/PrefixList is set to "SOAP-ENV wsse".

int soap_wsse_add_Timestamp ( struct soap * soap,

const char * id,

time_t lifetime

)

Adds Timestamp element with optional expiration date+time (lifetime).

Parameters:

[in] soap context

[in] id for signature referencing or NULL

[in] lifetime expressed in time_t units, or 0 for no expiration

Returns:
SOAP_OK

int soap_wsse_add_UsernameTokenDigest ( struct soap * soap,

const char * id,

const char * username,

const char * password

)

Adds UsernameToken element for digest authentication.

Parameters:

soap context

[in] id string for signature referencing or NULL

[in] username string

[in] password string

Returns:
SOAP_OK
Computes SHA1 digest of the time stamp, a nonce, and the password. The digest provides the authentication credentials. Passwords are NOT sent in the clear. Note: this release supports the use of at most one UsernameToken in the header.

int soap_wsse_add_UsernameTokenText ( struct soap * soap,

const char * id,

const char * username,

const char * password

)

Adds UsernameToken element with optional clear-text password.

Parameters:

soap context

[in] id string for signature referencing or NULL

[in] username string

[in] password string or NULL to omit the password

Returns:
SOAP_OK
Passwords are sent in the clear, so transport-level encryption is required. Note: this release supports the use of at most one UsernameToken in the header.

_wsse__BinarySecurityToken * soap_wsse_BinarySecurityToken ( struct soap * soap,

const char * id

)

Returns BinarySecurityToken element if present.

Parameters:

soap context

[in] id string of token to get or NULL

Returns:
_wsse__BinarySecurityToken object or NULL

int soap_wsse_decrypt_auto ( struct soap * soap,

int alg,

const void * key,

int keylen

)

Start automatic decryption when needed using the specified key. This function should be used just once. The algorithm should be SOAP_MEC_ENV_DEC_DES_CBC for public key encryption/decryption and SOAP_MEC_DEC_DES_CBC for symmetric shared secret keys.

Parameters:

soap context

[in] alg the decryption algorithm,

[in] key the decryption key for the algorithm, a private RSA key or a shared secret key

[in] keylen use 0 for public-key encryption/decryption or the shared secret decryption key length, 20 bytes for a DES CBC 160-bit key

Returns:
SOAP_OK or error code
This function can be called once before multiple messages are received with WS-Security encrypted content, where only one key is used for encryption (public key or shared secret key). The default decryption key is set. If multiple decryption keys should be used, do NOT use this function but set the security_token_handler callback of the wsse plugin. See Decrypting Message Parts. Use a NULL key to remove the default decryption key.

int soap_wsse_decrypt_begin ( struct soap * soap,

const unsigned char * key

)

Check for XML encryption tags and start decryption of the XML element content. If the KeyInfo element is present, the security_token_handler callback will be used to obtain a decryption key based on the key name. Otherwise the current decryption key will be used.

Parameters:

soap context

[in] key optional triple DES key for decryption (to override the current key)

Returns:
SOAP_OK or error code

int soap_wsse_decrypt_end ( struct soap * soap )

Check for XML encryption ending tags and stop decryption of the XML element content.

Parameters:

soap context

Returns:
SOAP_OK or error code

void soap_wsse_delete_EncryptedKey ( struct soap * soap )

Deletes EncryptedKey header element.

Parameters:

soap context

void soap_wsse_delete_Security ( struct soap * soap )

Deletes Security header element.

Parameters:

soap context

void soap_wsse_delete_Signature ( struct soap * soap )

Deletes Signature header element.

Parameters:

soap context

int soap_wsse_encrypt ( struct soap * soap,

int alg,

const void * key,

int keylen

)

Start encryption. This function is supposed to be used internally only. The algorithm should be SOAP_MEC_ENC_DES_CBC for symmetric encryption. Use soap_wsse_add_EncryptedKey for public key encryption.

Parameters:

soap context

[in] alg the encryption algorithm, should be SOAP_MEC_ENC_DES_CBC

[in] key the encryption key, a DES CBC 160-bit key

[in] keylen the encryption key length, 20 bytes for a DES CBC 160-bit key

Returns:
SOAP_OK or error code

int soap_wsse_encrypt_begin ( struct soap * soap,

const char * id,

const char * URI,

const char * keyname,

const unsigned char * key

)

Emit XML encryption tags and start encryption of the XML element content.

Parameters:

soap context

[in] id string for the EncryptedData element Id attribute

[in] URI string for the encrypted element wsu:Id attribute

[in] keyname optional subject key name

[in] key optional triple DES key for encryption (to override the current key)

Returns:
SOAP_OK or error code

int soap_wsse_encrypt_body ( struct soap * soap,

int alg,

const void * key,

int keylen

)

Initiates the encryption of the SOAP Body. The algorithm should be SOAP_MEC_ENC_DES_CBC for symmetric encryption. Use soap_wsse_add_EncryptedKey for public key encryption.

Parameters:

soap context

[in] alg the encryption algorithm, should be SOAP_MEC_ENC_DES_CBC

[in] key the encryption key, a DES CBC 160-bit key

[in] keylen the encryption key length, 20 bytes for a DES CBC 160-bit key

Returns:
SOAP_OK or error code
This function initiates the encryption of the SOAP Body using an RSA public key or a symmetric shared secret key. No WS-Security EncryptedKey header will be set. Use soap_wsse_add_EncryptedKey instead for public key encryption.

int soap_wsse_encrypt_end ( struct soap * soap )

Emit XML encryption end tags and stop encryption of the XML element content.

Parameters:

soap context

Returns:
SOAP_OK or error code

int soap_wsse_encrypt_only ( struct soap * soap,

const char * ids

)

xenc__EncryptedKeyType * soap_wsse_EncryptedKey ( struct soap * soap )

Returns EncryptedKey header element if present.

Parameters:

soap context

Returns:
xenc__EncryptedKeyType object or NULL

int soap_wsse_fault ( struct soap * soap,

enum wsse__FaultcodeEnum fault,

const char * detail

)

int soap_wsse_get_BinarySecurityToken ( struct soap * soap,

const char * id,

char ** valueType,

unsigned char ** data,

int * size

)

Get wsse:BinarySecurityToken element token data in binary form.

Parameters:

soap context

[in] id string of token to get or NULL

[out] valueType string

[out] data points to binary token data

[out] size is length of binary token

Returns:
SOAP_OK or SOAP_FAULT with wsse:SecurityTokenUnavailable fault

X509 * soap_wsse_get_BinarySecurityTokenX509 ( struct soap * soap,

const char * id

)

Get X509 wsse:BinarySecurityToken certificate and verify its content.

Parameters:

soap context

[in] id string of token to get or NULL

Returns:
X509 certificate (dynamically allocated) or NULL with wsse:SecurityTokenUnavailable fault

int soap_wsse_get_KeyInfo_KeyName ( struct soap * soap )

Returns KeyName element if present.

Parameters:

soap context

Returns:
string or NULL

const unsigned char * soap_wsse_get_KeyInfo_SecurityTokenReferenceKeyIdentifier ( struct soap * soap,

int * size

)

Returns KeyInfo/SecurityTokenReference/KeyIdentifier binary data.

Parameters:

soap context

[out] size is set to the size of the decoded data

Returns:
data or NULL

const char * soap_wsse_get_KeyInfo_SecurityTokenReferenceKeyIdentifierValueType ( struct soap * soap )

Returns KeyInfo/SecurityTokenReference/KeyIdentifier/ValueType if present.

Parameters:

soap context

Returns:
string or NULL

const char * soap_wsse_get_KeyInfo_SecurityTokenReferenceURI ( struct soap * soap )

Returns a SecurityTokenReference URI if present.

Parameters:

soap context

Returns:
string or NULL

const char * soap_wsse_get_KeyInfo_SecurityTokenReferenceValueType ( struct soap * soap )

Returns a SecurityTokenReference ValueType if present.

Parameters:

soap context

Returns:
string or NULL

X509 * soap_wsse_get_KeyInfo_SecurityTokenReferenceX509 ( struct soap * soap )

Returns a X509 certificate if present as a BinarySecurity token.

Parameters:

soap context

Returns:
X509 object or NULL with wsse:SecurityTokenUnavailable fault

int soap_wsse_get_SignedInfo_SignatureMethod ( struct soap * soap,

int * alg

)

Get SignatureMethod algorithm.

Parameters:

soap context

[out] alg is SOAP_SMD_HMAC_SHA1, SOAP_SMD_VRFY_DSA_SHA1, or SOAP_SMD_VRFY_RSA_SHA1

Returns:
SOAP_OK or SOAP_FAULT with wsse:UnsupportedAlgorithm or wsse:FailedCheck fault

const char * soap_wsse_get_Username ( struct soap * soap )

Returns UsernameToken/username string or wsse:FailedAuthentication fault.

Parameters:

soap context

Returns:
UsernameToken/username string or NULL with wsse:FailedAuthentication fault error set

See also:
soap_wsse_verify_Password
The returned username should be used to lookup the user's password in a dictionary or database for server-side authentication with soap_wsse_verify_Password.

ds__KeyInfoType * soap_wsse_KeyInfo ( struct soap * soap )

Returns KeyInfo element if present.

Parameters:

soap context

Returns:
ds__KeyInfo object or NULL

int soap_wsse_receiver_fault ( struct soap * soap,

const char * faultstring,

const char * faultdetail

)

Sets receiver SOAP Fault for server fault response.

Parameters:

soap context

[in] faultstring fault string

[in] faultdetail detail string

Returns:
SOAP_FAULT

int soap_wsse_receiver_fault_subcode ( struct soap * soap,

const char * faultsubcode,

const char * faultstring,

const char * faultdetail

)

Sets receiver SOAP Fault (sub)code for server fault response.

Parameters:

soap context

[in] faultsubcode sub code string

[in] faultstring fault string

[in] faultdetail detail string

Returns:
SOAP_FAULT

_wsse__Security * soap_wsse_Security ( struct soap * soap )

Returns Security header element if present.

Parameters:

soap context

Returns:
_wsse__Security object or NULL

int soap_wsse_sender_fault ( struct soap * soap,

const char * faultstring,

const char * faultdetail

)

Sets sender SOAP Fault for server fault response.

Parameters:

soap context

[in] faultstring fault string

[in] faultdetail detail string

Returns:
SOAP_FAULT

int soap_wsse_sender_fault_subcode ( struct soap * soap,

const char * faultsubcode,

const char * faultstring,

const char * faultdetail

)

Sets sender SOAP Fault (sub)code for server fault response.

Parameters:

soap context

[in] faultsubcode sub code string

[in] faultstring fault string

[in] faultdetail detail string

Returns:
SOAP_FAULT

int soap_wsse_set_wsu_id ( struct soap * soap,

const char * tags

)

Sets the elements that are to be extended with wsu:Id attributes. The wsu:Id attribute values are set to the string value of the tag's QName by replacing colons with hyphens to produce an xsd:ID value.

Parameters:

soap context

[in] tags string of space-separated qualified and unqualified element tag names

Returns:
SOAP_OK

int soap_wsse_sign ( struct soap * soap,

int alg,

const void * key,

int keylen

)

Uses the wsse plugin to sign all wsu:Id attributed elements.

Parameters:

soap context

[in] alg is the signature algorithm SOAP_SMD_HMAC_SHA1, SOAP_SMD_SIGN_DSA_SHA1, or SOAP_SMD_SIGN_RSA_SHA1

[in] key is the HMAC secret key or DSA/RSA private EVP_PKEY

[in] keylen is the HMAC key length

Returns:
SOAP_OK or fault
This function does not actually sign the message, but initiates the plugin's signature algorithm to sign the message upon message transfer.

int soap_wsse_sign_body ( struct soap * soap,

int alg,

const void * key,

int keylen

)

Uses the wsse plugin to sign all wsu:Id attributed elements, including the SOAP Body (by adding a wsu:Id="Body" attribute).

Parameters:

soap context

[in] alg is the signature algorithm SOAP_SMD_HMAC_SHA1, SOAP_SMD_SIGN_DSA_SHA1, or SOAP_SMD_SIGN_RSA_SHA1

[in] key is the HMAC secret key or DSA/RSA private EVP_PKEY

[in] keylen is the HMAC key length

Returns:
SOAP_OK
This function does not actually sign the message, but initiates the plugin's signature algorithm to sign the message upon message transfer.

int soap_wsse_sign_only ( struct soap * soap,

const char * ids

)

Filters only the specified wsu:Id names for signing. Can be used with soap_wsse_set_wsu_id() and if so should use the element tag names.

Parameters:

soap context

[in] ids string of space-separated id names

Returns:
SOAP_OK

ds__SignatureType * soap_wsse_Signature ( struct soap * soap )

Returns Signature header element if present.

Parameters:

soap context

Returns:
ds__SignatureType object or NULL

ds__SignedInfoType * soap_wsse_SignedInfo ( struct soap * soap )

Returns SignedInfo element if present.

Parameters:

soap context

Returns:
ds__SignedInfoType object or NULL

_wsu__Timestamp * soap_wsse_Timestamp ( struct soap * soap )

Returns Timestamp element if present.

Parameters:

soap context

Returns:
_wsu__Timestamp object or NULL

_wsse__UsernameToken * soap_wsse_UsernameToken ( struct soap * soap,

const char * id

)

Returns UsernameToken element if present.

Parameters:

soap context

[in] id string of UsernameToken or NULL

Returns:
_wsse__UsernameToken object or NULL
Note: this release supports the use of at most one UsernameToken in the header.

int soap_wsse_verify_auto ( struct soap * soap,

int alg,

const void * key,

size_t keylen

)

Uses the wsse plugin to initiate the automatic verification of the signature and SignedInfo Reference digests.

Parameters:

soap context

[in] alg to verify signature if signature has no secret or public key, use SOAP_SMD_NONE to omit

[in] key is HMAC key or EVP_PKEY or NULL

[in] keylen is HMAC key length or 0

Returns:
SOAP_OK
This function does not actually verify the message, but initiates the plugin's algorithm to store the message in a DOM to automatically verify the signature and digests. If the message does not contain a key to verify the signature, the alg, key, and keylen parameters are used. It is important that the X509 certificate used to verify the signature, which requires soap->cafile and/or soap->capath to be set.

int soap_wsse_verify_body ( struct soap * soap )

Post-checks the presence of signed SOAP Body. Does not verify the signature of the Body, which is done with soap_wsse_verify_auto.

Parameters:

soap context

Returns:
SOAP_OK (signed) or SOAP_ERR
This function does not actually verify the signature of the Body. It checks whether the Body is signed and thus its integrity is preserved. Clients should call this function after invocation. Services should call this function inside a service operation. This function traverses the entire DOM, so performance is determined by the size of a message.

int soap_wsse_verify_digest ( struct soap * soap,

int alg,

int canonical,

const char * id,

unsigned char hash[SOAP_SMD_MAX_SIZE]

)

Verifies the digest value of an XML element referenced by id against the hash.

Parameters:

soap context

[in] alg digest algorithm

[in] canonical flag indicating that element is signed in exc-c14n form

[in] id string of the XML element to verify

[in] hash digest value to verify against

Returns:
SOAP_OK or fault

int soap_wsse_verify_done ( struct soap * soap )

Terminates the automatic verification of signatures.

Parameters:

soap context

Returns:
SOAP_OK

size_t soap_wsse_verify_element ( struct soap * soap,

const char * URI,

const char * tag

)

Post-checks the presence of signed element(s). Does not verify the signature of these elements, which is done with soap_wsse_verify_auto.

Parameters:

soap context

URI namespace of element(s)

tag name of element(s)

Returns:
number of matching elements signed.
This function does not actually verify the signature of each element, but checks whether the elements are signed and thus their integrity is preserved. Signed element nesting rules are obeyed, so if the matching element is a descendent of a signed element, it is signed as well. Thus, the verification process follows nesting rules.
Client should call this function after invocation. Services should call this function inside a service operation. This function traverses the entire DOM, so performance is determined by the size of a message.
To check the SOAP Body (either using SOAP 1.1 or 1.2), soap_wsse_verify_element(soap, namespaces[0].ns, "Body"). To check whether the Timestamp was signed (assuming it is present and message expiration checked with soap_wsse_verify_Timestamp), use soap_wsse_verify_element(soap, "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd", "Timestamp").
Note: for future releases XPath queries (or forms of these) will be considered.

int soap_wsse_verify_EncryptedKey ( struct soap * soap )

Verifies the EncryptedKey header information (certificate validity requires soap->cacert to be set). Retrieves the decryption key from the token handler callback to decrypt the decryption key.

Parameters:

soap context

Returns:
SOAP_OK or error code

int soap_wsse_verify_init ( struct soap * soap )

Uses the wsse plugin to initiate the verification of the signature and SignedInfo Reference digests.

Parameters:

soap context

Returns:
SOAP_OK
This function does not actually verify the message, but initiates the plugin's data to store the message in a DOM to verify the signature. The signature and digests in the DOM must be verified manually.

int soap_wsse_verify_Password ( struct soap * soap,

const char * password

)

Verifies the supplied password or sets wsse:FailedAuthentication fault.

Parameters:

soap context

[in] password string to verify against

Returns:
SOAP_OK (authorized) or SOAP_FAULT with wsse:FailedAuthentication fault
The verification supports both clear-text password verification and digest password authentication. For digest authentication a history mechanism with a digest authentication session database ensures protection against replay attacks. Note: this release supports the use of at most one UsernameToken in the header.

int soap_wsse_verify_SignatureValue ( struct soap * soap,

int alg,

const void * key,

int keylen

)

Verifies the SignatureValue of a SignedInfo element.

Parameters:

soap context

[in] alg is SOAP_SMD_HMAC_SHA1, SOAP_SMD_VRFY_DSA_SHA1, or SOAP_SMD_VRFY_RSA_SHA1 determined by the SignedInfo/SignatureMethod

[in] key to use to verify (HMAC or EVP_PKEY)

[in] keylen length of HMAC key

Returns:
SOAP_OK, SOAP_EOM, or fault
This function searches for the SignedInfo element in the soap->dom DOM tree to verify the signature in the SignatureValue element. Using the DOM ensures we will verify the signature of a SignedInfo as it was exactly received by the parser, by using the -DWITH_DOM compile flag and SOAP_XML_DOM runtime flag. If there is no DOM, it verifies the signature of the deserialized SignedInfo element in the SOAP Header. However, serializing deserialized data may change the octet stream that was signed, unless we're using gSOAP as producers and consumers (with the SOAP_XML_INDENT flag reset).

int soap_wsse_verify_SignedInfo ( struct soap * soap )

Verifies the digest values of the XML elements referenced by the SignedInfo References.

Parameters:

soap context

Returns:
SOAP_OK or fault
This function searches for the SignedInfo element in the soap->dom DOM tree to verify the digests contained therein. Using the DOM ensures we will verify the digests of the locally signed elements as they were exactly received by the parser, by using the -DWITH_DOM compile flag and SOAP_XML_DOM runtime flag. If there is no DOM, the function fails.

int soap_wsse_verify_Timestamp ( struct soap * soap )

Verifies the Timestamp/Expires element against the current time.

Parameters:

soap context

Returns:
SOAP_OK or SOAP_FAULT with wsse:FailedAuthentication fault
Sets wsse:FailedAuthentication fault if wsu:Timestamp is expired. The SOAP_WSSE_CLKSKEW value is used as a margin to mitigate clock skew. Keeps silent when no timestamp is supplied or no expiration date is included in the wsu:Timestamp element.

int soap_wsse_verify_X509 ( struct soap * soap,

X509 * cert

)

Verifies X509 certificate against soap->cafile, soap->capath, and soap->crlfile.

Parameters:

soap context

[in] cert X509 certificate

Returns:
SOAP_OK or fault
This is an expensive operation. Whenever a new soap context is created, the cafile and objects are loaded into that context each time we need to verify a certificate.