* ksba.texi: Sanitized the wording of fixmes and added pointers to
authorWerner Koch <wk@gnupg.org>
Wed, 13 Nov 2002 10:47:47 +0000 (10:47 +0000)
committerWerner Koch <wk@gnupg.org>
Wed, 13 Nov 2002 10:47:47 +0000 (10:47 +0000)
example code.

Added missing files.

doc/ChangeLog
doc/Makefile.am
doc/fdl.texi [new file with mode: 0644]
doc/gpl.texi [new file with mode: 0644]
doc/ksba.texi [new file with mode: 0644]

index 183a542..f173c76 100644 (file)
@@ -1,4 +1,15 @@
+2002-11-13  Werner Koch  <wk@gnupg.org>
 
+       * ksba.texi: Sanitized the wording of fixmes and added pointers to
+       example code.
+
+2002-06-19  Werner Koch  <wk@gnupg.org>
+
+       * ksba.texi: Fixed the direntry.  Noted by Thomas Koester.
+
+2002-04-15  Werner Koch  <wk@gnupg.org>
+
+       * ksba.texi: Add new functions.
 
  Copyright 2002 g10 Code GmbH
 
index be8fb62..9a08968 100644 (file)
@@ -19,6 +19,8 @@
 
 ## Process this file with automake to produce Makefile.in
 
-#info_TEXINFOS = ksba.texi
-#ksba_TEXINFOS = gpl.texi fdl.texi
+DISTCLEANFILES = ksba.cps
+
+info_TEXINFOS = ksba.texi
+ksba_TEXINFOS = gpl.texi fdl.texi
 
diff --git a/doc/fdl.texi b/doc/fdl.texi
new file mode 100644 (file)
index 0000000..50028ab
--- /dev/null
@@ -0,0 +1,402 @@
+@node Free Documentation License
+@appendix GNU Free Documentation License
+
+@cindex FDL, GNU Free Documentation License
+@center Version 1.1, March 2000
+
+@display
+Copyright @copyright{} 2000 Free Software Foundation, Inc.
+59 Temple Place, Suite 330, Boston, MA  02111-1307, USA
+
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+@end display
+
+@enumerate 0
+@item
+PREAMBLE
+
+The purpose of this License is to make a manual, textbook, or other
+written document @dfn{free} in the sense of freedom: to assure everyone
+the effective freedom to copy and redistribute it, with or without
+modifying it, either commercially or noncommercially.  Secondarily,
+this License preserves for the author and publisher a way to get
+credit for their work, while not being considered responsible for
+modifications made by others.
+
+This License is a kind of ``copyleft'', which means that derivative
+works of the document must themselves be free in the same sense.  It
+complements the GNU General Public License, which is a copyleft
+license designed for free software.
+
+We have designed this License in order to use it for manuals for free
+software, because free software needs free documentation: a free
+program should come with manuals providing the same freedoms that the
+software does.  But this License is not limited to software manuals;
+it can be used for any textual work, regardless of subject matter or
+whether it is published as a printed book.  We recommend this License
+principally for works whose purpose is instruction or reference.
+
+@item
+APPLICABILITY AND DEFINITIONS
+
+This License applies to any manual or other work that contains a
+notice placed by the copyright holder saying it can be distributed
+under the terms of this License.  The ``Document'', below, refers to any
+such manual or work.  Any member of the public is a licensee, and is
+addressed as ``you''.
+
+A ``Modified Version'' of the Document means any work containing the
+Document or a portion of it, either copied verbatim, or with
+modifications and/or translated into another language.
+
+A ``Secondary Section'' is a named appendix or a front-matter section of
+the Document that deals exclusively with the relationship of the
+publishers or authors of the Document to the Document's overall subject
+(or to related matters) and contains nothing that could fall directly
+within that overall subject.  (For example, if the Document is in part a
+textbook of mathematics, a Secondary Section may not explain any
+mathematics.)  The relationship could be a matter of historical
+connection with the subject or with related matters, or of legal,
+commercial, philosophical, ethical or political position regarding
+them.
+
+The ``Invariant Sections'' are certain Secondary Sections whose titles
+are designated, as being those of Invariant Sections, in the notice
+that says that the Document is released under this License.
+
+The ``Cover Texts'' are certain short passages of text that are listed,
+as Front-Cover Texts or Back-Cover Texts, in the notice that says that
+the Document is released under this License.
+
+A ``Transparent'' copy of the Document means a machine-readable copy,
+represented in a format whose specification is available to the
+general public, whose contents can be viewed and edited directly and
+straightforwardly with generic text editors or (for images composed of
+pixels) generic paint programs or (for drawings) some widely available
+drawing editor, and that is suitable for input to text formatters or
+for automatic translation to a variety of formats suitable for input
+to text formatters.  A copy made in an otherwise Transparent file
+format whose markup has been designed to thwart or discourage
+subsequent modification by readers is not Transparent.  A copy that is
+not ``Transparent'' is called ``Opaque''.
+
+Examples of suitable formats for Transparent copies include plain
+@sc{ascii} without markup, Texinfo input format, La@TeX{} input format,
+@acronym{SGML} or @acronym{XML} using a publicly available
+@acronym{DTD}, and standard-conforming simple @acronym{HTML} designed
+for human modification.  Opaque formats include PostScript,
+@acronym{PDF}, proprietary formats that can be read and edited only by
+proprietary word processors, @acronym{SGML} or @acronym{XML} for which
+the @acronym{DTD} and/or processing tools are not generally available,
+and the machine-generated @acronym{HTML} produced by some word
+processors for output purposes only.
+
+The ``Title Page'' means, for a printed book, the title page itself,
+plus such following pages as are needed to hold, legibly, the material
+this License requires to appear in the title page.  For works in
+formats which do not have any title page as such, ``Title Page'' means
+the text near the most prominent appearance of the work's title,
+preceding the beginning of the body of the text.
+
+@item
+VERBATIM COPYING
+
+You may copy and distribute the Document in any medium, either
+commercially or noncommercially, provided that this License, the
+copyright notices, and the license notice saying this License applies
+to the Document are reproduced in all copies, and that you add no other
+conditions whatsoever to those of this License.  You may not use
+technical measures to obstruct or control the reading or further
+copying of the copies you make or distribute.  However, you may accept
+compensation in exchange for copies.  If you distribute a large enough
+number of copies you must also follow the conditions in section 3.
+
+You may also lend copies, under the same conditions stated above, and
+you may publicly display copies.
+
+@item
+COPYING IN QUANTITY
+
+If you publish printed copies of the Document numbering more than 100,
+and the Document's license notice requires Cover Texts, you must enclose
+the copies in covers that carry, clearly and legibly, all these Cover
+Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
+the back cover.  Both covers must also clearly and legibly identify
+you as the publisher of these copies.  The front cover must present
+the full title with all words of the title equally prominent and
+visible.  You may add other material on the covers in addition.
+Copying with changes limited to the covers, as long as they preserve
+the title of the Document and satisfy these conditions, can be treated
+as verbatim copying in other respects.
+
+If the required texts for either cover are too voluminous to fit
+legibly, you should put the first ones listed (as many as fit
+reasonably) on the actual cover, and continue the rest onto adjacent
+pages.
+
+If you publish or distribute Opaque copies of the Document numbering
+more than 100, you must either include a machine-readable Transparent
+copy along with each Opaque copy, or state in or with each Opaque copy
+a publicly-accessible computer-network location containing a complete
+Transparent copy of the Document, free of added material, which the
+general network-using public has access to download anonymously at no
+charge using public-standard network protocols.  If you use the latter
+option, you must take reasonably prudent steps, when you begin
+distribution of Opaque copies in quantity, to ensure that this
+Transparent copy will remain thus accessible at the stated location
+until at least one year after the last time you distribute an Opaque
+copy (directly or through your agents or retailers) of that edition to
+the public.
+
+It is requested, but not required, that you contact the authors of the
+Document well before redistributing any large number of copies, to give
+them a chance to provide you with an updated version of the Document.
+
+@item
+MODIFICATIONS
+
+You may copy and distribute a Modified Version of the Document under
+the conditions of sections 2 and 3 above, provided that you release
+the Modified Version under precisely this License, with the Modified
+Version filling the role of the Document, thus licensing distribution
+and modification of the Modified Version to whoever possesses a copy
+of it.  In addition, you must do these things in the Modified Version:
+
+@enumerate A
+@item
+Use in the Title Page (and on the covers, if any) a title distinct
+from that of the Document, and from those of previous versions
+(which should, if there were any, be listed in the History section
+of the Document).  You may use the same title as a previous version
+if the original publisher of that version gives permission.
+
+@item
+List on the Title Page, as authors, one or more persons or entities
+responsible for authorship of the modifications in the Modified
+Version, together with at least five of the principal authors of the
+Document (all of its principal authors, if it has less than five).
+
+@item
+State on the Title page the name of the publisher of the
+Modified Version, as the publisher.
+
+@item
+Preserve all the copyright notices of the Document.
+
+@item
+Add an appropriate copyright notice for your modifications
+adjacent to the other copyright notices.
+
+@item
+Include, immediately after the copyright notices, a license notice
+giving the public permission to use the Modified Version under the
+terms of this License, in the form shown in the Addendum below.
+
+@item
+Preserve in that license notice the full lists of Invariant Sections
+and required Cover Texts given in the Document's license notice.
+
+@item
+Include an unaltered copy of this License.
+
+@item
+Preserve the section entitled ``History'', and its title, and add to
+it an item stating at least the title, year, new authors, and
+publisher of the Modified Version as given on the Title Page.  If
+there is no section entitled ``History'' in the Document, create one
+stating the title, year, authors, and publisher of the Document as
+given on its Title Page, then add an item describing the Modified
+Version as stated in the previous sentence.
+
+@item
+Preserve the network location, if any, given in the Document for
+public access to a Transparent copy of the Document, and likewise
+the network locations given in the Document for previous versions
+it was based on.  These may be placed in the ``History'' section.
+You may omit a network location for a work that was published at
+least four years before the Document itself, or if the original
+publisher of the version it refers to gives permission.
+
+@item
+In any section entitled ``Acknowledgments'' or ``Dedications'',
+preserve the section's title, and preserve in the section all the
+substance and tone of each of the contributor acknowledgments
+and/or dedications given therein.
+
+@item
+Preserve all the Invariant Sections of the Document,
+unaltered in their text and in their titles.  Section numbers
+or the equivalent are not considered part of the section titles.
+
+@item
+Delete any section entitled ``Endorsements''.  Such a section
+may not be included in the Modified Version.
+
+@item
+Do not retitle any existing section as ``Endorsements''
+or to conflict in title with any Invariant Section.
+@end enumerate
+
+If the Modified Version includes new front-matter sections or
+appendices that qualify as Secondary Sections and contain no material
+copied from the Document, you may at your option designate some or all
+of these sections as invariant.  To do this, add their titles to the
+list of Invariant Sections in the Modified Version's license notice.
+These titles must be distinct from any other section titles.
+
+You may add a section entitled ``Endorsements'', provided it contains
+nothing but endorsements of your Modified Version by various
+parties---for example, statements of peer review or that the text has
+been approved by an organization as the authoritative definition of a
+standard.
+
+You may add a passage of up to five words as a Front-Cover Text, and a
+passage of up to 25 words as a Back-Cover Text, to the end of the list
+of Cover Texts in the Modified Version.  Only one passage of
+Front-Cover Text and one of Back-Cover Text may be added by (or
+through arrangements made by) any one entity.  If the Document already
+includes a cover text for the same cover, previously added by you or
+by arrangement made by the same entity you are acting on behalf of,
+you may not add another; but you may replace the old one, on explicit
+permission from the previous publisher that added the old one.
+
+The author(s) and publisher(s) of the Document do not by this License
+give permission to use their names for publicity for or to assert or
+imply endorsement of any Modified Version.
+
+@item
+COMBINING DOCUMENTS
+
+You may combine the Document with other documents released under this
+License, under the terms defined in section 4 above for modified
+versions, provided that you include in the combination all of the
+Invariant Sections of all of the original documents, unmodified, and
+list them all as Invariant Sections of your combined work in its
+license notice.
+
+The combined work need only contain one copy of this License, and
+multiple identical Invariant Sections may be replaced with a single
+copy.  If there are multiple Invariant Sections with the same name but
+different contents, make the title of each such section unique by
+adding at the end of it, in parentheses, the name of the original
+author or publisher of that section if known, or else a unique number.
+Make the same adjustment to the section titles in the list of
+Invariant Sections in the license notice of the combined work.
+
+In the combination, you must combine any sections entitled ``History''
+in the various original documents, forming one section entitled
+``History''; likewise combine any sections entitled ``Acknowledgments'',
+and any sections entitled ``Dedications''.  You must delete all sections
+entitled ``Endorsements.''
+
+@item
+COLLECTIONS OF DOCUMENTS
+
+You may make a collection consisting of the Document and other documents
+released under this License, and replace the individual copies of this
+License in the various documents with a single copy that is included in
+the collection, provided that you follow the rules of this License for
+verbatim copying of each of the documents in all other respects.
+
+You may extract a single document from such a collection, and distribute
+it individually under this License, provided you insert a copy of this
+License into the extracted document, and follow this License in all
+other respects regarding verbatim copying of that document.
+
+@item
+AGGREGATION WITH INDEPENDENT WORKS
+
+A compilation of the Document or its derivatives with other separate
+and independent documents or works, in or on a volume of a storage or
+distribution medium, does not as a whole count as a Modified Version
+of the Document, provided no compilation copyright is claimed for the
+compilation.  Such a compilation is called an ``aggregate'', and this
+License does not apply to the other self-contained works thus compiled
+with the Document, on account of their being thus compiled, if they
+are not themselves derivative works of the Document.
+
+If the Cover Text requirement of section 3 is applicable to these
+copies of the Document, then if the Document is less than one quarter
+of the entire aggregate, the Document's Cover Texts may be placed on
+covers that surround only the Document within the aggregate.
+Otherwise they must appear on covers around the whole aggregate.
+
+@item
+TRANSLATION
+
+Translation is considered a kind of modification, so you may
+distribute translations of the Document under the terms of section 4.
+Replacing Invariant Sections with translations requires special
+permission from their copyright holders, but you may include
+translations of some or all Invariant Sections in addition to the
+original versions of these Invariant Sections.  You may include a
+translation of this License provided that you also include the
+original English version of this License.  In case of a disagreement
+between the translation and the original English version of this
+License, the original English version will prevail.
+
+@item
+TERMINATION
+
+You may not copy, modify, sublicense, or distribute the Document except
+as expressly provided for under this License.  Any other attempt to
+copy, modify, sublicense or distribute the Document is void, and will
+automatically terminate your rights under this License.  However,
+parties who have received copies, or rights, from you under this
+License will not have their licenses terminated so long as such
+parties remain in full compliance.
+
+@item
+FUTURE REVISIONS OF THIS LICENSE
+
+The Free Software Foundation may publish new, revised versions
+of the GNU Free Documentation License from time to time.  Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.  See
+@uref{http://www.gnu.org/copyleft/}.
+
+Each version of the License is given a distinguishing version number.
+If the Document specifies that a particular numbered version of this
+License ``or any later version'' applies to it, you have the option of
+following the terms and conditions either of that specified version or
+of any later version that has been published (not as a draft) by the
+Free Software Foundation.  If the Document does not specify a version
+number of this License, you may choose any version ever published (not
+as a draft) by the Free Software Foundation.
+@end enumerate
+
+@page
+@appendixsubsec ADDENDUM: How to use this License for your documents
+
+To use this License in a document you have written, include a copy of
+the License in the document and put the following copyright and
+license notices just after the title page:
+
+@smallexample
+@group
+  Copyright (C)  @var{year}  @var{your name}.
+  Permission is granted to copy, distribute and/or modify this document
+  under the terms of the GNU Free Documentation License, Version 1.1
+  or any later version published by the Free Software Foundation;
+  with the Invariant Sections being @var{list their titles}, with the
+  Front-Cover Texts being @var{list}, and with the Back-Cover Texts being @var{list}.
+  A copy of the license is included in the section entitled ``GNU
+  Free Documentation License''.
+@end group
+@end smallexample
+
+If you have no Invariant Sections, write ``with no Invariant Sections''
+instead of saying which ones are invariant.  If you have no
+Front-Cover Texts, write ``no Front-Cover Texts'' instead of
+``Front-Cover Texts being @var{list}''; likewise for Back-Cover Texts.
+
+If your document contains nontrivial examples of program code, we
+recommend releasing these examples in parallel under your choice of
+free software license, such as the GNU General Public License,
+to permit their use in free software.
+
+@c Local Variables:
+@c ispell-local-pdict: "ispell-dict"
+@c End:
+
diff --git a/doc/gpl.texi b/doc/gpl.texi
new file mode 100644 (file)
index 0000000..ca0508f
--- /dev/null
@@ -0,0 +1,397 @@
+@node Copying
+@appendix GNU GENERAL PUBLIC LICENSE
+
+@cindex GPL, GNU General Public License
+@center Version 2, June 1991
+
+@display
+Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc.
+59 Temple Place -- Suite 330, Boston, MA 02111-1307, USA
+
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+@end display
+
+@appendixsubsec Preamble
+
+  The licenses for most software are designed to take away your
+freedom to share and change it.  By contrast, the GNU General Public
+License is intended to guarantee your freedom to share and change free
+software---to make sure the software is free for all its users.  This
+General Public License applies to most of the Free Software
+Foundation's software and to any other program whose authors commit to
+using it.  (Some other Free Software Foundation software is covered by
+the GNU Library General Public License instead.)  You can apply it to
+your programs, too.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+this service if you wish), that you receive source code or can get it
+if you want it, that you can change the software or use pieces of it
+in new free programs; and that you know you can do these things.
+
+  To protect your rights, we need to make restrictions that forbid
+anyone to deny you these rights or to ask you to surrender the rights.
+These restrictions translate to certain responsibilities for you if you
+distribute copies of the software, or if you modify it.
+
+  For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must give the recipients all the rights that
+you have.  You must make sure that they, too, receive or can get the
+source code.  And you must show them these terms so they know their
+rights.
+
+  We protect your rights with two steps: (1) copyright the software, and
+(2) offer you this license which gives you legal permission to copy,
+distribute and/or modify the software.
+
+  Also, for each author's protection and ours, we want to make certain
+that everyone understands that there is no warranty for this free
+software.  If the software is modified by someone else and passed on, we
+want its recipients to know that what they have is not the original, so
+that any problems introduced by others will not reflect on the original
+authors' reputations.
+
+  Finally, any free program is threatened constantly by software
+patents.  We wish to avoid the danger that redistributors of a free
+program will individually obtain patent licenses, in effect making the
+program proprietary.  To prevent this, we have made it clear that any
+patent must be licensed for everyone's free use or not licensed at all.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+@iftex
+@appendixsubsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+@end iftex
+@ifinfo
+@center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+@end ifinfo
+
+@enumerate
+@item
+This License applies to any program or other work which contains
+a notice placed by the copyright holder saying it may be distributed
+under the terms of this General Public License.  The ``Program'', below,
+refers to any such program or work, and a ``work based on the Program''
+means either the Program or any derivative work under copyright law:
+that is to say, a work containing the Program or a portion of it,
+either verbatim or with modifications and/or translated into another
+language.  (Hereinafter, translation is included without limitation in
+the term ``modification''.)  Each licensee is addressed as ``you''.
+
+Activities other than copying, distribution and modification are not
+covered by this License; they are outside its scope.  The act of
+running the Program is not restricted, and the output from the Program
+is covered only if its contents constitute a work based on the
+Program (independent of having been made by running the Program).
+Whether that is true depends on what the Program does.
+
+@item
+You may copy and distribute verbatim copies of the Program's
+source code as you receive it, in any medium, provided that you
+conspicuously and appropriately publish on each copy an appropriate
+copyright notice and disclaimer of warranty; keep intact all the
+notices that refer to this License and to the absence of any warranty;
+and give any other recipients of the Program a copy of this License
+along with the Program.
+
+You may charge a fee for the physical act of transferring a copy, and
+you may at your option offer warranty protection in exchange for a fee.
+
+@item
+You may modify your copy or copies of the Program or any portion
+of it, thus forming a work based on the Program, and copy and
+distribute such modifications or work under the terms of Section 1
+above, provided that you also meet all of these conditions:
+
+@enumerate a
+@item
+You must cause the modified files to carry prominent notices
+stating that you changed the files and the date of any change.
+
+@item
+You must cause any work that you distribute or publish, that in
+whole or in part contains or is derived from the Program or any
+part thereof, to be licensed as a whole at no charge to all third
+parties under the terms of this License.
+
+@item
+If the modified program normally reads commands interactively
+when run, you must cause it, when started running for such
+interactive use in the most ordinary way, to print or display an
+announcement including an appropriate copyright notice and a
+notice that there is no warranty (or else, saying that you provide
+a warranty) and that users may redistribute the program under
+these conditions, and telling the user how to view a copy of this
+License.  (Exception: if the Program itself is interactive but
+does not normally print such an announcement, your work based on
+the Program is not required to print an announcement.)
+@end enumerate
+
+These requirements apply to the modified work as a whole.  If
+identifiable sections of that work are not derived from the Program,
+and can be reasonably considered independent and separate works in
+themselves, then this License, and its terms, do not apply to those
+sections when you distribute them as separate works.  But when you
+distribute the same sections as part of a whole which is a work based
+on the Program, the distribution of the whole must be on the terms of
+this License, whose permissions for other licensees extend to the
+entire whole, and thus to each and every part regardless of who wrote it.
+
+Thus, it is not the intent of this section to claim rights or contest
+your rights to work written entirely by you; rather, the intent is to
+exercise the right to control the distribution of derivative or
+collective works based on the Program.
+
+In addition, mere aggregation of another work not based on the Program
+with the Program (or with a work based on the Program) on a volume of
+a storage or distribution medium does not bring the other work under
+the scope of this License.
+
+@item
+You may copy and distribute the Program (or a work based on it,
+under Section 2) in object code or executable form under the terms of
+Sections 1 and 2 above provided that you also do one of the following:
+
+@enumerate a
+@item
+Accompany it with the complete corresponding machine-readable
+source code, which must be distributed under the terms of Sections
+1 and 2 above on a medium customarily used for software interchange; or,
+
+@item
+Accompany it with a written offer, valid for at least three
+years, to give any third party, for a charge no more than your
+cost of physically performing source distribution, a complete
+machine-readable copy of the corresponding source code, to be
+distributed under the terms of Sections 1 and 2 above on a medium
+customarily used for software interchange; or,
+
+@item
+Accompany it with the information you received as to the offer
+to distribute corresponding source code.  (This alternative is
+allowed only for noncommercial distribution and only if you
+received the program in object code or executable form with such
+an offer, in accord with Subsection b above.)
+@end enumerate
+
+The source code for a work means the preferred form of the work for
+making modifications to it.  For an executable work, complete source
+code means all the source code for all modules it contains, plus any
+associated interface definition files, plus the scripts used to
+control compilation and installation of the executable.  However, as a
+special exception, the source code distributed need not include
+anything that is normally distributed (in either source or binary
+form) with the major components (compiler, kernel, and so on) of the
+operating system on which the executable runs, unless that component
+itself accompanies the executable.
+
+If distribution of executable or object code is made by offering
+access to copy from a designated place, then offering equivalent
+access to copy the source code from the same place counts as
+distribution of the source code, even though third parties are not
+compelled to copy the source along with the object code.
+
+@item
+You may not copy, modify, sublicense, or distribute the Program
+except as expressly provided under this License.  Any attempt
+otherwise to copy, modify, sublicense or distribute the Program is
+void, and will automatically terminate your rights under this License.
+However, parties who have received copies, or rights, from you under
+this License will not have their licenses terminated so long as such
+parties remain in full compliance.
+
+@item
+You are not required to accept this License, since you have not
+signed it.  However, nothing else grants you permission to modify or
+distribute the Program or its derivative works.  These actions are
+prohibited by law if you do not accept this License.  Therefore, by
+modifying or distributing the Program (or any work based on the
+Program), you indicate your acceptance of this License to do so, and
+all its terms and conditions for copying, distributing or modifying
+the Program or works based on it.
+
+@item
+Each time you redistribute the Program (or any work based on the
+Program), the recipient automatically receives a license from the
+original licensor to copy, distribute or modify the Program subject to
+these terms and conditions.  You may not impose any further
+restrictions on the recipients' exercise of the rights granted herein.
+You are not responsible for enforcing compliance by third parties to
+this License.
+
+@item
+If, as a consequence of a court judgment or allegation of patent
+infringement or for any other reason (not limited to patent issues),
+conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot
+distribute so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you
+may not distribute the Program at all.  For example, if a patent
+license would not permit royalty-free redistribution of the Program by
+all those who receive copies directly or indirectly through you, then
+the only way you could satisfy both it and this License would be to
+refrain entirely from distribution of the Program.
+
+If any portion of this section is held invalid or unenforceable under
+any particular circumstance, the balance of the section is intended to
+apply and the section as a whole is intended to apply in other
+circumstances.
+
+It is not the purpose of this section to induce you to infringe any
+patents or other property right claims or to contest validity of any
+such claims; this section has the sole purpose of protecting the
+integrity of the free software distribution system, which is
+implemented by public license practices.  Many people have made
+generous contributions to the wide range of software distributed
+through that system in reliance on consistent application of that
+system; it is up to the author/donor to decide if he or she is willing
+to distribute software through any other system and a licensee cannot
+impose that choice.
+
+This section is intended to make thoroughly clear what is believed to
+be a consequence of the rest of this License.
+
+@item
+If the distribution and/or use of the Program is restricted in
+certain countries either by patents or by copyrighted interfaces, the
+original copyright holder who places the Program under this License
+may add an explicit geographical distribution limitation excluding
+those countries, so that distribution is permitted only in or among
+countries not thus excluded.  In such case, this License incorporates
+the limitation as if written in the body of this License.
+
+@item
+The Free Software Foundation may publish revised and/or new versions
+of the General Public License from time to time.  Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+Each version is given a distinguishing version number.  If the Program
+specifies a version number of this License which applies to it and ``any
+later version'', you have the option of following the terms and conditions
+either of that version or of any later version published by the Free
+Software Foundation.  If the Program does not specify a version number of
+this License, you may choose any version ever published by the Free Software
+Foundation.
+
+@item
+If you wish to incorporate parts of the Program into other free
+programs whose distribution conditions are different, write to the author
+to ask for permission.  For software which is copyrighted by the Free
+Software Foundation, write to the Free Software Foundation; we sometimes
+make exceptions for this.  Our decision will be guided by the two goals
+of preserving the free status of all derivatives of our free software and
+of promoting the sharing and reuse of software generally.
+
+@iftex
+@heading NO WARRANTY
+@end iftex
+@ifinfo
+@center NO WARRANTY
+@end ifinfo
+
+@item
+BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
+FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN
+OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
+PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
+OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS
+TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
+PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
+REPAIR OR CORRECTION.
+
+@item
+IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
+REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
+INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
+OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
+TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
+YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
+PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGES.
+@end enumerate
+
+@iftex
+@heading END OF TERMS AND CONDITIONS
+@end iftex
+@ifinfo
+@center END OF TERMS AND CONDITIONS
+@end ifinfo
+
+@page
+@unnumberedsec How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+convey the exclusion of warranty; and each file should have at least
+the ``copyright'' line and a pointer to where the full notice is found.
+
+@smallexample
+@var{one line to give the program's name and an idea of what it does.}
+Copyright (C) 19@var{yy}  @var{name of author}
+
+This program is free software; you can redistribute it and/or
+modify it under the terms of the GNU General Public License
+as published by the Free Software Foundation; either version 2
+of the License, or (at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License along
+with this program; if not, write to the Free Software Foundation, Inc.,
+59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
+@end smallexample
+
+Also add information on how to contact you by electronic and paper mail.
+
+If the program is interactive, make it output a short notice like this
+when it starts in an interactive mode:
+
+@smallexample
+Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author}
+Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
+type `show w'.  This is free software, and you are welcome
+to redistribute it under certain conditions; type `show c' 
+for details.
+@end smallexample
+
+The hypothetical commands @samp{show w} and @samp{show c} should show
+the appropriate parts of the General Public License.  Of course, the
+commands you use may be called something other than @samp{show w} and
+@samp{show c}; they could even be mouse-clicks or menu items---whatever
+suits your program.
+
+You should also get your employer (if you work as a programmer) or your
+school, if any, to sign a ``copyright disclaimer'' for the program, if
+necessary.  Here is a sample; alter the names:
+
+@smallexample
+@group
+Yoyodyne, Inc., hereby disclaims all copyright
+interest in the program `Gnomovision'
+(which makes passes at compilers) written 
+by James Hacker.
+
+@var{signature of Ty Coon}, 1 April 1989
+Ty Coon, President of Vice
+@end group
+@end smallexample
+
+This General Public License does not permit incorporating your program into
+proprietary programs.  If your program is a subroutine library, you may
+consider it more useful to permit linking proprietary applications with the
+library.  If this is what you want to do, use the GNU Library General
+Public License instead of this License.
diff --git a/doc/ksba.texi b/doc/ksba.texi
new file mode 100644 (file)
index 0000000..7d37850
--- /dev/null
@@ -0,0 +1,927 @@
+\input texinfo
+@setfilename ksba.info
+@settitle The KSBA Reference Manual
+
+@dircategory GNU libraries
+@direntry
+* libksba: (ksba)              An X.509 Library.
+@end direntry
+
+@include version.texi
+
+@c Unify some of the indices.
+@syncodeindex tp fn
+@syncodeindex pg fn
+
+@ifinfo
+This file documents the @acronym{KSBA} library to access X.509 and CMS data
+structures.
+
+This is edition @value{EDITION}, last updated @value{UPDATED}, of
+@cite{The KSBA Reference Manual}, for Version @value{VERSION}.
+
+Copyright @copyright{} 2002 g10 Code GmbH.
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.1 or
+any later version published by the Free Software Foundation; with the
+Invariant Sections being ``Free Software Needs Free Documentation'' and
+``GNU General Public License'', the Front-Cover texts being (a)
+(see below), and with the Back-Cover Texts being (b) (see below).  A
+copy of the license is included in the section entitled ``GNU Free
+Documentation License''.
+@end ifinfo
+
+
+@iftex
+@shorttitlepage The `KSBA' Reference Manual
+@end iftex
+@titlepage
+@center @titlefont{The `KSBA'}
+@sp 1
+@center @titlefont{Reference Manual}
+@sp 6
+@center Edition @value{EDITION}
+@sp 1
+@center last updated @value{UPDATED}
+@sp 1
+@center for version @value{VERSION}
+@page
+@vskip 0pt plus 1filll
+Copyright @copyright{} 2002 g10 Code GmbH.
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.1 or
+any later version published by the Free Software Foundation; with the
+Invariant Sections being ``Free Software Needs Free Documentation'' and
+``GNU General Public License'', the Front-Cover texts being (a)
+(see below), and with the Back-Cover Texts being (b) (see below).  A
+copy of the license is included in the section entitled ``GNU Free
+Documentation License''.
+@author by Werner Koch, g10 Code GmbH
+@email{wk@@gnupg.org}
+@end titlepage
+@page
+
+
+@ifnottex
+@node Top
+@top Main Menu
+This is edition @value{EDITION}, last updated @value{UPDATED}, of
+@cite{The KSBA Reference Manual}, for Version
+@value{VERSION} of the @acronym{KSBA} library.
+@end ifnottex
+
+@menu
+* Introduction::                How to use this manual.
+* Preparation::                 What you should do before using the library.
+* Certificate Handling::        
+* CMS::                         
+* CRLs::                        
+* PKCS10::                      
+* Utilities::                   Various utility functions.
+* Error Handling::              Error numbers and their meanings.
+
+Appendices
+
+* Copying::                     The GNU General Public License says how you
+                                can copy and share `GnuPG Made Easy'.
+* Free Documentation License::  This manual is under the GNU Free
+                                Documentation License.
+
+Indices
+
+* Concept Index::               Index of concepts and programs.
+* Function and Data Index::     Index of functions, variables and data types.
+
+@detailmenu
+ --- The Detailed Node Listing ---
+
+Introduction
+
+* Getting Started::             
+* Features::                    
+* Overview::                    
+
+Preparation
+
+* Header::                      
+* Building the source::         
+
+Certificate Handling
+
+* Creating certificates::       How to create a certificate object.
+* Retrieving attributes::       How to get the attributes of a certificate.
+* Setting attributes::          How to set certicates attributes.
+
+Mastering the Cryptographic Message Syntax
+
+* CMS Basics::                  
+* CMS Parser::                  
+
+Error Handling
+
+* Error values::                A list of all error values used.
+* Error strings::               How to get a descriptive string from a value.
+
+@end detailmenu
+@end menu
+
+@node Introduction
+@chapter Introduction
+@acronym{KSBA} is a library to make the taks of working with X.509
+certifictes, CMS data and related data more easy.
+
+@menu
+* Getting Started::             
+* Features::                    
+* Overview::                    
+@end menu
+
+@node Getting Started
+@section Getting Started
+
+This manual documents the `KSBA' library programming interface.  All functions
+and data types provided by the library are explained.
+
+The reader is assumed to possess basic knowledge about the the implemented
+protocols.
+
+This manual can be used in several ways.  If read from the beginning
+to the end, it gives a good introduction into the library and how it
+can be used in an application.  Forward references are included where
+necessary.  Later on, the manual can be used as a reference manual to
+get just the information needed about any particular interface of the
+library.  Experienced programmers might want to start looking at the
+examples at the end of the manual, and then only read up those parts
+of the interface which are unclear.
+
+
+@node Features
+@section Features
+
+`KSBA' has a couple of advantages over other libraries doing a similar job,
+and over open coding the protocols in your application directly.
+
+@table @asis
+@item It's Free Software
+Anybody can use, modify, and redistribute it under the terms of the GNU
+General Public License (@pxref{Copying}).
+
+@item It hides the low level stuff
+`KSBA' a higlevel interface to the implemented protocols and presents the data
+in a consistent way.  There is no more need to worry about all the nasty
+details of the protocols.  The API gives the C programmer a more usual way of
+interacting with the data.
+
+@item It copes with the version details
+X.509 protocols tend to have many different versions  and dialects.
+Applications must usually cope with all of this and it has to be coded over
+and over again.  `KSBA' hides this by providing just one API which does the
+Right Thing.  Support for new versions will be added over time.
+@end table
+
+
+@node Overview
+@section Overview
+
+Blurb
+
+The `KSBA' library is thread-safe.
+
+
+@node Preparation
+@chapter Preparation
+
+To use `KSBA', you have to perform some changes to your
+sources and the build system.  The necessary changes are small and
+explained in the following sections.  At the end of this chapter, it
+is described how the library is initialized, and how the requirements
+of the library are verified.
+
+@menu
+* Header::                      
+* Version Check::
+* Building the source::         
+@end menu
+
+
+@node Header
+@section Header
+
+All interfaces (data types and functions) of the library are defined
+in the header file `ksba.h'.  You must include this in all programs
+using the library, either directly or through some other header file,
+like this:
+
+@example
+#include <ksba.h>
+@end example
+
+The name space of `KSBA' is @code{ksba_*} for function names, @code{Ksba*} for
+data types and @code{KSBA_*} for other symbols.  In addition the same name
+prefixes with one prepended underscore are reserved for internal use and
+should never be used by an application.
+
+@node Version Check
+@section Version Check
+
+It is often desirable to check that the version of `KSBA' used is indeed
+one which fits all requirements.  Even with binary compatibility new
+features may have been introduced but due to problem with the dynamic
+linker an old version is actually used.  So you may want to check that
+the version is okay right after program startup.
+
+@deftypefun const char *ksba_check_version (const char *@var{req_version})
+
+Check that the the version of the library is at minimum the one given as
+a string in @var{req_version} and return the actual version string of
+the library; return NULL if the condition is not met.  If @code{NULL} is
+passed to this function no check is done and only the version string is
+returned.  It is a pretty good idea to run this function as soon as
+possible, because it may also intializes some subsystems.  In a
+multithreaded environment if should be called before any more threads
+are created.
+@end deftypefun
+
+@node Building the source
+@section Building the source
+
+If you want to compile a source file including the `ksba.h' header
+file, you must make sure that the compiler can find it in the
+directory hierarchy.  This is accomplished by adding the path to the
+directory in which the header file is located to the compilers include
+file search path (via the @option{-I} option).
+
+However, the path to the include file is determined at the time the
+source is configured.  To solve this problem, `KSBA' ships with a small
+helper program @command{ksba-config} that knows about the path to the
+include file and other configuration options.  The options that need
+to be added to the compiler invocation at compile time are output by
+the @option{--cflags} option to @command{ksba-config}.  The following
+example shows how it can be used at the command line:
+
+@example
+gcc -c foo.c `ksba-config --cflags`
+@end example
+
+Adding the output of @samp{ksba-config --cflags} to the compilers
+command line will ensure that the compiler can find the `KSBA' header
+file.
+
+A similar problem occurs when linking the program with the library.
+Again, the compiler has to find the library files.  For this to work,
+the path to the library files has to be added to the library search
+path (via the @option{-L} option).  For this, the option
+@option{--libs} to @command{ksba-config} can be used.  For
+convenience, this option also outputs all other options that are
+required to link the program with the `KSBA' libararies (in particular, the
+@samp{-lksba} option).  The example shows how to link @file{foo.o}
+with the `KSBA' libraries to a program @command{foo}.
+
+@example
+gcc -o foo foo.o `ksba-config --libs`
+@end example
+
+Of course you can also combine both examples to a single command by
+specifying both options to @command{ksba-config}:
+
+@example
+gcc -o foo foo.c `ksba-config --cflags --libs`
+@end example
+
+
+
+@node Certificate Handling
+@chapter Certificate Handling
+
+One of the most complex data formats are the X.509 certificates.
+@acronym{KSBA} provides an easy to use interface to handle them.
+
+@deftp {Data type} KsbaCert
+The @code{KsbaCert} type is a handle for an X.509 certificate.
+@end deftp
+
+@menu
+* Creating certificates::       How to create a certificate object.
+* Retrieving attributes::       How to get the attributes of a certificate.
+* Setting attributes::          How to set certicates attributes.
+@end menu
+
+
+@node Creating certificates
+@section How to create a certificate object
+
+This section explains how to create a certificate object, initialize it
+copy it and eventually destroy it. 
+
+@deftypefun KsbaCert ksba_cert_new (void)
+The function @code{ksba_cert_new} creates a new @code{KsbaCert}
+object and returns a handle for it.
+
+The only reason why this function may fail is an out-of-memory condition in
+which case @code{NULL} is returned.
+@end deftypefun
+
+@deftypefun void ksba_cert_ref (KsbaCert cert)
+The function @code{ksba_cert_ref} bumps the reference counter of the
+certificate object up by one.  Thus an extra @code{ksba_cert_release} is
+required to actually release the memory used for the object.
+@end deftypefun
+
+@deftypefun void ksba_cert_release (@w{KsbaCert @var{cert}})
+The function @code{ksba_cert_release} destroys the certificate object with the
+handle @var{cert} and releases all associated resources.  Due to the use of
+reference counting no actual memory may be released.  It is okay to pass
+@code{NULL} to the function in which case nothing happens.
+@end deftypefun
+
+@deftypefun KsbaError ksba_cert_read_der (@w{KsbaCert @var{cert}}, @w{KsbaReader @var{reader}})
+
+Read the next certificate from @var{reader} and store it in the
+certificate object @var{cert} for future access.  The certificate is parsed
+and rejected if it has any syntactical or semantical error
+(i.e. does not match the ASN.1 description).
+
+The function returns zero if the operation was successfully performed or
+an error code.
+@end deftypefun
+
+@deftypefun KsbaError ksba_cert_init_from_mem (@w{KsbaCert @var{cert}}, @w{const void *@var{buffer}}, @w{size_t @var{length}})
+
+Parse the @var{buffer} which should contain a @acronym{DER} encoded
+certificate of @var{length} and initialize the @var{cert}.  This
+function is intended as a conveninence function to be used when a
+certifciate is already available in a internal memory buffer.  This
+avoids the extra code needed to setup the reader object.  Note that
+@var{cert} must be a valid certificate object.
+
+The function returns zero if the operation was successfully performed or
+an error code.
+@end deftypefun
+
+@node Retrieving attributes
+@section How to get the attributes of a certificate
+
+The functions in this section allow accesing the attributes of a
+certificate in a well defined manner.  An error will be retruned if the
+certificate object has not yet been initialzied by means of
+@code{ksba_cert_read_der} or @code{ksba_cert_init_from_mem}.
+
+@deftypefun const unsigned char *ksba_cert_get_image (@w{KsbaCert @var{cert}}, @w{size_t *@var{r_length}}) 
+
+This function returns a pointer
+to the @acronym{DER} encoded buffer with the raw certificate as well as
+the length of that buffer in @var{r_length}.  This function is useful to
+export or store the raw certificate.
+
+The function returns @code{NULL} on error or a pointer which is valid as
+long as @var{cert} is valid.
+@end deftypefun
+
+@deftypefun KsbaError ksba_cert_hash (@w{KsbaCert @var{cert}}, @w{int @var{what}}, @w{void (*@var{hasher})(void *, const void *, size_t length)}, @w{void *@var{hasher_arg}})
+
+This function feeds the data which is expected to be hashed into the
+given function @var{hasher}, where the first argument passed is
+@var{hasher_arg}, the second the pointer to the data to be hashed and
+the third the length of this data.
+
+The function returns 0 on success or an error code when somethign goes
+wrong.  The @var{hasher} function is not expected to retrun an error,
+instead the caller should setup that function in a way to store
+encounters error by means of the @var{hasher_arg}.  However, a hash
+function is not expected to yiled errors anyway.
+@end deftypefun
+
+
+@deftypefun const char *ksba_cert_get_digest_algo (KsbaCert cert)
+
+Figure out the the digest algorithm used for the signature and return
+its @acronym{OID} in dotted decimal format.  This function is most
+likely used to setup the hash context before calling @code{ksba_cert_hash}
+
+The function returns @code{NULL} for an error, otherwise a constant
+string with the @acronym{OID}.  This string is valid as long the
+certificate object is valid.
+@end deftypefun
+
+@deftypefun KsbaSexp ksba_cert_get_serial (KsbaCert cert)
+
+The function returns the serial number of the certificate @var{cert}.
+The serial number is an integer returned as an cancnical encoded
+S-expression with just one element.  The caller must free the returned
+value.  @code{NULL} is returned in case of error.
+@end deftypefun
+
+@deftypefun char *ksba_cert_get_issuer (KsbaCert cert, int idx)
+
+With @var{idx} given as @code{0}, this function returns the
+Distinguished Name (@acronym{DN}) of the certificate issuer which
+usually is the name of a @acronym{CA}.  The format of the returned
+string is in accordance with RFC-2253.  @code{NULL} is returned if the
+@acronym{DN} is not available which is an error and should have been
+catched by the certificate reading function.
+With @var{idx} greater than zero, the function may be used to enumerate
+alternate issuer names.  The function returns @code{NULL} when there are
+no more alternate names. Only alternate names recognized by
+@code{libksba} are returned, others are simply skipped.  The format of
+the returned name is either a RFC-2253 formated string which can be
+detected by checking whether the first character is letter or digit.
+rfc-2822 conform email addresses are returned enclosed in angle
+brackets, the opening angle bracket should be used to detect this.
+Other formats are returned as an S-Expression in canonical format, so a
+opening parenthesis should be used to detect this encoding, the name may
+include binary null characters, so strlen may return a length shorter
+than actually used, the real length is implictly given by the structure
+of the S-expression, an extra null is appended for safety reasons.
+The caller must free the returned string using @code{ksba_free} or
+whatever function has been registered as a replacement.
+@end deftypefun
+
+@deftypefun char *ksba_cert_get_subject (KsbaCert cert, int idx)
+
+With @var{idx} given as @code{0}, this function returns the
+Distinguished Name (@acronym{DN}) of the certificate's subject.  The
+format of the returned string is in accordance with RFC-2253.
+@code{NULL} is returned if the @acronym{DN} is not available.
+
+With @var{idx} greater than zero, the function may be used to enumerate
+alternate subject names.  The function returns @code{NULL} when there are
+no more alternate names. Only alternate names recognized by
+@code{libksba} are returned, others are simply skipped.  The format of
+the returned name is either a RFC-2253 formated string which can be
+detected by checking whether the first character is letter or digit.
+rfc-2822 conform email addresses are returned enclosed in angle
+brackets, the opening angle bracket should be used to detect this.
+Other formats are returned as an S-Expression in canonical format, so a
+opening parenthesis should be used to detect this encoding, the name may
+include binary null characters, so strlen may return a length shorter
+than actually used, the real length is implictly given by the structure
+of the S-expression, an extra null is appended for safety reasons.
+The caller must free the returned string using @code{ksba_free} or
+whatever function has been registered as a replacement.
+@end deftypefun
+
+
+@deftypefun time_t ksba_cert_get_validity (KsbaCert @var{cert}, int @var{what})
+
+Return the validity dates from the certificate.  If no value is
+available @code{0} is returned because we can safely assume that the
+first January 1970 is not a valid date.  @code{-1} casted to
+@code{time_t} is retruned in case of error.
+
+To return the `notBefore' date, the value @code{0} must be supplied for
+@var{what};  @code{1} yields the `notAfter' value.
+@end deftypefun
+
+@deftypefun KsbaSexp ksba_cert_get_public_key (KsbaCert cert)
+
+@c !FIXME!
+[This needs to get written - for now please see libksba/src/cert.c]
+
+@end deftypefun
+
+@deftypefun KsbaSexp ksba_cert_get_sig_val (KsbaCert cert)
+
+@c !FIXME!
+[This needs to get written - for now please see libksba/src/cert.c]
+@end deftypefun
+
+@deftypefun KsbaError ksba_cert_get_extension (KsbaCert cert, int idx, char const **r_oid, int *r_crit, size_t *r_deroff, size_t *r_derlen)
+
+@c !FIXME!
+[This needs to get written - for now please see libksba/src/cert.c]
+@end deftypefun
+
+@deftypefun KsbaError ksba_cert_is_ca (KsbaCert cert, int *r_ca, int *r_pathlen)
+
+Return information on the basicConstraint (2.5.19.19) of CERT.  R_CA
+receives true if this is a CA and only in that case R_PATHLEN is set to
+the maximim certification path length or -1 if there is no such
+limitation
+
+@end deftypefun
+
+@deftypefun KsbaError ksba_cert_get_key_usage (KsbaCert cert, unsigned int *r_flags)
+
+Get the key usage flags. The function returns Ksba_No_Data if no
+key usage is specified. 
+@end deftypefun
+
+
+@deftypefun KsbaError ksba_cert_get_cert_policies (KsbaCert cert, char **r_policies)
+
+Return a string with the certificatePolicies delimited by linefeeds.
+The return values may be extended to carry more information er line, so
+the caller should only use the first white-space delimited token per
+line.  The function returns KSBA_No_Data when this extension is not used.
+Caller must free the returned value. 
+
+@end deftypefun
+
+
+@deftypefun KsbaError ksba_cert_get_crl_dist_point (KsbaCert @var{cert}, int @var{idx}, KsbaName *@var{r_distpoint}, KsbaName *@var{r_issuer}, unsigned int *@var{r_reason})
+
+Return the CRLDistPoints given in the certificate extension of
+certificate @var{cert}.  @var{idx} should be iterated starting from 0
+until the function returns @code{-1}.  @var{r_distpoint} returns a
+KsbaName object with the distribution point name(s); the return value
+may be @code{NULL} to indicate that this name is not available.
+@var{r_issuer} returns the CRL issuer; if the returned value is
+@code{NULL} the caller should assume that the CRL issuer is the same as
+the certificate issuer.  @var{r_reason} returns the reason for the CRL.
+This is a bit encoded value with no bit set if no reason has been
+specified in the certificate.
+
+The caller may pass @code{NULL} to any of the pointer argumenst if he is
+not interested in this value.  The return values for @var{r_distpoint}
+and @var{r_issuer} must be released by the caller using
+@code{ksba_name_release}.
+@end deftypefun
+
+@deftypefun KsbaError ksba_cert_get_auth_key_id (KsbaCert @var{cert}, KsbaSexp *@var{r_keyid}, KsbaName *@var{r_name}, KsbaSexp *@var{r_serial})
+
+Return the authorityKeyIdentifier in @var{r_name} and @var{r_serial} or
+in @var{r_keyid}.  @code{KSBA_No_Data} is returned if no
+authorityKeyIdentifier or only one using the keyIdentifier method is
+available.
+
+Note that r_keyid is not yet implemented and @var{NULL} must be passed instead.
+@end deftypefun
+
+
+
+@node Setting attributes
+@section How to set certificate attributes
+
+[This needs to be written.  For example code see newpg/sm/sign.c]
+
+\f
+@node CMS
+@chapter Mastering the Cryptographic Message Syntax
+The @acronym{CMS} is also known under the name PKCS#7.  Is is
+acryptographic framework for securing data transactions adn storage,much
+like OpenPGP.  It is heavily based on X.509 semantics and for example
+used with the email encryption protocol S/MIME.
+
+@menu
+* CMS Basics::                  
+* CMS Parser::                  
+@end menu
+
+@node CMS Basics
+@section CMS Basics
+All operations with the CMS framework require the use of a so called CMS
+object which is internally used to keeptrack of the current state and to
+store some meta information.
+
+@deftp {Data type} KsbaCMS
+The @code{KsbaCMS} type is used for this CMS object.
+@end deftp
+@deftp {Data type} KsbaStopReason
+The @code{KsbaStopReason} type is an enumeration used for communication
+between the phases of a parsing or building process.
+@end deftp
+
+
+@deftypefun KsbaCMS ksba_cms_new (void)
+
+This function creates a new CMS object.  The only reason the function
+may fail is an out-of-memory condition in which case @code{NULL} is
+returned.  It is safe for the caller to translate this to the standard
+@acronym{KSBA} error code @code{KSBA_Out_Of_Core}.  Any object created
+with this function should be released after use by using
+@code{ksba_cms_release}.  
+@end deftypefun
+
+@deftypefun void ksba_cms_release (KsbaCMS cms)
+
+Release allresources associated with the @var{CMS} object.  It is
+perfectly okay to pass @code{NULL} to this function in which case
+nothing happens.
+@end deftypefun
+
+@deftypefun KsbaError ksba_cms_set_reader_writer (KsbaCMS @var{cms}, KsbaReader @var{r}, KsbaWriter @var{w})
+
+About all usages of the CMS framework require some input and output data
+(great surprise!).  Do accomplish this in the most abstract way, no
+direct output functions are used - instead special reader and writer
+objects are to be used.  Depending on the desired operations either a
+reader, a writer or both must be given.  Associate a reader object with
+@var{cms} by passing it as @var{r} and a wrter object by passing it as
+@var{w}.  Note that no reference counting is done,so make sure that
+those objects have a lifetime at least as long as @var{CMS}.
+
+If you forget to set these objects, you will get an appropriate error
+later when data is actually to be read or written.  The fnction returns
+zero on success or an error code when invalid objects are passed.
+@end deftypefun
+
+
+@node CMS Parser
+@section CMS Parser
+@acronym{KSBA} includes a versatile CMS parser for encryption (enveloped
+data) and digital signing.  The parser is capable of handling arbitrary
+amounts of data without requiring much memory.  Well, certain objects
+are build in memory because it can be assumed that those objects are
+limited in size; e.g. it does not make sense to use a video clip as the
+@acronym{DN} despite the fact that the standard does not forbid it.
+
+
+@deftypefun KsbaError ksba_cms_parse (KsbaCMS @var{cms}, KsbaStopReason *@var{r_stopreason})
+
+This is the core function of the parser and commonly used in a loop.
+The parsing process is divided into serveral phases to allow the user to
+get information at the right timeand prepare for further processing.
+The caller has to act on certain stop reasons which are returned by
+@var{r_stopreason} adn set up things accordingly; @acronym{KSBA} may
+introduce new stop reasons to let the caller know other details; there
+is no need for the caller to act on every stop reason; he should oly do
+so for reasons he knows and which are mandatory.  The function does
+return with an error if the caller did not setup things correctly for
+certain stop reasons.
+@end deftypefun
+
+The use of the function is best explained by an example, leaving out all
+error checking.
+@example
+  do 
+    @{
+      ksba_cms_parse (cms, &stopreason);
+      if (stopreason == KSBA_SR_BEGIN_DATA)
+        @{
+          get_recipients ();
+          decrypt_session_key ();
+          setup_bulk_decryption ();
+        @}
+      else if (stopreason == KSBA_SR_END_DATA)
+        @{
+          remove_padding ();
+        @}
+    @}
+  while (stopreason != KSBA_SR_READY);   
+@end example
+This function assumes that the parsed data issocalld `enveloped data'.
+@c FIXME: Reference to a list of stop reasons used here.
+
+As @acronym{CMS} provides a common framework for a variety of data
+formats, it is probably very useful tocheck the type of that data very
+early.  This can be accomplished by hooking into the stop reason
+@code{KSBA_SR_GOT_CONTENT} and retrieving the content using
+
+
+@deftypefun KsbaContentType ksba_cms_get_content_type (KsbaCMS @var{cms}, int @var{what})
+
+By using a value of @code{0} for @var{what} this function returns the
+content type of the outer container; using @code{1} does return the
+content type of the enclosed object.
+
+@deftp {Data type} KsbaContentType
+The @code{KsbaContentType} type is an enumeration used to describe the
+content of a CMS message.  Here is a list of possible values:
+
+@table @code
+@item KSBA_CT_NONE 
+No content type know, this one has the value @code{0}
+
+@item KSBA_CT_DATA
+The content is plain data, not further interpreted.
+
+@item KSBA_CT_SIGNED_DATA
+The content is an signed CMS object.  This alosincludes the case of a
+detachedsignature where no actual data is included in the message.
+
+@item  KSBA_CT_ENVELOPED_DATA
+The content is encrypted using a session key.
+
+@item KSBA_CT_DIGESTED_DATA
+Not yet supported
+
+@item KSBA_CT_ENCRYPTED_DATA
+Not yet supported
+
+@item KSBA_CT_AUTH_DATA
+Not yet supported
+@end table
+@end deftp
+@end deftypefun
+
+
+@deftypefun const char *ksba_cms_get_content_oid (KsbaCMS cms, int what)
+
+Return the object ID of @var{cms}.  This is a constant string valid as
+long as the context is valid and no new parse is started.  This function
+is similar to @code{ksba_cms_get_content_type} but returns the
+@acronym{OID} actually used in the data.  Debinding on the value of
+@var{what} different values are returned: USing a value of @code{0}
+yields the OID of the outer container, a value of @code{1} yields the
+OID of the inner container if available and the value @code{2} returns
+the OID of the algorithm used to encrypt the inner container.
+@end deftypefun
+
+@node CRLs
+@chapter Certification Revocation Lists
+KSBA also comes with an API to process certification revocation lists.
+The API is similar to the @acronym{CMS} one but does return entry by
+entry.
+
+
+@node PKCS10
+@chapter Certification Requests
+When using decentral generated keys, it is necessary to send out special
+formated messages so that a CA can generate the certificate.
+
+
+
+\f
+@node Utilities
+@chapter Utilities
+
+A few utility function and objects are available.  Some of them must be used
+to support some of the main functions.
+
+@menu
+* Names::                      General Names object
+* OIDs::                       Object Identifier helpers
+@end menu
+
+@node Names
+@section General Names object
+
+This is an object to handle some of the names used in X.509.  We need
+this object approach because those names may come as a set and there is
+no other clean way to access them.
+
+@deftp {Data type} KsbaName
+The @code{KsbaName} type is an object to represent names sets.
+@end deftp
+
+
+@deftypefun void ksba_name_release (KsbaName @var{name})
+This function releases the object @var{name}.  Passing @code{NULL} is
+allowed.
+@end deftypefun
+
+@deftypefun const char *ksba_name_enum (KsbaName @var{name}, int @var{idx})
+
+By iterating @var{idx} up starting with 0, this function returns all
+General Names stored in @var{name}.  The format of the returned name is either
+a RFC-2253 formated one which can be detected by checking whether the
+first character is letter or a digit.  RFC 2822 conform email addresses
+are returned enclosed in angle brackets, the opening angle bracket
+should be used to detect this.  Other formats are returned as an
+S-Expression in canonical format, so a opening parenthesis may be used
+to detect this encoding, in this case the name may include binary null
+characters, so strlen might return a length shorter than actually used,
+the real length is implictly given by the structure of the S-Exp, an
+extra null is appended for safety reasons.  One common format return is
+probably an Universal Resource Identifier which has the S-expression:
+@samp{(uri <urivalue>)}.
+
+The returned string has the same lifetime as @var{name}. 
+@end deftypefun
+
+@deftypefun char *ksba_name_get_uri (KsbaName @var{name}, int @var{idx})
+Convenience function to return names representing an URI.  Caller
+must free the returned value.  Note that this function should not be
+used to enumerate the names.
+
+Here is an example on how you can use this function to enumerate all
+@acronym{URI}s:
+
+@example
+void
+print_names (KsbaName name)
+@{
+  int idx;
+  const char *s;
+
+  for (idx=0; (s = ksba_name_enum (name, idx)); idx++)
+    @{
+      char *p = ksba_name_get_uri (name, idx);
+      if (p)
+        @{
+           puts (p);
+           ksba_free (p);
+        @}
+    @}
+@}
+@end example
+@end deftypefun
+
+
+@node OIDs
+@section Object Identifier helpers
+
+@c !FIXME!
+[This needs to get written - for now please see libksba/src/oids.c]
+
+
+\f
+@node Error Handling
+@chapter Error Handling
+
+Most functions in `KSBA' are returning an error if they fail.
+For this reason, the application should always catch the error
+condition and take appropriate measures, for example by releasing the
+resources and passing the error up to the caller, or by displaying a
+descriptive message to the user and cancelling the operation.
+
+Some error values do not indicate a system error or an error in the operation,
+but the result of an operation that failed properly.  For example, if you try
+to access optional attributes of a certificate you get an appropriate error
+message.  Some error values have specific meanings if returned by a specific
+function.  Such cases are described in the documentation of those functions.
+
+@menu
+* Error values::                A list of all error values used.
+* Error strings::               How to get a descriptive string from a value.
+@end menu
+
+
+@node Error values
+@section Error values
+
+@deftp {Data type} {enum KsbaError}
+The @code{KsbaError} type specifies the set of all error values that are used
+by `KSBA'.  Except for the EOF and No_Error cases an application should always
+use the constants.  Possible values are:
+
+@table @code
+@item KSBA_EOF
+This value indicates the end of a list, buffer or file and is defined to have
+the value @code{-1}.
+
+@item KSBA_No_Error
+This value indicates success.  The value of this error is @code{0}.
+
+@item KSBA_General_Error
+This value means that something went wrong, but either there is not
+enough information about the problem to return a more useful error
+value, or there is no seperate error value for this type of problem.
+
+@item KSBA_Out_Of_Core
+This value means that an out-of-memory condition occured.  This might be a
+transient error and the application should not assume that it is not anymore
+poosible to allocate memory.
+
+@item KSBA_Invalid_Value
+This value means that some user provided data was out of range.  This
+can also refer to objects.  In most cases this indicates a bug.
+
+@item KSBA_Not_Implemented
+This value indicates that the specific function (or operation) is not
+implemented.  This error should never happen.  It can only occur if
+you use certain values or configuration options which do not work,
+but for which we think that they should work at some later time.
+
+@item KSBA_Read_Error
+This value means that an I/O read operation failed.
+
+@item KSBA_Write_Error
+This value means that an I/O write operation failed.
+
+@item KSBA_File_Error
+This value means that a file I/O operation failed.  The value of
+@code{errno} contains the system error value.
+
+@end table
+@end deftp
+
+
+
+@node Error strings
+@section Error strings
+
+@deftypefun {const char *} ksba_strerror (@w{KSbaError @var{err}})
+The function @code{ksba_strerror} returns a pointer to a statically
+allocated string containing a description of the error with the error
+value @var{err}.  This string can be used to output a diagnostic
+message to the user.
+@end deftypefun
+
+
+
+
+
+@include gpl.texi
+
+@include fdl.texi
+
+@node Concept Index
+@unnumbered Concept Index
+
+@printindex cp
+
+@node Function and Data Index
+@unnumbered Function and Data Index
+
+@printindex fn
+
+@summarycontents
+@contents
+@bye