From 4cee250ec85cbbff7c8b943c856bce6685322d8e Mon Sep 17 00:00:00 2001 From: m0gg Date: Sat, 9 Dec 2006 09:35:00 +0000 Subject: Documentation enhancements --- libcsoap/soap-xmlsec.h | 52 ++++++++++++++++++++++++++++---------------------- 1 file changed, 29 insertions(+), 23 deletions(-) (limited to 'libcsoap') diff --git a/libcsoap/soap-xmlsec.h b/libcsoap/soap-xmlsec.h index 31ee408..7026d9c 100644 --- a/libcsoap/soap-xmlsec.h +++ b/libcsoap/soap-xmlsec.h @@ -1,5 +1,5 @@ /****************************************************************** - * $Id: soap-xmlsec.h,v 1.5 2006/12/06 11:27:21 m0gg Exp $ + * $Id: soap-xmlsec.h,v 1.6 2006/12/09 09:35:00 m0gg Exp $ * * CSOAP Project: A SOAP client/server library in C * Copyright (C) 2006 Heiko Ronsdorf @@ -26,12 +26,12 @@ /** @file * - * Web Services Security + * \section Web Services Security * * This module is implemented using the xmlsec1 library. * * @author H. Ronsdorf - * @version $Revision: 1.5 $ + * @version $Revision: 1.6 $ * * @see http://www.w3.org/TR/SOAP-dsig/ * @see http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=wss @@ -44,14 +44,14 @@ /** * - * Commandline argument to enabled 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 + * Commandline argument to set the keyfile. If this argument is not specified, a * random key will be used. * */ @@ -71,6 +71,12 @@ */ #define CSOAP_XMLSEC_CERTFILE "-CSOAPcertfile" +/** @defgroup xmlsec_errors XML-security errors + * + * Various errors related to XML-security + * + */ +/*@{*/ #define XMLSEC_ERROR 5100 #define XMLSEC_ERROR_GENERIC (XMLSEC_ERROR + 0) #define XMLSEC_ERROR_KEYSTORE (XMLSEC_ERROR + 10) @@ -84,6 +90,7 @@ #define XMLSEC_ERROR_SIGN_INIT (XMLSEC_ERROR + 90) #define XMLSEC_ERROR_ENCRYPT (XMLSEC_ERROR + 100) #define XMLSEC_ERROR_ENCRYPT_INIT (XMLSEC_ERROR + 110) +/*@}*/ #ifdef __cplusplus extern "C" { @@ -119,17 +126,17 @@ extern herror_t soap_xmlsec_client_init_args(int argc, char **argv); * the commandline. Our way to create a header entry is as * follows: * - * # Prepare the target SOAP Envelope with the body and necessary headers. - * # Create a template of a element. The template is assumed to + * - Prepare the target SOAP Envelope with the body and necessary headers. + * - Create a template of a element. The template is assumed to * contain empty contents for or elements, * but contains appropriate values for the elements such as * and required to calculate them. - * # Create a new header entry and add the template to this + * - Create a new header entry and add the template to this * entry. - * # Add the header entry to the SOAP Header. - * # Add the SOAP "actor" and "mustUnderstand" attributes to the entry, if + * - Add the header entry to the SOAP Header. + * - Add the SOAP "actor" and "mustUnderstand" attributes to the entry, if * necessary. - * # Calculate the and elements according + * - Calculate the and 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 @@ -144,12 +151,12 @@ extern herror_t soap_xmlsec_client_init_args(int argc, char **argv); * in the XML-Signature specification may be useful when signing the entire * Envelope including other header entries, if any. * - * @param envelope The SOAP envelope to be signed. + * @param context The SOAP context to be signed. * * @return H_OK on success * - * @see http://www.w3.org/TR/SOAP-dsig/, - * http://www.w3.org/TR/xmldsig-core/ + * @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); @@ -159,23 +166,23 @@ extern herror_t soap_xmlsec_sign(struct SoapCtx *context); * Verify a XML documents signature contained in a SOAP Envelope. The validation * of a header entry fails if: * - * # The syntax of the content of the header entry does not conform to SOAP + * - 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 + * - 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 + * - 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 envelope The SOAP envelope to be verified. + * @param context The SOAP context to be verified. * * @return H_OK on success * - * @see http://www.w3.org/TR/SOAP-dsig/, - * http://www.w3.org/TR/xmldsig-core/ + * @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); @@ -184,7 +191,7 @@ extern herror_t soap_xmlsec_verify(struct SoapCtx *context); * * Encrypt a XML document contained in a SOAP envelope. * - * @param envelope The SOAP envelope to be encrypted. + * @param context The SOAP context to be encrypted. * * @return H_OK on success * @@ -195,14 +202,13 @@ extern herror_t soap_xmlsec_encrypt(struct SoapCtx *context); * * Decrupt a XML document contained in a SOAP envelope. * - * @param envelope The SOAP envelope to be decrypted. + * @param context The SOAP context to be decrypted. * * @return H_OK on success * */ extern herror_t soap_xmlsec_decrypt(struct SoapCtx *context); - /** * * Frees the resources needed by the XML security subsystem. -- cgit v1.1-32-gdbae