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):
\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}
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}
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
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
\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?
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}
canl_io_destroy(my_ctx, my_io_h);
canl_free_ctx(my_ctx);
\end{lstlisting}
+
%
% -*- 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 <canl.h>
+#include <canl_cred.h>
+\end{lstlisting}
+
+
git://scientific.zcu.cz / jra1mw.git / commitdiff