summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorGravatar m0gg2006-12-09 09:35:00 +0000
committerGravatar m0gg2006-12-09 09:35:00 +0000
commit4cee250ec85cbbff7c8b943c856bce6685322d8e (patch)
treedabf1ae6369847ebf709a9fda82c86ca44c5fda4
parentc6e5a6765f5377d22f87d224fc4cc957a20c2f6b (diff)
downloadcsoap-4cee250ec85cbbff7c8b943c856bce6685322d8e.tar.gz
csoap-4cee250ec85cbbff7c8b943c856bce6685322d8e.tar.bz2
Documentation enhancements
-rw-r--r--libcsoap/soap-xmlsec.h52
1 files changed, 29 insertions, 23 deletions
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 <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
+ * - 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
+ * - 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
+ * - 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
+ * - 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
@@ -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 <SOAP-SEC:Signature> 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.