OpenSL ssl(3openssl)
NAME
SL - OpenSL SL/TLS library
SYNOPSIS
DESCRIPTION
The OpenSL ssl library implements the Secure Sockets Layer
(SL v2/v3) and Transport Layer Security (TLS v1) protocols.
It provides a rich API which is documented here.
At first the library must be initialized; see
SLlibraryinit(3).
Then an SLCTX object is created as a framework to
establish TLS/SL enabled connections (see SLCTXnew(3)).
Various options regarding certificates, algorithms etc. can
be set in this object.
When a network connection has been created, it can be
assigned to an SL object. After the SL object has been
created using SLnew(3), SLsetfd(3) or SLsetbio(3)
can be used to associate the network connection with the
object.
Then the TLS/SL handshake is performed using SLaccept(3)
or SLconnect(3) respectively. SLread(3) and
SLwrite(3) are used to read and write data on the TLS/SL
connection. SLshutdown(3) can be used to shut down the
TLS/SL connection.
DATA STRUCTURES
Currently the OpenSL ssl library functions deals with the
following data structures:
SLMETHOD (SL Method)
That's a dispatch structure describing the internal ssl
library methods/functions which implement the various
protocol versions (SLv1, SLv2 and TLSv1). It's needed
to create an SLCTX.
SLCIPHER (SL Cipher)
This structure holds the algorithm information for a
particular cipher which are a core part of the SL/TLS
protocol. The available ciphers are configured on a
SLCTX basis and the actually used ones are then part
of the SLSESION.
SLCTX (SL Context)
That's the global context structure which is created by
a server or client once per program life-time and which
holds mainly default values for the SL structures which
are later created for the connections.
OpenSL-0.9.8 Last change: Oct 11 2005 1
OpenSL ssl(3openssl)
SLSESION (SL Session)
This is a structure containing the current TLS/SL
session details for a connection: SLCIPHERs, client
and server certificates, keys, etc.
SL (SL Connection)
That's the main SL/TLS structure which is created by a
server or client per established connection. This
actually is the core structure in the SL API. Under
run-time the application usually deals with this
structure which has links to mostly all other
structures.
HEADER FILES
Currently the OpenSL ssl library provides the following C
header files containing the prototypes for the data
structures and and functions:
ssl.h
That's the common header file for the SL/TLS API.
Include it into your program to make the API of the ssl
library available. It internally includes both more
private SL headers and headers from the crypto library.
Whenever you need hard-core details on the internals of
the SL API, look inside this header file.
ssl2.h
That's the sub header file dealing with the SLv2
protocol only. Usually you don't have to include it
explicitly because it's already included by ssl.h.
ssl3.h
That's the sub header file dealing with the SLv3
protocol only. Usually you don't have to include it
explicitly because it's already included by ssl.h.
ssl23.h
That's the sub header file dealing with the combined use
of the SLv2 and SLv3 protocols. Usually you don't
have to include it explicitly because it's already
included by ssl.h.
tls1.h
That's the sub header file dealing with the TLSv1
protocol only. Usually you don't have to include it
explicitly because it's already included by ssl.h.
API FUNCTIONS
Currently the OpenSL ssl library exports 214 API functions.
They are documented in the following:
OpenSL-0.9.8 Last change: Oct 11 2005 2
OpenSL ssl(3openssl)
DEALING WITH PROTOCOL METHODS
Here we document the various API functions which deal with
the SL/TLS protocol methods defined in SLMETHOD
structures.
SLMETHOD *SLv2clientmethod(void);
Constructor for the SLv2 SLMETHOD structure for a
dedicated client.
SLMETHOD *SLv2servermethod(void);
Constructor for the SLv2 SLMETHOD structure for a
dedicated server.
SLMETHOD *SLv2method(void);
Constructor for the SLv2 SLMETHOD structure for
combined client and server.
SLMETHOD *SLv3clientmethod(void);
Constructor for the SLv3 SLMETHOD structure for a
dedicated client.
SLMETHOD *SLv3servermethod(void);
Constructor for the SLv3 SLMETHOD structure for a
dedicated server.
SLMETHOD *SLv3method(void);
Constructor for the SLv3 SLMETHOD structure for
combined client and server.
SLMETHOD *TLSv1clientmethod(void);
Constructor for the TLSv1 SLMETHOD structure for a
dedicated client.
SLMETHOD *TLSv1servermethod(void);
Constructor for the TLSv1 SLMETHOD structure for a
dedicated server.
SLMETHOD *TLSv1method(void);
Constructor for the TLSv1 SLMETHOD structure for
combined client and server.
DEALING WITH CIPHERS
Here we document the various API functions which deal with
the SL/TLS ciphers defined in SLCIPHER structures.
len);
char *SLCIPHERdescription(SLCIPHER *cipher, char *buf, int
Write a string to buf (with a maximum size of len)
containing a human readable description of cipher.
Returns buf.
OpenSL-0.9.8 Last change: Oct 11 2005 3
OpenSL ssl(3openssl)
int SLCIPHERgetbits(SLCIPHER *cipher, int *algbits);
Determine the number of bits in cipher. Because of
export crippled ciphers there are two bits: The bits the
algorithm supports in general (stored to algbits) and
the bits which are actually used (the return value).
const char *SLCIPHERgetname(SLCIPHER *cipher);
Return the internal name of cipher as a string. These
are the various strings defined by the SL2TXTxxx,
SL3TXTxxx and TLS1TXTxxx definitions in the header
files.
char *SLCIPHERgetversion(SLCIPHER *cipher);
Returns a string like "TLSv1/SLv3" or "SLv2" which
indicates the SL/TLS protocol version to which cipher
belongs (i.e. where it was defined in the specification
the first time).
DEALING WITH PROTOCOL CONTEXTS
Here we document the various API functions which deal with
the SL/TLS protocol context defined in the SLCTX
structure.
int SLCTXaddclientCA(SLCTX *ctx, X509 *x);
long SLCTXaddextrachaincert(SLCTX *ctx, X509 *x509);
int SLCTXaddsession(SLCTX *ctx, SLSESION *c);
int SLCTXcheckprivatekey(const SLCTX *ctx);
long SLCTXctrl(SLCTX *ctx, int cmd, long larg, char *parg);
void SLCTXflushsessions(SLCTX *s, long t);
void SLCTXfree(SLCTX *a);
char *SLCTXgetappdata(SLCTX *ctx);
X509STORE *SLCTXgetcertstore(SLCTX *ctx);
STACK *SLCTXgetclientCAlist(const SLCTX *ctx);
**x509, EVPKEY **pkey);
int (*SLCTXgetclientcertcb(SLCTX *ctx))(SL *ssl, X509
char *SLCTXgetexdata(const SLCTX *s, int idx);
(*newfunc);(void), int (*dupfunc)(void), void
(*freefunc)(void))
int SLCTXgetexnewindex(long argl, char *argp, int
int ret);
void (*SLCTXgetinfocallback(SLCTX *ctx))(SL *ssl, int cb,
int SLCTXgetquietshutdown(const SLCTX *ctx);
int SLCTXgetsessioncachemode(SLCTX *ctx);
long SLCTXgettimeout(const SLCTX *ctx);
X509STORECTX *ctx);
int (*SLCTXgetverifycallback(const SLCTX *ctx))(int ok,
int SLCTXgetverifymode(SLCTX *ctx);
char *CApath);
int SLCTXloadverifylocations(SLCTX *ctx, char *CAfile,
long SLCTXneedtmpRSA(SLCTX *ctx);
SLCTX *SLCTXnew(SLMETHOD *meth);
OpenSL-0.9.8 Last change: Oct 11 2005 4
OpenSL ssl(3openssl)
int SLCTXremovesession(SLCTX *ctx, SLSESION *c);
int SLCTXsessaccept(SLCTX *ctx);
int SLCTXsessacceptgood(SLCTX *ctx);
int SLCTXsessacceptrenegotiate(SLCTX *ctx);
int SLCTXsesscachefull(SLCTX *ctx);
int SLCTXsesscbhits(SLCTX *ctx);
int SLCTXsessconnect(SLCTX *ctx);
int SLCTXsessconnectgood(SLCTX *ctx);
int SLCTXsessconnectrenegotiate(SLCTX *ctx);
int SLCTXsessgetcachesize(SLCTX *ctx);
unsigned char *data, int len, int *copy);
SLSESION *(*SLCTXsessgetgetcb(SLCTX *ctx))(SL *ssl,
*sess);
int (*SLCTXsessgetnewcb(SLCTX *ctx)(SL *ssl, SLSESION
SLSESION *sess);
void (*SLCTXsessgetremovecb(SLCTX *ctx)(SLCTX *ctx,
int SLCTXsesshits(SLCTX *ctx);
int SLCTXsessmisses(SLCTX *ctx);
int SLCTXsessnumber(SLCTX *ctx);
void SLCTXsesssetcachesize(SLCTX *ctx,t);
*ssl, unsigned char *data, int len, int *copy));
void SLCTXsesssetgetcb(SLCTX *ctx, SLSESION *(*cb)(SL
SLSESION *sess));
void SLCTXsesssetnewcb(SLCTX *ctx, int (*cb)(SL *ssl,
*ctx, SLSESION *sess));
void SLCTXsesssetremovecb(SLCTX *ctx, void (*cb)(SLCTX
int SLCTXsesstimeouts(SLCTX *ctx);
LHASH *SLCTXsessions(SLCTX *ctx);
void SLCTXsetappdata(SLCTX *ctx, void *arg);
void SLCTXsetcertstore(SLCTX *ctx, X509STORE *cs);
*arg)
void SLCTXsetcertverifycb(SLCTX *ctx, int (*cb)(), char
int SLCTXsetcipherlist(SLCTX *ctx, char *str);
void SLCTXsetclientCAlist(SLCTX *ctx, STACK *list);
X509 **x509, EVPKEY **pkey));
void SLCTXsetclientcertcb(SLCTX *ctx, int (*cb)(SL *ssl,
(*cb);(void))
void SLCTXsetdefaultpasswdcb(SLCTX *ctx, int
void SLCTXsetdefaultreadahead(SLCTX *ctx, int m);
int SLCTXsetdefaultverifypaths(SLCTX *ctx);
int SLCTXsetexdata(SLCTX *s, int idx, char *arg);
int cb, int ret));
void SLCTXsetinfocallback(SLCTX *ctx, void (*cb)(SL *ssl,
writep, int version, int contenttype, const void *buf, sizet
len, SL *ssl, void *arg));
void SLCTXsetmsgcallback(SLCTX *ctx, void (*cb)(int
void SLCTXsetmsgcallbackarg(SLCTX *ctx, void *arg);
void SLCTXsetoptions(SLCTX *ctx, unsigned long op);
void SLCTXsetquietshutdown(SLCTX *ctx, int mode);
void SLCTXsetsessioncachemode(SLCTX *ctx, int mode);
int SLCTXsetsslversion(SLCTX *ctx, SLMETHOD *meth);
void SLCTXsettimeout(SLCTX *ctx, long t);
OpenSL-0.9.8 Last change: Oct 11 2005 5
OpenSL ssl(3openssl)
long SLCTXsettmpdh(SLCTX* ctx, DH *dh);
long SLCTXsettmpdhcallback(SLCTX *ctx, DH *(*cb)(void));
long SLCTXsettmprsa(SLCTX *ctx, RSA *rsa);
SLCTXsettmprsacallback
long SLCTXsettmprsacallback(SLCTX *ctx, RSA
*(*cb)(SL *ssl, int export, int keylength));
Sets the callback which will be called when a temporary
private key is required. The export flag will be set if
the reason for needing a temp key is that an export
ciphersuite is in use, in which case, keylength will
contain the required keylength in bits. Generate a key
of appropriate size (using ???) and return it.
SLsettmprsacallback
long SLsettmprsacallback(SL *ssl, RSA *(*cb)(SL
*ssl, int export, int keylength));
The same as SLCTXsettmprsacallback, except it
operates on an SL session instead of a context.
void SLCTXsetverify(SLCTX *ctx, int mode, int (*cb);(void))
int SLCTXusePrivateKey(SLCTX *ctx, EVPKEY *pkey);
char *d, long len);
int SLCTXusePrivateKeyASN1(int type, SLCTX *ctx, unsigned
type);
int SLCTXusePrivateKeyfile(SLCTX *ctx, char *file, int
int SLCTXuseRSAPrivateKey(SLCTX *ctx, RSA *rsa);
*d, long len);
int SLCTXuseRSAPrivateKeyASN1(SLCTX *ctx, unsigned char
type);
int SLCTXuseRSAPrivateKeyfile(SLCTX *ctx, char *file, int
int SLCTXusecertificate(SLCTX *ctx, X509 *x);
char *d);
int SLCTXusecertificateASN1(SLCTX *ctx, int len, unsigned
type);
int SLCTXusecertificatefile(SLCTX *ctx, char *file, int
DEALING WITH SESIONS
Here we document the various API functions which deal with
the SL/TLS sessions defined in the SLSESION structures.
int SLSESIONcmp(const SLSESION *a, const SLSESION *b);
void SLSESIONfree(SLSESION *ss);
char *SLSESIONgetappdata(SLSESION *s);
char *SLSESIONgetexdata(const SLSESION *s, int idx);
(*newfunc);(void), int (*dupfunc)(void), void
(*freefunc)(void))
int SLSESIONgetexnewindex(long argl, char *argp, int
long SLSESIONgettime(const SLSESION *s);
long SLSESIONgettimeout(const SLSESION *s);
OpenSL-0.9.8 Last change: Oct 11 2005 6
OpenSL ssl(3openssl)
unsigned long SLSESIONhash(const SLSESION *a);
SLSESION *SLSESIONnew(void);
int SLSESIONprint(BIO *bp, const SLSESION *x);
int SLSESIONprintfp(FILE *fp, const SLSESION *x);
void SLSESIONsetappdata(SLSESION *s, char *a);
int SLSESIONsetexdata(SLSESION *s, int idx, char *arg);
long SLSESIONsettime(SLSESION *s, long t);
long SLSESIONsettimeout(SLSESION *s, long t);
DEALING WITH CONECTIONS
Here we document the various API functions which deal with
the SL/TLS connection defined in the SL structure.
int SLaccept(SL *ssl);
*dir);
int SLadddircertsubjectstostack(STACK *stack, const char
*file);
int SLaddfilecertsubjectstostack(STACK *stack, const char
int SLaddclientCA(SL *ssl, X509 *x);
char *SLalertdescstring(int value);
char *SLalertdescstringlong(int value);
char *SLalerttypestring(int value);
char *SLalerttypestringlong(int value);
int SLcheckprivatekey(const SL *ssl);
void SLclear(SL *ssl);
long SLclearnumrenegotiations(SL *ssl);
int SLconnect(SL *ssl);
void SLcopysessionid(SL *t, const SL *f);
long SLctrl(SL *ssl, int cmd, long larg, char *parg);
int SLdohandshake(SL *ssl);
SL *SLdup(SL *ssl);
STACK *SLdupCAlist(STACK *sk);
void SLfree(SL *ssl);
SLCTX *SLgetSLCTX(const SL *ssl);
char *SLgetappdata(SL *ssl);
X509 *SLgetcertificate(const SL *ssl);
const char *SLgetcipher(const SL *ssl);
int SLgetcipherbits(const SL *ssl, int *algbits);
char *SLgetcipherlist(const SL *ssl, int n);
char *SLgetciphername(const SL *ssl);
char *SLgetcipherversion(const SL *ssl);
STACK *SLgetciphers(const SL *ssl);
STACK *SLgetclientCAlist(const SL *ssl);
SLCIPHER *SLgetcurrentcipher(SL *ssl);
long SLgetdefaulttimeout(const SL *ssl);
int SLgeterror(const SL *ssl, int i);
char *SLgetexdata(const SL *ssl, int idx);
int SLgetexdataX509STORECTXidx(void);
(*newfunc);(void), int (*dupfunc)(void), void
(*freefunc)(void))
int SLgetexnewindex(long argl, char *argp, int
OpenSL-0.9.8 Last change: Oct 11 2005 7
OpenSL ssl(3openssl)
int SLgetfd(const SL *ssl);
void (*SLgetinfocallback(const SL *ssl);)()
STACK *SLgetpeercertchain(const SL *ssl);
X509 *SLgetpeercertificate(const SL *ssl);
EVPKEY *SLgetprivatekey(SL *ssl);
int SLgetquietshutdown(const SL *ssl);
BIO *SLgetrbio(const SL *ssl);
int SLgetreadahead(const SL *ssl);
SLSESION *SLgetsession(const SL *ssl);
char *SLgetsharedciphers(const SL *ssl, char *buf, int len);
int SLgetshutdown(const SL *ssl);
SLMETHOD *SLgetsslmethod(SL *ssl);
int SLgetstate(const SL *ssl);
long SLgettime(const SL *ssl);
long SLgettimeout(const SL *ssl);
*)
int (*SLgetverifycallback(const SL *ssl))(int,X509STORECTX
int SLgetverifymode(const SL *ssl);
long SLgetverifyresult(const SL *ssl);
char *SLgetversion(const SL *ssl);
BIO *SLgetwbio(const SL *ssl);
int SLinacceptinit(SL *ssl);
int SLinbefore(SL *ssl);
int SLinconnectinit(SL *ssl);
int SLininit(SL *ssl);
int SLisinitfinished(SL *ssl);
STACK *SLloadclientCAfile(char *file);
void SLloaderrorstrings(void);
SL *SLnew(SLCTX *ctx);
long SLnumrenegotiations(SL *ssl);
int SLpeek(SL *ssl, void *buf, int num);
int SLpending(const SL *ssl);
int SLread(SL *ssl, void *buf, int num);
int SLrenegotiate(SL *ssl);
char *SLrstatestring(SL *ssl);
char *SLrstatestringlong(SL *ssl);
long SLsessionreused(SL *ssl);
void SLsetacceptstate(SL *ssl);
void SLsetappdata(SL *ssl, char *arg);
void SLsetbio(SL *ssl, BIO *rbio, BIO *wbio);
int SLsetcipherlist(SL *ssl, char *str);
void SLsetclientCAlist(SL *ssl, STACK *list);
void SLsetconnectstate(SL *ssl);
int SLsetexdata(SL *ssl, int idx, char *arg);
int SLsetfd(SL *ssl, int fd);
void SLsetinfocallback(SL *ssl, void (*cb);(void))
version, int contenttype, const void *buf, sizet len, SL *ssl,
void *arg));
void SLsetmsgcallback(SL *ctx, void (*cb)(int writep, int
void SLsetmsgcallbackarg(SL *ctx, void *arg);
void SLsetoptions(SL *ssl, unsigned long op);
void SLsetquietshutdown(SL *ssl, int mode);
OpenSL-0.9.8 Last change: Oct 11 2005 8
OpenSL ssl(3openssl)
void SLsetreadahead(SL *ssl, int yes);
int SLsetrfd(SL *ssl, int fd);
int SLsetsession(SL *ssl, SLSESION *session);
void SLsetshutdown(SL *ssl, int mode);
int SLsetsslmethod(SL *ssl, SLMETHOD *meth);
void SLsettime(SL *ssl, long t);
void SLsettimeout(SL *ssl, long t);
void SLsetverify(SL *ssl, int mode, int (*callback);(void))
void SLsetverifyresult(SL *ssl, long arg);
int SLsetwfd(SL *ssl, int fd);
int SLshutdown(SL *ssl);
int SLstate(const SL *ssl);
char *SLstatestring(const SL *ssl);
char *SLstatestringlong(const SL *ssl);
long SLtotalrenegotiations(SL *ssl);
int SLusePrivateKey(SL *ssl, EVPKEY *pkey);
long len);
int SLusePrivateKeyASN1(int type, SL *ssl, unsigned char *d,
int SLusePrivateKeyfile(SL *ssl, char *file, int type);
int SLuseRSAPrivateKey(SL *ssl, RSA *rsa);
len);
int SLuseRSAPrivateKeyASN1(SL *ssl, unsigned char *d, long
int SLuseRSAPrivateKeyfile(SL *ssl, char *file, int type);
int SLusecertificate(SL *ssl, X509 *x);
*d);
int SLusecertificateASN1(SL *ssl, int len, unsigned char
int SLusecertificatefile(SL *ssl, char *file, int type);
int SLversion(const SL *ssl);
int SLwant(const SL *ssl);
int SLwantnothing(const SL *ssl);
int SLwantread(const SL *ssl);
int SLwantwrite(const SL *ssl);
int SLwantx509lookup(const SL *ssl);
int SLwrite(SL *ssl, const void *buf, int num);
SEE ALSO
openssl(1), crypto(3), SLaccept(3), SLclear(3),
SLconnect(3), SLCIPHERgetname(3),
SLCOMPaddcompressionmethod(3),
SLCTXaddextrachaincert(3), SLCTXaddsession(3),
SLCTXctrl(3), SLCTXflushsessions(3),
SLCTXgetexnewindex(3), SLCTXgetverifymode(3),
SLCTXloadverifylocations(3) SLCTXnew(3),
SLCTXsessnumber(3), SLCTXsesssetcachesize(3),
SLCTXsesssetgetcb(3), SLCTXsessions(3),
SLCTXsetcertstore(3),
SLCTXsetcertverifycallback(3),
SLCTXsetcipherlist(3), SLCTXsetclientCAlist(3),
SLCTXsetclientcertcb(3),
SLCTXsetdefaultpasswdcb(3),
SLCTXsetgeneratesessionid(3),
SLCTXsetinfocallback(3), SLCTXsetmaxcertlist(3),
OpenSL-0.9.8 Last change: Oct 11 2005 9
OpenSL ssl(3openssl)
SLCTXsetmode(3), SLCTXsetmsgcallback(3),
SLCTXsetoptions(3), SLCTXsetquietshutdown(3),
SLCTXsetsessioncachemode(3),
SLCTXsetsessionidcontext(3),
SLCTXsetsslversion(3), SLCTXsettimeout(3),
SLCTXsettmprsacallback(3),
SLCTXsettmpdhcallback(3), SLCTXsetverify(3),
SLCTXusecertificate(3), SLalerttypestring(3),
SLdohandshake(3), SLgetSLCTX(3), SLgetciphers(3),
SLgetclientCAlist(3), SLgetdefaulttimeout(3),
SLgeterror(3), SLgetexdataX509STORECTXidx(3),
SLgetexnewindex(3), SLgetfd(3),
SLgetpeercertchain(3), SLgetrbio(3),
SLgetsession(3), SLgetverifyresult(3),
SLgetversion(3), SLlibraryinit(3),
SLloadclientCAfile(3), SLnew(3), SLpending(3),
SLread(3), SLrstatestring(3), SLsessionreused(3),
SLsetbio(3), SLsetconnectstate(3), SLsetfd(3),
SLsetsession(3), SLsetshutdown(3), SLshutdown(3),
SLstatestring(3), SLwant(3), SLwrite(3),
SLSESIONfree(3), SLSESIONgetexnewindex(3),
SLSESIONgettime(3), d2iSLSESION(3)
HISTORY
The ssl(3) document appeared in OpenSL 0.9.2
OpenSL-0.9.8 Last change: Oct 11 2005 10
|
