on any cryptography toolkit as possible, so it may support
other libraries in the future.
-\subsection{MAIN API Without Direct Calls To Openssl}
-These are the functions of the \verb'Main API' that do not
+\subsection{Main API Without Direct Calls To Openssl}
+These are the functions of the \textit{Main API} that do not
use \textit{openssl API} calls or variable types directly
(as a parameter or in their definitions):
\begin{itemize}
\item \verb'canl_ctx canl_create_ctx()'--This function
- returns an initialized authentication context object
- \item \verb'void CANL_CALLCONV canl_free_ctx(canl_ctx cc)'--This
- function will free the authentication context, releasing
+ returns an initialized \textit{authentication context} object
+ \item \verb'void CANL_CALLCONV canl_free_ctx(canl_ctx cc)'
+
+ This function will free the \textit{authentication context}, releasing
all associated information. The context must not be used after this call.
\begin{itemize}
- \item param cc - the authentication context to free.
+ \item param cc - the \textit{authentication context} to free.
\end{itemize}
- \item \verb'canl_err_code'
- \verb'canl_create_io_handler(canl_ctx cc, canl_io_handler *io)' --
- This function will create an \verb'i/o handler' from the authentication
+ \item \textit{canl error code}
+ \verb'canl_create_io_handler(canl_ctx cc, canl_io_handler *io)'
+
+ This function will create an \textit{i/o handler} from the authentication
context. This handler shall be passed to all I/O-related functions.
\begin{itemize}
- \item param cc - the authentication context
- \item param io - return an initialized \verb'i/o context', or NULL if
- it did not succeed.
+ \item param cc - the \textit{autehentication context}
+ \item param io - return an initialized \textit{i/o context},
+or NULL if it did not succeed.
\item return - \CANL error code
\end{itemize}
- \item \verb'canl_err_code canl_io_close(canl_ctx cc, canl_io_handler io)' --
+ \item \verb'canl_err_code canl_io_close(canl_ctx cc, canl_io_handler io)'
+
This function will close an existing connection. The 'io' object may
be reused by another connection. It is safe to call this
function on an io object which was connected.
\begin{itemize}
- \item param cc - The authentication context
- \item param io - The \verb'i/o context'
- \item return - \verb'canl_err_code'
+ \item param cc - The \textit{autehentication context}
+ \item param io - The \textit{i/o context}
+ \item return - \textit{canl error code}
\end{itemize}
- \item \verb'canl_err_code canl_io_connect(canl_ctx cc, canl_io_handler io,'
- \verb'const char *host, const char *service, int port,'
- \verb'gss_OID_set auth_mechs,'
- \verb'int flags, struct timeval *timeout)' --
+ \item \begin{verbatim}canl_err_code canl_io_connect(canl_ctx cc, canl_io_handler io,
+const char *host, const char *service, int port, gss_OID_set auth_mechs,
+ int flags, struct timeval *timeout)\end{verbatim}
This function will try to connect to a server object,
doing authentication (if not forbidden)
\begin{itemize}
- \item param cc - The authentication context
- \item param io - The \verb'i/o context'
+ \item param cc - The \textit{autehentication context}
+ \item param io - The \textit{i/o context}
\item param host - The server to which to connect
\item param service - TODO DK
\item param port - The port on which the server is listening
\item param auth\_mechs - Authentication mechanism to use
\item flags - TODO
\item param timeout - The timeout after which to drop the connect attempt
- \item return - \verb'canl_err_code'
+ \item return - \textit{canl error code}
\end{itemize}
- \item \verb'canl_io_accept(canl_ctx cc, canl_io_handler io,'
- \verb'int fd, struct sockaddr s_addr, int flags,'
- \verb'canl_principal *peer, struct timeval *timeout)' -- This function will
+ \item \begin{verbatim}canl_io_accept(canl_ctx cc, canl_io_handler io,int fd,
+ struct sockaddr s_addr, int flags,canl_principal *peer,
+ struct timeval *timeout)\end{verbatim}
+ This function will
setup a server to accept connections from clients, doing
authentication (if not forbidden)
\begin{itemize}
- \item param cc - The authentication context
- \item param io - The \verb'i/o context'
+ \item param cc - The \textit{autehentication context}
+ \item param io - The \textit{i/o context}
\item param fd - \TODO
\item param port - The port on which the server is listening
\end{itemize}
\end{itemize}
-\subsection{MAIN API With Direct Calls To Openssl}
+\subsection{Main API With Direct Calls To Openssl}
\begin{itemize}
- \item \verb'canl_err_code'
- \verb'canl_ctx_set_ssl_cred(canl_ctx cc, char *cert, char *key, char *proxy,'
- \verb'canl_password_callback clb, void *pass)' This function
- will set the credential to be associated to the \textit{context}. These
- credentials will become the default ones for all API calls
- depending on this \textit{context}.
+ \item \begin{verbatim}canl_err_code canl_ctx_set_ssl_cred(canl_ctx cc, char *cert, char *key,
+char *proxy, canl_password_callback clb, void *pass)\end{verbatim}
+ This function will set the credential to be associated to the
+ \textit{context}. These credentials will become the default ones
+ for all API calls depending on this \textit{context}.
\begin{itemize}
- \item param cc - The authentication context
+ \item param cc - The \textit{autehentication context}
\item param cert - The certificate to be set
\item param key - Its private key
\item param proxy - The proxy certificate to be set
will be passed
directly to the callback. This means that altering the data
pointed by it will have a direct effect on the behaviour of the function.
- \item return - \verb'canl_err_code'
+ \item return - \textit{canl error code}
\end{itemize}
\item \verb'canl_err_code'
\verb'canl_ctx_set_ca_dir(canl_ctx cc, const char *ca_dir)'
+
+ Set certficate authority directory (openssl ca directory structure)
\begin{itemize}
- \item param cc - The authentication context
+ \item param cc - The \textit{autehentication context}
\item ca\_dir - The path that will be set. It will not be
checked whether this path actually contains the CAs or not.
- \item return - \verb'canl_err_code'
+ \item return - \textit{canl error code}
\end{itemize}
\item \verb'canl_err_code'
\verb'canl_ctx_set_crl_dir(canl_ctx cc, const char *crl_dir)'
\begin{itemize}
- \item param cc - The authentication context
+ \item param cc - The \textit{autehentication context}
\item crl\_dir - The path that will be set. It will not be
checked whether this path actually contains the CRLs or not.
- \item return - \verb'canl_err_code'
+ \item return - \textit{canl error code}
\end{itemize}
\end{itemize}
\subsection{Secure Client-Server Connection Example}
-We give example of caNl client that use \textit{Main API}
+We give an xample of a caNl client that use \textit{Main API}
with openssl. We do not define variables in this example, unless
their type is \CANL defined. For complete sample see
-\verb'canl_samples_server.c' in
+{\tt canl\_samples\_server.c} in
\TODO Where to find sources (package?)- Frantisek?
Include nesessary header files:
connection with one or both sides authenticated, send or receive data,
\item \textit{\CANL Certificate API}
\end{itemize}
-The Main API is independent from the Certificate API, but the latter
+The \textit{Main API} is independent from the \textit{Certificate API}
+, but the latter
one shares a number of data types and functions with the first one.
\subsection{Language Bindings}
\subsection{General Guidelines}
\marginpar{Naming conventions}%
-All function names are prefixed with canl\_
+All function names are prefixed with \verb'canl_'
\marginpar{Input and output arguments}%
All structures and objects passed in output of functions
(even though pointers are used as a help)
are dynamically allocated, so proper functions to free the allocated
-memory has to be called. e.g. \verb'canl_free_ctx()' deallocates members
-of the stucture.
+memory has to be called. e.g. \verb'canl_free_ctx()'
+deallocates members of the stucture.
\marginpar{Opaque types}%
Almost all types used in caNl are \textit{Opaque types}- i.e. their structure is
not exposed to users. To use and/or modify these structures API call has
-to be used. Example of opaque type is \verb'canl_ctx'.
+to be used. Example of opaque type is {\tt canl\_ctx}.
\marginpar{Return values}%
-The return type of most of the API functions is \verb'canl_err_code' which
+The return type of most of the API functions is {\tt canl\_err\_code} which
in most cases can be interpreted as int. Unless specified otherwise, zero
return value means success, non-zero failure. Standard error codes from
-\verb'errno.h' are used as much as possible.
+{\tt errno.h} are used as much as possible.
TODO openssl mapping
-Few API function return \verb'char *'. In such a~case
-\verb'NULL' indicates an error, non-null value means success.
+Few API functions return {\tt char *}. In such a~case
+{\tt NULL} indicates an error, non-null value means success.
\subsection{Context and Parameter Settings}
\label{s:context}
-All the API functions use a \emph{context} parameter of type \verb'canl_ctx'
+All the API functions use a \emph{context} parameter of type {\tt canl\_ctx}
to maintain state information like error message and code.
-Some API functions also use an \emph{io context} of type \verb'canl_io_handler'
+Some API functions also use an \emph{io context} of type {\tt canl\_io\_handler}
which keeps information about each particular connection
(\eg socket number, oid, SSL context).The caller can create as many
contexts as needed, all of them will be independent. When calling
\subsection{Context}
\label{s:canl_ctx}
\marginpar{Context initialization}%
-There are two opaque data structures representing caNl \textit{Main API}
-context: \verb'canl_ctx' and \verb'canl\_io\_handler' (see
-section~\ref{s:context}.
-\verb'canl_ctx' must be initialized before any caNl API call.
-\verb'canl_io_handler' must be initialized before function call
+There are two opaque data structures representing
+caNl \textit{Main API} context: {\tt canl\_ctx} and
+ {\tt canl\_io\_handler} (see section~\ref{s:context}).
+{\tt canl\_ctx} must be initialized before any caNl API call.
+{\tt canl\_io\_handler} must be initialized before function call
representing io operation (e.g. \verb'canl_io_connect()') and after
-\verb'canl_ctx' initialization.
+{\tt canl\_ctx} initialization.
\begin{lstlisting}
#include <canl.h>
#include <canl_ssl.h>
err = canl_create_io_handler(my_ctx, &my_io_h);
\end{lstlisting}
There is one opaque data structure representing \CANL
-\textit{Certificate API}: \verb'canl_cred'.
+\textit{Certificate API} context: {\tt canl\_cred}.
It must only be initialized before function calls
that use this context as a parametr.
\begin{lstlisting}
ctx = canl_create_ctx();
\end{lstlisting}
\marginpar{Obtaining error description}%
-\verb'canl_ctx' stores details of all errors which has occurred since
+{\tt canl\_ctx} stores details of all errors which has occurred since
context initialization, in human readable format. To obtain it use
\verb'canl_get_error_message()':
\begin{lstlisting}
\marginpar{Context deallocation}%
It is recommended to free the memory allocated to each
-context if they are not needed anymore, in first case \verb'canl_io_handler'
-, then \verb'canl_ctx' in case of the \textit{Main API}:
+context if they are not needed anymore, in first case {\tt canl\_io\_handler}
+, then {\tt canl\_ctx} in case of the \textit{Main API}:
\begin{lstlisting}
if (my_io_h)
canl_io_destroy(my_ctx, my_io_h);
\label{s:cs-auth-conn}
If we want to create new proxy certificate or \Eg delegate
-credentials, we can use \CANL \verb'Certificate API'.
+credentials, we can use \CANL \textit{Certificate API}.
This part of API uses X509 authentication mechanism
(uses openssl library now)
-\subsection{Credentials API}
-These are the functions of the \verb'Credentials API', all of them use
-\verb'canl_ctx' as first parameter and \verb'canl_err_code' as a return
+\subsection{Certificate API}
+These are the functions of the \textit{Certificate API}, all of them use
+{\tt canl\_ctx} as first parameter and {\tt canl\_err\_code} as a return
value, so we do not include them in following description:
\begin{itemize}
\item param cert - openssl structure to load certificate from.
\end{itemize}
\item \begin{verbatim}
-canl_err_code canl_cred_load_cert_file(canl_ctx, canl_cred cred, const char *file)\end{verbatim}
+canl_err_code canl_cred_load_cert_file(canl_ctx, canl_cred cred,
+const char *file)\end{verbatim}
This funcion loads user certificate out of a file.
\begin{itemize}
\item param cred - credentials which save certificate to
\item param lt - lifetime in seconds
\end{itemize}
\item \begin{verbatim}
-canl_err_code canl_cred_set_extension(canl_ctx, canl_cred cred, X509_EXTENSION *ext)\end{verbatim}
+canl_err_code canl_cred_set_extension(canl_ctx, canl_cred cred,
+X509_EXTENSION *ext)\end{verbatim}
This function sets the certificate extension to for the certificate
which is going to be created
\begin{itemize}
\item param ext - openssl structure holding X509 certificate extension
\end{itemize}
\item \begin{verbatim}
-canl_err_code canl_cred_set_cert_type(canl_ctx, canl_cred cred, const enum canl_cert_type type)\end{verbatim}
+canl_err_code canl_cred_set_cert_type(canl_ctx, canl_cred cred,
+const enum canl_cert_type type)\end{verbatim}
This function sets the certificate type to for the certificate
which is going to be created
\begin{itemize}
\item param type - \CANL enum type ...\TODO type
\end{itemize}
\item \begin{verbatim}
-canl_err_code canl_cred_sign_proxy(canl_ctx, canl_cred signer, canl_cred proxy)\end{verbatim}
+canl_err_code canl_cred_sign_proxy(canl_ctx, canl_cred signer,
+canl_cred proxy)\end{verbatim}
This function makes new proxy certificate based on information in
\textit{proxy} parameter. The new certificate is signed with private key
saved in \textit{signer}. A new certificate chain is saved
certificate type and extensions.
\end{itemize}
\item \begin{verbatim}
-canl_err_code canl_cred_save_proxyfile(canl_ctx, canl_cred cred, const char * file)\end{verbatim}
+canl_err_code canl_cred_save_proxyfile(canl_ctx, canl_cred cred,
+const char * file)\end{verbatim}
This function saves proxy certificate into a file
\begin{itemize}
\item param cred - credentials context with certificate to save
git://scientific.zcu.cz / jra1mw.git / commitdiff