%
%% Copyright (c) Members of the EGEE Collaboration. 2004-2010.
%% See http://www.eu-egee.org/partners for details on the copyright holders.
%% 
%% Licensed under the Apache License, Version 2.0 (the "License");
%% you may not use this file except in compliance with the License.
%% You may obtain a copy of the License at
%% 
%%     http://www.apache.org/licenses/LICENSE-2.0
%% 
%% Unless required by applicable law or agreed to in writing, software
%% distributed under the License is distributed on an "AS IS" BASIS,
%% WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
%% See the License for the specific language governing permissions and
%% limitations under the License.
%
% -*- mode: latex -*-

\section{Credentials Handling}
\label{s:cs-auth-conn}

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 
(openssl library now)

\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 \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 -- 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 -- 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.
  \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 the credentials context.
  \begin{itemize}
    \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
  \end{itemize}
  \item \verb'canl_cred_load_chain(canl_ctx, canl_cred cred,'
  \verb' STACK_OF(X509) *chain)'
  This function loads the certificate chain out of an openssl structure. The 
  chain usually 
  consist of a proxy certificate and certificates forming
  a chain of trust.
  \begin{itemize}
    \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 the certificate chain out of a file. The chain usually 
  consists of a proxy certificate and certificates forming
  a chain of trust.
  \begin{itemize}
    \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
  \begin{itemize}
    \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 -- 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 -- 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,
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 -- 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.
  \begin{itemize}
    \item param cred -- the credentials context
    \item param type -- a canl\_cert\_type in canl\_cred.h
  \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 -- the credentials context which holds signer's certificate
    and key.
    \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.
  \begin{itemize}
    \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 -- 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)}.
  \begin{itemize}
   \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 a new certificate signing request after a new key pair 
  is generated.
   \begin{itemize}
    \item param cred -- the credentials context, certificate signing request 
    is saved there
    \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}.
  \begin{itemize}
    \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 -- the credentials context, the cert. request
  will be stored there
    \item param to -- load the certificate request from
  \end{itemize}

  \item \begin{verbatim}
canl_err_code canl_verify_chain(canl_ctx ctx, X509 *ucert, STACK_OF(X509) *cert_chain, char *cadir)\end{verbatim}
  Verify the certificate chain, openssl verification, CRL, OCSP, 
  signing policies etc...
  \begin{itemize}
    \item param ucert -- user certificate
    \item param cert\_chain  -- certificate chain to verify
    \item param cadir  -- CA certificate directory
  \end{itemize}

  \item \begin{verbatim}
canl_err_code canl_verify_chain_wo_ossl(canl_ctx ctx, char *cadir, X509_STORE_CTX *store_ctx)\end{verbatim}
  Verify certificate chain, SKIP openssl verif. part; Check CRL, OCSP (if on), 
  signing policies etc. (This is special case usage of caNl, not recommended to use unless you really know what you are doing)
  \begin{itemize}
    \item param cadir  -- CA certificate directory
    \item param store\_ctx -- openssl store context structure fed with certificates to verify
  \end{itemize}

\end{itemize}

\subsection{Make New Proxy Certificate -- Example}
We give an example of a proxy certificate creation. We do not 
define variables in this example, unless
their type is \CANL defined. We do not check return values in most
cases as well.
For complete sample see example sources.

Include necessary header files:
\begin{lstlisting}
#include <canl.h>
#include <canl_cred.h>
\end{lstlisting}
\CANL context variables
\begin{lstlisting}
canl_cred signer = NULL;
canl_cred proxy = NULL;
canl_ctx ctx = NULL;
\end{lstlisting}

Initialize context:
\begin{lstlisting}
ctx = canl_create_ctx();
ret = canl_cred_new(ctx, &proxy);
\end{lstlisting}

Create a certificate request with a new key-pair.
\begin{lstlisting}
ret = canl_cred_new_req(ctx, proxy, bits);
\end{lstlisting}

(Optional) Set cert. creation parameters
\begin{lstlisting}
ret = canl_cred_set_lifetime(ctx, proxy, lifetime);
ret = canl_cred_set_cert_type(ctx, proxy, CANL_RFC);
\end{lstlisting}

Load the signing credentials
\begin{lstlisting}
ret = canl_cred_new(ctx, &signer);
ret = canl_cred_load_cert_file(ctx, signer, user_cert);
ret = canl_cred_load_priv_key_file(ctx, signer, user_key, NULL, NULL);
\end{lstlisting}

Create the new proxy certificate
\begin{lstlisting}
ret = canl_cred_sign_proxy(ctx, signer, proxy);
\end{lstlisting}

And store it in a file
\begin{lstlisting}
ret = canl_cred_save_proxyfile(ctx, proxy, output);
\end{lstlisting}


\begin{lstlisting}
if (signer)
    canl_cred_free(ctx, signer);
if (proxy)
    canl_cred_free(ctx, proxy);
if (ctx)
    canl_free_ctx(ctx);
\end{lstlisting}
