For client-server authenticated connection we just use \CANL
\textit{Main API} calls. In time of writing this paper
-\CANL use \textit{openssl - SSL/TLS and cryptography toolkit}.
+\CANL use \textit{openssl -- SSL/TLS and cryptography toolkit}.
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.
(as a parameter or in their definitions):
\begin{itemize}
- \item \verb'canl_ctx canl_create_ctx()'--This function
+ \item \verb'canl_ctx canl_create_ctx()'
+
+ This function
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 \textit{authentication context} to free.
+ \item param cc -- the \textit{authentication context} to free
\end{itemize}
\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.
+ This function will create an \textit{i/o handler} from the
+\textit{authentication context}. This handler shall be passed to
+all I/O-related functions.
\begin{itemize}
- \item param cc - the \textit{authentication context}
- \item param io - return an initialized \textit{i/o context},
-or NULL if it did not succeed.
- \item return - \CANL error code
+ \item param cc -- the \textit{authentication 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)'
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 \textit{authentication context}
- \item param io - The \textit{i/o context}
- \item return - \textit{canl error code}
+ \item param cc -- the \textit{authentication context}
+ \item param io -- the \textit{i/o context}
+ \item return -- \textit{canl error code}
\end{itemize}
\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,
This function will try to connect to a server object,
doing authentication (if not forbidden)
\begin{itemize}
- \item param cc - The \textit{authentication 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 - \textit{canl error code}
+ \item param cc -- the \textit{authentication 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 -- \textit{canl error code}
\end{itemize}
\item \begin{verbatim}canl_io_accept(canl_ctx cc, canl_io_handler io,int fd,
struct sockaddr s_addr, int flags,canl_principal *peer,
setup a server to accept connections from clients, doing
authentication (if not forbidden)
\begin{itemize}
- \item param cc - The \textit{authentication context}
- \item param io - The \textit{i/o context}
- \item param fd - \TODO
- \item param port - The port on which the server is listening
+ \item param cc -- the \textit{authentication context}
+ \item param io -- the \textit{i/o context}
+ \item param fd -- \TODO this param?
+ \item param port -- the port on which the server is listening
\end{itemize}
\end{itemize}
\textit{context}. These credentials will become the default ones
for all API calls depending on this \textit{context}.
\begin{itemize}
- \item param cc - The \textit{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
+ \item param cc -- the \textit{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 callback 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 behavior of the function. User specified
- data that will be passed as is to the callback 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 behavior of the function.
- \item return - \textit{canl error code}
+ a direct effect on the behavior of the function.
+ \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 \textit{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 - \textit{canl error code}
+ \item param cc -- rhe \textit{authentication context}
+ \item ca\_dir -- rhe path that will be set. It will not be
+ checked whether this path actually contains the CAs or not
+ \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 \textit{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 - \textit{canl error code}
+ \item param cc -- the \textit{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 -- \textit{canl error code}
\end{itemize}
\end{itemize}
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 )
+will be used, \ie those in proper env. variables )
.
.
.
the header files may give the reader better insights into that matter.
Common Authentication Library (\CANL for short)
-CANL was designed to provide common security layer support in grid
+was designed to provide common security layer support in grid
applications. It is largely based on existing code (VOMS, LB). Its
simple API can be devided by functionality into two parts:
\item \textit{\CANL Main API} is used to establish (secure) client-server
connection with one or both sides authenticated, send or receive data.
As will be described in~\ref{s:cs-auth-conn}, most of the \textit{Main API}
-is not directly dependent on cryptography toolkit (SSL implementation) It is
+is not directly dependent on some chosen cryptography toolkit
+(SSL implementation). It is
also internally plugin-based and therefore other security mechanisms support can
be added in future.
\item \textit{\CANL Certificate API} allows certificate and proxy management \eg
(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 structure.
+deallocates members of the structure \verb'canl_ctx'.
\marginpar{Opaque types}%
-Almost all types used in caNl are \textit{Opaque types}- i.e. their structure is
+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 {\tt canl\_ctx}.
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
+{\tt canl\_io\_handler} must be initialized before calling function
+representing io operation (\eg \verb'canl_io_connect()') and after
{\tt canl\_ctx} initialization.
\begin{lstlisting}
#include <canl.h>
#include <canl.h>
#include <canl_cred.h>
-canl_ctx ctx = NULL;
+canl_ctx ctx;
+canl_cred c_cred;
ctx = canl_create_ctx();
+canl_cred_new(ctx, &c_cred);
\end{lstlisting}
\marginpar{Obtaining error description}%
{\tt canl\_ctx} stores details of all errors which has occurred since
\end{lstlisting}
as for the Certificate API:
\begin{lstlisting}
-canl_cred_free(ctx, signer);
+canl_cred_free(ctx, c_cred);
\end{lstlisting}
\section{Credentials Handling}
\label{s:cs-auth-conn}
-If we want to create new proxy certificate or \Eg delegate
+If we want to create new proxy certificate or \eg delegate
credentials, we can use \CANL \textit{Certificate API}.
This part of API uses X509 authentication mechanism
-(uses openssl library now)
+(openssl library now)
\subsection{Certificate API}
These are the functions of the \textit{Certificate API}, all of them use
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 returned to this pointer after
- success.
+ \item param cred -- a new object will be returned 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
+ \item param cred -- the 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
+ This one sets users credentials to \CANL context.
\begin{itemize}
- \item param cred - credentials to set to global \CANL context
+ \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.
+ Load private key from specified file into the 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
+ \item param cred -- credentials which save private key to
+ \item param file -- the file to load private key from
+ \item param clb -- the 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.
+ \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 function loads certificate chain out of an openssl structure. The
+ This function loads the certificate chain out of an openssl structure. The
chain usually
consist of a proxy certificate and certificates forming
- chain of trust
+ a chain of trust.
\begin{itemize}
- \item param cred - credentials context to set chain to
- \item param chain - openssl structure to load certificate chain from.
+ \item param cred -- the credentials context to set chain to
+ \item param chain -- the openssl structure to load certificate chain from.
\end{itemize}
\item \verb'canl_cred_load_chain_file(canl_ctx, canl_cred cred,'
\verb' const char * file)'
- This function loads certificate chain out of a file. The chain usually
+ This function loads the certificate chain out of a file. The chain usually
consists of a proxy certificate and certificates forming
- chain of trust
+ a chain of trust.
\begin{itemize}
- \item param cred - credentials which save certificate chain to
- \item param file - file to load certificate chain from.
+ \item param cred -- credentials which save certificate chain to
+ \item param file -- the 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 function loads user certificate out of an openssl structure.
+ This function 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.
+ \item param cred -- the credentials context to set certificate to
+ \item param cert -- the 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 function 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.
+ \item param cred -- credentials which save certificate to
+ \item param file -- the 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
+ \item param cred -- the credentials context
+ \item param lt -- the lifetime in seconds
\end{itemize}
\item \begin{verbatim}
canl_err_code canl_cred_set_extension(canl_ctx, canl_cred cred,
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
+ \item param cred -- the credentials context
+ \item param ext -- the 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
+ which is going to be created.
\begin{itemize}
- \item param cred - credentials context
- \item param type - \CANL enum type ...\TODO type
+ \item param cred -- the credentials context
+ \item param type -- a \CANL enum type ...\TODO type
\end{itemize}
\item \begin{verbatim}
canl_err_code canl_cred_sign_proxy(canl_ctx, canl_cred signer,
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}
+ into \textit{proxy}.
\begin{itemize}
- \item param signer - credentials context which holds signer's certificate
+ \item param signer -- the credentials context which holds signer's certificate
and key.
- \item param proxy - credentials context with a certificate
+ \item param proxy -- the credentials context with a certificate
signing request, public key and user certificate; 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
+ 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
+ \item param cred -- the credentials context with certificate to save
+ \item param file -- save the 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
+ \begin{itemize}.
+ \item param cred -- the credentials context with certificate to save
+ \item param to -- save the 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)}
+ 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
+ \item param cred -- the credentials context with certificate chain to save
+ \item param to -- save the 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
+ This function creates a new certificate signing request after a new key pair
is generated.
\begin{itemize}
- \item param cred - credentials context, certificate signing request
+ \item param cred -- the credentials context, certificate signing request
is saved there
- \item param bits - key length
+ \item param bits -- the 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}
+ 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
+ \item param cred -- the credentials context with certificate request
+ \item param to -- save the 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
+ \item param cred -- the credentials context, the cert. request
+ will be stored there
+ \item param to -- load the certificate request from
\end{itemize}
\end{itemize}
git://scientific.zcu.cz / jra1mw.git / commitdiff