%
%% 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{Client-Server Authenticated Connection}
\label{s:cs-auth-conn}

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}. 
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 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 \textit{authentication context} object
  \item \verb'void 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
  \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 
\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
  \end{itemize}

  \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 \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,
 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 \textit{authentication context}
    \item param io -- the \textit{i/o context}
    \item param host -- the server to which to connect
    \item param service -- the service on the server - usually NULL
    \item param port -- the port on which the server is listening
    \item param auth\_mechs -- authentication mechanism to use
    \item param flags -- for future usage
    \item param peer -- if not NULL the canl\_principal will be filled with peer's principal info. Approppriate free funcion should be called if canl\_princ is no longer to be used
    \item param timeout -- the timeout after which to drop the connect attempt
    \item return -- \textit{canl error code}
  \end{itemize}
  \item \begin{verbatim}canl_err_code 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 \textit{authentication context}
    \item param io -- the \textit{i/o context}
    \item param fd -- file descriptor to use
    \item param port -- the port on which the server is listening
    \item param sockaddr -- open socket address 
    \item param flags -- for future usage
    \item param peer -- if not NULL the canl\_principal will be filled with peer's principal info. Approppriate free funcion should be called if canl\_princ is no longer to be used
    \item return -- \textit{canl error code}
  \end{itemize}

  \item \begin{verbatim}canl_err_code canl_princ_name(canl_ctx cc, const canl_principal cp, char **ret_name)\end{verbatim}
  Get the peer's principal name in text readable form. 
  \begin{itemize}
    \item param cc -- the \textit{authentication context}
    \item param cp -- canl structure to hold peer's principal info. Have to be filled by previous call to canl\_io\_accept or canl\_io\_connect funcions.
    \item param ret\_name -- text form of the peer's princ. name 
    \item return -- \textit{canl error code}
  \end{itemize}

  \item \begin{verbatim}void canl_princ_free(canl_ctx cc, canl_principal cp)\end{verbatim}
  If canl\_princ structure filled before by some canl io funcion, this function should be called to free the allocated memory. 
  \begin{itemize}
    \item param cc -- the \textit{authentication context}
    \item param cp -- canl peer's principal structure
    \item return -- void
  \end{itemize}

\end{itemize}

\subsection{Main API With Direct Calls To Openssl}

\begin{itemize}
  \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 \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.
    \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 -- rhe \textit{authentication context}
    \item param 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}
    \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 param 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}

  \item \begin{verbatim}canl_err_code  canl_ctx_set_ssl_flags(canl_ctx cc, unsigned int flags) \end{verbatim}
  Set SSL specific flags. This function can turn OCSP check ON. 
  (OFF by default)
  \begin{itemize}
    \item param cc -- the \textit{authentication context}
    \item param flags -- one of the canl\_ctx\_ssl\_flags in canl\_ssl.h (e.g. 
  CANL\_SSL\_OCSP\_VERIFY\_ALL)
    \item return -- \textit{canl error code}
  \end{itemize}

\end{itemize}
\subsection{Secure Client-Server Connection Example}
We give an example 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 
{\tt canl\_samples\_server.c} in source package or \href{http://glite.cvs.cern.ch/cgi-bin/glite.cgi/emi.canl.canl-c/examples/canl\_sample\_server.c?revision=HEAD}{canl\_sample\_server.c at CVS}

Include nesessary header files:
\begin{lstlisting}
#include <canl.h>
#include <canl_ssl.h>
\end{lstlisting}

Initialize context and set parameters:
\begin{lstlisting}
canl_ctx my_ctx;
canl_io_handler my_io_h = NULL;
my_ctx = canl_create_ctx();
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}
err = canl_io_connect(my_ctx, my_io_h, p_server, NULL, port, NULL, 0, &timeout);
if (err) {
        printf("[CLIENT] connection to %s cannot be established: %s\n",
               p_server, canl_get_error_message(my_ctx));
        goto end;
    }
err = canl_io_write (my_ctx, my_io_h, buf, buf_len, &timeout);
if (err <= 0) {
        printf("can't write using ssl: %s\n",
               canl_get_error_message(my_ctx));
        goto end;
    }
err = canl_io_read (my_ctx, my_io_h, buf, sizeof(buf)-1, &timeout);
if (err > 0) {
        buf[err] = '\0';
        printf ("[CLIENT] received: %s\n", buf);
        err = 0;
    }
\end{lstlisting}

Free the allocated memory:

\begin{lstlisting}
if (my_io_h)
        canl_io_destroy(my_ctx, my_io_h);
canl_free_ctx(my_ctx);
\end{lstlisting}

