]>
Commit | Line | Data |
---|---|---|
458781c7 JB |
1 | --- libmicrohttpd-0.9.24/doc/ecos.texi.orig 1970-01-01 01:00:00.000000000 +0100 |
2 | +++ libmicrohttpd-0.9.24/doc/ecos.texi 2013-01-03 19:01:45.646387769 +0100 | |
3 | @@ -0,0 +1,420 @@ | |
4 | +@cindex GPL, GNU General Public License | |
5 | +@cindex eCos, GNU General Public License with eCos Extension | |
6 | +@center Version 2, June 1991 | |
7 | + | |
8 | +@display | |
9 | +Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc. | |
10 | +59 Temple Place -- Suite 330, Boston, MA 02111-1307, USA | |
11 | + | |
12 | +Everyone is permitted to copy and distribute verbatim copies | |
13 | +of this license document, but changing it is not allowed. | |
14 | +@end display | |
15 | + | |
16 | + | |
17 | + | |
18 | + | |
19 | +@subheading Preamble | |
20 | + | |
21 | + The licenses for most software are designed to take away your | |
22 | +freedom to share and change it. By contrast, the GNU General Public | |
23 | +License is intended to guarantee your freedom to share and change free | |
24 | +software---to make sure the software is free for all its users. This | |
25 | +General Public License applies to most of the Free Software | |
26 | +Foundation's software and to any other program whose authors commit to | |
27 | +using it. (Some other Free Software Foundation software is covered by | |
28 | +the GNU Library General Public License instead.) You can apply it to | |
29 | +your programs, too. | |
30 | + | |
31 | + When we speak of free software, we are referring to freedom, not | |
32 | +price. Our General Public Licenses are designed to make sure that you | |
33 | +have the freedom to distribute copies of free software (and charge for | |
34 | +this service if you wish), that you receive source code or can get it | |
35 | +if you want it, that you can change the software or use pieces of it | |
36 | +in new free programs; and that you know you can do these things. | |
37 | + | |
38 | + To protect your rights, we need to make restrictions that forbid | |
39 | +anyone to deny you these rights or to ask you to surrender the rights. | |
40 | +These restrictions translate to certain responsibilities for you if you | |
41 | +distribute copies of the software, or if you modify it. | |
42 | + | |
43 | + For example, if you distribute copies of such a program, whether | |
44 | +gratis or for a fee, you must give the recipients all the rights that | |
45 | +you have. You must make sure that they, too, receive or can get the | |
46 | +source code. And you must show them these terms so they know their | |
47 | +rights. | |
48 | + | |
49 | + We protect your rights with two steps: (1) copyright the software, and | |
50 | +(2) offer you this license which gives you legal permission to copy, | |
51 | +distribute and/or modify the software. | |
52 | + | |
53 | + Also, for each author's protection and ours, we want to make certain | |
54 | +that everyone understands that there is no warranty for this free | |
55 | +software. If the software is modified by someone else and passed on, we | |
56 | +want its recipients to know that what they have is not the original, so | |
57 | +that any problems introduced by others will not reflect on the original | |
58 | +authors' reputations. | |
59 | + | |
60 | + Finally, any free program is threatened constantly by software | |
61 | +patents. We wish to avoid the danger that redistributors of a free | |
62 | +program will individually obtain patent licenses, in effect making the | |
63 | +program proprietary. To prevent this, we have made it clear that any | |
64 | +patent must be licensed for everyone's free use or not licensed at all. | |
65 | + | |
66 | + The precise terms and conditions for copying, distribution and | |
67 | +modification follow. | |
68 | + | |
69 | +@iftex | |
70 | +@subheading TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION | |
71 | +@end iftex | |
72 | +@ifinfo | |
73 | +@center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION | |
74 | +@end ifinfo | |
75 | + | |
76 | +@enumerate | |
77 | +@item | |
78 | +This License applies to any program or other work which contains | |
79 | +a notice placed by the copyright holder saying it may be distributed | |
80 | +under the terms of this General Public License. The ``Program'', below, | |
81 | +refers to any such program or work, and a ``work based on the Program'' | |
82 | +means either the Program or any derivative work under copyright law: | |
83 | +that is to say, a work containing the Program or a portion of it, | |
84 | +either verbatim or with modifications and/or translated into another | |
85 | +language. (Hereinafter, translation is included without limitation in | |
86 | +the term ``modification''.) Each licensee is addressed as ``you''. | |
87 | + | |
88 | +Activities other than copying, distribution and modification are not | |
89 | +covered by this License; they are outside its scope. The act of | |
90 | +running the Program is not restricted, and the output from the Program | |
91 | +is covered only if its contents constitute a work based on the | |
92 | +Program (independent of having been made by running the Program). | |
93 | +Whether that is true depends on what the Program does. | |
94 | + | |
95 | +@item | |
96 | +You may copy and distribute verbatim copies of the Program's | |
97 | +source code as you receive it, in any medium, provided that you | |
98 | +conspicuously and appropriately publish on each copy an appropriate | |
99 | +copyright notice and disclaimer of warranty; keep intact all the | |
100 | +notices that refer to this License and to the absence of any warranty; | |
101 | +and give any other recipients of the Program a copy of this License | |
102 | +along with the Program. | |
103 | + | |
104 | +You may charge a fee for the physical act of transferring a copy, and | |
105 | +you may at your option offer warranty protection in exchange for a fee. | |
106 | + | |
107 | +@item | |
108 | +You may modify your copy or copies of the Program or any portion | |
109 | +of it, thus forming a work based on the Program, and copy and | |
110 | +distribute such modifications or work under the terms of Section 1 | |
111 | +above, provided that you also meet all of these conditions: | |
112 | + | |
113 | +@enumerate a | |
114 | +@item | |
115 | +You must cause the modified files to carry prominent notices | |
116 | +stating that you changed the files and the date of any change. | |
117 | + | |
118 | +@item | |
119 | +You must cause any work that you distribute or publish, that in | |
120 | +whole or in part contains or is derived from the Program or any | |
121 | +part thereof, to be licensed as a whole at no charge to all third | |
122 | +parties under the terms of this License. | |
123 | + | |
124 | +@item | |
125 | +If the modified program normally reads commands interactively | |
126 | +when run, you must cause it, when started running for such | |
127 | +interactive use in the most ordinary way, to print or display an | |
128 | +announcement including an appropriate copyright notice and a | |
129 | +notice that there is no warranty (or else, saying that you provide | |
130 | +a warranty) and that users may redistribute the program under | |
131 | +these conditions, and telling the user how to view a copy of this | |
132 | +License. (Exception: if the Program itself is interactive but | |
133 | +does not normally print such an announcement, your work based on | |
134 | +the Program is not required to print an announcement.) | |
135 | +@end enumerate | |
136 | + | |
137 | +These requirements apply to the modified work as a whole. If | |
138 | +identifiable sections of that work are not derived from the Program, | |
139 | +and can be reasonably considered independent and separate works in | |
140 | +themselves, then this License, and its terms, do not apply to those | |
141 | +sections when you distribute them as separate works. But when you | |
142 | +distribute the same sections as part of a whole which is a work based | |
143 | +on the Program, the distribution of the whole must be on the terms of | |
144 | +this License, whose permissions for other licensees extend to the | |
145 | +entire whole, and thus to each and every part regardless of who wrote it. | |
146 | + | |
147 | +Thus, it is not the intent of this section to claim rights or contest | |
148 | +your rights to work written entirely by you; rather, the intent is to | |
149 | +exercise the right to control the distribution of derivative or | |
150 | +collective works based on the Program. | |
151 | + | |
152 | +In addition, mere aggregation of another work not based on the Program | |
153 | +with the Program (or with a work based on the Program) on a volume of | |
154 | +a storage or distribution medium does not bring the other work under | |
155 | +the scope of this License. | |
156 | + | |
157 | +@item | |
158 | +You may copy and distribute the Program (or a work based on it, | |
159 | +under Section 2) in object code or executable form under the terms of | |
160 | +Sections 1 and 2 above provided that you also do one of the following: | |
161 | + | |
162 | +@enumerate a | |
163 | +@item | |
164 | +Accompany it with the complete corresponding machine-readable | |
165 | +source code, which must be distributed under the terms of Sections | |
166 | +1 and 2 above on a medium customarily used for software interchange; or, | |
167 | + | |
168 | +@item | |
169 | +Accompany it with a written offer, valid for at least three | |
170 | +years, to give any third party, for a charge no more than your | |
171 | +cost of physically performing source distribution, a complete | |
172 | +machine-readable copy of the corresponding source code, to be | |
173 | +distributed under the terms of Sections 1 and 2 above on a medium | |
174 | +customarily used for software interchange; or, | |
175 | + | |
176 | +@item | |
177 | +Accompany it with the information you received as to the offer | |
178 | +to distribute corresponding source code. (This alternative is | |
179 | +allowed only for noncommercial distribution and only if you | |
180 | +received the program in object code or executable form with such | |
181 | +an offer, in accord with Subsection b above.) | |
182 | +@end enumerate | |
183 | + | |
184 | +The source code for a work means the preferred form of the work for | |
185 | +making modifications to it. For an executable work, complete source | |
186 | +code means all the source code for all modules it contains, plus any | |
187 | +associated interface definition files, plus the scripts used to | |
188 | +control compilation and installation of the executable. However, as a | |
189 | +special exception, the source code distributed need not include | |
190 | +anything that is normally distributed (in either source or binary | |
191 | +form) with the major components (compiler, kernel, and so on) of the | |
192 | +operating system on which the executable runs, unless that component | |
193 | +itself accompanies the executable. | |
194 | + | |
195 | +If distribution of executable or object code is made by offering | |
196 | +access to copy from a designated place, then offering equivalent | |
197 | +access to copy the source code from the same place counts as | |
198 | +distribution of the source code, even though third parties are not | |
199 | +compelled to copy the source along with the object code. | |
200 | + | |
201 | +@item | |
202 | +You may not copy, modify, sublicense, or distribute the Program | |
203 | +except as expressly provided under this License. Any attempt | |
204 | +otherwise to copy, modify, sublicense or distribute the Program is | |
205 | +void, and will automatically terminate your rights under this License. | |
206 | +However, parties who have received copies, or rights, from you under | |
207 | +this License will not have their licenses terminated so long as such | |
208 | +parties remain in full compliance. | |
209 | + | |
210 | +@item | |
211 | +You are not required to accept this License, since you have not | |
212 | +signed it. However, nothing else grants you permission to modify or | |
213 | +distribute the Program or its derivative works. These actions are | |
214 | +prohibited by law if you do not accept this License. Therefore, by | |
215 | +modifying or distributing the Program (or any work based on the | |
216 | +Program), you indicate your acceptance of this License to do so, and | |
217 | +all its terms and conditions for copying, distributing or modifying | |
218 | +the Program or works based on it. | |
219 | + | |
220 | +@item | |
221 | +Each time you redistribute the Program (or any work based on the | |
222 | +Program), the recipient automatically receives a license from the | |
223 | +original licensor to copy, distribute or modify the Program subject to | |
224 | +these terms and conditions. You may not impose any further | |
225 | +restrictions on the recipients' exercise of the rights granted herein. | |
226 | +You are not responsible for enforcing compliance by third parties to | |
227 | +this License. | |
228 | + | |
229 | +@item | |
230 | +If, as a consequence of a court judgment or allegation of patent | |
231 | +infringement or for any other reason (not limited to patent issues), | |
232 | +conditions are imposed on you (whether by court order, agreement or | |
233 | +otherwise) that contradict the conditions of this License, they do not | |
234 | +excuse you from the conditions of this License. If you cannot | |
235 | +distribute so as to satisfy simultaneously your obligations under this | |
236 | +License and any other pertinent obligations, then as a consequence you | |
237 | +may not distribute the Program at all. For example, if a patent | |
238 | +license would not permit royalty-free redistribution of the Program by | |
239 | +all those who receive copies directly or indirectly through you, then | |
240 | +the only way you could satisfy both it and this License would be to | |
241 | +refrain entirely from distribution of the Program. | |
242 | + | |
243 | +If any portion of this section is held invalid or unenforceable under | |
244 | +any particular circumstance, the balance of the section is intended to | |
245 | +apply and the section as a whole is intended to apply in other | |
246 | +circumstances. | |
247 | + | |
248 | +It is not the purpose of this section to induce you to infringe any | |
249 | +patents or other property right claims or to contest validity of any | |
250 | +such claims; this section has the sole purpose of protecting the | |
251 | +integrity of the free software distribution system, which is | |
252 | +implemented by public license practices. Many people have made | |
253 | +generous contributions to the wide range of software distributed | |
254 | +through that system in reliance on consistent application of that | |
255 | +system; it is up to the author/donor to decide if he or she is willing | |
256 | +to distribute software through any other system and a licensee cannot | |
257 | +impose that choice. | |
258 | + | |
259 | +This section is intended to make thoroughly clear what is believed to | |
260 | +be a consequence of the rest of this License. | |
261 | + | |
262 | +@item | |
263 | +If the distribution and/or use of the Program is restricted in | |
264 | +certain countries either by patents or by copyrighted interfaces, the | |
265 | +original copyright holder who places the Program under this License | |
266 | +may add an explicit geographical distribution limitation excluding | |
267 | +those countries, so that distribution is permitted only in or among | |
268 | +countries not thus excluded. In such case, this License incorporates | |
269 | +the limitation as if written in the body of this License. | |
270 | + | |
271 | +@item | |
272 | +The Free Software Foundation may publish revised and/or new versions | |
273 | +of the General Public License from time to time. Such new versions will | |
274 | +be similar in spirit to the present version, but may differ in detail to | |
275 | +address new problems or concerns. | |
276 | + | |
277 | +Each version is given a distinguishing version number. If the Program | |
278 | +specifies a version number of this License which applies to it and ``any | |
279 | +later version'', you have the option of following the terms and conditions | |
280 | +either of that version or of any later version published by the Free | |
281 | +Software Foundation. If the Program does not specify a version number of | |
282 | +this License, you may choose any version ever published by the Free Software | |
283 | +Foundation. | |
284 | + | |
285 | +@item | |
286 | +If you wish to incorporate parts of the Program into other free | |
287 | +programs whose distribution conditions are different, write to the author | |
288 | +to ask for permission. For software which is copyrighted by the Free | |
289 | +Software Foundation, write to the Free Software Foundation; we sometimes | |
290 | +make exceptions for this. Our decision will be guided by the two goals | |
291 | +of preserving the free status of all derivatives of our free software and | |
292 | +of promoting the sharing and reuse of software generally. | |
293 | + | |
294 | +@iftex | |
295 | +@heading NO WARRANTY | |
296 | +@end iftex | |
297 | +@ifinfo | |
298 | +@center NO WARRANTY | |
299 | +@end ifinfo | |
300 | + | |
301 | +@item | |
302 | +BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY | |
303 | +FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN | |
304 | +OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES | |
305 | +PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED | |
306 | +OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF | |
307 | +MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS | |
308 | +TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE | |
309 | +PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, | |
310 | +REPAIR OR CORRECTION. | |
311 | + | |
312 | +@item | |
313 | +IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING | |
314 | +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR | |
315 | +REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, | |
316 | +INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING | |
317 | +OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED | |
318 | +TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY | |
319 | +YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER | |
320 | +PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE | |
321 | +POSSIBILITY OF SUCH DAMAGES. | |
322 | + | |
323 | +@iftex | |
324 | +@heading ECOS EXTENSION | |
325 | +@end iftex | |
326 | +@ifinfo | |
327 | +@center ECOS EXTENSION | |
328 | +@end ifinfo | |
329 | + | |
330 | + | |
331 | +@item | |
332 | +As a special exception, if other files instantiate templates or use | |
333 | +macros or inline functions from this file, or you compile this file | |
334 | +and link it with other works to produce a work based on this file, | |
335 | +this file does not by itself cause the resulting work to be covered by | |
336 | +the GNU General Public License. However the source code for this file | |
337 | +must still be made available in accordance with section (3) of the GNU | |
338 | +General Public License v2. | |
339 | + | |
340 | +This exception does not invalidate any other reasons why a work based | |
341 | +on this file might be covered by the GNU General Public License. | |
342 | + | |
343 | +@end enumerate | |
344 | + | |
345 | + | |
346 | +@iftex | |
347 | +@heading END OF TERMS AND CONDITIONS | |
348 | +@end iftex | |
349 | +@ifinfo | |
350 | +@center END OF TERMS AND CONDITIONS | |
351 | +@end ifinfo | |
352 | + | |
353 | +@page | |
354 | +@unnumberedsec How to Apply These Terms to Your New Programs | |
355 | + | |
356 | + If you develop a new program, and you want it to be of the greatest | |
357 | +possible use to the public, the best way to achieve this is to make it | |
358 | +free software which everyone can redistribute and change under these terms. | |
359 | + | |
360 | + To do so, attach the following notices to the program. It is safest | |
361 | +to attach them to the start of each source file to most effectively | |
362 | +convey the exclusion of warranty; and each file should have at least | |
363 | +the ``copyright'' line and a pointer to where the full notice is found. | |
364 | + | |
365 | +@smallexample | |
366 | +@var{one line to give the program's name and an idea of what it does.} | |
367 | +Copyright (C) 19@var{yy} @var{name of author} | |
368 | + | |
369 | +This program is free software; you can redistribute it and/or | |
370 | +modify it under the terms of the GNU General Public License | |
371 | +as published by the Free Software Foundation; either version 2 | |
372 | +of the License, or (at your option) any later version. | |
373 | + | |
374 | +This program is distributed in the hope that it will be useful, | |
375 | +but WITHOUT ANY WARRANTY; without even the implied warranty of | |
376 | +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
377 | +GNU General Public License for more details. | |
378 | + | |
379 | +You should have received a copy of the GNU General Public License along | |
380 | +with this program; if not, write to the Free Software Foundation, Inc., | |
381 | +59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. | |
382 | +@end smallexample | |
383 | + | |
384 | +Also add information on how to contact you by electronic and paper mail. | |
385 | + | |
386 | +If the program is interactive, make it output a short notice like this | |
387 | +when it starts in an interactive mode: | |
388 | + | |
389 | +@smallexample | |
390 | +Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author} | |
391 | +Gnomovision comes with ABSOLUTELY NO WARRANTY; for details | |
392 | +type `show w'. This is free software, and you are welcome | |
393 | +to redistribute it under certain conditions; type `show c' | |
394 | +for details. | |
395 | +@end smallexample | |
396 | + | |
397 | +The hypothetical commands @samp{show w} and @samp{show c} should show | |
398 | +the appropriate parts of the General Public License. Of course, the | |
399 | +commands you use may be called something other than @samp{show w} and | |
400 | +@samp{show c}; they could even be mouse-clicks or menu items---whatever | |
401 | +suits your program. | |
402 | + | |
403 | +You should also get your employer (if you work as a programmer) or your | |
404 | +school, if any, to sign a ``copyright disclaimer'' for the program, if | |
405 | +necessary. Here is a sample; alter the names: | |
406 | + | |
407 | +@smallexample | |
408 | +@group | |
409 | +Yoyodyne, Inc., hereby disclaims all copyright | |
410 | +interest in the program `Gnomovision' | |
411 | +(which makes passes at compilers) written | |
412 | +by James Hacker. | |
413 | + | |
414 | +@var{signature of Ty Coon}, 1 April 1989 | |
415 | +Ty Coon, President of Vice | |
416 | +@end group | |
417 | +@end smallexample | |
418 | + | |
419 | +This General Public License does not permit incorporating your program into | |
420 | +proprietary programs. If your program is a subroutine library, you may | |
421 | +consider it more useful to permit linking proprietary applications with the | |
422 | +library. If this is what you want to do, use the GNU Library General | |
423 | +Public License instead of this License. | |
424 | --- libmicrohttpd-0.9.24/doc/fdl-1.3.texi.orig 1970-01-01 01:00:00.000000000 +0100 | |
425 | +++ libmicrohttpd-0.9.24/doc/fdl-1.3.texi 2013-01-03 19:01:45.646387769 +0100 | |
426 | @@ -0,0 +1,506 @@ | |
427 | +@c The GNU Free Documentation License. | |
428 | +@center Version 1.3, 3 November 2008 | |
429 | + | |
430 | +@c This file is intended to be included within another document, | |
431 | +@c hence no sectioning command or @node. | |
432 | + | |
433 | +@display | |
434 | +Copyright @copyright{} 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. | |
435 | +@uref{http://fsf.org/} | |
436 | + | |
437 | +Everyone is permitted to copy and distribute verbatim copies | |
438 | +of this license document, but changing it is not allowed. | |
439 | +@end display | |
440 | + | |
441 | +@enumerate 0 | |
442 | +@item | |
443 | +PREAMBLE | |
444 | + | |
445 | +The purpose of this License is to make a manual, textbook, or other | |
446 | +functional and useful document @dfn{free} in the sense of freedom: to | |
447 | +assure everyone the effective freedom to copy and redistribute it, | |
448 | +with or without modifying it, either commercially or noncommercially. | |
449 | +Secondarily, this License preserves for the author and publisher a way | |
450 | +to get credit for their work, while not being considered responsible | |
451 | +for modifications made by others. | |
452 | + | |
453 | +This License is a kind of ``copyleft'', which means that derivative | |
454 | +works of the document must themselves be free in the same sense. It | |
455 | +complements the GNU General Public License, which is a copyleft | |
456 | +license designed for free software. | |
457 | + | |
458 | +We have designed this License in order to use it for manuals for free | |
459 | +software, because free software needs free documentation: a free | |
460 | +program should come with manuals providing the same freedoms that the | |
461 | +software does. But this License is not limited to software manuals; | |
462 | +it can be used for any textual work, regardless of subject matter or | |
463 | +whether it is published as a printed book. We recommend this License | |
464 | +principally for works whose purpose is instruction or reference. | |
465 | + | |
466 | +@item | |
467 | +APPLICABILITY AND DEFINITIONS | |
468 | + | |
469 | +This License applies to any manual or other work, in any medium, that | |
470 | +contains a notice placed by the copyright holder saying it can be | |
471 | +distributed under the terms of this License. Such a notice grants a | |
472 | +world-wide, royalty-free license, unlimited in duration, to use that | |
473 | +work under the conditions stated herein. The ``Document'', below, | |
474 | +refers to any such manual or work. Any member of the public is a | |
475 | +licensee, and is addressed as ``you''. You accept the license if you | |
476 | +copy, modify or distribute the work in a way requiring permission | |
477 | +under copyright law. | |
478 | + | |
479 | +A ``Modified Version'' of the Document means any work containing the | |
480 | +Document or a portion of it, either copied verbatim, or with | |
481 | +modifications and/or translated into another language. | |
482 | + | |
483 | +A ``Secondary Section'' is a named appendix or a front-matter section | |
484 | +of the Document that deals exclusively with the relationship of the | |
485 | +publishers or authors of the Document to the Document's overall | |
486 | +subject (or to related matters) and contains nothing that could fall | |
487 | +directly within that overall subject. (Thus, if the Document is in | |
488 | +part a textbook of mathematics, a Secondary Section may not explain | |
489 | +any mathematics.) The relationship could be a matter of historical | |
490 | +connection with the subject or with related matters, or of legal, | |
491 | +commercial, philosophical, ethical or political position regarding | |
492 | +them. | |
493 | + | |
494 | +The ``Invariant Sections'' are certain Secondary Sections whose titles | |
495 | +are designated, as being those of Invariant Sections, in the notice | |
496 | +that says that the Document is released under this License. If a | |
497 | +section does not fit the above definition of Secondary then it is not | |
498 | +allowed to be designated as Invariant. The Document may contain zero | |
499 | +Invariant Sections. If the Document does not identify any Invariant | |
500 | +Sections then there are none. | |
501 | + | |
502 | +The ``Cover Texts'' are certain short passages of text that are listed, | |
503 | +as Front-Cover Texts or Back-Cover Texts, in the notice that says that | |
504 | +the Document is released under this License. A Front-Cover Text may | |
505 | +be at most 5 words, and a Back-Cover Text may be at most 25 words. | |
506 | + | |
507 | +A ``Transparent'' copy of the Document means a machine-readable copy, | |
508 | +represented in a format whose specification is available to the | |
509 | +general public, that is suitable for revising the document | |
510 | +straightforwardly with generic text editors or (for images composed of | |
511 | +pixels) generic paint programs or (for drawings) some widely available | |
512 | +drawing editor, and that is suitable for input to text formatters or | |
513 | +for automatic translation to a variety of formats suitable for input | |
514 | +to text formatters. A copy made in an otherwise Transparent file | |
515 | +format whose markup, or absence of markup, has been arranged to thwart | |
516 | +or discourage subsequent modification by readers is not Transparent. | |
517 | +An image format is not Transparent if used for any substantial amount | |
518 | +of text. A copy that is not ``Transparent'' is called ``Opaque''. | |
519 | + | |
520 | +Examples of suitable formats for Transparent copies include plain | |
521 | +@sc{ascii} without markup, Texinfo input format, La@TeX{} input | |
522 | +format, @acronym{SGML} or @acronym{XML} using a publicly available | |
523 | +@acronym{DTD}, and standard-conforming simple @acronym{HTML}, | |
524 | +PostScript or @acronym{PDF} designed for human modification. Examples | |
525 | +of transparent image formats include @acronym{PNG}, @acronym{XCF} and | |
526 | +@acronym{JPG}. Opaque formats include proprietary formats that can be | |
527 | +read and edited only by proprietary word processors, @acronym{SGML} or | |
528 | +@acronym{XML} for which the @acronym{DTD} and/or processing tools are | |
529 | +not generally available, and the machine-generated @acronym{HTML}, | |
530 | +PostScript or @acronym{PDF} produced by some word processors for | |
531 | +output purposes only. | |
532 | + | |
533 | +The ``Title Page'' means, for a printed book, the title page itself, | |
534 | +plus such following pages as are needed to hold, legibly, the material | |
535 | +this License requires to appear in the title page. For works in | |
536 | +formats which do not have any title page as such, ``Title Page'' means | |
537 | +the text near the most prominent appearance of the work's title, | |
538 | +preceding the beginning of the body of the text. | |
539 | + | |
540 | +The ``publisher'' means any person or entity that distributes copies | |
541 | +of the Document to the public. | |
542 | + | |
543 | +A section ``Entitled XYZ'' means a named subunit of the Document whose | |
544 | +title either is precisely XYZ or contains XYZ in parentheses following | |
545 | +text that translates XYZ in another language. (Here XYZ stands for a | |
546 | +specific section name mentioned below, such as ``Acknowledgements'', | |
547 | +``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title'' | |
548 | +of such a section when you modify the Document means that it remains a | |
549 | +section ``Entitled XYZ'' according to this definition. | |
550 | + | |
551 | +The Document may include Warranty Disclaimers next to the notice which | |
552 | +states that this License applies to the Document. These Warranty | |
553 | +Disclaimers are considered to be included by reference in this | |
554 | +License, but only as regards disclaiming warranties: any other | |
555 | +implication that these Warranty Disclaimers may have is void and has | |
556 | +no effect on the meaning of this License. | |
557 | + | |
558 | +@item | |
559 | +VERBATIM COPYING | |
560 | + | |
561 | +You may copy and distribute the Document in any medium, either | |
562 | +commercially or noncommercially, provided that this License, the | |
563 | +copyright notices, and the license notice saying this License applies | |
564 | +to the Document are reproduced in all copies, and that you add no other | |
565 | +conditions whatsoever to those of this License. You may not use | |
566 | +technical measures to obstruct or control the reading or further | |
567 | +copying of the copies you make or distribute. However, you may accept | |
568 | +compensation in exchange for copies. If you distribute a large enough | |
569 | +number of copies you must also follow the conditions in section 3. | |
570 | + | |
571 | +You may also lend copies, under the same conditions stated above, and | |
572 | +you may publicly display copies. | |
573 | + | |
574 | +@item | |
575 | +COPYING IN QUANTITY | |
576 | + | |
577 | +If you publish printed copies (or copies in media that commonly have | |
578 | +printed covers) of the Document, numbering more than 100, and the | |
579 | +Document's license notice requires Cover Texts, you must enclose the | |
580 | +copies in covers that carry, clearly and legibly, all these Cover | |
581 | +Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on | |
582 | +the back cover. Both covers must also clearly and legibly identify | |
583 | +you as the publisher of these copies. The front cover must present | |
584 | +the full title with all words of the title equally prominent and | |
585 | +visible. You may add other material on the covers in addition. | |
586 | +Copying with changes limited to the covers, as long as they preserve | |
587 | +the title of the Document and satisfy these conditions, can be treated | |
588 | +as verbatim copying in other respects. | |
589 | + | |
590 | +If the required texts for either cover are too voluminous to fit | |
591 | +legibly, you should put the first ones listed (as many as fit | |
592 | +reasonably) on the actual cover, and continue the rest onto adjacent | |
593 | +pages. | |
594 | + | |
595 | +If you publish or distribute Opaque copies of the Document numbering | |
596 | +more than 100, you must either include a machine-readable Transparent | |
597 | +copy along with each Opaque copy, or state in or with each Opaque copy | |
598 | +a computer-network location from which the general network-using | |
599 | +public has access to download using public-standard network protocols | |
600 | +a complete Transparent copy of the Document, free of added material. | |
601 | +If you use the latter option, you must take reasonably prudent steps, | |
602 | +when you begin distribution of Opaque copies in quantity, to ensure | |
603 | +that this Transparent copy will remain thus accessible at the stated | |
604 | +location until at least one year after the last time you distribute an | |
605 | +Opaque copy (directly or through your agents or retailers) of that | |
606 | +edition to the public. | |
607 | + | |
608 | +It is requested, but not required, that you contact the authors of the | |
609 | +Document well before redistributing any large number of copies, to give | |
610 | +them a chance to provide you with an updated version of the Document. | |
611 | + | |
612 | +@item | |
613 | +MODIFICATIONS | |
614 | + | |
615 | +You may copy and distribute a Modified Version of the Document under | |
616 | +the conditions of sections 2 and 3 above, provided that you release | |
617 | +the Modified Version under precisely this License, with the Modified | |
618 | +Version filling the role of the Document, thus licensing distribution | |
619 | +and modification of the Modified Version to whoever possesses a copy | |
620 | +of it. In addition, you must do these things in the Modified Version: | |
621 | + | |
622 | +@enumerate A | |
623 | +@item | |
624 | +Use in the Title Page (and on the covers, if any) a title distinct | |
625 | +from that of the Document, and from those of previous versions | |
626 | +(which should, if there were any, be listed in the History section | |
627 | +of the Document). You may use the same title as a previous version | |
628 | +if the original publisher of that version gives permission. | |
629 | + | |
630 | +@item | |
631 | +List on the Title Page, as authors, one or more persons or entities | |
632 | +responsible for authorship of the modifications in the Modified | |
633 | +Version, together with at least five of the principal authors of the | |
634 | +Document (all of its principal authors, if it has fewer than five), | |
635 | +unless they release you from this requirement. | |
636 | + | |
637 | +@item | |
638 | +State on the Title page the name of the publisher of the | |
639 | +Modified Version, as the publisher. | |
640 | + | |
641 | +@item | |
642 | +Preserve all the copyright notices of the Document. | |
643 | + | |
644 | +@item | |
645 | +Add an appropriate copyright notice for your modifications | |
646 | +adjacent to the other copyright notices. | |
647 | + | |
648 | +@item | |
649 | +Include, immediately after the copyright notices, a license notice | |
650 | +giving the public permission to use the Modified Version under the | |
651 | +terms of this License, in the form shown in the Addendum below. | |
652 | + | |
653 | +@item | |
654 | +Preserve in that license notice the full lists of Invariant Sections | |
655 | +and required Cover Texts given in the Document's license notice. | |
656 | + | |
657 | +@item | |
658 | +Include an unaltered copy of this License. | |
659 | + | |
660 | +@item | |
661 | +Preserve the section Entitled ``History'', Preserve its Title, and add | |
662 | +to it an item stating at least the title, year, new authors, and | |
663 | +publisher of the Modified Version as given on the Title Page. If | |
664 | +there is no section Entitled ``History'' in the Document, create one | |
665 | +stating the title, year, authors, and publisher of the Document as | |
666 | +given on its Title Page, then add an item describing the Modified | |
667 | +Version as stated in the previous sentence. | |
668 | + | |
669 | +@item | |
670 | +Preserve the network location, if any, given in the Document for | |
671 | +public access to a Transparent copy of the Document, and likewise | |
672 | +the network locations given in the Document for previous versions | |
673 | +it was based on. These may be placed in the ``History'' section. | |
674 | +You may omit a network location for a work that was published at | |
675 | +least four years before the Document itself, or if the original | |
676 | +publisher of the version it refers to gives permission. | |
677 | + | |
678 | +@item | |
679 | +For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve | |
680 | +the Title of the section, and preserve in the section all the | |
681 | +substance and tone of each of the contributor acknowledgements and/or | |
682 | +dedications given therein. | |
683 | + | |
684 | +@item | |
685 | +Preserve all the Invariant Sections of the Document, | |
686 | +unaltered in their text and in their titles. Section numbers | |
687 | +or the equivalent are not considered part of the section titles. | |
688 | + | |
689 | +@item | |
690 | +Delete any section Entitled ``Endorsements''. Such a section | |
691 | +may not be included in the Modified Version. | |
692 | + | |
693 | +@item | |
694 | +Do not retitle any existing section to be Entitled ``Endorsements'' or | |
695 | +to conflict in title with any Invariant Section. | |
696 | + | |
697 | +@item | |
698 | +Preserve any Warranty Disclaimers. | |
699 | +@end enumerate | |
700 | + | |
701 | +If the Modified Version includes new front-matter sections or | |
702 | +appendices that qualify as Secondary Sections and contain no material | |
703 | +copied from the Document, you may at your option designate some or all | |
704 | +of these sections as invariant. To do this, add their titles to the | |
705 | +list of Invariant Sections in the Modified Version's license notice. | |
706 | +These titles must be distinct from any other section titles. | |
707 | + | |
708 | +You may add a section Entitled ``Endorsements'', provided it contains | |
709 | +nothing but endorsements of your Modified Version by various | |
710 | +parties---for example, statements of peer review or that the text has | |
711 | +been approved by an organization as the authoritative definition of a | |
712 | +standard. | |
713 | + | |
714 | +You may add a passage of up to five words as a Front-Cover Text, and a | |
715 | +passage of up to 25 words as a Back-Cover Text, to the end of the list | |
716 | +of Cover Texts in the Modified Version. Only one passage of | |
717 | +Front-Cover Text and one of Back-Cover Text may be added by (or | |
718 | +through arrangements made by) any one entity. If the Document already | |
719 | +includes a cover text for the same cover, previously added by you or | |
720 | +by arrangement made by the same entity you are acting on behalf of, | |
721 | +you may not add another; but you may replace the old one, on explicit | |
722 | +permission from the previous publisher that added the old one. | |
723 | + | |
724 | +The author(s) and publisher(s) of the Document do not by this License | |
725 | +give permission to use their names for publicity for or to assert or | |
726 | +imply endorsement of any Modified Version. | |
727 | + | |
728 | +@item | |
729 | +COMBINING DOCUMENTS | |
730 | + | |
731 | +You may combine the Document with other documents released under this | |
732 | +License, under the terms defined in section 4 above for modified | |
733 | +versions, provided that you include in the combination all of the | |
734 | +Invariant Sections of all of the original documents, unmodified, and | |
735 | +list them all as Invariant Sections of your combined work in its | |
736 | +license notice, and that you preserve all their Warranty Disclaimers. | |
737 | + | |
738 | +The combined work need only contain one copy of this License, and | |
739 | +multiple identical Invariant Sections may be replaced with a single | |
740 | +copy. If there are multiple Invariant Sections with the same name but | |
741 | +different contents, make the title of each such section unique by | |
742 | +adding at the end of it, in parentheses, the name of the original | |
743 | +author or publisher of that section if known, or else a unique number. | |
744 | +Make the same adjustment to the section titles in the list of | |
745 | +Invariant Sections in the license notice of the combined work. | |
746 | + | |
747 | +In the combination, you must combine any sections Entitled ``History'' | |
748 | +in the various original documents, forming one section Entitled | |
749 | +``History''; likewise combine any sections Entitled ``Acknowledgements'', | |
750 | +and any sections Entitled ``Dedications''. You must delete all | |
751 | +sections Entitled ``Endorsements.'' | |
752 | + | |
753 | +@item | |
754 | +COLLECTIONS OF DOCUMENTS | |
755 | + | |
756 | +You may make a collection consisting of the Document and other documents | |
757 | +released under this License, and replace the individual copies of this | |
758 | +License in the various documents with a single copy that is included in | |
759 | +the collection, provided that you follow the rules of this License for | |
760 | +verbatim copying of each of the documents in all other respects. | |
761 | + | |
762 | +You may extract a single document from such a collection, and distribute | |
763 | +it individually under this License, provided you insert a copy of this | |
764 | +License into the extracted document, and follow this License in all | |
765 | +other respects regarding verbatim copying of that document. | |
766 | + | |
767 | +@item | |
768 | +AGGREGATION WITH INDEPENDENT WORKS | |
769 | + | |
770 | +A compilation of the Document or its derivatives with other separate | |
771 | +and independent documents or works, in or on a volume of a storage or | |
772 | +distribution medium, is called an ``aggregate'' if the copyright | |
773 | +resulting from the compilation is not used to limit the legal rights | |
774 | +of the compilation's users beyond what the individual works permit. | |
775 | +When the Document is included in an aggregate, this License does not | |
776 | +apply to the other works in the aggregate which are not themselves | |
777 | +derivative works of the Document. | |
778 | + | |
779 | +If the Cover Text requirement of section 3 is applicable to these | |
780 | +copies of the Document, then if the Document is less than one half of | |
781 | +the entire aggregate, the Document's Cover Texts may be placed on | |
782 | +covers that bracket the Document within the aggregate, or the | |
783 | +electronic equivalent of covers if the Document is in electronic form. | |
784 | +Otherwise they must appear on printed covers that bracket the whole | |
785 | +aggregate. | |
786 | + | |
787 | +@item | |
788 | +TRANSLATION | |
789 | + | |
790 | +Translation is considered a kind of modification, so you may | |
791 | +distribute translations of the Document under the terms of section 4. | |
792 | +Replacing Invariant Sections with translations requires special | |
793 | +permission from their copyright holders, but you may include | |
794 | +translations of some or all Invariant Sections in addition to the | |
795 | +original versions of these Invariant Sections. You may include a | |
796 | +translation of this License, and all the license notices in the | |
797 | +Document, and any Warranty Disclaimers, provided that you also include | |
798 | +the original English version of this License and the original versions | |
799 | +of those notices and disclaimers. In case of a disagreement between | |
800 | +the translation and the original version of this License or a notice | |
801 | +or disclaimer, the original version will prevail. | |
802 | + | |
803 | +If a section in the Document is Entitled ``Acknowledgements'', | |
804 | +``Dedications'', or ``History'', the requirement (section 4) to Preserve | |
805 | +its Title (section 1) will typically require changing the actual | |
806 | +title. | |
807 | + | |
808 | +@item | |
809 | +TERMINATION | |
810 | + | |
811 | +You may not copy, modify, sublicense, or distribute the Document | |
812 | +except as expressly provided under this License. Any attempt | |
813 | +otherwise to copy, modify, sublicense, or distribute it is void, and | |
814 | +will automatically terminate your rights under this License. | |
815 | + | |
816 | +However, if you cease all violation of this License, then your license | |
817 | +from a particular copyright holder is reinstated (a) provisionally, | |
818 | +unless and until the copyright holder explicitly and finally | |
819 | +terminates your license, and (b) permanently, if the copyright holder | |
820 | +fails to notify you of the violation by some reasonable means prior to | |
821 | +60 days after the cessation. | |
822 | + | |
823 | +Moreover, your license from a particular copyright holder is | |
824 | +reinstated permanently if the copyright holder notifies you of the | |
825 | +violation by some reasonable means, this is the first time you have | |
826 | +received notice of violation of this License (for any work) from that | |
827 | +copyright holder, and you cure the violation prior to 30 days after | |
828 | +your receipt of the notice. | |
829 | + | |
830 | +Termination of your rights under this section does not terminate the | |
831 | +licenses of parties who have received copies or rights from you under | |
832 | +this License. If your rights have been terminated and not permanently | |
833 | +reinstated, receipt of a copy of some or all of the same material does | |
834 | +not give you any rights to use it. | |
835 | + | |
836 | +@item | |
837 | +FUTURE REVISIONS OF THIS LICENSE | |
838 | + | |
839 | +The Free Software Foundation may publish new, revised versions | |
840 | +of the GNU Free Documentation License from time to time. Such new | |
841 | +versions will be similar in spirit to the present version, but may | |
842 | +differ in detail to address new problems or concerns. See | |
843 | +@uref{http://www.gnu.org/copyleft/}. | |
844 | + | |
845 | +Each version of the License is given a distinguishing version number. | |
846 | +If the Document specifies that a particular numbered version of this | |
847 | +License ``or any later version'' applies to it, you have the option of | |
848 | +following the terms and conditions either of that specified version or | |
849 | +of any later version that has been published (not as a draft) by the | |
850 | +Free Software Foundation. If the Document does not specify a version | |
851 | +number of this License, you may choose any version ever published (not | |
852 | +as a draft) by the Free Software Foundation. If the Document | |
853 | +specifies that a proxy can decide which future versions of this | |
854 | +License can be used, that proxy's public statement of acceptance of a | |
855 | +version permanently authorizes you to choose that version for the | |
856 | +Document. | |
857 | + | |
858 | +@item | |
859 | +RELICENSING | |
860 | + | |
861 | +``Massive Multiauthor Collaboration Site'' (or ``MMC Site'') means any | |
862 | +World Wide Web server that publishes copyrightable works and also | |
863 | +provides prominent facilities for anybody to edit those works. A | |
864 | +public wiki that anybody can edit is an example of such a server. A | |
865 | +``Massive Multiauthor Collaboration'' (or ``MMC'') contained in the | |
866 | +site means any set of copyrightable works thus published on the MMC | |
867 | +site. | |
868 | + | |
869 | +``CC-BY-SA'' means the Creative Commons Attribution-Share Alike 3.0 | |
870 | +license published by Creative Commons Corporation, a not-for-profit | |
871 | +corporation with a principal place of business in San Francisco, | |
872 | +California, as well as future copyleft versions of that license | |
873 | +published by that same organization. | |
874 | + | |
875 | +``Incorporate'' means to publish or republish a Document, in whole or | |
876 | +in part, as part of another Document. | |
877 | + | |
878 | +An MMC is ``eligible for relicensing'' if it is licensed under this | |
879 | +License, and if all works that were first published under this License | |
880 | +somewhere other than this MMC, and subsequently incorporated in whole | |
881 | +or in part into the MMC, (1) had no cover texts or invariant sections, | |
882 | +and (2) were thus incorporated prior to November 1, 2008. | |
883 | + | |
884 | +The operator of an MMC Site may republish an MMC contained in the site | |
885 | +under CC-BY-SA on the same site at any time before August 1, 2009, | |
886 | +provided the MMC is eligible for relicensing. | |
887 | + | |
888 | +@end enumerate | |
889 | + | |
890 | +@page | |
891 | +@heading ADDENDUM: How to use this License for your documents | |
892 | + | |
893 | +To use this License in a document you have written, include a copy of | |
894 | +the License in the document and put the following copyright and | |
895 | +license notices just after the title page: | |
896 | + | |
897 | +@smallexample | |
898 | +@group | |
899 | + Copyright (C) @var{year} @var{your name}. | |
900 | + Permission is granted to copy, distribute and/or modify this document | |
901 | + under the terms of the GNU Free Documentation License, Version 1.3 | |
902 | + or any later version published by the Free Software Foundation; | |
903 | + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover | |
904 | + Texts. A copy of the license is included in the section entitled ``GNU | |
905 | + Free Documentation License''. | |
906 | +@end group | |
907 | +@end smallexample | |
908 | + | |
909 | +If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, | |
910 | +replace the ``with@dots{}Texts.'' line with this: | |
911 | + | |
912 | +@smallexample | |
913 | +@group | |
914 | + with the Invariant Sections being @var{list their titles}, with | |
915 | + the Front-Cover Texts being @var{list}, and with the Back-Cover Texts | |
916 | + being @var{list}. | |
917 | +@end group | |
918 | +@end smallexample | |
919 | + | |
920 | +If you have Invariant Sections without Cover Texts, or some other | |
921 | +combination of the three, merge those two alternatives to suit the | |
922 | +situation. | |
923 | + | |
924 | +If your document contains nontrivial examples of program code, we | |
925 | +recommend releasing these examples in parallel under your choice of | |
926 | +free software license, such as the GNU General Public License, | |
927 | +to permit their use in free software. | |
928 | + | |
929 | +@c Local Variables: | |
930 | +@c ispell-local-pdict: "ispell-dict" | |
931 | +@c End: | |
932 | + | |
933 | --- libmicrohttpd-0.9.24/doc/lgpl.texi.orig 1970-01-01 01:00:00.000000000 +0100 | |
934 | +++ libmicrohttpd-0.9.24/doc/lgpl.texi 2013-01-03 19:01:45.646387769 +0100 | |
935 | @@ -0,0 +1,561 @@ | |
936 | +@c The GNU Lesser General Public License. | |
937 | +@center Version 2.1, February 1999 | |
938 | + | |
939 | +@c This file is intended to be included within another document, | |
940 | +@c hence no sectioning command or @node. | |
941 | + | |
942 | +@display | |
943 | +Copyright @copyright{} 1991, 1999 Free Software Foundation, Inc. | |
944 | +51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA | |
945 | + | |
946 | +Everyone is permitted to copy and distribute verbatim copies | |
947 | +of this license document, but changing it is not allowed. | |
948 | + | |
949 | +[This is the first released version of the Lesser GPL. It also counts | |
950 | +as the successor of the GNU Library Public License, version 2, hence the | |
951 | +version number 2.1.] | |
952 | +@end display | |
953 | + | |
954 | +@subheading Preamble | |
955 | + | |
956 | + The licenses for most software are designed to take away your | |
957 | +freedom to share and change it. By contrast, the GNU General Public | |
958 | +Licenses are intended to guarantee your freedom to share and change | |
959 | +free software---to make sure the software is free for all its users. | |
960 | + | |
961 | + This license, the Lesser General Public License, applies to some | |
962 | +specially designated software---typically libraries---of the Free | |
963 | +Software Foundation and other authors who decide to use it. You can use | |
964 | +it too, but we suggest you first think carefully about whether this | |
965 | +license or the ordinary General Public License is the better strategy to | |
966 | +use in any particular case, based on the explanations below. | |
967 | + | |
968 | + When we speak of free software, we are referring to freedom of use, | |
969 | +not price. Our General Public Licenses are designed to make sure that | |
970 | +you have the freedom to distribute copies of free software (and charge | |
971 | +for this service if you wish); that you receive source code or can get | |
972 | +it if you want it; that you can change the software and use pieces of it | |
973 | +in new free programs; and that you are informed that you can do these | |
974 | +things. | |
975 | + | |
976 | + To protect your rights, we need to make restrictions that forbid | |
977 | +distributors to deny you these rights or to ask you to surrender these | |
978 | +rights. These restrictions translate to certain responsibilities for | |
979 | +you if you distribute copies of the library or if you modify it. | |
980 | + | |
981 | + For example, if you distribute copies of the library, whether gratis | |
982 | +or for a fee, you must give the recipients all the rights that we gave | |
983 | +you. You must make sure that they, too, receive or can get the source | |
984 | +code. If you link other code with the library, you must provide | |
985 | +complete object files to the recipients, so that they can relink them | |
986 | +with the library after making changes to the library and recompiling | |
987 | +it. And you must show them these terms so they know their rights. | |
988 | + | |
989 | + We protect your rights with a two-step method: (1) we copyright the | |
990 | +library, and (2) we offer you this license, which gives you legal | |
991 | +permission to copy, distribute and/or modify the library. | |
992 | + | |
993 | + To protect each distributor, we want to make it very clear that | |
994 | +there is no warranty for the free library. Also, if the library is | |
995 | +modified by someone else and passed on, the recipients should know | |
996 | +that what they have is not the original version, so that the original | |
997 | +author's reputation will not be affected by problems that might be | |
998 | +introduced by others. | |
999 | + | |
1000 | + Finally, software patents pose a constant threat to the existence of | |
1001 | +any free program. We wish to make sure that a company cannot | |
1002 | +effectively restrict the users of a free program by obtaining a | |
1003 | +restrictive license from a patent holder. Therefore, we insist that | |
1004 | +any patent license obtained for a version of the library must be | |
1005 | +consistent with the full freedom of use specified in this license. | |
1006 | + | |
1007 | + Most GNU software, including some libraries, is covered by the | |
1008 | +ordinary GNU General Public License. This license, the GNU Lesser | |
1009 | +General Public License, applies to certain designated libraries, and | |
1010 | +is quite different from the ordinary General Public License. We use | |
1011 | +this license for certain libraries in order to permit linking those | |
1012 | +libraries into non-free programs. | |
1013 | + | |
1014 | + When a program is linked with a library, whether statically or using | |
1015 | +a shared library, the combination of the two is legally speaking a | |
1016 | +combined work, a derivative of the original library. The ordinary | |
1017 | +General Public License therefore permits such linking only if the | |
1018 | +entire combination fits its criteria of freedom. The Lesser General | |
1019 | +Public License permits more lax criteria for linking other code with | |
1020 | +the library. | |
1021 | + | |
1022 | + We call this license the @dfn{Lesser} General Public License because it | |
1023 | +does @emph{Less} to protect the user's freedom than the ordinary General | |
1024 | +Public License. It also provides other free software developers Less | |
1025 | +of an advantage over competing non-free programs. These disadvantages | |
1026 | +are the reason we use the ordinary General Public License for many | |
1027 | +libraries. However, the Lesser license provides advantages in certain | |
1028 | +special circumstances. | |
1029 | + | |
1030 | + For example, on rare occasions, there may be a special need to | |
1031 | +encourage the widest possible use of a certain library, so that it becomes | |
1032 | +a de-facto standard. To achieve this, non-free programs must be | |
1033 | +allowed to use the library. A more frequent case is that a free | |
1034 | +library does the same job as widely used non-free libraries. In this | |
1035 | +case, there is little to gain by limiting the free library to free | |
1036 | +software only, so we use the Lesser General Public License. | |
1037 | + | |
1038 | + In other cases, permission to use a particular library in non-free | |
1039 | +programs enables a greater number of people to use a large body of | |
1040 | +free software. For example, permission to use the GNU C Library in | |
1041 | +non-free programs enables many more people to use the whole GNU | |
1042 | +operating system, as well as its variant, the GNU/Linux operating | |
1043 | +system. | |
1044 | + | |
1045 | + Although the Lesser General Public License is Less protective of the | |
1046 | +users' freedom, it does ensure that the user of a program that is | |
1047 | +linked with the Library has the freedom and the wherewithal to run | |
1048 | +that program using a modified version of the Library. | |
1049 | + | |
1050 | + The precise terms and conditions for copying, distribution and | |
1051 | +modification follow. Pay close attention to the difference between a | |
1052 | +``work based on the library'' and a ``work that uses the library''. The | |
1053 | +former contains code derived from the library, whereas the latter must | |
1054 | +be combined with the library in order to run. | |
1055 | + | |
1056 | +@subheading TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION | |
1057 | + | |
1058 | +@enumerate 0 | |
1059 | +@item | |
1060 | +This License Agreement applies to any software library or other program | |
1061 | +which contains a notice placed by the copyright holder or other | |
1062 | +authorized party saying it may be distributed under the terms of this | |
1063 | +Lesser General Public License (also called ``this License''). Each | |
1064 | +licensee is addressed as ``you''. | |
1065 | + | |
1066 | + A ``library'' means a collection of software functions and/or data | |
1067 | +prepared so as to be conveniently linked with application programs | |
1068 | +(which use some of those functions and data) to form executables. | |
1069 | + | |
1070 | + The ``Library'', below, refers to any such software library or work | |
1071 | +which has been distributed under these terms. A ``work based on the | |
1072 | +Library'' means either the Library or any derivative work under | |
1073 | +copyright law: that is to say, a work containing the Library or a | |
1074 | +portion of it, either verbatim or with modifications and/or translated | |
1075 | +straightforwardly into another language. (Hereinafter, translation is | |
1076 | +included without limitation in the term ``modification''.) | |
1077 | + | |
1078 | + ``Source code'' for a work means the preferred form of the work for | |
1079 | +making modifications to it. For a library, complete source code means | |
1080 | +all the source code for all modules it contains, plus any associated | |
1081 | +interface definition files, plus the scripts used to control compilation | |
1082 | +and installation of the library. | |
1083 | + | |
1084 | + Activities other than copying, distribution and modification are not | |
1085 | +covered by this License; they are outside its scope. The act of | |
1086 | +running a program using the Library is not restricted, and output from | |
1087 | +such a program is covered only if its contents constitute a work based | |
1088 | +on the Library (independent of the use of the Library in a tool for | |
1089 | +writing it). Whether that is true depends on what the Library does | |
1090 | +and what the program that uses the Library does. | |
1091 | + | |
1092 | +@item | |
1093 | +You may copy and distribute verbatim copies of the Library's | |
1094 | +complete source code as you receive it, in any medium, provided that | |
1095 | +you conspicuously and appropriately publish on each copy an | |
1096 | +appropriate copyright notice and disclaimer of warranty; keep intact | |
1097 | +all the notices that refer to this License and to the absence of any | |
1098 | +warranty; and distribute a copy of this License along with the | |
1099 | +Library. | |
1100 | + | |
1101 | + You may charge a fee for the physical act of transferring a copy, | |
1102 | +and you may at your option offer warranty protection in exchange for a | |
1103 | +fee. | |
1104 | + | |
1105 | +@item | |
1106 | +You may modify your copy or copies of the Library or any portion | |
1107 | +of it, thus forming a work based on the Library, and copy and | |
1108 | +distribute such modifications or work under the terms of Section 1 | |
1109 | +above, provided that you also meet all of these conditions: | |
1110 | + | |
1111 | +@enumerate a | |
1112 | +@item | |
1113 | +The modified work must itself be a software library. | |
1114 | + | |
1115 | +@item | |
1116 | +You must cause the files modified to carry prominent notices | |
1117 | +stating that you changed the files and the date of any change. | |
1118 | + | |
1119 | +@item | |
1120 | +You must cause the whole of the work to be licensed at no | |
1121 | +charge to all third parties under the terms of this License. | |
1122 | + | |
1123 | +@item | |
1124 | +If a facility in the modified Library refers to a function or a | |
1125 | +table of data to be supplied by an application program that uses | |
1126 | +the facility, other than as an argument passed when the facility | |
1127 | +is invoked, then you must make a good faith effort to ensure that, | |
1128 | +in the event an application does not supply such function or | |
1129 | +table, the facility still operates, and performs whatever part of | |
1130 | +its purpose remains meaningful. | |
1131 | + | |
1132 | +(For example, a function in a library to compute square roots has | |
1133 | +a purpose that is entirely well-defined independent of the | |
1134 | +application. Therefore, Subsection 2d requires that any | |
1135 | +application-supplied function or table used by this function must | |
1136 | +be optional: if the application does not supply it, the square | |
1137 | +root function must still compute square roots.) | |
1138 | +@end enumerate | |
1139 | + | |
1140 | +These requirements apply to the modified work as a whole. If | |
1141 | +identifiable sections of that work are not derived from the Library, | |
1142 | +and can be reasonably considered independent and separate works in | |
1143 | +themselves, then this License, and its terms, do not apply to those | |
1144 | +sections when you distribute them as separate works. But when you | |
1145 | +distribute the same sections as part of a whole which is a work based | |
1146 | +on the Library, the distribution of the whole must be on the terms of | |
1147 | +this License, whose permissions for other licensees extend to the | |
1148 | +entire whole, and thus to each and every part regardless of who wrote | |
1149 | +it. | |
1150 | + | |
1151 | +Thus, it is not the intent of this section to claim rights or contest | |
1152 | +your rights to work written entirely by you; rather, the intent is to | |
1153 | +exercise the right to control the distribution of derivative or | |
1154 | +collective works based on the Library. | |
1155 | + | |
1156 | +In addition, mere aggregation of another work not based on the Library | |
1157 | +with the Library (or with a work based on the Library) on a volume of | |
1158 | +a storage or distribution medium does not bring the other work under | |
1159 | +the scope of this License. | |
1160 | + | |
1161 | +@item | |
1162 | +You may opt to apply the terms of the ordinary GNU General Public | |
1163 | +License instead of this License to a given copy of the Library. To do | |
1164 | +this, you must alter all the notices that refer to this License, so | |
1165 | +that they refer to the ordinary GNU General Public License, version 2, | |
1166 | +instead of to this License. (If a newer version than version 2 of the | |
1167 | +ordinary GNU General Public License has appeared, then you can specify | |
1168 | +that version instead if you wish.) Do not make any other change in | |
1169 | +these notices. | |
1170 | + | |
1171 | + Once this change is made in a given copy, it is irreversible for | |
1172 | +that copy, so the ordinary GNU General Public License applies to all | |
1173 | +subsequent copies and derivative works made from that copy. | |
1174 | + | |
1175 | + This option is useful when you wish to copy part of the code of | |
1176 | +the Library into a program that is not a library. | |
1177 | + | |
1178 | +@item | |
1179 | +You may copy and distribute the Library (or a portion or | |
1180 | +derivative of it, under Section 2) in object code or executable form | |
1181 | +under the terms of Sections 1 and 2 above provided that you accompany | |
1182 | +it with the complete corresponding machine-readable source code, which | |
1183 | +must be distributed under the terms of Sections 1 and 2 above on a | |
1184 | +medium customarily used for software interchange. | |
1185 | + | |
1186 | + If distribution of object code is made by offering access to copy | |
1187 | +from a designated place, then offering equivalent access to copy the | |
1188 | +source code from the same place satisfies the requirement to | |
1189 | +distribute the source code, even though third parties are not | |
1190 | +compelled to copy the source along with the object code. | |
1191 | + | |
1192 | +@item | |
1193 | +A program that contains no derivative of any portion of the | |
1194 | +Library, but is designed to work with the Library by being compiled or | |
1195 | +linked with it, is called a ``work that uses the Library''. Such a | |
1196 | +work, in isolation, is not a derivative work of the Library, and | |
1197 | +therefore falls outside the scope of this License. | |
1198 | + | |
1199 | + However, linking a ``work that uses the Library'' with the Library | |
1200 | +creates an executable that is a derivative of the Library (because it | |
1201 | +contains portions of the Library), rather than a ``work that uses the | |
1202 | +library''. The executable is therefore covered by this License. | |
1203 | +Section 6 states terms for distribution of such executables. | |
1204 | + | |
1205 | + When a ``work that uses the Library'' uses material from a header file | |
1206 | +that is part of the Library, the object code for the work may be a | |
1207 | +derivative work of the Library even though the source code is not. | |
1208 | +Whether this is true is especially significant if the work can be | |
1209 | +linked without the Library, or if the work is itself a library. The | |
1210 | +threshold for this to be true is not precisely defined by law. | |
1211 | + | |
1212 | + If such an object file uses only numerical parameters, data | |
1213 | +structure layouts and accessors, and small macros and small inline | |
1214 | +functions (ten lines or less in length), then the use of the object | |
1215 | +file is unrestricted, regardless of whether it is legally a derivative | |
1216 | +work. (Executables containing this object code plus portions of the | |
1217 | +Library will still fall under Section 6.) | |
1218 | + | |
1219 | + Otherwise, if the work is a derivative of the Library, you may | |
1220 | +distribute the object code for the work under the terms of Section 6. | |
1221 | +Any executables containing that work also fall under Section 6, | |
1222 | +whether or not they are linked directly with the Library itself. | |
1223 | + | |
1224 | +@item | |
1225 | +As an exception to the Sections above, you may also combine or | |
1226 | +link a ``work that uses the Library'' with the Library to produce a | |
1227 | +work containing portions of the Library, and distribute that work | |
1228 | +under terms of your choice, provided that the terms permit | |
1229 | +modification of the work for the customer's own use and reverse | |
1230 | +engineering for debugging such modifications. | |
1231 | + | |
1232 | + You must give prominent notice with each copy of the work that the | |
1233 | +Library is used in it and that the Library and its use are covered by | |
1234 | +this License. You must supply a copy of this License. If the work | |
1235 | +during execution displays copyright notices, you must include the | |
1236 | +copyright notice for the Library among them, as well as a reference | |
1237 | +directing the user to the copy of this License. Also, you must do one | |
1238 | +of these things: | |
1239 | + | |
1240 | +@enumerate a | |
1241 | +@item | |
1242 | +Accompany the work with the complete corresponding | |
1243 | +machine-readable source code for the Library including whatever | |
1244 | +changes were used in the work (which must be distributed under | |
1245 | +Sections 1 and 2 above); and, if the work is an executable linked | |
1246 | +with the Library, with the complete machine-readable ``work that | |
1247 | +uses the Library'', as object code and/or source code, so that the | |
1248 | +user can modify the Library and then relink to produce a modified | |
1249 | +executable containing the modified Library. (It is understood | |
1250 | +that the user who changes the contents of definitions files in the | |
1251 | +Library will not necessarily be able to recompile the application | |
1252 | +to use the modified definitions.) | |
1253 | + | |
1254 | +@item | |
1255 | +Use a suitable shared library mechanism for linking with the Library. A | |
1256 | +suitable mechanism is one that (1) uses at run time a copy of the | |
1257 | +library already present on the user's computer system, rather than | |
1258 | +copying library functions into the executable, and (2) will operate | |
1259 | +properly with a modified version of the library, if the user installs | |
1260 | +one, as long as the modified version is interface-compatible with the | |
1261 | +version that the work was made with. | |
1262 | + | |
1263 | +@item | |
1264 | +Accompany the work with a written offer, valid for at | |
1265 | +least three years, to give the same user the materials | |
1266 | +specified in Subsection 6a, above, for a charge no more | |
1267 | +than the cost of performing this distribution. | |
1268 | + | |
1269 | +@item | |
1270 | +If distribution of the work is made by offering access to copy | |
1271 | +from a designated place, offer equivalent access to copy the above | |
1272 | +specified materials from the same place. | |
1273 | + | |
1274 | +@item | |
1275 | +Verify that the user has already received a copy of these | |
1276 | +materials or that you have already sent this user a copy. | |
1277 | +@end enumerate | |
1278 | + | |
1279 | + For an executable, the required form of the ``work that uses the | |
1280 | +Library'' must include any data and utility programs needed for | |
1281 | +reproducing the executable from it. However, as a special exception, | |
1282 | +the materials to be distributed need not include anything that is | |
1283 | +normally distributed (in either source or binary form) with the major | |
1284 | +components (compiler, kernel, and so on) of the operating system on | |
1285 | +which the executable runs, unless that component itself accompanies the | |
1286 | +executable. | |
1287 | + | |
1288 | + It may happen that this requirement contradicts the license | |
1289 | +restrictions of other proprietary libraries that do not normally | |
1290 | +accompany the operating system. Such a contradiction means you cannot | |
1291 | +use both them and the Library together in an executable that you | |
1292 | +distribute. | |
1293 | + | |
1294 | +@item | |
1295 | +You may place library facilities that are a work based on the | |
1296 | +Library side-by-side in a single library together with other library | |
1297 | +facilities not covered by this License, and distribute such a combined | |
1298 | +library, provided that the separate distribution of the work based on | |
1299 | +the Library and of the other library facilities is otherwise | |
1300 | +permitted, and provided that you do these two things: | |
1301 | + | |
1302 | +@enumerate a | |
1303 | +@item | |
1304 | +Accompany the combined library with a copy of the same work | |
1305 | +based on the Library, uncombined with any other library | |
1306 | +facilities. This must be distributed under the terms of the | |
1307 | +Sections above. | |
1308 | + | |
1309 | +@item | |
1310 | +Give prominent notice with the combined library of the fact | |
1311 | +that part of it is a work based on the Library, and explaining | |
1312 | +where to find the accompanying uncombined form of the same work. | |
1313 | +@end enumerate | |
1314 | + | |
1315 | +@item | |
1316 | +You may not copy, modify, sublicense, link with, or distribute | |
1317 | +the Library except as expressly provided under this License. Any | |
1318 | +attempt otherwise to copy, modify, sublicense, link with, or | |
1319 | +distribute the Library is void, and will automatically terminate your | |
1320 | +rights under this License. However, parties who have received copies, | |
1321 | +or rights, from you under this License will not have their licenses | |
1322 | +terminated so long as such parties remain in full compliance. | |
1323 | + | |
1324 | +@item | |
1325 | +You are not required to accept this License, since you have not | |
1326 | +signed it. However, nothing else grants you permission to modify or | |
1327 | +distribute the Library or its derivative works. These actions are | |
1328 | +prohibited by law if you do not accept this License. Therefore, by | |
1329 | +modifying or distributing the Library (or any work based on the | |
1330 | +Library), you indicate your acceptance of this License to do so, and | |
1331 | +all its terms and conditions for copying, distributing or modifying | |
1332 | +the Library or works based on it. | |
1333 | + | |
1334 | +@item | |
1335 | +Each time you redistribute the Library (or any work based on the | |
1336 | +Library), the recipient automatically receives a license from the | |
1337 | +original licensor to copy, distribute, link with or modify the Library | |
1338 | +subject to these terms and conditions. You may not impose any further | |
1339 | +restrictions on the recipients' exercise of the rights granted herein. | |
1340 | +You are not responsible for enforcing compliance by third parties with | |
1341 | +this License. | |
1342 | + | |
1343 | +@item | |
1344 | +If, as a consequence of a court judgment or allegation of patent | |
1345 | +infringement or for any other reason (not limited to patent issues), | |
1346 | +conditions are imposed on you (whether by court order, agreement or | |
1347 | +otherwise) that contradict the conditions of this License, they do not | |
1348 | +excuse you from the conditions of this License. If you cannot | |
1349 | +distribute so as to satisfy simultaneously your obligations under this | |
1350 | +License and any other pertinent obligations, then as a consequence you | |
1351 | +may not distribute the Library at all. For example, if a patent | |
1352 | +license would not permit royalty-free redistribution of the Library by | |
1353 | +all those who receive copies directly or indirectly through you, then | |
1354 | +the only way you could satisfy both it and this License would be to | |
1355 | +refrain entirely from distribution of the Library. | |
1356 | + | |
1357 | +If any portion of this section is held invalid or unenforceable under any | |
1358 | +particular circumstance, the balance of the section is intended to apply, | |
1359 | +and the section as a whole is intended to apply in other circumstances. | |
1360 | + | |
1361 | +It is not the purpose of this section to induce you to infringe any | |
1362 | +patents or other property right claims or to contest validity of any | |
1363 | +such claims; this section has the sole purpose of protecting the | |
1364 | +integrity of the free software distribution system which is | |
1365 | +implemented by public license practices. Many people have made | |
1366 | +generous contributions to the wide range of software distributed | |
1367 | +through that system in reliance on consistent application of that | |
1368 | +system; it is up to the author/donor to decide if he or she is willing | |
1369 | +to distribute software through any other system and a licensee cannot | |
1370 | +impose that choice. | |
1371 | + | |
1372 | +This section is intended to make thoroughly clear what is believed to | |
1373 | +be a consequence of the rest of this License. | |
1374 | + | |
1375 | +@item | |
1376 | +If the distribution and/or use of the Library is restricted in | |
1377 | +certain countries either by patents or by copyrighted interfaces, the | |
1378 | +original copyright holder who places the Library under this License may add | |
1379 | +an explicit geographical distribution limitation excluding those countries, | |
1380 | +so that distribution is permitted only in or among countries not thus | |
1381 | +excluded. In such case, this License incorporates the limitation as if | |
1382 | +written in the body of this License. | |
1383 | + | |
1384 | +@item | |
1385 | +The Free Software Foundation may publish revised and/or new | |
1386 | +versions of the Lesser General Public License from time to time. | |
1387 | +Such new versions will be similar in spirit to the present version, | |
1388 | +but may differ in detail to address new problems or concerns. | |
1389 | + | |
1390 | +Each version is given a distinguishing version number. If the Library | |
1391 | +specifies a version number of this License which applies to it and | |
1392 | +``any later version'', you have the option of following the terms and | |
1393 | +conditions either of that version or of any later version published by | |
1394 | +the Free Software Foundation. If the Library does not specify a | |
1395 | +license version number, you may choose any version ever published by | |
1396 | +the Free Software Foundation. | |
1397 | + | |
1398 | +@item | |
1399 | +If you wish to incorporate parts of the Library into other free | |
1400 | +programs whose distribution conditions are incompatible with these, | |
1401 | +write to the author to ask for permission. For software which is | |
1402 | +copyrighted by the Free Software Foundation, write to the Free | |
1403 | +Software Foundation; we sometimes make exceptions for this. Our | |
1404 | +decision will be guided by the two goals of preserving the free status | |
1405 | +of all derivatives of our free software and of promoting the sharing | |
1406 | +and reuse of software generally. | |
1407 | + | |
1408 | +@iftex | |
1409 | +@heading NO WARRANTY | |
1410 | +@end iftex | |
1411 | +@ifinfo | |
1412 | +@center NO WARRANTY | |
1413 | + | |
1414 | +@end ifinfo | |
1415 | + | |
1416 | +@item | |
1417 | +BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO | |
1418 | +WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW. | |
1419 | +EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR | |
1420 | +OTHER PARTIES PROVIDE THE LIBRARY ``AS IS'' WITHOUT WARRANTY OF ANY | |
1421 | +KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE | |
1422 | +IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR | |
1423 | +PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE | |
1424 | +LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME | |
1425 | +THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. | |
1426 | + | |
1427 | +@item | |
1428 | +IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN | |
1429 | +WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY | |
1430 | +AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU | |
1431 | +FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR | |
1432 | +CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE | |
1433 | +LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING | |
1434 | +RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A | |
1435 | +FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF | |
1436 | +SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH | |
1437 | +DAMAGES. | |
1438 | +@end enumerate | |
1439 | + | |
1440 | +@iftex | |
1441 | +@heading END OF TERMS AND CONDITIONS | |
1442 | +@end iftex | |
1443 | +@ifinfo | |
1444 | +@center END OF TERMS AND CONDITIONS | |
1445 | + | |
1446 | +@end ifinfo | |
1447 | + | |
1448 | +@page | |
1449 | +@subheading How to Apply These Terms to Your New Libraries | |
1450 | + | |
1451 | + If you develop a new library, and you want it to be of the greatest | |
1452 | +possible use to the public, we recommend making it free software that | |
1453 | +everyone can redistribute and change. You can do so by permitting | |
1454 | +redistribution under these terms (or, alternatively, under the terms of the | |
1455 | +ordinary General Public License). | |
1456 | + | |
1457 | + To apply these terms, attach the following notices to the library. It is | |
1458 | +safest to attach them to the start of each source file to most effectively | |
1459 | +convey the exclusion of warranty; and each file should have at least the | |
1460 | +``copyright'' line and a pointer to where the full notice is found. | |
1461 | + | |
1462 | +@smallexample | |
1463 | +@var{one line to give the library's name and an idea of what it does.} | |
1464 | +Copyright (C) @var{year} @var{name of author} | |
1465 | + | |
1466 | +This library is free software; you can redistribute it and/or modify it | |
1467 | +under the terms of the GNU Lesser General Public License as published by | |
1468 | +the Free Software Foundation; either version 2.1 of the License, or (at | |
1469 | +your option) any later version. | |
1470 | + | |
1471 | +This library is distributed in the hope that it will be useful, but | |
1472 | +WITHOUT ANY WARRANTY; without even the implied warranty of | |
1473 | +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | |
1474 | +Lesser General Public License for more details. | |
1475 | + | |
1476 | +You should have received a copy of the GNU Lesser General Public | |
1477 | +License along with this library; if not, write to the Free Software | |
1478 | +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, | |
1479 | +USA. | |
1480 | +@end smallexample | |
1481 | + | |
1482 | +Also add information on how to contact you by electronic and paper mail. | |
1483 | + | |
1484 | +You should also get your employer (if you work as a programmer) or your | |
1485 | +school, if any, to sign a ``copyright disclaimer'' for the library, if | |
1486 | +necessary. Here is a sample; alter the names: | |
1487 | + | |
1488 | +@smallexample | |
1489 | +Yoyodyne, Inc., hereby disclaims all copyright interest in the library | |
1490 | +`Frob' (a library for tweaking knobs) written by James Random Hacker. | |
1491 | + | |
1492 | +@var{signature of Ty Coon}, 1 April 1990 | |
1493 | +Ty Coon, President of Vice | |
1494 | +@end smallexample | |
1495 | + | |
1496 | +That's all there is to it! | |
1497 | --- libmicrohttpd-0.9.24/doc/chapters.orig/basicauthentication.inc 1970-01-01 01:00:00.000000000 +0100 | |
1498 | +++ libmicrohttpd-0.9.24/doc/chapters/basicauthentication.inc 2013-01-03 19:12:00.176374962 +0100 | |
1499 | @@ -0,0 +1,159 @@ | |
1500 | +With the small exception of IP address based access control, | |
1501 | +requests from all connecting clients where served equally until now. | |
1502 | +This chapter discusses a first method of client's authentication and | |
1503 | +its limits. | |
1504 | + | |
1505 | +A very simple approach feasible with the means already discussed would | |
1506 | +be to expect the password in the @emph{URI} string before granting access to | |
1507 | +the secured areas. The password could be separated from the actual resource identifier | |
1508 | +by a certain character, thus the request line might look like | |
1509 | +@verbatim | |
1510 | +GET /picture.png?mypassword | |
1511 | +@end verbatim | |
1512 | +@noindent | |
1513 | + | |
1514 | +In the rare situation where the client is customized enough and the connection occurs | |
1515 | +through secured lines (e.g., a embedded device directly attached to another via wire) | |
1516 | +and where the ability to embedd a password in the URI or to pass on a URI with a | |
1517 | +password are desired, this can be a reasonable choice. | |
1518 | + | |
1519 | +But when it is assumed that the user connecting does so with an ordinary Internet browser, | |
1520 | +this implementation brings some problems about. For example, the URI including the password | |
1521 | +stays in the address field or at least in the history of the browser for anybody near enough to see. | |
1522 | +It will also be inconvenient to add the password manually to any new URI when the browser does | |
1523 | +not know how to compose this automatically. | |
1524 | + | |
1525 | +At least the convenience issue can be addressed by employing the simplest built-in password | |
1526 | +facilities of HTTP compliant browsers, hence we want to start there. It will however turn out | |
1527 | +to have still severe weaknesses in terms of security which need consideration. | |
1528 | + | |
1529 | +Before we will start implementing @emph{Basic Authentication} as described in @emph{RFC 2617}, | |
1530 | +we should finally abandon the bad practice of responding every request the first time our callback | |
1531 | +is called for a given connection. This is becoming more important now because the client and | |
1532 | +the server will have to talk in a more bi-directional way than before to | |
1533 | + | |
1534 | +But how can we tell whether the callback has been called before for the particular connection? | |
1535 | +Initially, the pointer this parameter references is set by @emph{MHD} in the callback. But it will | |
1536 | +also be "remembered" on the next call (for the same connection). | |
1537 | +Thus, we will generate no response until the parameter is non-null---implying the callback was | |
1538 | +called before at least once. We do not need to share information between different calls of the callback, | |
1539 | +so we can set the parameter to any adress that is assured to be not null. The pointer to the | |
1540 | +@code{connection} structure will be pointing to a legal address, so we take this. | |
1541 | + | |
1542 | +The first time @code{answer_to_connection} is called, we will not even look at the headers. | |
1543 | + | |
1544 | +@verbatim | |
1545 | +static int | |
1546 | +answer_to_connection (void *cls, struct MHD_Connection *connection, | |
1547 | + const char *url, const char *method, const char *version, | |
1548 | + const char *upload_data, size_t *upload_data_size, | |
1549 | + void **con_cls) | |
1550 | +{ | |
1551 | + if (0 != strcmp(method, "GET")) return MHD_NO; | |
1552 | + if (NULL == *con_cls) {*con_cls = connection; return MHD_YES;} | |
1553 | + | |
1554 | + ... | |
1555 | + /* else respond accordingly */ | |
1556 | + ... | |
1557 | +} | |
1558 | +@end verbatim | |
1559 | +@noindent | |
1560 | + | |
1561 | +Note how we lop off the connection on the first condition (no "GET" request), but return asking for more on | |
1562 | +the other one with @code{MHD_YES}. | |
1563 | +With this minor change, we can proceed to implement the actual authentication process. | |
1564 | + | |
1565 | +@heading Request for authentication | |
1566 | + | |
1567 | +Let us assume we had only files not intended to be handed out without the correct username/password, | |
1568 | +so every "GET" request will be challenged. | |
1569 | +@emph{RFC 2617} describes how the server shall ask for authentication by adding a | |
1570 | +@emph{WWW-Authenticate} response header with the name of the @emph{realm} protected. | |
1571 | +MHD can generate and queue such a failure response for you using | |
1572 | +the @code{MHD_queue_basic_auth_fail_response} API. The only thing you need to do | |
1573 | +is construct a response with the error page to be shown to the user | |
1574 | +if he aborts basic authentication. But first, you should check if the | |
1575 | +proper credentials were already supplied using the | |
1576 | +@code{MHD_basic_auth_get_username_password} call. | |
1577 | + | |
1578 | +Your code would then look like this: | |
1579 | +@verbatim | |
1580 | +static int | |
1581 | +answer_to_connection (void *cls, struct MHD_Connection *connection, | |
1582 | + const char *url, const char *method, | |
1583 | + const char *version, const char *upload_data, | |
1584 | + size_t *upload_data_size, void **con_cls) | |
1585 | +{ | |
1586 | + char *user; | |
1587 | + char *pass; | |
1588 | + int fail; | |
1589 | + struct MHD_Response *response; | |
1590 | + | |
1591 | + if (0 != strcmp (method, MHD_HTTP_METHOD_GET)) | |
1592 | + return MHD_NO; | |
1593 | + if (NULL == *con_cls) | |
1594 | + { | |
1595 | + *con_cls = connection; | |
1596 | + return MHD_YES; | |
1597 | + } | |
1598 | + pass = NULL; | |
1599 | + user = MHD_basic_auth_get_username_password (connection, &pass); | |
1600 | + fail = ( (user == NULL) || | |
1601 | + (0 != strcmp (user, "root")) || | |
1602 | + (0 != strcmp (pass, "pa$$w0rd") ) ); | |
1603 | + if (user != NULL) free (user); | |
1604 | + if (pass != NULL) free (pass); | |
1605 | + if (fail) | |
1606 | + { | |
1607 | + const char *page = "<html><body>Go away.</body></html>"; | |
1608 | + response = | |
1609 | + MHD_create_response_from_buffer (strlen (page), (void *) page, | |
1610 | + MHD_RESPMEM_PERSISTENT); | |
1611 | + ret = MHD_queue_basic_auth_fail_response (connection, | |
1612 | + "my realm", | |
1613 | + response); | |
1614 | + } | |
1615 | + else | |
1616 | + { | |
1617 | + const char *page = "<html><body>A secret.</body></html>"; | |
1618 | + response = | |
1619 | + MHD_create_response_from_buffer (strlen (page), (void *) page, | |
1620 | + MHD_RESPMEM_PERSISTENT); | |
1621 | + ret = MHD_queue_response (connection, MHD_HTTP_OK, response); | |
1622 | + } | |
1623 | + MHD_destroy_response (response); | |
1624 | + return ret; | |
1625 | +} | |
1626 | +@end verbatim | |
1627 | + | |
1628 | +See the @code{examples} directory for the complete example file. | |
1629 | + | |
1630 | +@heading Remarks | |
1631 | +For a proper server, the conditional statements leading to a return of @code{MHD_NO} should yield a | |
1632 | +response with a more precise status code instead of silently closing the connection. For example, | |
1633 | +failures of memory allocation are best reported as @emph{internal server error} and unexpected | |
1634 | +authentication methods as @emph{400 bad request}. | |
1635 | + | |
1636 | +@heading Exercises | |
1637 | +@itemize @bullet | |
1638 | +@item | |
1639 | +Make the server respond to wrong credentials (but otherwise well-formed requests) with the recommended | |
1640 | +@emph{401 unauthorized} status code. If the client still does not authenticate correctly within the | |
1641 | +same connection, close it and store the client's IP address for a certain time. (It is OK to check for | |
1642 | +expiration not until the main thread wakes up again on the next connection.) If the client fails | |
1643 | +authenticating three times during this period, add it to another list for which the | |
1644 | +@code{AcceptPolicyCallback} function denies connection (temporally). | |
1645 | + | |
1646 | +@item | |
1647 | +With the network utility @code{netcat} connect and log the response of a "GET" request as you | |
1648 | +did in the exercise of the first example, this time to a file. Now stop the server and let @emph{netcat} | |
1649 | +listen on the same port the server used to listen on and have it fake being the proper server by giving | |
1650 | +the file's content as the response (e.g. @code{cat log | nc -l -p 8888}). Pretending to think your were | |
1651 | +connecting to the actual server, browse to the eavesdropper and give the correct credentials. | |
1652 | + | |
1653 | +Copy and paste the encoded string you see in @code{netcat}'s output to some of the Base64 decode tools available online | |
1654 | +and see how both the user's name and password could be completely restored. | |
1655 | + | |
1656 | +@end itemize | |
1657 | + | |
1658 | + | |
1659 | --- libmicrohttpd-0.9.24/doc/chapters.orig/bibliography.inc 1970-01-01 01:00:00.000000000 +0100 | |
1660 | +++ libmicrohttpd-0.9.24/doc/chapters/bibliography.inc 2013-01-03 19:12:00.176374962 +0100 | |
1661 | @@ -0,0 +1,29 @@ | |
1662 | +@heading API reference | |
1663 | +@itemize @bullet | |
1664 | +@item | |
1665 | +The @emph{GNU libmicrohttpd} manual by Marco Maggi and Christian Grothoff 2008 | |
1666 | +@uref{http://gnunet.org/libmicrohttpd/microhttpd.html} | |
1667 | + | |
1668 | +@item | |
1669 | +All referenced RFCs can be found on the website of @emph{The Internet Engineering Task Force} | |
1670 | +@uref{http://www.ietf.org/} | |
1671 | + | |
1672 | +@item | |
1673 | +@emph{RFC 2616}: Fielding, R., Gettys, J., Mogul, J., Frystyk, H., and T. Berners-Lee, | |
1674 | +"Hypertext Transfer Protocol -- HTTP/1.1", RFC 2016, January 1997. | |
1675 | + | |
1676 | +@item | |
1677 | +@emph{RFC 2617}: Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., Leach, P., | |
1678 | +Luotonen, A., and L. Stewart, "HTTP Authentication: Basic and Digest Access Authentication", RFC 2617, June 1999. | |
1679 | + | |
1680 | + | |
1681 | +@item | |
1682 | +A well--structured @emph{HTML} reference can be found on | |
1683 | +@uref{http://www.echoecho.com/html.htm} | |
1684 | + | |
1685 | +For those readers understanding German or French, there is an excellent document both for learning | |
1686 | +@emph{HTML} and for reference, whose English version unfortunately has been discontinued. | |
1687 | +@uref{http://de.selfhtml.org/} and @uref{http://fr.selfhtml.org/} | |
1688 | + | |
1689 | + | |
1690 | +@end itemize | |
1691 | --- libmicrohttpd-0.9.24/doc/chapters.orig/exploringrequests.inc 1970-01-01 01:00:00.000000000 +0100 | |
1692 | +++ libmicrohttpd-0.9.24/doc/chapters/exploringrequests.inc 2013-01-03 19:12:00.176374962 +0100 | |
1693 | @@ -0,0 +1,109 @@ | |
1694 | +This chapter will deal with the information which the client sends to the | |
1695 | +server at every request. We are going to examine the most useful fields of such an request | |
1696 | +and print them out in a readable manner. This could be useful for logging facilities. | |
1697 | + | |
1698 | +The starting point is the @emph{hellobrowser} program with the former response removed. | |
1699 | + | |
1700 | +This time, we just want to collect information in the callback function, thus we will | |
1701 | +just return MHD_NO after we have probed the request. This way, the connection is closed | |
1702 | +without much ado by the server. | |
1703 | + | |
1704 | +@verbatim | |
1705 | +static int | |
1706 | +answer_to_connection (void *cls, struct MHD_Connection *connection, | |
1707 | + const char *url, | |
1708 | + const char *method, const char *version, | |
1709 | + const char *upload_data, | |
1710 | + size_t *upload_data_size, void **con_cls) | |
1711 | +{ | |
1712 | + ... | |
1713 | + return MHD_NO; | |
1714 | +} | |
1715 | +@end verbatim | |
1716 | +@noindent | |
1717 | +The ellipsis marks the position where the following instructions shall be inserted. | |
1718 | + | |
1719 | + | |
1720 | +We begin with the most obvious information available to the server, the request line. You should | |
1721 | +already have noted that a request consists of a command (or "HTTP method") and a URI (e.g. a filename). | |
1722 | +It also contains a string for the version of the protocol which can be found in @code{version}. | |
1723 | +To call it a "new request" is justified because we return only @code{MHD_NO}, thus ensuring the | |
1724 | +function will not be called again for this connection. | |
1725 | +@verbatim | |
1726 | +printf ("New %s request for %s using version %s\n", method, url, version); | |
1727 | +@end verbatim | |
1728 | +@noindent | |
1729 | + | |
1730 | +The rest of the information is a bit more hidden. Nevertheless, there is lot of it sent from common | |
1731 | +Internet browsers. It is stored in "key-value" pairs and we want to list what we find in the header. | |
1732 | +As there is no mandatory set of keys a client has to send, each key-value pair is printed out one by | |
1733 | +one until there are no more left. We do this by writing a separate function which will be called for | |
1734 | +each pair just like the above function is called for each HTTP request. | |
1735 | +It can then print out the content of this pair. | |
1736 | +@verbatim | |
1737 | +int print_out_key (void *cls, enum MHD_ValueKind kind, | |
1738 | + const char *key, const char *value) | |
1739 | +{ | |
1740 | + printf ("%s: %s\n", key, value); | |
1741 | + return MHD_YES; | |
1742 | +} | |
1743 | +@end verbatim | |
1744 | +@noindent | |
1745 | + | |
1746 | +To start the iteration process that calls our new function for every key, the line | |
1747 | +@verbatim | |
1748 | +MHD_get_connection_values (connection, MHD_HEADER_KIND, &print_out_key, NULL); | |
1749 | +@end verbatim | |
1750 | +@noindent | |
1751 | +needs to be inserted in the connection callback function too. The second parameter tells the function | |
1752 | +that we are only interested in keys from the general HTTP header of the request. Our iterating | |
1753 | +function @code{print_out_key} does not rely on any additional information to fulfill its duties | |
1754 | +so the last parameter can be NULL. | |
1755 | + | |
1756 | +All in all, this constitutes the complete @code{logging.c} program for this chapter which can be | |
1757 | +found in the @code{examples} section. | |
1758 | + | |
1759 | +Connecting with any modern Internet browser should yield a handful of keys. You should try to | |
1760 | +interpret them with the aid of @emph{RFC 2616}. | |
1761 | +Especially worth mentioning is the "Host" key which is often used to serve several different websites | |
1762 | +hosted under one single IP address but reachable by different domain names (this is called virtual hosting). | |
1763 | + | |
1764 | +@heading Conclusion | |
1765 | +The introduced capabilities to itemize the content of a simple GET request---especially the | |
1766 | +URI---should already allow the server to satisfy clients' requests for small specific resources | |
1767 | +(e.g. files) or even induce alteration of server state. However, the latter is not | |
1768 | +recommended as the GET method (including its header data) is by convention considered a "safe" | |
1769 | +operation, which should not change the server's state in a significant way. By convention, | |
1770 | +GET operations can thus be performed by crawlers and other automatic software. Naturally | |
1771 | +actions like searching for a passed string are fine. | |
1772 | + | |
1773 | +Of course, no transmission can occur while the return value is still set to @code{MHD_NO} in the | |
1774 | +callback function. | |
1775 | + | |
1776 | +@heading Exercises | |
1777 | +@itemize @bullet | |
1778 | +@item | |
1779 | +By parsing the @code{url} string and delivering responses accordingly, implement a small server for | |
1780 | +"virtual" files. When asked for @code{/index.htm@{l@}}, let the response consist of a HTML page | |
1781 | +containing a link to @code{/another.html} page which is also to be created "on the fly" in case of | |
1782 | +being requested. If neither of these two pages are requested, @code{MHD_HTTP_NOT_FOUND} shall be | |
1783 | +returned accompanied by an informative message. | |
1784 | + | |
1785 | +@item | |
1786 | +A very interesting information has still been ignored by our logger---the client's IP address. | |
1787 | +Implement a callback function | |
1788 | +@verbatim | |
1789 | +static int on_client_connect (void *cls, | |
1790 | + const struct sockaddr *addr, | |
1791 | + socklen_t addrlen) | |
1792 | +@end verbatim | |
1793 | +@noindent | |
1794 | +that prints out the IP address in an appropriate format. You might want to use the POSIX function | |
1795 | +@code{inet_ntoa} but bear in mind that @code{addr} is actually just a structure containing other | |
1796 | +substructures and is @emph{not} the variable this function expects. | |
1797 | +Make sure to return @code{MHD_YES} so that the library knows the client is allowed to connect | |
1798 | +(and to then process the request). If one wanted to limit access basing on IP addresses, this would be the place | |
1799 | +to do it. The address of your @code{on_client_connect} function must be passed as the third parameter to the | |
1800 | +@code{MHD_start_daemon} call. | |
1801 | + | |
1802 | +@end itemize | |
1803 | --- libmicrohttpd-0.9.24/doc/chapters.orig/hellobrowser.inc 1970-01-01 01:00:00.000000000 +0100 | |
1804 | +++ libmicrohttpd-0.9.24/doc/chapters/hellobrowser.inc 2013-01-03 19:12:00.176374962 +0100 | |
1805 | @@ -0,0 +1,222 @@ | |
1806 | +The most basic task for a HTTP server is to deliver a static text message to any client connecting to it. | |
1807 | +Given that this is also easy to implement, it is an excellent problem to start with. | |
1808 | + | |
1809 | +For now, the particular URI the client asks for shall have no effect on the message that will | |
1810 | +be returned. In addition, the server shall end the connection after the message has been sent so that | |
1811 | +the client will know there is nothing more to expect. | |
1812 | + | |
1813 | +The C program @code{hellobrowser.c}, which is to be found in the examples section, does just that. | |
1814 | +If you are very eager, you can compile and start it right away but it is advisable to type the | |
1815 | +lines in by yourself as they will be discussed and explained in detail. | |
1816 | + | |
1817 | +After the necessary includes and the definition of the port which our server should listen on | |
1818 | +@verbatim | |
1819 | +#include <sys/types.h> | |
1820 | +#include <sys/select.h> | |
1821 | +#include <sys/socket.h> | |
1822 | +#include <microhttpd.h> | |
1823 | + | |
1824 | +#define PORT 8888 | |
1825 | + | |
1826 | +@end verbatim | |
1827 | + | |
1828 | +@noindent | |
1829 | +the desired behaviour of our server when HTTP request arrive has to be implemented. We already have | |
1830 | +agreed that it should not care about the particular details of the request, such as who is requesting | |
1831 | +what. The server will respond merely with the same small HTML page to every request. | |
1832 | + | |
1833 | +The function we are going to write now will be called by @emph{GNU libmicrohttpd} every time an | |
1834 | +appropriate request comes in. While the name of this callback function is arbitrary, its parameter | |
1835 | +list has to follow a certain layout. So please, ignore the lot of parameters for now, they will be | |
1836 | +explained at the point they are needed. We have to use only one of them, | |
1837 | +@code{struct MHD_Connection *connection}, for the minimalistic functionality we want to archive at the moment. | |
1838 | + | |
1839 | +This parameter is set by the @emph{libmicrohttpd} daemon and holds the necessary information to | |
1840 | +relate the call with a certain connection. Keep in mind that a server might have to satisfy hundreds | |
1841 | +of concurrent connections and we have to make sure that the correct data is sent to the destined | |
1842 | +client. Therefore, this variable is a means to refer to a particular connection if we ask the | |
1843 | +daemon to sent the reply. | |
1844 | + | |
1845 | +Talking about the reply, it is defined as a string right after the function header | |
1846 | +@verbatim | |
1847 | +int answer_to_connection (void *cls, struct MHD_Connection *connection, | |
1848 | + const char *url, | |
1849 | + const char *method, const char *version, | |
1850 | + const char *upload_data, | |
1851 | + size_t *upload_data_size, void **con_cls) | |
1852 | +{ | |
1853 | + const char *page = "<html><body>Hello, browser!</body></html>"; | |
1854 | + | |
1855 | +@end verbatim | |
1856 | + | |
1857 | +@noindent | |
1858 | +HTTP is a rather strict protocol and the client would certainly consider it "inappropriate" if we | |
1859 | +just sent the answer string "as is". Instead, it has to be wrapped with additional information stored in so-called headers and footers. Most of the work in this area is done by the library for us---we | |
1860 | +just have to ask. Our reply string packed in the necessary layers will be called a "response". | |
1861 | +To obtain such a response we hand our data (the reply--string) and its size over to the | |
1862 | +@code{MHD_create_response_from_buffer} function. The last two parameters basically tell @emph{MHD} | |
1863 | +that we do not want it to dispose the message data for us when it has been sent and there also needs | |
1864 | +no internal copy to be done because the @emph{constant} string won't change anyway. | |
1865 | + | |
1866 | +@verbatim | |
1867 | + struct MHD_Response *response; | |
1868 | + int ret; | |
1869 | + | |
1870 | + response = MHD_create_response_from_buffer (strlen (page), | |
1871 | + (void*) page, MHD_RESPMEM_PERSISTENT); | |
1872 | + | |
1873 | +@end verbatim | |
1874 | + | |
1875 | +@noindent | |
1876 | +Now that the the response has been laced up, it is ready for delivery and can be queued for sending. | |
1877 | +This is done by passing it to another @emph{GNU libmicrohttpd} function. As all our work was done in | |
1878 | +the scope of one function, the recipient is without doubt the one associated with the | |
1879 | +local variable @code{connection} and consequently this variable is given to the queue function. | |
1880 | +Every HTTP response is accompanied by a status code, here "OK", so that the client knows | |
1881 | +this response is the intended result of his request and not due to some error or malfunction. | |
1882 | + | |
1883 | +Finally, the packet is destroyed and the return value from the queue returned, | |
1884 | +already being set at this point to either MHD_YES or MHD_NO in case of success or failure. | |
1885 | + | |
1886 | +@verbatim | |
1887 | + ret = MHD_queue_response (connection, MHD_HTTP_OK, response); | |
1888 | + MHD_destroy_response (response); | |
1889 | + | |
1890 | + return ret; | |
1891 | +} | |
1892 | + | |
1893 | +@end verbatim | |
1894 | + | |
1895 | +@noindent | |
1896 | +With the primary task of our server implemented, we can start the actual server daemon which will listen | |
1897 | +on @code{PORT} for connections. This is done in the main function. | |
1898 | +@verbatim | |
1899 | +int main () | |
1900 | +{ | |
1901 | + struct MHD_Daemon *daemon; | |
1902 | + | |
1903 | + daemon = MHD_start_daemon (MHD_USE_SELECT_INTERNALLY, PORT, NULL, NULL, | |
1904 | + &answer_to_connection, NULL, MHD_OPTION_END); | |
1905 | + if (NULL == daemon) return 1; | |
1906 | + | |
1907 | +@end verbatim | |
1908 | + | |
1909 | +@noindent | |
1910 | +The first parameter is one of three possible modes of operation. Here we want the daemon to run in | |
1911 | +a separate thread and to manage all incoming connections in the same thread. This means that while | |
1912 | +producing the response for one connection, the other connections will be put on hold. In this | |
1913 | +example, where the reply is already known and therefore the request is served quickly, this poses no problem. | |
1914 | + | |
1915 | +We will allow all clients to connect regardless of their name or location, therefore we do not check | |
1916 | +them on connection and set the forth and fifth parameter to NULL. | |
1917 | + | |
1918 | +Parameter six is the address of the function we want to be called whenever a new connection has been | |
1919 | +established. Our @code{answer_to_connection} knows best what the client wants and needs no additional | |
1920 | +information (which could be passed via the next parameter) so the next parameter is NULL. Likewise, | |
1921 | +we do not need to pass extra options to the daemon so we just write the MHD_OPTION_END as the last parameter. | |
1922 | + | |
1923 | +As the server daemon runs in the background in its own thread, the execution flow in our main | |
1924 | +function will contine right after the call. Because of this, we must delay the execution flow in the | |
1925 | +main thread or else the program will terminate prematurely. We let it pause in a processing-time | |
1926 | +friendly manner by waiting for the enter key to be pressed. In the end, we stop the daemon so it can | |
1927 | +do its cleanup tasks. | |
1928 | +@verbatim | |
1929 | + getchar (); | |
1930 | + | |
1931 | + MHD_stop_daemon (daemon); | |
1932 | + return 0; | |
1933 | +} | |
1934 | + | |
1935 | +@end verbatim | |
1936 | + | |
1937 | +@noindent | |
1938 | +The first example is now complete. | |
1939 | + | |
1940 | +Compile it with | |
1941 | +@verbatim | |
1942 | +cc hellobrowser.c -o hellobrowser -I$PATH_TO_LIBMHD_INCLUDES | |
1943 | + -L$PATH_TO_LIBMHD_LIBS -lmicrohttpd | |
1944 | +@end verbatim | |
1945 | +with the two paths set accordingly and run it. | |
1946 | + | |
1947 | +Now open your favorite Internet browser and go to the address @code{http://localhost:8888/}, provided that 8888 | |
1948 | +is the port you chose. If everything works as expected, the browser will present the message of the | |
1949 | +static HTML page it got from our minimal server. | |
1950 | + | |
1951 | +@heading Remarks | |
1952 | +To keep this first example as small as possible, some drastic shortcuts were taken and are to be | |
1953 | +discussed now. | |
1954 | + | |
1955 | +Firstly, there is no distinction made between the kinds of requests a client could send. We implied | |
1956 | +that the client sends a GET request, that means, that he actually asked for some data. Even when | |
1957 | +it is not intended to accept POST requests, a good server should at least recognize that this | |
1958 | +request does not constitute a legal request and answer with an error code. This can be easily | |
1959 | +implemented by checking if the parameter @code{method} equals the string "GET" and returning a | |
1960 | +@code{MHD_NO} if not so. | |
1961 | + | |
1962 | +Secondly, the above practice of queuing a response upon the first call of the callback function | |
1963 | +brings with it some limitations. This is because the content of the message body will not be | |
1964 | +received if a response is queued in the first iteration. Furthermore, the connection will be closed | |
1965 | +right after the response has been transferred then. This is typically not what you want as it | |
1966 | +disables HTTP pipelining. The correct approach is to simply not queue a message on the first | |
1967 | +callback unless there is an error. The @code{void**} argument to the callback provides a location | |
1968 | +for storing information about the history of the connection; for the first call, the pointer | |
1969 | +will point to NULL. A simplistic way to differenciate the first call from others is to check | |
1970 | +if the pointer is NULL and set it to a non-NULL value during the first call. | |
1971 | + | |
1972 | +Both of these issues you will find addressed in the official @code{minimal_example.c} residing in | |
1973 | +the @code{src/examples} directory of the @emph{MHD} package. The source code of this | |
1974 | +program should look very familiar to you by now and easy to understand. | |
1975 | + | |
1976 | +For our example, the @code{must_copy} and @code{must_free} parameter at the response construction | |
1977 | +function could be set to @code{MHD_NO}. In the usual case, responses cannot be sent immediately | |
1978 | +after being queued. For example, there might be other data on the system that needs to be sent with | |
1979 | +a higher priority. Nevertheless, the queue function will return successfully---raising the problem | |
1980 | +that the data we have pointed to may be invalid by the time it is about being sent. This is not an | |
1981 | +issue here because we can expect the @code{page} string, which is a constant @emph{string literal} | |
1982 | +here, to be static. That means it will be present and unchanged for as long as the program runs. | |
1983 | +For dynamic data, one could choose to either have @emph{MHD} free the memory @code{page} points | |
1984 | +to itself when it is not longer needed or, alternatively, have the library to make and manage | |
1985 | +its own copy of it. | |
1986 | + | |
1987 | +@heading Exercises | |
1988 | +@itemize @bullet | |
1989 | +@item | |
1990 | +While the server is running, use a program like @code{telnet} or @code{netcat} to connect to it. Try to form a | |
1991 | +valid HTTP 1.1 request yourself like | |
1992 | +@verbatim | |
1993 | +GET /dontcare HTTP/1.1 | |
1994 | +Host: itsme | |
1995 | +<enter> | |
1996 | +@end verbatim | |
1997 | +@noindent | |
1998 | +and see what the server returns to you. | |
1999 | + | |
2000 | + | |
2001 | +@item | |
2002 | +Also, try other requests, like POST, and see how our server does not mind and why. | |
2003 | +How far in malforming a request can you go before the builtin functionality of @emph{MHD} intervenes | |
2004 | +and an altered response is sent? Make sure you read about the status codes in the @emph{RFC}. | |
2005 | + | |
2006 | + | |
2007 | +@item | |
2008 | +Add the option @code{MHD_USE_PEDANTIC_CHECKS} to the start function of the daemon in @code{main}. | |
2009 | +Mind the special format of the parameter list here which is described in the manual. How indulgent | |
2010 | +is the server now to your input? | |
2011 | + | |
2012 | + | |
2013 | +@item | |
2014 | +Let the main function take a string as the first command line argument and pass @code{argv[1]} to | |
2015 | +the @code{MHD_start_daemon} function as the sixth parameter. The address of this string will be | |
2016 | +passed to the callback function via the @code{cls} variable. Decorate the text given at the command | |
2017 | +line when the server is started with proper HTML tags and send it as the response instead of the | |
2018 | +former static string. | |
2019 | + | |
2020 | + | |
2021 | +@item | |
2022 | +@emph{Demanding:} Write a separate function returning a string containing some useful information, | |
2023 | +for example, the time. Pass the function's address as the sixth parameter and evaluate this function | |
2024 | +on every request anew in @code{answer_to_connection}. Remember to free the memory of the string | |
2025 | +every time after satisfying the request. | |
2026 | + | |
2027 | +@end itemize | |
2028 | --- libmicrohttpd-0.9.24/doc/chapters.orig/introduction.inc 1970-01-01 01:00:00.000000000 +0100 | |
2029 | +++ libmicrohttpd-0.9.24/doc/chapters/introduction.inc 2013-01-03 19:12:00.176374962 +0100 | |
2030 | @@ -0,0 +1,23 @@ | |
2031 | +This tutorial is for developers who want to learn how they can add HTTP serving | |
2032 | +capabilities to their applications with the @emph{GNU libmicrohttpd} library, | |
2033 | +abbreviated @emph{MHD}. The reader will learn how to | |
2034 | +implement basic HTTP functions from simple executable | |
2035 | +sample programs that implement various features. | |
2036 | + | |
2037 | +The text is supposed to be a supplement to the API reference manual of | |
2038 | +@emph{GNU libmicrohttpd} and for that reason does not explain many of the parameters. | |
2039 | +Therefore, the reader should always consult the manual to find the exact meaning | |
2040 | +of the functions used in the tutorial. Furthermore, the reader is | |
2041 | +encouraged to study the relevant @emph{RFCs}, which document the HTTP standard. | |
2042 | + | |
2043 | +@emph{GNU libmicrohttpd} is assumed to be already installed. This tutorial | |
2044 | +is written for version @value{VERSION}. At the time being, | |
2045 | +this tutorial has only been tested on @emph{GNU/Linux} machines even though | |
2046 | +efforts were made not to rely on anything that would prevent the samples from being | |
2047 | +built on similar systems. | |
2048 | + | |
2049 | +@section History | |
2050 | + | |
2051 | +This tutorial was originally written by Sebastian Gerhardt for MHD | |
2052 | +0.4.0. It was slighly polished and updated to MHD 0.9.0 by Christian | |
2053 | +Grothoff. | |
2054 | --- libmicrohttpd-0.9.24/doc/chapters.orig/largerpost.inc 1970-01-01 01:00:00.000000000 +0100 | |
2055 | +++ libmicrohttpd-0.9.24/doc/chapters/largerpost.inc 2013-01-03 19:12:00.176374962 +0100 | |
2056 | @@ -0,0 +1,319 @@ | |
2057 | +The previous chapter introduced a way to upload data to the server, but the developed example program | |
2058 | +has some shortcomings, such as not being able to handle larger chunks of data. In this chapter, we | |
2059 | +are going to discuss a more advanced server program that allows clients to upload a file in order to | |
2060 | +have it stored on the server's filesystem. The server shall also watch and limit the number of | |
2061 | +clients concurrently uploading, responding with a proper busy message if necessary. | |
2062 | + | |
2063 | + | |
2064 | +@heading Prepared answers | |
2065 | +We choose to operate the server with the @code{SELECT_INTERNALLY} method. This makes it easier to | |
2066 | +synchronize the global states at the cost of possible delays for other connections if the processing | |
2067 | +of a request is too slow. One of these variables that needs to be shared for all connections is the | |
2068 | +total number of clients that are uploading. | |
2069 | + | |
2070 | +@verbatim | |
2071 | +#define MAXCLIENTS 2 | |
2072 | +static unsigned int nr_of_uploading_clients = 0; | |
2073 | +@end verbatim | |
2074 | +@noindent | |
2075 | + | |
2076 | +If there are too many clients uploading, we want the server to respond to all requests with a busy | |
2077 | +message. | |
2078 | +@verbatim | |
2079 | +const char* busypage = | |
2080 | + "<html><body>This server is busy, please try again later.</body></html>"; | |
2081 | +@end verbatim | |
2082 | +@noindent | |
2083 | + | |
2084 | +Otherwise, the server will send a @emph{form} that informs the user of the current number of uploading clients, | |
2085 | +and ask her to pick a file on her local filesystem which is to be uploaded. | |
2086 | +@verbatim | |
2087 | +const char* askpage = "<html><body>\n\ | |
2088 | + Upload a file, please!<br>\n\ | |
2089 | + There are %u clients uploading at the moment.<br>\n\ | |
2090 | + <form action=\"/filepost\" method=\"post\" \ | |
2091 | + enctype=\"multipart/form-data\">\n\ | |
2092 | + <input name=\"file\" type=\"file\">\n\ | |
2093 | + <input type=\"submit\" value=\" Send \"></form>\n\ | |
2094 | + </body></html>"; | |
2095 | +@end verbatim | |
2096 | +@noindent | |
2097 | + | |
2098 | +If the upload has succeeded, the server will respond with a message saying so. | |
2099 | +@verbatim | |
2100 | +const char* completepage = "<html><body>The upload has been completed.</body></html>"; | |
2101 | +@end verbatim | |
2102 | +@noindent | |
2103 | + | |
2104 | +We want the server to report internal errors, such as memory shortage or file access problems, | |
2105 | +adequately. | |
2106 | +@verbatim | |
2107 | +const char* servererrorpage | |
2108 | + = "<html><body>An internal server error has occured.</body></html>"; | |
2109 | +const char* fileexistspage | |
2110 | + = "<html><body>This file already exists.</body></html>"; | |
2111 | +@end verbatim | |
2112 | +@noindent | |
2113 | + | |
2114 | +It would be tolerable to send all these responses undifferentiated with a @code{200 HTTP_OK} | |
2115 | +status code but in order to improve the @code{HTTP} conformance of our server a bit, we extend the | |
2116 | +@code{send_page} function so that it accepts individual status codes. | |
2117 | + | |
2118 | +@verbatim | |
2119 | +static int | |
2120 | +send_page (struct MHD_Connection *connection, | |
2121 | + const char* page, int status_code) | |
2122 | +{ | |
2123 | + int ret; | |
2124 | + struct MHD_Response *response; | |
2125 | + | |
2126 | + response = MHD_create_response_from_buffer (strlen (page), (void*) page, | |
2127 | + MHD_RESPMEM_MUST_COPY); | |
2128 | + if (!response) return MHD_NO; | |
2129 | + | |
2130 | + ret = MHD_queue_response (connection, status_code, response); | |
2131 | + MHD_destroy_response (response); | |
2132 | + | |
2133 | + return ret; | |
2134 | +} | |
2135 | +@end verbatim | |
2136 | +@noindent | |
2137 | + | |
2138 | +Note how we ask @emph{MHD} to make its own copy of the message data. The reason behind this will | |
2139 | +become clear later. | |
2140 | + | |
2141 | + | |
2142 | +@heading Connection cycle | |
2143 | +The decision whether the server is busy or not is made right at the beginning of the connection. To | |
2144 | +do that at this stage is especially important for @emph{POST} requests because if no response is | |
2145 | +queued at this point, and @code{MHD_YES} returned, @emph{MHD} will not sent any queued messages until | |
2146 | +a postprocessor has been created and the post iterator is called at least once. | |
2147 | + | |
2148 | +@verbatim | |
2149 | +static int | |
2150 | +answer_to_connection (void *cls, struct MHD_Connection *connection, | |
2151 | + const char *url, | |
2152 | + const char *method, const char *version, | |
2153 | + const char *upload_data, | |
2154 | + size_t *upload_data_size, void **con_cls) | |
2155 | +{ | |
2156 | + if (NULL == *con_cls) | |
2157 | + { | |
2158 | + struct connection_info_struct *con_info; | |
2159 | + | |
2160 | + if (nr_of_uploading_clients >= MAXCLIENTS) | |
2161 | + return send_page(connection, busypage, MHD_HTTP_SERVICE_UNAVAILABLE); | |
2162 | +@end verbatim | |
2163 | +@noindent | |
2164 | + | |
2165 | +If the server is not busy, the @code{connection_info} structure is initialized as usual, with | |
2166 | +the addition of a filepointer for each connection. | |
2167 | + | |
2168 | +@verbatim | |
2169 | + con_info = malloc (sizeof (struct connection_info_struct)); | |
2170 | + if (NULL == con_info) return MHD_NO; | |
2171 | + con_info->fp = 0; | |
2172 | + | |
2173 | + if (0 == strcmp (method, "POST")) | |
2174 | + { | |
2175 | + ... | |
2176 | + } | |
2177 | + else con_info->connectiontype = GET; | |
2178 | + | |
2179 | + *con_cls = (void*) con_info; | |
2180 | + | |
2181 | + return MHD_YES; | |
2182 | + } | |
2183 | +@end verbatim | |
2184 | +@noindent | |
2185 | + | |
2186 | +For @emph{POST} requests, the postprocessor is created and we register a new uploading client. From | |
2187 | +this point on, there are many possible places for errors to occur that make it necessary to interrupt | |
2188 | +the uploading process. We need a means of having the proper response message ready at all times. | |
2189 | +Therefore, the @code{connection_info} structure is extended to hold the most current response | |
2190 | +message so that whenever a response is sent, the client will get the most informative message. Here, | |
2191 | +the structure is initialized to "no error". | |
2192 | +@verbatim | |
2193 | + if (0 == strcmp (method, "POST")) | |
2194 | + { | |
2195 | + con_info->postprocessor | |
2196 | + = MHD_create_post_processor (connection, POSTBUFFERSIZE, | |
2197 | + iterate_post, (void*) con_info); | |
2198 | + | |
2199 | + if (NULL == con_info->postprocessor) | |
2200 | + { | |
2201 | + free (con_info); | |
2202 | + return MHD_NO; | |
2203 | + } | |
2204 | + | |
2205 | + nr_of_uploading_clients++; | |
2206 | + | |
2207 | + con_info->connectiontype = POST; | |
2208 | + con_info->answercode = MHD_HTTP_OK; | |
2209 | + con_info->answerstring = completepage; | |
2210 | + } | |
2211 | + else con_info->connectiontype = GET; | |
2212 | +@end verbatim | |
2213 | +@noindent | |
2214 | + | |
2215 | +If the connection handler is called for the second time, @emph{GET} requests will be answered with | |
2216 | +the @emph{form}. We can keep the buffer under function scope, because we asked @emph{MHD} to make its | |
2217 | +own copy of it for as long as it is needed. | |
2218 | +@verbatim | |
2219 | + if (0 == strcmp (method, "GET")) | |
2220 | + { | |
2221 | + int ret; | |
2222 | + char buffer[1024]; | |
2223 | + | |
2224 | + sprintf (buffer, askpage, nr_of_uploading_clients); | |
2225 | + return send_page (connection, buffer, MHD_HTTP_OK); | |
2226 | + } | |
2227 | +@end verbatim | |
2228 | +@noindent | |
2229 | + | |
2230 | + | |
2231 | +The rest of the @code{answer_to_connection} function is very similar to the @code{simplepost.c} | |
2232 | +example, except the more flexible content of the responses. The @emph{POST} data is processed until | |
2233 | +there is none left and the execution falls through to return an error page if the connection | |
2234 | +constituted no expected request method. | |
2235 | +@verbatim | |
2236 | + if (0 == strcmp (method, "POST")) | |
2237 | + { | |
2238 | + struct connection_info_struct *con_info = *con_cls; | |
2239 | + | |
2240 | + if (0 != *upload_data_size) | |
2241 | + { | |
2242 | + MHD_post_process (con_info->postprocessor, | |
2243 | + upload_data, *upload_data_size); | |
2244 | + *upload_data_size = 0; | |
2245 | + | |
2246 | + return MHD_YES; | |
2247 | + } | |
2248 | + else | |
2249 | + return send_page (connection, con_info->answerstring, | |
2250 | + con_info->answercode); | |
2251 | + } | |
2252 | + | |
2253 | + return send_page(connection, errorpage, MHD_HTTP_BAD_REQUEST); | |
2254 | +} | |
2255 | +@end verbatim | |
2256 | +@noindent | |
2257 | + | |
2258 | + | |
2259 | +@heading Storing to data | |
2260 | +Unlike the @code{simplepost.c} example, here it is to be expected that post iterator will be called | |
2261 | +several times now. This means that for any given connection (there might be several concurrent of them) | |
2262 | +the posted data has to be written to the correct file. That is why we store a file handle in every | |
2263 | +@code{connection_info}, so that the it is preserved between successive iterations. | |
2264 | +@verbatim | |
2265 | +static int | |
2266 | +iterate_post (void *coninfo_cls, enum MHD_ValueKind kind, | |
2267 | + const char *key, | |
2268 | + const char *filename, const char *content_type, | |
2269 | + const char *transfer_encoding, const char *data, | |
2270 | + uint64_t off, size_t size) | |
2271 | +{ | |
2272 | + struct connection_info_struct *con_info = coninfo_cls; | |
2273 | +@end verbatim | |
2274 | +@noindent | |
2275 | + | |
2276 | +Because the following actions depend heavily on correct file processing, which might be error prone, | |
2277 | +we default to reporting internal errors in case anything will go wrong. | |
2278 | + | |
2279 | +@verbatim | |
2280 | +con_info->answerstring = servererrorpage; | |
2281 | +con_info->answercode = MHD_HTTP_INTERNAL_SERVER_ERROR; | |
2282 | +@end verbatim | |
2283 | +@noindent | |
2284 | + | |
2285 | +In the "askpage" @emph{form}, we told the client to label its post data with the "file" key. Anything else | |
2286 | +would be an error. | |
2287 | + | |
2288 | +@verbatim | |
2289 | + if (0 != strcmp (key, "file")) return MHD_NO; | |
2290 | +@end verbatim | |
2291 | +@noindent | |
2292 | + | |
2293 | +If the iterator is called for the first time, no file will have been opened yet. The @code{filename} | |
2294 | +string contains the name of the file (without any paths) the user selected on his system. We want to | |
2295 | +take this as the name the file will be stored on the server and make sure no file of that name exists | |
2296 | +(or is being uploaded) before we create one (note that the code below technically contains a | |
2297 | +race between the two "fopen" calls, but we will overlook this for portability sake). | |
2298 | +@verbatim | |
2299 | + if (!con_info->fp) | |
2300 | + { | |
2301 | + if (NULL != (fp = fopen (filename, "rb")) ) | |
2302 | + { | |
2303 | + fclose (fp); | |
2304 | + con_info->answerstring = fileexistspage; | |
2305 | + con_info->answercode = MHD_HTTP_FORBIDDEN; | |
2306 | + return MHD_NO; | |
2307 | + } | |
2308 | + | |
2309 | + con_info->fp = fopen (filename, "ab"); | |
2310 | + if (!con_info->fp) return MHD_NO; | |
2311 | + } | |
2312 | +@end verbatim | |
2313 | +@noindent | |
2314 | + | |
2315 | + | |
2316 | +Occasionally, the iterator function will be called even when there are 0 new bytes to process. The | |
2317 | +server only needs to write data to the file if there is some. | |
2318 | +@verbatim | |
2319 | +if (size > 0) | |
2320 | + { | |
2321 | + if (!fwrite (data, size, sizeof(char), con_info->fp)) | |
2322 | + return MHD_NO; | |
2323 | + } | |
2324 | +@end verbatim | |
2325 | +@noindent | |
2326 | + | |
2327 | +If this point has been reached, everything worked well for this iteration and the response can | |
2328 | +be set to success again. If the upload has finished, this iterator function will not be called again. | |
2329 | +@verbatim | |
2330 | + con_info->answerstring = completepage; | |
2331 | + con_info->answercode = MHD_HTTP_OK; | |
2332 | + | |
2333 | + return MHD_YES; | |
2334 | +} | |
2335 | +@end verbatim | |
2336 | +@noindent | |
2337 | + | |
2338 | + | |
2339 | +The new client was registered when the postprocessor was created. Likewise, we unregister the client | |
2340 | +on destroying the postprocessor when the request is completed. | |
2341 | +@verbatim | |
2342 | +void request_completed (void *cls, struct MHD_Connection *connection, | |
2343 | + void **con_cls, | |
2344 | + enum MHD_RequestTerminationCode toe) | |
2345 | +{ | |
2346 | + struct connection_info_struct *con_info = *con_cls; | |
2347 | + | |
2348 | + if (NULL == con_info) return; | |
2349 | + | |
2350 | + if (con_info->connectiontype == POST) | |
2351 | + { | |
2352 | + if (NULL != con_info->postprocessor) | |
2353 | + { | |
2354 | + MHD_destroy_post_processor (con_info->postprocessor); | |
2355 | + nr_of_uploading_clients--; | |
2356 | + } | |
2357 | + | |
2358 | + if (con_info->fp) fclose (con_info->fp); | |
2359 | + } | |
2360 | + | |
2361 | + free (con_info); | |
2362 | + *con_cls = NULL; | |
2363 | +} | |
2364 | +@end verbatim | |
2365 | +@noindent | |
2366 | + | |
2367 | + | |
2368 | +This is essentially the whole example @code{largepost.c}. | |
2369 | + | |
2370 | + | |
2371 | +@heading Remarks | |
2372 | +Now that the clients are able to create files on the server, security aspects are becoming even more | |
2373 | +important than before. Aside from proper client authentication, the server should always make sure | |
2374 | +explicitly that no files will be created outside of a dedicated upload directory. In particular, | |
2375 | +filenames must be checked to not contain strings like "../". | |
2376 | --- libmicrohttpd-0.9.24/doc/chapters.orig/processingpost.inc 1970-01-01 01:00:00.000000000 +0100 | |
2377 | +++ libmicrohttpd-0.9.24/doc/chapters/processingpost.inc 2013-01-03 19:12:00.176374962 +0100 | |
2378 | @@ -0,0 +1,238 @@ | |
2379 | +The previous chapters already have demonstrated a variety of possibilities to send information | |
2380 | +to the HTTP server, but it is not recommended that the @emph{GET} method is used to alter the way | |
2381 | +the server operates. To induce changes on the server, the @emph{POST} method is preferred over | |
2382 | +and is much more powerful than @emph{GET} and will be introduced in this chapter. | |
2383 | + | |
2384 | +We are going to write an application that asks for the visitor's name and, after the user has posted it, | |
2385 | +composes an individual response text. Even though it was not mandatory to use the @emph{POST} method here, | |
2386 | +as there is no permanent change caused by the POST, it is an illustrative example on how to share data | |
2387 | +between different functions for the same connection. Furthermore, the reader should be able to extend | |
2388 | +it easily. | |
2389 | + | |
2390 | +@heading GET request | |
2391 | +When the first @emph{GET} request arrives, the server shall respond with a HTML page containing an | |
2392 | +edit field for the name. | |
2393 | + | |
2394 | +@verbatim | |
2395 | +const char* askpage = "<html><body>\ | |
2396 | + What's your name, Sir?<br>\ | |
2397 | + <form action=\"/namepost\" method=\"post\">\ | |
2398 | + <input name=\"name\" type=\"text\"\ | |
2399 | + <input type=\"submit\" value=\" Send \"></form>\ | |
2400 | + </body></html>"; | |
2401 | +@end verbatim | |
2402 | +@noindent | |
2403 | + | |
2404 | +The @code{action} entry is the @emph{URI} to be called by the browser when posting, and the | |
2405 | +@code{name} will be used later to be sure it is the editbox's content that has been posted. | |
2406 | + | |
2407 | +We also prepare the answer page, where the name is to be filled in later, and an error page | |
2408 | +as the response for anything but proper @emph{GET} and @emph{POST} requests: | |
2409 | + | |
2410 | +@verbatim | |
2411 | +const char* greatingpage="<html><body><h1>Welcome, %s!</center></h1></body></html>"; | |
2412 | + | |
2413 | +const char* errorpage="<html><body>This doesn't seem to be right.</body></html>"; | |
2414 | +@end verbatim | |
2415 | +@noindent | |
2416 | + | |
2417 | +Whenever we need to send a page, we use an extra function | |
2418 | +@code{int send_page(struct MHD_Connection *connection, const char* page)} | |
2419 | +for this, which does not contain anything new and whose implementation is therefore | |
2420 | +not discussed further in the tutorial. | |
2421 | + | |
2422 | + | |
2423 | +@heading POST request | |
2424 | +Posted data can be of arbitrary and considerable size; for example, if a user uploads a big | |
2425 | +image to the server. Similar to the case of the header fields, there may also be different streams | |
2426 | +of posted data, such as one containing the text of an editbox and another the state of a button. | |
2427 | +Likewise, we will have to register an iterator function that is going to be called maybe several times | |
2428 | +not only if there are different POSTs but also if one POST has only been received partly yet and | |
2429 | +needs processing before another chunk can be received. | |
2430 | + | |
2431 | +Such an iterator function is called by a @emph{postprocessor}, which must be created upon arriving | |
2432 | +of the post request. We want the iterator function to read the first post data which is tagged | |
2433 | +@code{name} and to create an individual greeting string based on the template and the name. | |
2434 | +But in order to pass this string to other functions and still be able to differentiate different | |
2435 | +connections, we must first define a structure to share the information, holding the most import entries. | |
2436 | + | |
2437 | +@verbatim | |
2438 | +struct connection_info_struct | |
2439 | +{ | |
2440 | + int connectiontype; | |
2441 | + char *answerstring; | |
2442 | + struct MHD_PostProcessor *postprocessor; | |
2443 | +}; | |
2444 | +@end verbatim | |
2445 | +@noindent | |
2446 | + | |
2447 | +With these information available to the iterator function, it is able to fulfill its task. | |
2448 | +Once it has composed the greeting string, it returns @code{MHD_NO} to inform the post processor | |
2449 | +that it does not need to be called again. Note that this function does not handle processing | |
2450 | +of data for the same @code{key}. If we were to expect that the name will be posted in several | |
2451 | +chunks, we had to expand the namestring dynamically as additional parts of it with the same @code{key} | |
2452 | +came in. But in this example, the name is assumed to fit entirely inside one single packet. | |
2453 | + | |
2454 | +@verbatim | |
2455 | +static int | |
2456 | +iterate_post (void *coninfo_cls, enum MHD_ValueKind kind, const char *key, | |
2457 | + const char *filename, const char *content_type, | |
2458 | + const char *transfer_encoding, const char *data, | |
2459 | + uint64_t off, size_t size) | |
2460 | +{ | |
2461 | + struct connection_info_struct *con_info = coninfo_cls; | |
2462 | + | |
2463 | + if (0 == strcmp (key, "name")) | |
2464 | + { | |
2465 | + if ((size > 0) && (size <= MAXNAMESIZE)) | |
2466 | + { | |
2467 | + char *answerstring; | |
2468 | + answerstring = malloc (MAXANSWERSIZE); | |
2469 | + if (!answerstring) return MHD_NO; | |
2470 | + | |
2471 | + snprintf (answerstring, MAXANSWERSIZE, greatingpage, data); | |
2472 | + con_info->answerstring = answerstring; | |
2473 | + } | |
2474 | + else con_info->answerstring = NULL; | |
2475 | + | |
2476 | + return MHD_NO; | |
2477 | + } | |
2478 | + | |
2479 | + return MHD_YES; | |
2480 | +} | |
2481 | +@end verbatim | |
2482 | +@noindent | |
2483 | + | |
2484 | +Once a connection has been established, it can be terminated for many reasons. As these | |
2485 | +reasons include unexpected events, we have to register another function that cleans up any resources | |
2486 | +that might have been allocated for that connection by us, namely the post processor and the greetings | |
2487 | +string. This cleanup function must take into account that it will also be called for finished | |
2488 | +requests other than @emph{POST} requests. | |
2489 | + | |
2490 | +@verbatim | |
2491 | +void request_completed (void *cls, struct MHD_Connection *connection, | |
2492 | + void **con_cls, | |
2493 | + enum MHD_RequestTerminationCode toe) | |
2494 | +{ | |
2495 | + struct connection_info_struct *con_info = *con_cls; | |
2496 | + | |
2497 | + if (NULL == con_info) return; | |
2498 | + if (con_info->connectiontype == POST) | |
2499 | + { | |
2500 | + MHD_destroy_post_processor (con_info->postprocessor); | |
2501 | + if (con_info->answerstring) free (con_info->answerstring); | |
2502 | + } | |
2503 | + | |
2504 | + free (con_info); | |
2505 | + *con_cls = NULL; | |
2506 | +} | |
2507 | +@end verbatim | |
2508 | +@noindent | |
2509 | + | |
2510 | +@emph{GNU libmicrohttpd} is informed that it shall call the above function when the daemon is started | |
2511 | +in the main function. | |
2512 | + | |
2513 | +@verbatim | |
2514 | +... | |
2515 | +daemon = MHD_start_daemon (MHD_USE_SELECT_INTERNALLY, PORT, NULL, NULL, | |
2516 | + &answer_to_connection, NULL, | |
2517 | + MHD_OPTION_NOTIFY_COMPLETED, &request_completed, NULL, | |
2518 | + MHD_OPTION_END); | |
2519 | +... | |
2520 | +@end verbatim | |
2521 | +@noindent | |
2522 | + | |
2523 | +@heading Request handling | |
2524 | +With all other functions prepared, we can now discuss the actual request handling. | |
2525 | + | |
2526 | +On the first iteration for a new request, we start by allocating a new instance of a | |
2527 | +@code{struct connection_info_struct} structure, which will store all necessary information for later | |
2528 | +iterations and other functions. | |
2529 | + | |
2530 | +@verbatim | |
2531 | +static int | |
2532 | +answer_to_connection (void *cls, struct MHD_Connection *connection, | |
2533 | + const char *url, | |
2534 | + const char *method, const char *version, | |
2535 | + const char *upload_data, | |
2536 | + size_t *upload_data_size, void **con_cls) | |
2537 | +{ | |
2538 | + if(NULL == *con_cls) | |
2539 | + { | |
2540 | + struct connection_info_struct *con_info; | |
2541 | + | |
2542 | + con_info = malloc (sizeof (struct connection_info_struct)); | |
2543 | + if (NULL == con_info) return MHD_NO; | |
2544 | + con_info->answerstring = NULL; | |
2545 | +@end verbatim | |
2546 | +@noindent | |
2547 | + | |
2548 | +If the new request is a @emph{POST}, the postprocessor must be created now. In addition, the type | |
2549 | +of the request is stored for convenience. | |
2550 | +@verbatim | |
2551 | + if (0 == strcmp (method, "POST")) | |
2552 | + { | |
2553 | + con_info->postprocessor | |
2554 | + = MHD_create_post_processor (connection, POSTBUFFERSIZE, | |
2555 | + iterate_post, (void*) con_info); | |
2556 | + | |
2557 | + if (NULL == con_info->postprocessor) | |
2558 | + { | |
2559 | + free (con_info); | |
2560 | + return MHD_NO; | |
2561 | + } | |
2562 | + con_info->connectiontype = POST; | |
2563 | + } | |
2564 | + else con_info->connectiontype = GET; | |
2565 | +@end verbatim | |
2566 | +@noindent | |
2567 | + | |
2568 | +The address of our structure will both serve as the indicator for successive iterations and to remember | |
2569 | +the particular details about the connection. | |
2570 | +@verbatim | |
2571 | + *con_cls = (void*) con_info; | |
2572 | + return MHD_YES; | |
2573 | + } | |
2574 | +@end verbatim | |
2575 | +@noindent | |
2576 | + | |
2577 | +The rest of the function will not be executed on the first iteration. A @emph{GET} request is easily | |
2578 | +satisfied by sending the question form. | |
2579 | +@verbatim | |
2580 | + if (0 == strcmp (method, "GET")) | |
2581 | + { | |
2582 | + return send_page (connection, askpage); | |
2583 | + } | |
2584 | +@end verbatim | |
2585 | +@noindent | |
2586 | + | |
2587 | +In case of @emph{POST}, we invoke the post processor for as long as data keeps incoming, setting | |
2588 | +@code{*upload_data_size} to zero in order to indicate that we have processed---or at least have | |
2589 | +considered---all of it. | |
2590 | +@verbatim | |
2591 | + if (0 == strcmp (method, "POST")) | |
2592 | + { | |
2593 | + struct connection_info_struct *con_info = *con_cls; | |
2594 | + | |
2595 | + if (*upload_data_size != 0) | |
2596 | + { | |
2597 | + MHD_post_process (con_info->postprocessor, upload_data, | |
2598 | + *upload_data_size); | |
2599 | + *upload_data_size = 0; | |
2600 | + | |
2601 | + return MHD_YES; | |
2602 | + } | |
2603 | + else if (NULL != con_info->answerstring) | |
2604 | + return send_page (connection, con_info->answerstring); | |
2605 | + } | |
2606 | +@end verbatim | |
2607 | +@noindent | |
2608 | + | |
2609 | +Finally, if they are neither @emph{GET} nor @emph{POST} requests, the error page is returned. | |
2610 | +@verbatim | |
2611 | + return send_page(connection, errorpage); | |
2612 | +} | |
2613 | +@end verbatim | |
2614 | +@noindent | |
2615 | + | |
2616 | +These were the important parts of the program @code{simplepost.c}. | |
2617 | --- libmicrohttpd-0.9.24/doc/chapters.orig/responseheaders.inc 1970-01-01 01:00:00.000000000 +0100 | |
2618 | +++ libmicrohttpd-0.9.24/doc/chapters/responseheaders.inc 2013-01-03 19:12:00.176374962 +0100 | |
2619 | @@ -0,0 +1,193 @@ | |
2620 | +Now that we are able to inspect the incoming request in great detail, | |
2621 | +this chapter discusses the means to enrich the outgoing responses likewise. | |
2622 | + | |
2623 | +As you have learned in the @emph{Hello, Browser} chapter, some obligatory | |
2624 | +header fields are added and set automatically for simple responses by the library | |
2625 | +itself but if more advanced features are desired, additional fields have to be created. | |
2626 | +One of the possible fields is the content type field and an example will be developed around it. | |
2627 | +This will lead to an application capable of correctly serving different types of files. | |
2628 | + | |
2629 | + | |
2630 | +When we responded with HTML page packed in the static string previously, the client had no choice | |
2631 | +but guessing about how to handle the response, because the server had not told him. | |
2632 | +What if we had sent a picture or a sound file? Would the message have been understood | |
2633 | +or merely been displayed as an endless stream of random characters in the browser? | |
2634 | +This is what the mime content types are for. The header of the response is extended | |
2635 | +by certain information about how the data is to be interpreted. | |
2636 | + | |
2637 | +To introduce the concept, a picture of the format @emph{PNG} will be sent to the client | |
2638 | +and labeled accordingly with @code{image/png}. | |
2639 | +Once again, we can base the new example on the @code{hellobrowser} program. | |
2640 | + | |
2641 | +@verbatim | |
2642 | +#define FILENAME "picture.png" | |
2643 | +#define MIMETYPE "image/png" | |
2644 | + | |
2645 | +static int | |
2646 | +answer_to_connection (void *cls, struct MHD_Connection *connection, | |
2647 | + const char *url, | |
2648 | + const char *method, const char *version, | |
2649 | + const char *upload_data, | |
2650 | + size_t *upload_data_size, void **con_cls) | |
2651 | +{ | |
2652 | + unsigned char *buffer = NULL; | |
2653 | + struct MHD_Response *response; | |
2654 | +@end verbatim | |
2655 | +@noindent | |
2656 | + | |
2657 | +We want the program to open the file for reading and determine its size: | |
2658 | +@verbatim | |
2659 | + int fd; | |
2660 | + int ret; | |
2661 | + struct stat sbuf; | |
2662 | + | |
2663 | + if (0 != strcmp (method, "GET")) | |
2664 | + return MHD_NO; | |
2665 | + if ( (-1 == (fd = open (FILENAME, O_RDONLY))) || | |
2666 | + (0 != fstat (fd, &sbuf)) ) | |
2667 | + { | |
2668 | + /* error accessing file */ | |
2669 | + /* ... (see below) */ | |
2670 | + } | |
2671 | + /* ... (see below) */ | |
2672 | +@end verbatim | |
2673 | +@noindent | |
2674 | + | |
2675 | +When dealing with files, there is a lot that could go wrong on the | |
2676 | +server side and if so, the client should be informed with @code{MHD_HTTP_INTERNAL_SERVER_ERROR}. | |
2677 | + | |
2678 | +@verbatim | |
2679 | + /* error accessing file */ | |
2680 | + if (fd != -1) close (fd); | |
2681 | + const char *errorstr = | |
2682 | + "<html><body>An internal server error has occured!\ | |
2683 | + </body></html>"; | |
2684 | + response = | |
2685 | + MHD_create_response_from_buffer (strlen (errorstr), | |
2686 | + (void *) errorstr, | |
2687 | + MHD_RESPMEM_PERSISTENT); | |
2688 | + if (response) | |
2689 | + { | |
2690 | + ret = | |
2691 | + MHD_queue_response (connection, MHD_HTTP_INTERNAL_SERVER_ERROR, | |
2692 | + response); | |
2693 | + MHD_destroy_response (response); | |
2694 | + | |
2695 | + return MHD_YES; | |
2696 | + } | |
2697 | + else | |
2698 | + return MHD_NO; | |
2699 | + if (!ret) | |
2700 | + { | |
2701 | + const char *errorstr = "<html><body>An internal server error has occured!\ | |
2702 | + </body></html>"; | |
2703 | + | |
2704 | + if (buffer) free(buffer); | |
2705 | + | |
2706 | + response = MHD_create_response_from_buffer (strlen(errorstr), (void*) errorstr, | |
2707 | + MHD_RESPMEM_PERSISTENT); | |
2708 | + | |
2709 | + if (response) | |
2710 | + { | |
2711 | + ret = MHD_queue_response (connection, | |
2712 | + MHD_HTTP_INTERNAL_SERVER_ERROR, | |
2713 | + response); | |
2714 | + MHD_destroy_response (response); | |
2715 | + | |
2716 | + return MHD_YES; | |
2717 | + } | |
2718 | + else return MHD_NO; | |
2719 | + } | |
2720 | +@end verbatim | |
2721 | +@noindent | |
2722 | + | |
2723 | +Note that we nevertheless have to create a response object even for sending a simple error code. | |
2724 | +Otherwise, the connection would just be closed without comment, leaving the client curious about | |
2725 | +what has happened. | |
2726 | + | |
2727 | +But in the case of success a response will be constructed directly from the file descriptor: | |
2728 | + | |
2729 | +@verbatim | |
2730 | + /* error accessing file */ | |
2731 | + /* ... (see above) */ | |
2732 | + } | |
2733 | + | |
2734 | + response = | |
2735 | + MHD_create_response_from_fd_at_offset (sbuf.st_size, fd, 0); | |
2736 | + MHD_add_response_header (response, "Content-Type", MIMETYPE); | |
2737 | + ret = MHD_queue_response (connection, MHD_HTTP_OK, response); | |
2738 | + MHD_destroy_response (response); | |
2739 | +@end verbatim | |
2740 | +@noindent | |
2741 | + | |
2742 | +Note that the response object will take care of closing the file desciptor for us. | |
2743 | + | |
2744 | +Up to this point, there was little new. The actual novelty is that we enhance the header with the | |
2745 | +meta data about the content. Aware of the field's name we want to add, it is as easy as that: | |
2746 | +@verbatim | |
2747 | +MHD_add_response_header(response, "Content-Type", MIMETYPE); | |
2748 | +@end verbatim | |
2749 | +@noindent | |
2750 | +We do not have to append a colon expected by the protocol behind the first | |
2751 | +field---@emph{GNU libhttpdmicro} will take care of this. | |
2752 | + | |
2753 | +The function finishes with the well-known lines | |
2754 | +@verbatim | |
2755 | + ret = MHD_queue_response (connection, MHD_HTTP_OK, response); | |
2756 | + MHD_destroy_response (response); | |
2757 | + return ret; | |
2758 | +} | |
2759 | +@end verbatim | |
2760 | +@noindent | |
2761 | + | |
2762 | +The complete program @code{responseheaders.c} is in the @code{examples} section as usual. | |
2763 | +Find a @emph{PNG} file you like and save it to the directory the example is run from under the name | |
2764 | +@code{picture.png}. You should find the image displayed on your browser if everything worked well. | |
2765 | + | |
2766 | +@heading Remarks | |
2767 | +The include file of the @emph{MHD} library comes with the header types mentioned in @emph{RFC 2616} | |
2768 | +already defined as macros. Thus, we could have written @code{MHD_HTTP_HEADER_CONTENT_TYPE} instead | |
2769 | +of @code{"Content-Type"} as well. However, one is not limited to these standard headers and could | |
2770 | +add custom response headers without violating the protocol. Whether, and how, the client would react | |
2771 | +to these custom header is up to the receiver. Likewise, the client is allowed to send custom request | |
2772 | +headers to the server as well, opening up yet more possibilities how client and server could | |
2773 | +communicate with each other. | |
2774 | + | |
2775 | +The method of creating the response from a file on disk only works for static content. | |
2776 | +Serving dynamically created responses will be a topic of a future chapter. | |
2777 | + | |
2778 | +@heading Exercises | |
2779 | +@itemize @bullet | |
2780 | + | |
2781 | +@item | |
2782 | +Remember that the original program was written under a few assumptions---a static response | |
2783 | +using a local file being one of them. In order to simulate a very large or hard to reach file that cannot be provided | |
2784 | +instantly, postpone the queuing in the callback with the @code{sleep} function for 30 seconds | |
2785 | +@emph{if} the file @code{/big.png} is requested (but deliver the same as above). A request for | |
2786 | +@code{/picture.png} should provide just the same but without any artificial delays. | |
2787 | + | |
2788 | +Now start two instances of your browser (or even use two machines) and see how the second client | |
2789 | +is put on hold while the first waits for his request on the slow file to be fulfilled. | |
2790 | + | |
2791 | +Finally, change the sourcecode to use @code{MHD_USE_THREAD_PER_CONNECTION} when the daemon is | |
2792 | +started and try again. | |
2793 | + | |
2794 | + | |
2795 | +@item | |
2796 | +Did you succeed in implementing the clock exercise yet? This time, let the server save the | |
2797 | +program's start time @code{t} and implement a response simulating a countdown that reaches 0 at | |
2798 | +@code{t+60}. Returning a message saying on which point the countdown is, the response should | |
2799 | +ultimately be to reply "Done" if the program has been running long enough, | |
2800 | + | |
2801 | +An unofficial, but widely understood, response header line is @code{Refresh: DELAY; url=URL} with | |
2802 | +the uppercase words substituted to tell the client it should request the given resource after | |
2803 | +the given delay again. Improve your program in that the browser (any modern browser should work) | |
2804 | +automatically reconnects and asks for the status again every 5 seconds or so. The URL would have | |
2805 | +to be composed so that it begins with "http://", followed by the @emph{URI} the server is reachable | |
2806 | +from the client's point of view. | |
2807 | + | |
2808 | +Maybe you want also to visualize the countdown as a status bar by creating a | |
2809 | +@code{<table>} consisting of one row and @code{n} columns whose fields contain small images of either | |
2810 | +a red or a green light. | |
2811 | + | |
2812 | +@end itemize | |
2813 | --- libmicrohttpd-0.9.24/doc/chapters.orig/sessions.inc 1970-01-01 01:00:00.000000000 +0100 | |
2814 | +++ libmicrohttpd-0.9.24/doc/chapters/sessions.inc 2013-01-03 19:12:00.176374962 +0100 | |
2815 | @@ -0,0 +1,71 @@ | |
2816 | +This chapter discusses how one should manage sessions, that is, share state between multiple | |
2817 | +HTTP requests from the same user. We use a simple example where the user submits multiple | |
2818 | +forms and the server is supposed to accumulate state from all of these forms. Naturally, as | |
2819 | +this is a network protocol, our session mechanism must support having many users with | |
2820 | +many concurrent sessions at the same time. | |
2821 | + | |
2822 | +In order to track users, we use a simple session cookie. A session cookie expires when the | |
2823 | +user closes the browser. Changing from session cookies to persistent cookies only requires | |
2824 | +adding an expiration time to the cookie. The server creates a fresh session cookie whenever | |
2825 | +a request without a cookie is received, or if the supplied session cookie is not known to | |
2826 | +the server. | |
2827 | + | |
2828 | +@heading Looking up the cookie | |
2829 | + | |
2830 | +Since MHD parses the HTTP cookie header for us, looking up an existing cookie | |
2831 | +is straightforward: | |
2832 | + | |
2833 | +@verbatim | |
2834 | +FIXME. | |
2835 | +@end verbatim | |
2836 | + | |
2837 | +Here, FIXME is the name we chose for our session cookie. | |
2838 | + | |
2839 | + | |
2840 | +@heading Setting the cookie header | |
2841 | + | |
2842 | +MHD requires the user to provide the full cookie format string in order to set | |
2843 | +cookies. In order to generate a unique cookie, our example creates a random | |
2844 | +64-character text string to be used as the value of the cookie: | |
2845 | + | |
2846 | +@verbatim | |
2847 | +FIXME. | |
2848 | +@end verbatim | |
2849 | + | |
2850 | +Given this cookie value, we can then set the cookie header in our HTTP response | |
2851 | +as follows: | |
2852 | + | |
2853 | +@verbatim | |
2854 | +FIXME. | |
2855 | +@end verbatim | |
2856 | + | |
2857 | + | |
2858 | +@heading Remark: Session expiration | |
2859 | + | |
2860 | +It is of course possible that clients stop their interaction with the | |
2861 | +server at any time. In order to avoid using too much storage, the | |
2862 | +server must thus discard inactive sessions at some point. Our example | |
2863 | +implements this by discarding inactive sessions after a certain amount | |
2864 | +of time. Alternatively, the implementation may limit the total number | |
2865 | +of active sessions. Which bounds are used for idle sessions or the | |
2866 | +total number of sessions obviously depends largely on the type of | |
2867 | +the application and available server resources. | |
2868 | + | |
2869 | +@heading Example code | |
2870 | + | |
2871 | +A sample application implementing a website with multiple | |
2872 | +forms (which are dynamically created using values from previous | |
2873 | +POST requests from the same session) is available | |
2874 | +as the example @code{sessions.c}. | |
2875 | + | |
2876 | +Note that the example uses a simple, $O(n)$ linked list traversal to | |
2877 | +look up sessions and to expire old sessions. Using a hash table and a | |
2878 | +heap would be more appropriate if a large number of concurrent | |
2879 | +sessions is expected. | |
2880 | + | |
2881 | +@heading Remarks | |
2882 | + | |
2883 | +Naturally, it is quite conceivable to store session data in a database | |
2884 | +instead of in memory. Still, having mechanisms to expire data | |
2885 | +associated with long-time idle sessions (where the business process | |
2886 | +has still not finished) is likely a good idea. | |
2887 | --- libmicrohttpd-0.9.24/doc/chapters.orig/tlsauthentication.inc 1970-01-01 01:00:00.000000000 +0100 | |
2888 | +++ libmicrohttpd-0.9.24/doc/chapters/tlsauthentication.inc 2013-01-03 19:12:00.176374962 +0100 | |
2889 | @@ -0,0 +1,317 @@ | |
2890 | +We left the basic authentication chapter with the unsatisfactory conclusion that | |
2891 | +any traffic, including the credentials, could be intercepted by anyone between | |
2892 | +the browser client and the server. Protecting the data while it is sent over | |
2893 | +unsecured lines will be the goal of this chapter. | |
2894 | + | |
2895 | +Since version 0.4, the @emph{MHD} library includes support for encrypting the | |
2896 | +traffic by employing SSL/TSL. If @emph{GNU libmicrohttpd} has been configured to | |
2897 | +support these, encryption and decryption can be applied transparently on the | |
2898 | +data being sent, with only minimal changes to the actual source code of the example. | |
2899 | + | |
2900 | + | |
2901 | +@heading Preparation | |
2902 | + | |
2903 | +First, a private key for the server will be generated. With this key, the server | |
2904 | +will later be able to authenticate itself to the client---preventing anyone else | |
2905 | +from stealing the password by faking its identity. The @emph{OpenSSL} suite, which | |
2906 | +is available on many operating systems, can generate such a key. For the scope of | |
2907 | +this tutorial, we will be content with a 1024 bit key: | |
2908 | +@verbatim | |
2909 | +> openssl genrsa -out server.key 1024 | |
2910 | +@end verbatim | |
2911 | +@noindent | |
2912 | + | |
2913 | +In addition to the key, a certificate describing the server in human readable tokens | |
2914 | +is also needed. This certificate will be attested with our aforementioned key. In this way, | |
2915 | +we obtain a self-signed certificate, valid for one year. | |
2916 | + | |
2917 | +@verbatim | |
2918 | +> openssl req -days 365 -out server.pem -new -x509 -key server.key | |
2919 | +@end verbatim | |
2920 | +@noindent | |
2921 | + | |
2922 | +To avoid unnecessary error messages in the browser, the certificate needs to | |
2923 | +have a name that matches the @emph{URI}, for example, "localhost" or the domain. | |
2924 | +If you plan to have a publicly reachable server, you will need to ask a trusted third party, | |
2925 | +called @emph{Certificate Authority}, or @emph{CA}, to attest the certificate for you. This way, | |
2926 | +any visitor can make sure the server's identity is real. | |
2927 | + | |
2928 | +Whether the server's certificate is signed by us or a third party, once it has been accepted | |
2929 | +by the client, both sides will be communicating over encrypted channels. From this point on, | |
2930 | +it is the client's turn to authenticate itself. But this has already been implemented in the basic | |
2931 | +authentication scheme. | |
2932 | + | |
2933 | + | |
2934 | +@heading Changing the source code | |
2935 | + | |
2936 | +We merely have to extend the server program so that it loads the two files into memory, | |
2937 | + | |
2938 | +@verbatim | |
2939 | +int | |
2940 | +main () | |
2941 | +{ | |
2942 | + struct MHD_Daemon *daemon; | |
2943 | + char *key_pem; | |
2944 | + char *cert_pem; | |
2945 | + | |
2946 | + key_pem = load_file (SERVERKEYFILE); | |
2947 | + cert_pem = load_file (SERVERCERTFILE); | |
2948 | + | |
2949 | + if ((key_pem == NULL) || (cert_pem == NULL)) | |
2950 | + { | |
2951 | + printf ("The key/certificate files could not be read.\n"); | |
2952 | + return 1; | |
2953 | + } | |
2954 | +@end verbatim | |
2955 | +@noindent | |
2956 | + | |
2957 | +and then we point the @emph{MHD} daemon to it upon initalization. | |
2958 | +@verbatim | |
2959 | + | |
2960 | + daemon = MHD_start_daemon (MHD_USE_SELECT_INTERNALLY | MHD_USE_SSL, | |
2961 | + PORT, NULL, NULL, | |
2962 | + &answer_to_connection, NULL, | |
2963 | + MHD_OPTION_HTTPS_MEM_KEY, key_pem, | |
2964 | + MHD_OPTION_HTTPS_MEM_CERT, cert_pem, | |
2965 | + MHD_OPTION_END); | |
2966 | + | |
2967 | + if (NULL == daemon) | |
2968 | + { | |
2969 | + printf ("%s\n", cert_pem); | |
2970 | + | |
2971 | + free (key_pem); | |
2972 | + free (cert_pem); | |
2973 | + | |
2974 | + return 1; | |
2975 | + } | |
2976 | +@end verbatim | |
2977 | +@noindent | |
2978 | + | |
2979 | + | |
2980 | +The rest consists of little new besides some additional memory cleanups. | |
2981 | +@verbatim | |
2982 | + | |
2983 | + getchar (); | |
2984 | + | |
2985 | + MHD_stop_daemon (daemon); | |
2986 | + free (key_pem); | |
2987 | + free (cert_pem); | |
2988 | + | |
2989 | + return 0; | |
2990 | +} | |
2991 | +@end verbatim | |
2992 | +@noindent | |
2993 | + | |
2994 | + | |
2995 | +The rather unexciting file loader can be found in the complete example @code{tlsauthentication.c}. | |
2996 | + | |
2997 | + | |
2998 | +@heading Remarks | |
2999 | +@itemize @bullet | |
3000 | +@item | |
3001 | +While the standard @emph{HTTP} port is 80, it is 443 for @emph{HTTPS}. The common internet browsers assume | |
3002 | +standard @emph{HTTP} if they are asked to access other ports than these. Therefore, you will have to type | |
3003 | +@code{https://localhost:8888} explicitly when you test the example, or the browser will not know how to | |
3004 | +handle the answer properly. | |
3005 | + | |
3006 | +@item | |
3007 | +The remaining weak point is the question how the server will be trusted initially. Either a @emph{CA} signs the | |
3008 | +certificate or the client obtains the key over secure means. Anyway, the clients have to be aware (or configured) | |
3009 | +that they should not accept certificates of unknown origin. | |
3010 | + | |
3011 | +@item | |
3012 | +The introduced method of certificates makes it mandatory to set an expiration date---making it less feasible to | |
3013 | +hardcode certificates in embedded devices. | |
3014 | + | |
3015 | +@item | |
3016 | +The cryptographic facilities consume memory space and computing time. For this reason, websites usually consists | |
3017 | +both of uncritically @emph{HTTP} parts and secured @emph{HTTPS}. | |
3018 | + | |
3019 | +@end itemize | |
3020 | + | |
3021 | + | |
3022 | +@heading Client authentication | |
3023 | + | |
3024 | +You can also use MHD to authenticate the client via SSL/TLS certificates | |
3025 | +(as an alternative to using the password-based Basic or Digest authentication). | |
3026 | +To do this, you will need to link your application against @emph{gnutls}. | |
3027 | +Next, when you start the MHD daemon, you must specify the root CA that you're | |
3028 | +willing to trust: | |
3029 | +@verbatim | |
3030 | + daemon = MHD_start_daemon (MHD_USE_SELECT_INTERNALLY | MHD_USE_SSL, | |
3031 | + PORT, NULL, NULL, | |
3032 | + &answer_to_connection, NULL, | |
3033 | + MHD_OPTION_HTTPS_MEM_KEY, key_pem, | |
3034 | + MHD_OPTION_HTTPS_MEM_CERT, cert_pem, | |
3035 | + MHD_OPTION_HTTPS_MEM_TRUST, root_ca_pem, | |
3036 | + MHD_OPTION_END); | |
3037 | +@end verbatim | |
3038 | + | |
3039 | +With this, you can then obtain client certificates for each session. | |
3040 | +In order to obtain the identity of the client, you first need to | |
3041 | +obtain the raw GnuTLS session handle from @emph{MHD} using | |
3042 | +@code{MHD_get_connection_info}. | |
3043 | + | |
3044 | +@verbatim | |
3045 | +#include <gnutls/gnutls.h> | |
3046 | +#include <gnutls/x509.h> | |
3047 | + | |
3048 | +gnutls_session_t tls_session; | |
3049 | +union MHD_ConnectionInfo *ci; | |
3050 | + | |
3051 | +ci = MHD_get_connection_info (connection, | |
3052 | + MHD_CONNECTION_INFO_GNUTLS_SESSION); | |
3053 | +tls_session = ci->tls_session; | |
3054 | +@end verbatim | |
3055 | + | |
3056 | +You can then extract the client certificate: | |
3057 | + | |
3058 | +@verbatim | |
3059 | +/** | |
3060 | + * Get the client's certificate | |
3061 | + * | |
3062 | + * @param tls_session the TLS session | |
3063 | + * @return NULL if no valid client certificate could be found, a pointer | |
3064 | + * to the certificate if found | |
3065 | + */ | |
3066 | +static gnutls_x509_crt_t | |
3067 | +get_client_certificate (gnutls_session_t tls_session) | |
3068 | +{ | |
3069 | + unsigned int listsize; | |
3070 | + const gnutls_datum_t * pcert; | |
3071 | + gnutls_certificate_status_t client_cert_status; | |
3072 | + gnutls_x509_crt_t client_cert; | |
3073 | + | |
3074 | + if (tls_session == NULL) | |
3075 | + return NULL; | |
3076 | + if (gnutls_certificate_verify_peers2(tls_session, | |
3077 | + &client_cert_status)) | |
3078 | + return NULL; | |
3079 | + pcert = gnutls_certificate_get_peers(tls_session, | |
3080 | + &listsize); | |
3081 | + if ( (pcert == NULL) || | |
3082 | + (listsize == 0)) | |
3083 | + { | |
3084 | + fprintf (stderr, | |
3085 | + "Failed to retrieve client certificate chain\n"); | |
3086 | + return NULL; | |
3087 | + } | |
3088 | + if (gnutls_x509_crt_init(&client_cert)) | |
3089 | + { | |
3090 | + fprintf (stderr, | |
3091 | + "Failed to initialize client certificate\n"); | |
3092 | + return NULL; | |
3093 | + } | |
3094 | + /* Note that by passing values between 0 and listsize here, you | |
3095 | + can get access to the CA's certs */ | |
3096 | + if (gnutls_x509_crt_import(client_cert, | |
3097 | + &pcert[0], | |
3098 | + GNUTLS_X509_FMT_DER)) | |
3099 | + { | |
3100 | + fprintf (stderr, | |
3101 | + "Failed to import client certificate\n"); | |
3102 | + gnutls_x509_crt_deinit(client_cert); | |
3103 | + return NULL; | |
3104 | + } | |
3105 | + return client_cert; | |
3106 | +} | |
3107 | +@end verbatim | |
3108 | + | |
3109 | +Using the client certificate, you can then get the client's distinguished name | |
3110 | +and alternative names: | |
3111 | + | |
3112 | +@verbatim | |
3113 | +/** | |
3114 | + * Get the distinguished name from the client's certificate | |
3115 | + * | |
3116 | + * @param client_cert the client certificate | |
3117 | + * @return NULL if no dn or certificate could be found, a pointer | |
3118 | + * to the dn if found | |
3119 | + */ | |
3120 | +char * | |
3121 | +cert_auth_get_dn(gnutls_x509_crt_c client_cert) | |
3122 | +{ | |
3123 | + char* buf; | |
3124 | + size_t lbuf; | |
3125 | + | |
3126 | + lbuf = 0; | |
3127 | + gnutls_x509_crt_get_dn(client_cert, NULL, &lbuf); | |
3128 | + buf = malloc(lbuf); | |
3129 | + if (buf == NULL) | |
3130 | + { | |
3131 | + fprintf (stderr, | |
3132 | + "Failed to allocate memory for certificate dn\n"); | |
3133 | + return NULL; | |
3134 | + } | |
3135 | + gnutls_x509_crt_get_dn(client_cert, buf, &lbuf); | |
3136 | + return buf; | |
3137 | +} | |
3138 | + | |
3139 | + | |
3140 | +/** | |
3141 | + * Get the alternative name of specified type from the client's certificate | |
3142 | + * | |
3143 | + * @param client_cert the client certificate | |
3144 | + * @param nametype The requested name type | |
3145 | + * @param index The position of the alternative name if multiple names are | |
3146 | + * matching the requested type, 0 for the first matching name | |
3147 | + * @return NULL if no matching alternative name could be found, a pointer | |
3148 | + * to the alternative name if found | |
3149 | + */ | |
3150 | +char * | |
3151 | +MHD_cert_auth_get_alt_name(gnutls_x509_crt_t client_cert, | |
3152 | + int nametype, | |
3153 | + unsigned int index) | |
3154 | +{ | |
3155 | + char* buf; | |
3156 | + size_t lbuf; | |
3157 | + unsigned int seq; | |
3158 | + unsigned int subseq; | |
3159 | + unsigned int type; | |
3160 | + int result; | |
3161 | + | |
3162 | + subseq = 0; | |
3163 | + for (seq=0;;seq++) | |
3164 | + { | |
3165 | + lbuf = 0; | |
3166 | + result = gnutls_x509_crt_get_subject_alt_name2(client_cert, seq, NULL, &lbuf, | |
3167 | + &type, NULL); | |
3168 | + if (result == GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE) | |
3169 | + return NULL; | |
3170 | + if (nametype != (int) type) | |
3171 | + continue; | |
3172 | + if (subseq == index) | |
3173 | + break; | |
3174 | + subseq++; | |
3175 | + } | |
3176 | + buf = malloc(lbuf); | |
3177 | + if (buf == NULL) | |
3178 | + { | |
3179 | + fprintf (stderr, | |
3180 | + "Failed to allocate memory for certificate alt name\n"); | |
3181 | + return NULL; | |
3182 | + } | |
3183 | + result = gnutls_x509_crt_get_subject_alt_name2(client_cert, | |
3184 | + seq, | |
3185 | + buf, | |
3186 | + &lbuf, | |
3187 | + NULL, NULL); | |
3188 | + if (result != nametype) | |
3189 | + { | |
3190 | + fprintf (stderr, | |
3191 | + "Unexpected return value from gnutls: %d\n", | |
3192 | + result); | |
3193 | + free (buf); | |
3194 | + return NULL; | |
3195 | + } | |
3196 | + return buf; | |
3197 | +} | |
3198 | +@end verbatim | |
3199 | + | |
3200 | +Finally, you should release the memory associated with the client | |
3201 | +certificate: | |
3202 | + | |
3203 | +@verbatim | |
3204 | +gnutls_x509_crt_deinit (client_cert); | |
3205 | +@end verbatim | |
3206 | + |