/****************************************************************** * $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 * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Library General Public * License as published by the Free Software Foundation; either * version 2 of the License, or (at your option) any later version. * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Library General Public License for more details. * * You should have received a copy of the GNU Library General Public * License along with this library; if not, write to the * Free Software Foundation, Inc., 59 Temple Place - Suite 330, * Boston, MA 02111-1307, USA. * * Email: hero@persua.de ******************************************************************/ #ifndef __csoap_xmlsec_h #define __csoap_xmlsec_h /** @page csoap_xmlsec_page Howto use xmlsec with csoap * * @section csoap_xmlsec_toc Table of contents * * - @ref csoap_xmlsec_key_sec * - @ref csoap_xmlsec_cert_sec * - @ref csoap_xmlsec_cmdline_sec * * @section csoap_xmlsec_key_sec Simple key generation * @section csoap_xmlsec_cert_sec Generate a key with a certificate * @section csoap_xmlsec_cmdline_sec Commandline arguments for startup * * @code * -CSOAPxmlsec Commandline argument to enable WS-Security. * * -CSOAPkeyfile Commandline argument to set the keyfile. If this argument is * not specified, a random key will be generated. * * -CSOAPpassword Commandline argument to set the password of the key. * * -CSOAPcertfile Commandline argument to set a file of certificates. * @endcode * * @see nanohttp_ssl_page * @see http://www.aleksey.com/xmlsec/ */ /** @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.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. */ #define CSOAP_ENABLE_XMLSEC "-CSOAPxmlsec" /** 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. */ #define CSOAP_XMLSEC_PASSWORD "-CSOAPpassword" /** Commandline argument to set a file of certificates. */ #define CSOAP_XMLSEC_CERTFILE "-CSOAPcertfile" /** @defgroup CSOAP_XMLSEC_ERRORS XML-security errors * @ingroup CSOAP_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) #define XMLSEC_ERROR_KEYMANAGER (XMLSEC_ERROR + 20) #define XMLSEC_ERROR_KEY (XMLSEC_ERROR + 30) #define XMLSEC_ERROR_CERTIFICATE (XMLSEC_ERROR + 40) #define XMLSEC_ERROR_INIT (XMLSEC_ERROR + 50) #define XMLSEC_ERROR_VERSION (XMLSEC_ERROR + 60) #define XMLSEC_ERROR_DLLOAD (XMLSEC_ERROR + 70) #define XMLSEC_ERROR_SIGN (XMLSEC_ERROR + 80) #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" { #endif /** 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. * * @see soap_xmlsec_destroy() */ extern herror_t soap_xmlsec_server_init_args(int argc, char **argv); /** 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. * * @see soap_xmlsec_destroy() */ extern herror_t soap_xmlsec_client_init_args(int argc, char **argv); /** This function signs an XML document contained in a SOAP Envelope * with the key specified on 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 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 entry. * - 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 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. * * @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); /** This function verifies an 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 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. * * @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); /** This function encrypts an XML document contained in a SOAP * envelope. * * @param context The SOAP context to be encrypted. * * @return H_OK on success. */ extern herror_t soap_xmlsec_encrypt(struct SoapCtx *context); /** This function decrypts an XML document contained in a SOAP * envelope. * * @param context The SOAP context to be decrypted. * * @return H_OK on success. */ extern herror_t soap_xmlsec_decrypt(struct SoapCtx *context); /** This function frees the resources needed by the XML security * subsystem. * * @see soap_xmlsec_init() */ extern void soap_xmlsec_destroy(void); #ifdef __cplusplus } #endif /**@}*/ #endif