From 2a75fafadc6d7b268b9ab503ab456ce03d8a82f3 Mon Sep 17 00:00:00 2001 From: Marcel Poul Date: Wed, 25 Apr 2012 14:16:17 +0000 Subject: [PATCH] Clean bibtex files too --- emi.canl.canl-c/Makefile | 3 +- .../doc/src/canl-cs-auth-connection.tex | 82 +++++++++- emi.canl.canl-c/doc/src/canl-proxy-cert.tex | 175 ++++++++++++++++++++- emi.canl.canl-c/doc/src/definitions.tex | 3 +- 4 files changed, 254 insertions(+), 9 deletions(-) diff --git a/emi.canl.canl-c/Makefile b/emi.canl.canl-c/Makefile index b8a5111..39195fb 100644 --- a/emi.canl.canl-c/Makefile +++ b/emi.canl.canl-c/Makefile @@ -162,7 +162,8 @@ stage: all clean: rm -rfv *.o *.lo ${LIBCANL} .libs client server proxy delegation \ ${top_srcdir}/*.c ${top_srcdir}/*.h lex.backup stage \ - canl.aux canl.log canl.pdf canl.out canl.toc ver.tex + canl.aux canl.log canl.pdf canl.out canl.toc ver.tex \ + canl.bbl canl.blg distclean: rm -rvf Makefile.inc config.status project/changelog *.spec debian/ diff --git a/emi.canl.canl-c/doc/src/canl-cs-auth-connection.tex b/emi.canl.canl-c/doc/src/canl-cs-auth-connection.tex index f5d7853..a9843db 100644 --- a/emi.canl.canl-c/doc/src/canl-cs-auth-connection.tex +++ b/emi.canl.canl-c/doc/src/canl-cs-auth-connection.tex @@ -26,7 +26,7 @@ However, core of the \CANL has been developed to be as independent on any cryptography toolkit as possible, so it may support other libraries in the future. -\subsection{Main API Reference guide} +\subsection{MAIN API Without Direct Calls To Openssl} These are the functions of the \verb'Main API' that do not use \textit{openssl API} calls or variable types directly (as a parameter or in their definitions): @@ -41,7 +41,7 @@ use \textit{openssl API} calls or variable types directly \item param cc - the authentication context to free. \end{itemize} \item \verb'canl_err_code' - \verb'canl_create_io_handler(canl_ctx cc, canl_io_handler *io)' -- + \verb'canl_create_io_handler(canl_ctx cc, canl_io_handler *io)' -- This function will create an \verb'i/o handler' from the authentication context. This handler shall be passed to all I/O-related functions. \begin{itemize} @@ -56,7 +56,7 @@ use \textit{openssl API} calls or variable types directly be reused by another connection. It is safe to call this function on an io object which was connected. \begin{itemize} - \item param ac - The authentication context + \item param cc - The authentication context \item param io - The \verb'i/o context' \item return - \verb'canl_err_code' \end{itemize} @@ -67,7 +67,7 @@ use \textit{openssl API} calls or variable types directly This function will try to connect to a server object, doing authentication (if not forbidden) \begin{itemize} - \item param ac - The authentication context + \item param cc - The authentication context \item param io - The \verb'i/o context' \item param host - The server to which to connect \item param service - TODO DK @@ -83,7 +83,7 @@ use \textit{openssl API} calls or variable types directly setup a server to accept connections from clients, doing authentication (if not forbidden) \begin{itemize} - \item param ac - The authentication context + \item param cc - The authentication context \item param io - The \verb'i/o context' \item param fd - \TODO \item param port - The port on which the server is listening @@ -91,8 +91,57 @@ use \textit{openssl API} calls or variable types directly \end{itemize} +\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}. + \begin{itemize} + \item param cc - The authentication context + \item param cert - The certificate to be set + \item param key - Its private key + \item param proxy - The proxy certificate to be set + \item param clb - A callback function which should return + the password to the private key, if needed. + \item param pass - User specified data that will be passed + as is to the callvack function. Note that the content of this + pointer will not be copied internally, and 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. User specified + data that will be passed as is to the callvack function. Note that + the content of this pointer will not be copied internally, and + 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' + \end{itemize} + \item \verb'canl_err_code' + \verb'canl_ctx_set_ca_dir(canl_ctx cc, const char *ca_dir)' + \begin{itemize} + \item param cc - The authentication 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' + \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 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' + \end{itemize} + +\end{itemize} \subsection{Secure Client-Server Connection Example} -We give example of caNl client, for complete sample see +We give example of 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 \TODO Where to find sources (package?)- Frantisek? @@ -111,6 +160,26 @@ err = canl_create_io_handler(my_ctx, &my_io_h); err = canl_ctx_set_ssl_cred(my_ctx, serv_cert, serv_key, NULL, NULL); \end{lstlisting} +set user's credentials (X509 auth. mechanism) +\begin{lstlisting} +if (serv_cert || serv_key || proxy_cert){ + err = canl_ctx_set_ssl_cred(my_ctx, serv_cert, serv_key, proxy_cert, + NULL, NULL); + if (err) { + printf("[CLIENT] cannot set certificate or key to context: %s\n", + canl_get_error_message(my_ctx)); + goto end; + } +} +\end{lstlisting} + +If using X509 auth. mechanism, we might set \textit{CA directory} and/or + \textit{CRL directory} at this place. (If not set, default directories +will be used \Ie those in proper env. variables ) +. +. +. + Connect to the server, send something then read the response: \begin{lstlisting} @@ -141,3 +210,4 @@ if (my_io_h) canl_io_destroy(my_ctx, my_io_h); canl_free_ctx(my_ctx); \end{lstlisting} + diff --git a/emi.canl.canl-c/doc/src/canl-proxy-cert.tex b/emi.canl.canl-c/doc/src/canl-proxy-cert.tex index 4365215..c64566d 100644 --- a/emi.canl.canl-c/doc/src/canl-proxy-cert.tex +++ b/emi.canl.canl-c/doc/src/canl-proxy-cert.tex @@ -16,4 +16,177 @@ % % -*- mode: latex -*- -\section{Main section} +\section{Credentials Handling} +\label{s:cs-auth-conn} + +If we want to create new proxy certificate or \Eg delegate +credentials, we can use \CANL \verb'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 +value, so we do not include them in following description: + +\begin{itemize} + \item \begin{verbatim} +canl_err_code canl_cred_new(canl_ctx, canl_cred *cred)\end{verbatim} +This function creates new structure (context) to hold credentials. + \begin{itemize} + \item param cred - new object will be retured to this pointer after + success. + \end{itemize} + \item \begin{verbatim} +canl_err_code canl_cred_free(canl_ctx, canl_cred *cred)\end{verbatim} + This function will free the credentials context, releasing + all associated information. The context must not be used after this call. + \begin{itemize} + \item param cred - credentials context to free + \end{itemize} + \item \begin{verbatim} +canl_err_code canl_ctx_set_cred(canl_ctx, canl_cred cred)\end{verbatim} + This one sets users credentials to \CANL context + \begin{itemize} + \item param cred - credentials to set to global \CANL context + \end{itemize} + \item \begin{verbatim} +canl_err_code canl_cred_load_priv_key_file(canl_ctx, canl_cred cred, const +char * file, canl_password_callback clb, void *pass)\end{verbatim} + Load private key from specified file into credentials context. + \begin{itemize} + \item param cred - credentials which save private key to + \item param file - file to load private key from + \item param clb - A callback function which should return + the password to the private key, if needed. + \item param pass - User specified data that will be passed + as is to the callback function. + \end{itemize} + \item \verb'canl_cred_load_chain(canl_ctx, canl_cred cred,' + \verb' STACK_OF(X509) *chain)' + This funcion loads certificate chain out of an openssl structure. The + chain usualy + consist of a proxy certificate and certificates forming + chain of trust + \begin{itemize} + \item param cred - credentials context to set chain to + \item param chain - openssl structre to load certificate chain from. + \end{itemize} + \item \verb'canl_cred_load_chain_file(canl_ctx, canl_cred cred,' + \verb' const char * file)' + This funcion loads certificate chain out of a file. The chain usualy + consist of a proxy certificate and certificates forming + chain of trust + \begin{itemize} + \item param cred - credentials which save certificate chain to + \item param file - file to load certificate chain from. + \end{itemize} + \item \begin{verbatim} +canl_err_code canl_cred_load_cert(canl_ctx, canl_cred cred, X509 *cert)\end{verbatim} + This funcion loads user certificate out of an openssl structure. + \begin{itemize} + \item param cred - credentials context to set certificate to + \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} + This funcion loads user certificate out of a file. + \begin{itemize} + \item param cred - credentials which save certificate to + \item param file - file to load certificate from. + \end{itemize} + \item \begin{verbatim} +canl_err_code canl_cred_set_lifetime(canl_ctx, canl_cred cred, const long lt)\end{verbatim} + This function sets the lifetime for a certificate which is going to + be created + \begin{itemize} + \item param cred - credentials context + \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} + This function sets the certificate extension to for the certificate + which is going to be created + \begin{itemize} + \item param cred - credentials context + \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} + This function sets the certificate type to for the certificate + which is going to be created + \begin{itemize} + \item param cred - credentials context + \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} + 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 + into \textit{proxy} + \begin{itemize} + \item param signer - credentials context which holds signer's certificate + and key. + \item param proxy - credentials context with a certificate + signing request, public key and user certifice; optionally lifetime, + 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} + This function saves proxy certificate into a file + \begin{itemize} + \item param cred - credentials context with certificate to save + \item param file - save certificate into + \end{itemize} + \item \begin{verbatim} +canl_err_code canl_cred_save_cert(canl_ctx, canl_cred cred, X509 **to)\end{verbatim} + This function saves certificate into openssl object of type \textit{X509} + \begin{itemize} + \item param cred - credentials context with certificate to save + \item param to - save certificate into + \end{itemize} + \item \begin{verbatim} +canl_err_code canl_cred_save_chain(canl_ctx, canl_cred cred, STACK_OF(X509) **to)\end{verbatim} + This function saves certificate chain of trust with proxy + certificate into openssl object of type \textit{STACK\_OF(X509)} + \begin{itemize} + \item param cred - credentials context with certificate chain to save + \item param to - save certificate into + \end{itemize} + \item \begin{verbatim} +canl_err_code canl_cred_new_req(canl_ctx, canl_cred cred, unsigned int bits)\end{verbatim} + This function creates new certificate signing request after new key pair + is generated. + \begin{itemize} + \item param cred - credentials context, certificate signing request + is saved there + \item param bits - key length + \end{itemize} + \item \begin{verbatim} +canl_err_code canl_cred_save_req(canl_ctx, canl_cred cred, X509_REQ **to)\end{verbatim} + This function saves certificate signing request into openssl object of type \textit{X509\_REQ} + \begin{itemize} + \item param cred - credentials context with certificate request + \item param to - save certificate request into + \end{itemize} + \item \begin{verbatim} +canl_err_code canl_cred_save_req(canl_ctx, canl_cred cred, X509_REQ **to)\end{verbatim} + This function loads certificate signing request from openssl object of type \textit{X509\_REQ} into \CANL certificate context + \begin{itemize} + \item param cred - credentials context, cert. request will be stored there + \item param to - load certificate request from + \end{itemize} + +\end{itemize} + +\subsection{Make and Initialize New proxy certificate - example} +\TODO Do it + +Include nesessary header files: +\begin{lstlisting} +#include +#include +\end{lstlisting} + + diff --git a/emi.canl.canl-c/doc/src/definitions.tex b/emi.canl.canl-c/doc/src/definitions.tex index 85fedc9..5d784c8 100644 --- a/emi.canl.canl-c/doc/src/definitions.tex +++ b/emi.canl.canl-c/doc/src/definitions.tex @@ -21,7 +21,7 @@ \usepackage{listings} % useful definitions -\def\CANL{caNl} +\def\CANL{caNl\xspace} \newcommand\LBver[1]{\textit{\LB version {#1}}} \def\JP{JP\xspace} %\def\eg{e.\,g.} @@ -29,6 +29,7 @@ \def\Eg{For example\xspace} %\def\ie{i.\,e.} \def\ie{that is\xspace} +\def\Ie{That is\xspace} \def\wrt{with respect to\xspace} \def\Dash{---\penalty-1000} -- 1.8.2.3