--- /dev/null
+%
+%% 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.
+%
+% when changed, update also http://egee.cesnet.cz/en/JRA1/LB/lb.html
+% (in CVSROOT=:gserver:lindir.ics.muni.cz:/cvs/edg, cvsweb/lb.html)
+The Developer's Guide explains how to use the canl C (\CANL)
+API. Main and Credentials API is described in details together with
+programing examples.
--- /dev/null
+%
+%% 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 Reference guide}
+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):
+
+\begin{itemize}
+\item \verb'canl_ctx canl_create_ctx()'--This function
+returns an initialized authentication context object
+\item \verb'void CANL_CALLCONV canl_free_ctx(canl_ctx cc)'--This
+function will free the authentication context, releasing
+all associated information. The context must not be used after this call.
+\begin{itemize}
+\item param cc - the authentication context to free.
+\end{itemize}
+\item \verb'canl_err_code
+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}
+\item param cc - the authentication context
+\item param io - return an initialized \verb'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 ac - The authentication context
+\item param io - The \verb'i/o context'
+\item return - \verb'canl_err_code'
+\end{itemize}
+\item \verb'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)' --
+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 io - The \verb'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 - \verb'canl_err_code'
+\end{itemize}
+\item \verb'canl_io_accept(canl_ctx cc, canl_io_handler io,
+int fd, struct sockaddr s_addr, int flags,
+canl_principal *peer, struct timeval *timeout)' -- This function will
+setup a server to accept connections from clients, doing
+authentication (if not forbidden)
+\begin{itemize}
+\item param ac - 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}
+
+\end{itemize}
+
+\subsection{Secure Client-Server Connection Example}
+We give example of caNl client, for complete sample see
+\verb'canl_samples_server.c' in
+\TODO Where to find sources (package?)- Frantisek?
+
+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}
+
+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}
--- /dev/null
+%
+%% 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{Introduction}
+
+This document serves as a developer's guide and could be
+seen as an API reference too, even though comments in
+the header files may give the reader better insights into that matter.
+
+The \CANL API can be devided by functionality into two parts:
+
+\begin{itemize}
+\item \textit{\CANL Main API} is used to establish (secure) client-server
+connection with one or both sides authenticated, send or receive data,
+\item \textit{\CANL Certificate API}
+\end{itemize}
+The Main API is independent from the Certificate API, but the latter
+one shares a number of data types and functions with the first one.
+
+\subsection{Language Bindings}
+\CANL is developed in C language as well as C++ and Java language bindings,
+however this document covers only the C interface.
+
+\subsection{Getting and Building Library}
+TODO package names
+
+external dependencies:
+\begin{itemize}
+\item c-ares -- asynchronous resolver library
+\item openssl -- cryptography and SSL/TLS toolkit
+\end{itemize}
+
+\subsection{General Guidelines}
+
+\marginpar{Naming conventions}%
+All function names are prefixed with canl\_
+
+\marginpar{Input and output arguments}%
+All structures and objects passed in output of functions
+(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 stucture.
+
+\marginpar{Opaque types}%
+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 \verb'canl_ctx'.
+
+\marginpar{Return values}%
+The return type of most of the API functions is \verb'canl_err_code' which
+ in most cases can be interpreted as int. Unless specified otherwise, zero
+return value means success, non-zero failure. Standard error codes from
+\verb'errno.h' are used as much as possible.
+TODO openssl mapping
+
+Few API function return \verb'char *'. In such a~case
+\verb'NULL' indicates an error, non-null value means success.
+
+\subsection{Context and Parameter Settings}
+\label{s:context}
+All the API functions use a \emph{context} parameter of type \verb'canl_ctx'
+to maintain state information like error message and code.
+Some API functions also use an \emph{io context} of type \verb'canl_io_handler'
+which keeps information about each particular connection
+(\eg socket number, oid, SSL context).The caller can create as many
+contexts as needed, all of them will be independent. When calling
+\verb'canl_create_ctx()' or \verb'canl_create_io_handler()' all members
+of the objects are initialized with default values which are often
+NULL for pointer type and 0 in case of int and similar types.
+
+\section{\CANL Components}
+\label{s:common}
+
+\subsection{Header Files}
+
+Header files for the common structures and functions are summarized in
+table~\ref{t:cheaders}.
+
+\begin{table}[h]
+\begin{tabularx}{\textwidth}{>{\tt}lX}
+canl.h & Definition of context objects and \textit{Main API} common
+functions declarations. \\
+canl\_ssl.h & Declaration of functions that use X509 certificates
+based authentication mechanism (pretty much dependent on
+openssl library funcions).\\
+canl\_cred.h & Definition of context objects of the
+\textit{Certificate API} and functions declarations.\\
+\end{tabularx}
+\caption{Header files}
+\label{t:cheaders}
+\end{table}
+
+\subsection{Building Client Programs}
+The easiest way to build programs using \CANL in C is to use
+GNU's libtool to take care of all the dependencies:
+\begin{verbatim}
+libtool --mode=compile gcc -c example1.c -D_GNU_SOURCE
+libtool --mode=link gcc -o example1 example1.o -lcanl_c
+\end{verbatim}
+
+\subsection{Context}
+\label{s:canl_ctx}
+\marginpar{Context initialization}%
+There are two opaque data structures representing caNl \textit{Main API}
+context: \verb'canl_ctx' and \verb'canl\_io\_handler' (see
+section~\ref{s:context}.
+\verb'canl_ctx' must be initialized before any caNl API call.
+\verb'canl_io_handler' must be initialized before function call
+representing io operation (e.g. \verb'canl_io_connect()') and after
+\verb'canl_ctx' initialization.
+\begin{lstlisting}
+#include <canl.h>
+#include <canl_ssl.h>
+
+canl_io_handler my_io_h = NULL;
+canl_ctx my_ctx;
+my_ctx = canl_create_ctx();
+err = canl_create_io_handler(my_ctx, &my_io_h);
+\end{lstlisting}
+There is one opaque data structure representing \CANL
+\textit{Certificate API}: \verb'canl_cred'.
+It must only be initialized before function calls
+that use this context as a parametr.
+\begin{lstlisting}
+#include <canl.h>
+#include <canl_cred.h>
+
+canl_ctx ctx = NULL;
+ctx = canl_create_ctx();
+\end{lstlisting}
+\marginpar{Obtaining error description}%
+\verb'canl_ctx' stores details of all errors which has occurred since
+context initialization, in human readable format. To obtain it use
+\verb'canl_get_error_message()':
+\begin{lstlisting}
+printf("%s\n", canl_get_error_message(my_ctx));
+\end{lstlisting}
+
+\marginpar{Context deallocation}%
+It is recommended to free the memory allocated to each
+context if they are not needed anymore, in first case \verb'canl_io_handler'
+, then \verb'canl_ctx' in case of the \texit{Main API}:
+\begin{lstlisting}
+if (my_io_h)
+ canl_io_destroy(my_ctx, my_io_h);
+canl_free_ctx(my_ctx);
+\end{lstlisting}
+as for the Certificate API:
+\begin{lstlisting}
+canl_cred_free(ctx, signer);
+\end{lstlisting}
--- /dev/null
+%
+%% 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{Proxy certificate creation and credentials delegation}
+\label{s:proxy-cert
+
+\TODO
+\subsection{Main API Reference guide}
+\TODO
--- /dev/null
+%
+%% 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 -*-
+\documentclass{emi}
+\def\insideDG{}
+
+\input{definitions}
+%\def\LB{LB\xspace}
+
+\title{Common Authentication Library -- Developer's Guide}
+%\Subtitle{Developer's Guide}
+\author{CESNET caNl team}
+%\DocIdentifier{glite-lb-doc-dg-\version}
+%\DeliverableId{}
+\Date{\today}
+%\Activity{JRA1: Middleware Engineering}
+%\DocStatus{DRAFT}
+\DocVersion{\version}
+%\Dissemination{PUBLIC}
+%\DocumentLink{\url{http://egee.cesnet.cz/cvsweb/LB/LBDG.pdf}}
+\Abstract{\input{canl-abstract}}
+\EMICompVersion{3.x}
+
+
+\usepackage{listings}
+\usepackage{amsmath}
+
+%\setlength{\marginparwidth}{1.2in}
+\let\oldmarginpar\marginpar
+\renewcommand\marginpar[1]{\-\oldmarginpar[\raggedleft\footnotesize #1]%
+{\raggedright\footnotesize #1}}
+
+\begin{document}
+\reversemarginpar
+\lstset{language=C,basicstyle=\footnotesize,numbers=none,breaklines=true}
+%\lstset{title={\bf File: }\lstname}
+\lstset{rangeprefix=/*,rangesuffix=*/,includerangemarker=false}
+\lstset{escapeinside={//*}{\^^M}}
+
+% ----- BEGIN COPY -----
+% copied from org.glite.lb.client/doc/api/api.tex in hope it could be useful
+
+%\parindent=0pt
+%\parskip=\smallskipamount
+
+\makeatletter
+\def\jobid{\textit{JobId}\xspace}
+\def\@tti[#1]{\item[{\normalfont\texttt{#1}}]\catcode`\_=8}
+\def\tti{\catcode`\_=11\noexpand\@tti}
+\newlength{\tw}
+
+\def\synopsis{\catcode`\_=11\noexpand\@synopsis}
+\def\@synopsis#1#2{
+\tw=\linewidth
+\advance\tw-2em
+\texttt{#1(}\\
+\strut\hskip2em\begin{tabularx}\tw{>{\begingroup\tt}l<{\endgroup}lX}
+#2
+\end{tabularx}\\
+\texttt)
+\catcode`\_=8
+}
+
+\def\Synopsis{\subsubsection*{Synopsis}}
+\def\Description{\subsubsection*{Description}}
+\def\Return{\subsubsection*{Return values}}
+
+% ----- END COPY -----
+
+%\input{frontmatter}
+\input{funding}
+\input{copyright}
+\tableofcontents
+
+%TODO is it necessery
+%\newpage
+%\input{versions}
+
+\newpage
+\input{canl-introduction}
+
+\newpage
+\input{canl-cs-auth-connection}
+
+\newpage
+\input{canl-proxy-cert}
+
+%\newpage
+%\bibliographystyle{unsrt}
+%\bibliography{lbjp}
+
+\end{document}
+
--- /dev/null
+%
+%% 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.
+%
+% Taken from:
+% https://twiki.cern.ch/twiki/bin/view/EGEE/EGEEgLiteSoftwareLicense
+%
+~
+
+\vfill{}
+
+{\bf
+Copyright} \copyright\ {\bf Members of the EGEE Collaboration. 2004. See
+\href{http://www.eu-egee.org/partners/}{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
+
+\begin{center}
+\href{http://www.apache.org/licenses/LICENSE-2.0}{http://www.apache.org/licenses/LICENSE-2.0}
+\end{center}
+
+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.
+}
+\clearpage
+
+TODO check
--- /dev/null
+%
+%% 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.
+%
+% external packages
+\usepackage{xspace}
+\usepackage{ifthen}
+\usepackage{comment}
+\usepackage{listings}
+
+% useful definitions
+\def\CANL{caNl}
+\newcommand\LBver[1]{\textit{\LB version {#1}}}
+\def\JP{JP\xspace}
+%\def\eg{e.\,g.}
+\def\eg{for example\xspace}
+\def\Eg{For example\xspace}
+%\def\ie{i.\,e.}
+\def\ie{that is\xspace}
+\def\wrt{with respect to\xspace}
+\def\Dash{---\penalty-1000}
+
+\def\req{\noindent\textbf{Prerequisities:}}
+\def\how{\noindent\textbf{How to run:}}
+\def\what{\noindent\textbf{What to test:}}
+\def\result{\noindent\textbf{Expected result:}}
+\def\note{\noindent\textbf{Note:}}
+\def\path#1{{\normalfont\textsf{#1}}}
+\def\code#1{\texttt{#1}}
+\def\ctblb#1{\code{org.glite.testsuites.ctb/LB/tests/#1}}
+
+\specialcomment{hints}{\par\noindent\textbf{Hints: }\begingroup\slshape}{\endgroup}
+%\includecomment{hints}
+
+\long\def\TODO#1{\par\noindent\textbf{TODO:} {\sl#1}\par}
+\long\def\ludek#1{}
+
+\hyphenation{plug-in}
+
+\newcommand{\email}[1]{\href{mailto:#1}{#1}}
+
+\input{ver.tex}
--- /dev/null
+TODO check this one
+This work is co-funded by the European Commission as part of
+the EMI project under
+Grant Agreement INFSO-RI-261611.
git://scientific.zcu.cz / jra1mw.git / commitdiff