From 9a412b7569c11277f3e532964c4d883d9d3a0969 Mon Sep 17 00:00:00 2001 From: lloyd Date: Wed, 11 Oct 2006 22:56:09 +0000 Subject: Various small updates to the API doc, mostly in the section about writing modules. --- doc/api.tex | 249 ++++++++++++++++++++++++++++++------------------------------ 1 file changed, 123 insertions(+), 126 deletions(-) (limited to 'doc') diff --git a/doc/api.tex b/doc/api.tex index 0a9ecfdcb..c2e3a10ba 100644 --- a/doc/api.tex +++ b/doc/api.tex @@ -12,7 +12,7 @@ \title{\textbf{Botan API Reference}} \author{} -\date{2006/09/26} +\date{2006/10/11} \newcommand{\filename}[1]{\texttt{#1}} \newcommand{\manpage}[2]{\texttt{#1}(#2)} @@ -25,6 +25,8 @@ \renewcommand{\arg}[1]{\textsl{#1}} \newcommand{\namespace}[1]{\texttt{#1}} +\newcommand{\url}[1]{\texttt{#1}} + \newcommand{\ie}[0]{\emph{i.e.}} \newcommand{\eg}[0]{\emph{e.g.}} @@ -3011,18 +3013,20 @@ contents when their destructors are called, and b) have easy plugins for various memory locking functions, such as the \function{mlock}(2) call on many Unix systems. -Two of the allocation method used (``malloc'' and ``mmap'') don't require any -extra privileges on Unix, but locking memory does. At startup, each allocator -type will attempt to allocate a few blocks (typically totaling 128k), so if you -want, you can run your application \texttt{setuid} \texttt{root}, and then drop -privileges immediately after creating your \type{LibraryInitializer}. If you -end up using more than what's been allocated, some of your sensitive data might -end up being swappable, but that beats running as \texttt{root} all the -time. BTW, I would note that, at least on Linux, you can use a kernel module to -give your process extra privileges (such as the ability to call -\function{mlock}) without being root. For example, check out my Capability -Override LSM (\texttt{http://www.randombit.net/projects/cap\_over/}), which -makes this pretty easy to do. +Two of the allocation method used (``malloc'' and ``mmap'') don't +require any extra privileges on Unix, but locking memory does. At +startup, each allocator type will attempt to allocate a few blocks +(typically totaling 128k), so if you want, you can run your +application \texttt{setuid} \texttt{root}, and then drop privileges +immediately after creating your \type{LibraryInitializer}. If you end +up using more than what's been allocated, some of your sensitive data +might end up being swappable, but that beats running as \texttt{root} +all the time. BTW, I would note that, at least on Linux, you can use a +kernel module to give your process extra privileges (such as the +ability to call \function{mlock}) without being root. For example, +check out my Capability Override LSM +(\url{http://www.randombit.net/projects/cap\_over/}), which makes this +pretty easy to do. These classes should also be used within your own code for storing sensitive data. They are only meant for primitive data types (int, long, etc): if you @@ -3334,16 +3338,13 @@ a \type{BarrettReducer} ahead of time. If the exponent or base is a constant, use the classes in \filename{mod\_exp.h}. This stuff is all handled for you by the normal high-level interfaces, of course. -\subsection{A Warning} - -Don't ever even consider using the low-level MPI functions (those that begin -with \texttt{bigint\_}). These are completely internal to the library, and make -arbitrarily strange and undocumented assumptions about their inputs, and don't -check to see if they are actually true, on the assumption that only the library -itself calls them, and that the library knows what the assumptions are. The -interfaces for these functions can change completely without notice. These -functions aren't visible without effort on your part specifically to that end, -so you will get no sympathy if you decide to use any of them. +Never use the low-level MPI functions (those that begin with +\texttt{bigint\_}). These are completely internal to the library, and +may make arbitrarily strange and undocumented assumptions about their +inputs, and don't check to see if they are actually true, on the +assumption that only the library itself calls them, and that the +library knows what the assumptions are. The interfaces for these +functions can change completely without notice. \pagebreak @@ -3417,20 +3418,22 @@ added to Botan, the application will start using it automagically. \section{Writing Modules} -It's a lot simpler to write modules for Botan that it is to write code in the -core library, for several reasons. First, a module can rely on external -libraries and services beyond the base ISO C++ libraries, and also machine -dependent features (assembler, anyone?). Also, the code can be added at -configuration time on the user's end with very little effort (\ie the code can -be distributed separately and without depending on patching anything). - -Creating a module is quite simple. First, there must be a subdirectory in the -\filename{modules} directory for it. The name of the module is the same as the -name of this directory. Inside this directory, there needs to be a file, with -exactly the same name as the directory (that's so the configuration script -knows where to look). This file contains directives it uses to specify what -this module does, what systems it runs on, and so on. Comments start with a -\verb|#| character and continue to end of line. +It's a lot simpler to write modules for Botan that it is to write code +in the core library, for several reasons. First, a module can rely on +external libraries and services beyond the base ISO C++ libraries, and +also machine dependent features. Also, the code can be added at +configuration time on the user's end with very little effort (\ie the +code can be distributed separately, and included by the user without +needing to patch any existing source files). + +Each module lives in a subdirectory of the \filename{modules} +directory, which exists at the top-level of the Botan source tree. The +``short name'' of the module is the same as the name of this +directory. The only required file in this directory is +\filename{modinfo.txt}, which contains directives that specify what a +particular module does, what systems it runs on, and so on. Comments +in \filename{modinfo.txt} start with a \verb|#| character and continue +to end of line. Recognized directives include: @@ -3444,17 +3447,18 @@ Recognized directives include: is \texttt{}.} \directive{note }{Add a note that will be seen by the end-user at -configure time.} - -\directive{require\_version }{Require at configure time that the -version of Botan in use be at least \texttt{}. If not, the module will -be ignored. Note that this directive is ignored prior to 1.4.3.} - -\directive{define }{Define \macro{BOTAN\_EXT\_} in - \filename{config.h}. This may only be used if the module creates - user-visible changes. There is a set of conventions that should be followed - in deciding what to call this macro (where xxx denotes some descriptive and - distinguishing characteristic of the thing implemented, such as +configure time if the module is included into the library.} + +\directive{require\_version }{Require at configure time that +the version of Botan in use be at least \texttt{}.} + +\directive{define [,[,...]]}{Cause the macro + \macro{BOTAN\_EXT\_} (for each instance of \macro{} + in the directive) to be defined in \filename{build.h}. This should + only be used if the module creates user-visible changes. There is a + set of conventions that should be followed in deciding what to call + this macro (where xxx denotes some descriptive and distinguishing + characteristic of the thing implemented, such as \macro{ALLOC\_MLOCK} or \macro{MUTEX\_PTHREAD}): \begin{itemize} @@ -3467,29 +3471,27 @@ be ignored. Note that this directive is ignored prior to 1.4.3.} \end{itemize} } -\directive{ / }{This specifies any extra libraries to be linked in. -It is a mapping from OS to library name, for example \texttt{linux -> rt}, -which means that on Linux librt should be linked in. You can also use ``all'' -to force the library to be linked in on all systems.} +\directive{ / }{This specifies any extra libraries to be +linked in. It is a mapping from OS to library name, for example +\texttt{linux -> rt}, which means that on Linux librt should be linked +in. You can also use ``all'' to force the library to be linked in on +all systems.} -\directive{add\_file }{Tell the configuration script to add the file - given into the source tree. This file must exist in the module directory.} +\directive{ / }{Tell the configuration script to add the + files named between these two tags into the source tree. All these + files must exist in the current module directory.} -\directive{ignore\_file }{Tell the configuration script to ignore the - file given in the main source tree.} +\directive{ / }{Tell the configuration script to + ignore the files named in the main source tree. This is useful, for + example, when replacing a C++ implementation with a pure assembly + version.} -\directive{replace\_file }{Tell the configuration script to ignore the - file given in the main source tree, and instead use the one in the module's - directory.} +\directive{ / }{Tell the configuration script to + ignore the file given in the main source tree, and instead use the + one in the module's directory.} -\directive{local\_only }{Mark this header file as being for the build - only; it will not be installed. This is useful for headers used internally - that are not exposed to the client.} - -\vskip 10pt -\noindent -Additionally, the module file can contain blocks, delimited by -the following pairs: +Additionally, the module file can contain blocks, delimited by the +following pairs: \texttt{ / }, \texttt{ / }, \texttt{ / } @@ -3498,10 +3500,6 @@ For example, putting ``alpha'' and ``ia64'' in a \texttt{} block will make the configuration script only allow the module to be compiled on those architectures. Not having a block means any value is acceptable. -\section{Writing BigInt assembly modules} - -Write me... - \pagebreak \section{Compliance with Standards} @@ -3579,28 +3577,30 @@ be more secure than the ones listed, but the algorithms listed here are \section{Algorithms Listing} -Botan includes a very sizable number of cryptographic algorithms. In nearly all -cases, you never need to know the header file or type name to use -them. However, you do need to know what string (or strings) are used to -identify that algorithm. Generally, these names conform to those set out by -SCAN (Standard Cryptographic Algorithm Naming), which is a document which -specifies how strings are mapped onto algorithm objects, which is useful for a -wide variety of crypto APIs (SCAN is oriented towards Java, but Botan and -several other non-Java libraries also make at least some use of it). For full -details, read the SCAN document, which can be found at -\textbf{http://www.users.zetnet.co.uk/hopwood/crypto/scan/} - -Many of these algorithms can take options (such as the number of rounds in a -block cipher, the output size of a hash function, etc). These are shown in the -following list; all of them default to reasonable values (unless otherwise -marked). There are algorithm-specific limits on most of them. When you see -something like ``HASH'' or ``BLOCK'', that means you should insert the name of -some algorithm of that type. There are no defaults for those options. - -A few very obscure algorithms are skipped; if you need one of them, you'll know -it, and you can look in the appropriate header to see what that classes' -\function{name} function returns (the names tend to match that in SCAN, if it's -defined there). +Botan includes a very sizable number of cryptographic algorithms. In +nearly all cases, you never need to know the header file or type name +to use them. However, you do need to know what string (or strings) are +used to identify that algorithm. Generally, these names conform to +those set out by SCAN (Standard Cryptographic Algorithm Naming), which +is a document which specifies how strings are mapped onto algorithm +objects, which is useful for a wide variety of crypto APIs (SCAN is +oriented towards Java, but Botan and several other non-Java libraries +also make at least some use of it). For full details, read the SCAN +document, which can be found at +\url{http://www.users.zetnet.co.uk/hopwood/crypto/scan/} + +Many of these algorithms can take options (such as the number of +rounds in a block cipher, the output size of a hash function, +etc). These are shown in the following list; all of them default to +reasonable values (unless otherwise marked). There are +algorithm-specific limits on most of them. When you see something like +``HASH'' or ``BLOCK'', that means you should insert the name of some +algorithm of that type. There are no defaults for those options. + +A few very obscure algorithms are skipped; if you need one of them, +you'll know it, and you can look in the appropriate header to see what +that classes' \function{name} function returns (the names tend to +match that in SCAN, if it's defined there). \begin{list}{$\cdot$} \item ROUNDS: The number of rounds in a block cipher. @@ -3612,10 +3612,11 @@ defined there). \vskip .05in \noindent -\textbf{Block Ciphers:} ``AES'', ``Blowfish'', ``CAST-128'', ``CAST-256'', -``DES'', ``DESX'', ``TripleDES'', ``GOST'', ``IDEA'', ``MARS'', -``MISTY1(ROUNDS)'', ``RC2'', ``RC5(ROUNDS)'', ``RC6'', ``SAFER-SK(ROUNDS)'', -``SEED'', ``Serpent'', ``Skipjack'', ``SQUARE'', ``TEA'', ``Twofish'', ``XTEA'' +\textbf{Block Ciphers:} ``AES'', ``Blowfish'', ``CAST-128'', +``CAST-256'', ``DES'', ``DESX'', ``TripleDES'', ``GOST'', ``IDEA'', +``MARS'', ``MISTY1(ROUNDS)'', ``RC2'', ``RC5(ROUNDS)'', ``RC6'', +``SAFER-SK(ROUNDS)'', ``SEED'', ``Serpent'', ``Skipjack'', ``Square'', +``TEA'', ``Twofish'', ``XTEA'' \noindent \textbf{Stream Ciphers:} ``ARC4'', ``MARK4'', ``Turing'', ``WiderWake4+1-BE'' @@ -3630,16 +3631,7 @@ defined there). \pagebreak -\section{More Information} - -\subsection{Support} - -Questions or problems you have with Botan can be directed to the development -mailing list (currently called \texttt{opencl-devel}). Joining this list is -highly recommended if you're going to be using Botan, since often advance -notice of upcoming changes is sent there. ``Philosophical'' bug reports, -announcements of programs using Botan, and basically anything else having to do -with Botan are also welcome. +\section{Support and Further Information} \subsection{Compatibility} @@ -3670,12 +3662,12 @@ not encumbered by patents. If you have any concerns about the patent status of any algorithm you are considering using in an application, please discuss it with your attorney. -\subsection{Further Reading and Information} +\subsection{Recommended Reading} -It's a very good idea if you have some knowledge of cryptography prior to -trying to use this stuff. You really should read one or more of these books -before seriously using the library (note that the Handbook of Applied -Cryptography is available online, and I highly recommend you read it): +It's a very good idea if you have some knowledge of cryptography prior +to trying to use this stuff. You really should read one or more of +these books before seriously using the library (note that the Handbook +of Applied Cryptography is available for free online): \setlength{\parskip}{5pt} @@ -3698,7 +3690,17 @@ Once you've got the basics down, these are good things to at least take a look at: IEEE 1363 and 1363a, SCAN, NESSIE, PKCS \#1 v2.1, the security related FIPS documents, and the CFRG RFCs. -\pagebreak +\subsection{Support} + +Questions or problems you have with Botan can be directed to the +development mailing list. Joining this list is highly recommended if +you're going to be using Botan, since often advance notice of upcoming +changes is sent there. ``Philosophical'' bug reports, announcements of +programs using Botan, and basically anything else having to do with +Botan are also welcome. + +The lists can be found at +\url{http://www.randombit.net/mailman/listinfo/}. \subsection{Contact Information} @@ -3707,25 +3709,20 @@ A PGP key with a fingerprint of Botan releases. This key can be found in the file \filename{doc/pgpkeys.asc}; PGP keys for the developers are also stored there. -Another key, with fingerprint -\verb|33E3 9768 1D13 E7B4 1A01 BBCE A63F 2CBD FA02 FBCC|, was used for signing -releases up to version 1.4.2. This key has been retired. - \vskip 5pt \noindent -Web Site: \verb|http://botan.randombit.net| +Web Site: \url{http://botan.randombit.net} \vskip 5pt \noindent -Mailing lists: \verb|http://www.randombit.net/mailman/| - -\pagebreak +Mailing lists: \url{http://www.randombit.net/mailman/} -\section{License} +\subsection{License} Copyright \copyright 2000-2006, The Botan Project -This work is licensed under the Creative Commons Attribution-ShareAlike 2.5 -License. To view a copy of this license, visit -http://creativecommons.org/licenses/by-sa/2.5/ or send a letter to Creative -Commons, 543 Howard Street, 5th Floor, San Francisco, California, 94105, USA. +This work is licensed under the Creative Commons +Attribution-ShareAlike 2.5 License. To view a copy of this license, +visit \url{http://creativecommons.org/licenses/by-sa/2.5/} or send a +letter to Creative Commons, 543 Howard Street, 5th Floor, San +Francisco, California, 94105, USA. \end{document} -- cgit v1.2.3