# /Users/engelen/Projects/gsoap/plugin/wsseapi.c File Reference

`#include "wsseapi.h"`
`#include "smdevp.h"`
`#include "threads.h"`

Include dependency graph for wsseapi.c:

## Classes

struct | soap_wsse_session
| Digest authentication session data. More...

## Defines

#define | SOAP_WSSE_MAX_REF (100)
#define | SOAP_WSSE_CLKSKEW (300)
#define | SOAP_WSSE_NONCELEN (20)
#define | SOAP_WSSE_NONCETIME (SOAP_WSSE_CLKSKEW + 240)

## Functions

int | soap_wsse_session_verify (struct soap *soap, const char hash[SOAP_SMD_SHA1_SIZE], const char *created, const char *nonce)
| Verifies and updates the digest, nonce, and creation time against the digest authentication session database to prevent replay attacks.
void | soap_wsse_session_cleanup (struct soap *soap)
| Removes expired authentication data from the digest authentication session database.
void | calc_digest (struct soap *soap, const char *created, const char *nonce, int noncelen, const char *password, char hash[SOAP_SMD_SHA1_SIZE])
| Calculates digest value SHA1(created, nonce, password).
void | calc_nonce (struct soap *soap, char nonce[SOAP_WSSE_NONCELEN])
| Calculates randomized nonce (also uses time() in case a poorly seeded PRNG is used).
int | soap_wsse_init (struct soap *soap, struct soap_wsse_data *data, const void *(*arg)(struct soap *, int, int *))
int | soap_wsse_copy (struct soap *soap, struct soap_plugin *dst, struct soap_plugin *src)
| Copies plugin data to localize plugin data for threads.
void | soap_wsse_delete (struct soap *soap, struct soap_plugin *p)
| Deletes plugin data.
int | soap_wsse_preparesend (struct soap *soap, const char *buf, size_t len)
| Takes a piece of the XML message (tokenized) to compute digest.
int | soap_wsse_preparefinalsend (struct soap *soap)
| Collects the digests of all the wsu:Id elements and populates the SignedInfo.
void | soap_wsse_preparecleanup (struct soap *soap, struct soap_wsse_data *data)
| Restores engine state.
int | soap_wsse_disconnect (struct soap *soap)
| Verify signature and SignedInfo digests initiated with soap_wsse_verify_auto.
size_t | soap_wsse_verify_nested (struct soap *soap, struct soap_dom_element *dom, const char *URI, const char *tag)
| Counts signed matching elements from the dom node and down.
_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, wsse__FaultcodeEnum fault, const char *detail)
| Sets SOAP Fault (sub)code for server response.
int | soap_wsse (struct soap *soap, struct soap_plugin *p, void *arg)
| Plugin registry function, used with soap_register_plugin.
int | soap_wsse_init (struct soap *soap, struct soap_wsse_data *data, const void *(*arg)(struct soap *, int alg, int *keylen))
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.
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_wee_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_wee_verify_auto.

## Variables

const char | soap_wsse_id [14] = SOAP_WSSE_ID
const char * | wsse_PasswordTextURI = "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText"
const char * | wsse_PasswordDigestURI = "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordDigest"
const char * | wsse_Base64BinaryURI = "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary"
const char * | wsse_X509v3URI = "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3"
const char * | wsse_X509v3SubjectKeyIdentifierURI = "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509SubjectKeyIdentifier"
const char * | ds_sha1URI = "http://www.w3.org/2000/09/xmldsig#sha1"
const char * | ds_hmac_sha1URI = "http://www.w3.org/2000/09/xmldsig#hmac-sha1"
const char * | ds_dsa_sha1URI = "http://www.w3.org/2000/09/xmldsig#dsa-sha1"
const char * | ds_rsa_sha1URI = "http://www.w3.org/2000/09/xmldsig#rsa-sha1"
const char * | ds_URI = "http://www.w3.org/2000/09/xmldsig#"
const char * | c14n_URI = "http://www.w3.org/2001/10/xml-exc-c14n#"
const char * | wsu_URI = "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
soap_wsse_session * | soap_wsse_session = NULL
MUTEX_TYPE | soap_wsse_session_lock = PTHREAD_MUTEX_INITIALIZER

## Define Documentation

#define SOAP_WSSE_CLKSKEW (300)

| Clock skew between machines (in sec) to fit message expiration in window

#define SOAP_WSSE_MAX_REF (100)

| Maximum number of SignedInfo References

#define SOAP_WSSE_NONCELEN (20)

| Size of the random nonce

#define SOAP_WSSE_NONCETIME (SOAP_WSSE_CLKSKEW + 240)

| Digest authentication accepts messages that are not older than creation time + SOAP_WSSE_NONCETIME

## Function Documentation

void calc_digest | ( | struct soap * | soap,
|  | const char * | created,
|  | const char * | nonce,
|  | int | noncelen,
|  | const char * | password,
|  | char | hash[SOAP_SMD_SHA1_SIZE]
| ) | `[static]`

Calculates digest value SHA1(created, nonce, password).

Parameters:

  | soap | context
  `[in]` | created | string (XSD dateTime format)
  `[in]` | nonce | value
  `[in]` | noncelen | length of nonce value
  `[in]` | password | string
  `[out]` | hash | SHA1 digest

void calc_nonce | ( | struct soap * | soap,
|  | char | nonce[SOAP_WSSE_NONCELEN]
| ) | `[static]`

Calculates randomized nonce (also uses time() in case a poorly seeded PRNG is used).

Parameters:

  | soap | context
  `[out]` | nonce | value

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.

struct 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

struct _wsse__Security* soap_wsse_add_Security | ( | struct soap * | soap | ) |

Adds Security header element.

Parameters:

  | soap | context

Returns:
  _wsse__Security object

struct _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

struct 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.

struct 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.

struct _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_copy | ( | struct soap * | soap,
|  | struct soap_plugin * | dst,
|  | struct soap_plugin * | src
| ) | `[static]`

Copies plugin data to localize plugin data for threads.

Parameters:

  | soap | context
  `[out]` | dst | target plugin
  `[in]` | src | source plugin

Returns:
  SOAP_OK

void soap_wsse_delete | ( | struct soap * | soap,
|  | struct soap_plugin * | p
| ) | `[static]`

Deletes plugin data.

Parameters:

  | soap | context
  `[in,out]` | p | plugin

Returns:
  SOAP_OK

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_disconnect | ( | struct soap * | soap | ) | `[static]`

Verify signature and SignedInfo digests initiated with soap_wsse_verify_auto.

Parameters:

  | soap | context

Returns:
  SOAP_OK or fault

See also:
  soap_wsse_verify_auto

This callback is invoked just after a message was received.

int soap_wsse_fault | ( | struct soap * | soap,
|  | wsse__FaultcodeEnum | fault,
|  | const char * | detail
| ) |

Sets SOAP Fault (sub)code for server response.

Parameters:

  | soap | context
  `[in]` | fault | is one of wsse:FaultcodeEnum
  `[in]` | detail | string with optional text message

Returns:
  SOAP_FAULT

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

const char* 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.

int soap_wsse_init | ( | struct soap * | soap,
|  | struct soap_wsse_data * | data,
|  | const void *(* | arg)(struct soap *, int alg, int *keylen)
| ) | `[static]`

int soap_wsse_init | ( | struct soap * | soap,
|  | struct soap_wsse_data * | data,
|  | const void *(* | arg)(struct soap *, int, int *)
| ) | `[static]`

struct ds__KeyInfoType* soap_wsse_KeyInfo | ( | struct soap * | soap | ) |

Returns KeyInfo element if present.

Parameters:

  | soap | context

Returns:
  ds__KeyInfo object or NULL

void soap_wsse_preparecleanup | ( | struct soap * | soap,
|  | struct soap_wsse_data * | data
| ) | `[static]`

Restores engine state.

Parameters:

  | soap | context
  `[in,out]` | data | plugin data

int soap_wsse_preparefinalsend | ( | struct soap * | soap | ) | `[static]`

Collects the digests of all the wsu:Id elements and populates the SignedInfo.

Parameters:

  | soap | context

Returns:
  SOAP_OK or fault

This callback is invoked just before the message is send.

int soap_wsse_preparesend | ( | struct soap * | soap,
|  | const char * | buf,
|  | size_t | len
| ) | `[static]`

Takes a piece of the XML message (tokenized) to compute digest.

Parameters:

  | soap | context
  `[in]` | buf | string (XML "tokenized") to be send
  `[in]` | len | buf length

Returns:
  SOAP_OK or fault

This callback is invoked to analyze a message (usually during the HTTP content length phase). Note: nested elements with wsu:Id attributes cannot be individually signed in this release.

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

struct _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

void soap_wsse_session_cleanup | ( | struct soap * | soap | ) | `[static]`

Removes expired authentication data from the digest authentication session database.

Parameters:

  | soap | context

int soap_wsse_session_verify | ( | struct soap * | soap,
|  | const char | hash[SOAP_SMD_SHA1_SIZE],
|  | const char * | created,
|  | const char * | nonce
| ) | `[static]`

Verifies and updates the digest, nonce, and creation time against the digest authentication session database to prevent replay attacks.

Parameters:

  | soap | context
  `[in]` | hash | binary digest value of PasswordDigest
  `[in]` | created | string
  `[in]` | nonce | string (base64)

Returns:
  SOAP_OK or 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.

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.

struct ds__SignatureType* soap_wsse_Signature | ( | struct soap * | soap | ) |

Returns Signature header element if present.

Parameters:

  | soap | context

Returns:
  ds__SignatureType object or NULL

struct ds__SignedInfoType* soap_wsse_SignedInfo | ( | struct soap * | soap | ) |

Returns SignedInfo element if present.

Parameters:

  | soap | context

Returns:
  ds__SignedInfoType object or NULL

struct _wsu__Timestamp* soap_wsse_Timestamp | ( | struct soap * | soap | ) |

Returns Timestamp element if present.

Parameters:

  | soap | context

Returns:
  _wsu__Timestamp object or NULL

struct _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_wee_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_wee_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_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.

size_t soap_wsse_verify_nested | ( | struct soap * | soap,
|  | struct soap_dom_element * | dom,
|  | const char * | URI,
|  | const char * | tag
| ) | `[static]`

Counts signed matching elements from the dom node and down.

Parameters:

  | soap | context
  | dom | node to check and down
  | URI | namespace of element(s)
  | tag | name of element(s)

Returns:
  number of matching elements.

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.

## Variable Documentation

const char* c14n_URI = "http://www.w3.org/2001/10/xml-exc-c14n#"

const char* ds_dsa_sha1URI = "http://www.w3.org/2000/09/xmldsig#dsa-sha1"

const char* ds_hmac_sha1URI = "http://www.w3.org/2000/09/xmldsig#hmac-sha1"

const char* ds_rsa_sha1URI = "http://www.w3.org/2000/09/xmldsig#rsa-sha1"

const char* ds_sha1URI = "http://www.w3.org/2000/09/xmldsig#sha1"

const char* ds_URI = "http://www.w3.org/2000/09/xmldsig#"

const char soap_wsse_id[14] = SOAP_WSSE_ID

| Plugin identification for plugin registry

struct soap_wsse_session* soap_wsse_session = NULL`[static]`

| The digest authentication session database

MUTEX_TYPE soap_wsse_session_lock = PTHREAD_MUTEX_INITIALIZER`[static]`

| Lock for digest authentication session database exclusive access

const char* wsse_Base64BinaryURI = "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary"

const char* wsse_PasswordDigestURI = "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordDigest"

const char* wsse_PasswordTextURI = "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText"

const char* wsse_X509v3SubjectKeyIdentifierURI = "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509SubjectKeyIdentifier"

const char* wsse_X509v3URI = "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3"

const char* wsu_URI = "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"