diff options
Diffstat (limited to 'libcsoap/soap-xmlsec.h')
| -rw-r--r-- | libcsoap/soap-xmlsec.h | 170 |
1 files changed, 78 insertions, 92 deletions
diff --git a/libcsoap/soap-xmlsec.h b/libcsoap/soap-xmlsec.h index 2952368..89b00e7 100644 --- a/libcsoap/soap-xmlsec.h +++ b/libcsoap/soap-xmlsec.h @@ -1,5 +1,5 @@ /****************************************************************** - * $Id: soap-xmlsec.h,v 1.9 2007/01/25 10:28:30 m0gg Exp $ + * $Id: soap-xmlsec.h,v 1.10 2007/11/03 22:40:10 m0gg Exp $ * * CSOAP Project: A SOAP client/server library in C * Copyright (C) 2006 Heiko Ronsdorf @@ -49,57 +49,48 @@ * * @see nanohttp_ssl_page * @see http://www.aleksey.com/xmlsec/ - * */ -/** @file +/** @file soap-xmlsec.h xmlsec wrapper + * + * @defgroup CSOAP_WSS Web Service Security + * @ingroup CSOAP * * @section soap_wss_sec Web Services Security * * This module is implemented using the xmlsec1 library. * * @author H. Ronsdorf - * @version $Revision: 1.9 $ + * @version $Revision: 1.10 $ * * @see http://www.w3.org/TR/SOAP-dsig/ * @see http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=wss * @see http://www.aleksey.com/xmlsec/ - * */ +/**@{*/ #define SOAP_SECURITY_NAMESPACE "http://schemas.xmlsoap.org/soap/security/2000-12" #define SOAP_SECURITY_PREFIX "SOAP-SEC" -/** - * - * Commandline argument to enable WS-Security. - * +/** Commandline argument to enable WS-Security. */ #define CSOAP_ENABLE_XMLSEC "-CSOAPxmlsec" -/** - * - * Commandline argument to set the keyfile. If this argument is not specified, a - * random key will be used. - * +/** Commandline argument to set the keyfile. If this argument is not + * specified, a random key will be used. */ #define CSOAP_XMLSEC_KEYFILE "-CSOAPkeyfile" -/** - * - * Commandline argument to set the password of the key. - * +/** Commandline argument to set the password of the key. */ #define CSOAP_XMLSEC_PASSWORD "-CSOAPpassword" -/** - * - * Commandline argument to set a file of certificates. - * +/** Commandline argument to set a file of certificates. */ #define CSOAP_XMLSEC_CERTFILE "-CSOAPcertfile" -/** @defgroup xmlsec_errors XML-security errors +/** @defgroup CSOAP_XMLSEC_ERRORS XML-security errors + * @ingroup CSOAP_ERRORS * * Various errors related to XML-security * @@ -124,123 +115,116 @@ extern "C" { #endif -/** - * - * Initializes the WS-Security subsystem. +/** This function initializes the WS-Security subsystem for a SOAP + * server. * * @param argc commandline arg count * @param argv commandline arg vector * - * @return H_OK on success + * @return H_OK on success. * + * @see soap_xmlsec_destroy() */ extern herror_t soap_xmlsec_server_init_args(int argc, char **argv); -/** - * - * Initializes the WS-Security subsystem. +/** This function initializes the WS-Security subsystem for a SOAP + * client. * * @param argc commandline arg count * @param argv commandline arg vector * - * @return H_OK on success + * @return H_OK on success. * + * @see soap_xmlsec_destroy() */ extern herror_t soap_xmlsec_client_init_args(int argc, char **argv); -/** - * - * Sign a 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. +/** 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. + * - 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. * * @param context The SOAP context to be signed. * - * @return H_OK on success + * @return H_OK on success. * * @see http://www.w3.org/TR/SOAP-dsig/ * @see http://www.w3.org/TR/xmldsig-core/ - * */ extern herror_t soap_xmlsec_sign(struct SoapCtx *context); -/** - * - * Verify a 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. +/** 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. * * @param context The SOAP context to be verified. * - * @return H_OK on success + * @return H_OK on success. * * @see http://www.w3.org/TR/SOAP-dsig/ * @see http://www.w3.org/TR/xmldsig-core/ - * */ extern herror_t soap_xmlsec_verify(struct SoapCtx *context); -/** - * - * Encrypt a XML document contained in a SOAP envelope. +/** This function encrypts an XML document contained in a SOAP + * envelope. * * @param context The SOAP context to be encrypted. * - * @return H_OK on success - * + * @return H_OK on success. */ extern herror_t soap_xmlsec_encrypt(struct SoapCtx *context); -/** - * - * Decrupt a XML document contained in a SOAP envelope. +/** This function decrypts an XML document contained in a SOAP + * envelope. * * @param context The SOAP context to be decrypted. * - * @return H_OK on success - * + * @return H_OK on success. */ extern herror_t soap_xmlsec_decrypt(struct SoapCtx *context); -/** - * - * Frees the resources needed by the XML security subsystem. +/** This function frees the resources needed by the XML security + * subsystem. * + * @see soap_xmlsec_init() */ extern void soap_xmlsec_destroy(void); @@ -248,4 +232,6 @@ extern void soap_xmlsec_destroy(void); } #endif +/**@}*/ + #endif |