1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
|
/******************************************************************
* $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
* <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.
*
* @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 <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.
*
* @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
|
