From: Marcel Poul Date: Tue, 24 Apr 2012 15:13:58 +0000 (+0000) Subject: canl-c documentation X-Git-Tag: canl_merge_branch_1_0_head_take_3_src~21 X-Git-Url: http://scientific.zcu.cz/git/?a=commitdiff_plain;h=32c8db50fe5e15e1fbbfe48036fe8d6413e8f19c;p=jra1mw.git canl-c documentation --- diff --git a/emi.canl.canl-c/doc/src/canl-abstract.tex b/emi.canl.canl-c/doc/src/canl-abstract.tex new file mode 100644 index 0000000..a8a80e7 --- /dev/null +++ b/emi.canl.canl-c/doc/src/canl-abstract.tex @@ -0,0 +1,21 @@ +% +%% 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. diff --git a/emi.canl.canl-c/doc/src/canl-cs-auth-connection.tex b/emi.canl.canl-c/doc/src/canl-cs-auth-connection.tex new file mode 100644 index 0000000..e39d8a3 --- /dev/null +++ b/emi.canl.canl-c/doc/src/canl-cs-auth-connection.tex @@ -0,0 +1,142 @@ +% +%% 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 +#include +\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} diff --git a/emi.canl.canl-c/doc/src/canl-introduction.tex b/emi.canl.canl-c/doc/src/canl-introduction.tex new file mode 100644 index 0000000..b0fff24 --- /dev/null +++ b/emi.canl.canl-c/doc/src/canl-introduction.tex @@ -0,0 +1,167 @@ +% +%% 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 +#include + +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 +#include + +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} diff --git a/emi.canl.canl-c/doc/src/canl-proxy-cert.tex b/emi.canl.canl-c/doc/src/canl-proxy-cert.tex new file mode 100644 index 0000000..22b6550 --- /dev/null +++ b/emi.canl.canl-c/doc/src/canl-proxy-cert.tex @@ -0,0 +1,24 @@ +% +%% 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 diff --git a/emi.canl.canl-c/doc/src/canl.tex b/emi.canl.canl-c/doc/src/canl.tex new file mode 100644 index 0000000..18b572d --- /dev/null +++ b/emi.canl.canl-c/doc/src/canl.tex @@ -0,0 +1,107 @@ +% +%% 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} + diff --git a/emi.canl.canl-c/doc/src/copyright.tex b/emi.canl.canl-c/doc/src/copyright.tex new file mode 100644 index 0000000..a54293f --- /dev/null +++ b/emi.canl.canl-c/doc/src/copyright.tex @@ -0,0 +1,44 @@ +% +%% 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 diff --git a/emi.canl.canl-c/doc/src/definitions.tex b/emi.canl.canl-c/doc/src/definitions.tex new file mode 100644 index 0000000..85fedc9 --- /dev/null +++ b/emi.canl.canl-c/doc/src/definitions.tex @@ -0,0 +1,54 @@ +% +%% 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} diff --git a/emi.canl.canl-c/doc/src/funding.tex b/emi.canl.canl-c/doc/src/funding.tex new file mode 100644 index 0000000..3da7646 --- /dev/null +++ b/emi.canl.canl-c/doc/src/funding.tex @@ -0,0 +1,4 @@ +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.