ssl(3) OpenSL ssl(3)
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 SLcon-
nect(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 con-
nections.
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 struc-
ture 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:
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.
char *SLCIPHERdescription(SLCIPHER *cipher, char *buf, int len);
Write a string to buf (with a maximum size of len) containing a
human readable description of cipher. Returns buf.
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 gen-
eral (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 vari-
ous 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);
int (*SLCTXgetclientcertcb(SLCTX *ctx))(SL *ssl, X509 **x509,
EVPKEY **pkey);
char *SLCTXgetexdata(const SLCTX *s, int idx);
int SLCTXgetexnewindex(long argl, char *argp, int
(*newfunc);(void), int (*dupfunc)(void), void (*freefunc)(void))
void (*SLCTXgetinfocallback(SLCTX *ctx))(SL *ssl, int cb, int
ret);
int SLCTXgetquietshutdown(const SLCTX *ctx);
int SLCTXgetsessioncachemode(SLCTX *ctx);
long SLCTXgettimeout(const SLCTX *ctx);
int (*SLCTXgetverifycallback(const SLCTX *ctx))(int ok,
X509STORECTX *ctx);
int SLCTXgetverifymode(SLCTX *ctx);
int SLCTXloadverifylocations(SLCTX *ctx, char *CAfile, char
*CApath);
long SLCTXneedtmpRSA(SLCTX *ctx);
SLCTX *SLCTXnew(SLMETHOD *meth);
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);
SLSESION *(*SLCTXsessgetgetcb(SLCTX *ctx))(SL *ssl,
unsigned char *data, int len, int *copy);
int (*SLCTXsessgetnewcb(SLCTX *ctx)(SL *ssl, SLSESION
*sess);
void (*SLCTXsessgetremovecb(SLCTX *ctx)(SLCTX *ctx, SLSES-
SION *sess);
int SLCTXsesshits(SLCTX *ctx);
int SLCTXsessmisses(SLCTX *ctx);
int SLCTXsessnumber(SLCTX *ctx);
void SLCTXsesssetcachesize(SLCTX *ctx,t);
void SLCTXsesssetgetcb(SLCTX *ctx, SLSESION *(*cb)(SL *ssl,
unsigned char *data, int len, int *copy));
void SLCTXsesssetnewcb(SLCTX *ctx, int (*cb)(SL *ssl, SLSES-
SION *sess));
void SLCTXsesssetremovecb(SLCTX *ctx, void (*cb)(SLCTX *ctx,
SLSESION *sess));
int SLCTXsesstimeouts(SLCTX *ctx);
LHASH *SLCTXsessions(SLCTX *ctx);
void SLCTXsetappdata(SLCTX *ctx, void *arg);
void SLCTXsetcertstore(SLCTX *ctx, X509STORE *cs);
void SLCTXsetcertverifycb(SLCTX *ctx, int (*cb)(), char *arg)
int SLCTXsetcipherlist(SLCTX *ctx, char *str);
void SLCTXsetclientCAlist(SLCTX *ctx, STACK *list);
void SLCTXsetclientcertcb(SLCTX *ctx, int (*cb)(SL *ssl, X509
**x509, EVPKEY **pkey));
void SLCTXsetdefaultpasswdcb(SLCTX *ctx, int (*cb);(void))
void SLCTXsetdefaultreadahead(SLCTX *ctx, int m);
int SLCTXsetdefaultverifypaths(SLCTX *ctx);
int SLCTXsetexdata(SLCTX *s, int idx, char *arg);
void SLCTXsetinfocallback(SLCTX *ctx, void (*cb)(SL *ssl, int
cb, int ret));
void SLCTXsetmsgcallback(SLCTX *ctx, void (*cb)(int writep, int
version, int contenttype, const void *buf, sizet len, SL *ssl, void
*arg));
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);
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 need-
ing a temp key is that an export ciphersuite is in use, in which
case, ""keylength"" will contain the required keylength in bits. Gen-
erate 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);
int SLCTXusePrivateKeyASN1(int type, SLCTX *ctx, unsigned char
*d, long len);
int SLCTXusePrivateKeyfile(SLCTX *ctx, char *file, int type);
int SLCTXuseRSAPrivateKey(SLCTX *ctx, RSA *rsa);
int SLCTXuseRSAPrivateKeyASN1(SLCTX *ctx, unsigned char *d, long
len);
int SLCTXuseRSAPrivateKeyfile(SLCTX *ctx, char *file, int type);
int SLCTXusecertificate(SLCTX *ctx, X509 *x);
int SLCTXusecertificateASN1(SLCTX *ctx, int len, unsigned char
*d);
int SLCTXusecertificatefile(SLCTX *ctx, char *file, int type);
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);
int SLSESIONgetexnewindex(long argl, char *argp, int
(*newfunc);(void), int (*dupfunc)(void), void (*freefunc)(void))
long SLSESIONgettime(const SLSESION *s);
long SLSESIONgettimeout(const SLSESION *s);
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);
int SLadddircertsubjectstostack(STACK *stack, const char *dir);
int SLaddfilecertsubjectstostack(STACK *stack, const char
*file);
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 SLgetexdataX5009STORECTXidx(void);
int SLgetexnewindex(long argl, char *argp, int (*newfunc);(void),
int (*dupfunc)(void), void (*freefunc)(void))
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))
void SLsetmsgcallback(SL *ctx, void (*cb)(int writep, int ver-
sion, int contenttype, const void *buf, sizet len, SL *ssl, void
*arg));
void SLsetmsgcallbackarg(SL *ctx, void *arg);
void SLsetoptions(SL *ssl, unsigned long op);
void SLsetquietshutdown(SL *ssl, int mode);
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);
int SLusePrivateKeyASN1(int type, SL *ssl, unsigned char *d, long
len);
int SLusePrivateKeyfile(SL *ssl, char *file, int type);
int SLuseRSAPrivateKey(SL *ssl, RSA *rsa);
int SLuseRSAPrivateKeyASN1(SL *ssl, unsigned char *d, long len);
int SLuseRSAPrivateKeyfile(SL *ssl, char *file, int type);
int SLusecertificate(SL *ssl, X509 *x);
int SLusecertificateASN1(SL *ssl, int len, unsigned char *d);
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 SLwantx5009lookup(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), SLCTXsessnum-
ber(3), SLCTXsesssetcachesize(3), SLCTXsesssetgetcb(3),
SLCTXsessions(3), SLCTXsetcertstore(3), SLCTXsetcertver-
ifycallback(3), SLCTXsetcipherlist(3),
SLCTXsetclientCAlist(3), SLCTXsetclientcertcb(3),
SLCTXsetdefaultpasswdcb(3), SLCTXsetgeneratesessionid(3),
SLCTXsetinfocallback(3), SLCTXsetmaxcertlist(3),
SLCTXsetmode(3), SLCTXsetmsgcallback(3),
SLCTXsetoptions(3), SLCTXsetquietshutdown(3), SLCTXsetses-
sioncachemode(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), SLgetdefaulttime-
out(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), SLses-
sionreused(3), SLsetbio(3), SLsetconnectstate(3),
SLsetfd(3), SLsetsession(3), SLsetshutdown(3), SLshut-
down(3), SLstatestring(3), SLwant(3), SLwrite(3), SLSES-
SIONfree(3), SLSESIONgetexnewindex(3), SLSESIONgettime(3),
d2iSLSESION(3)
HISTORY
The ssl(3) document appeared in OpenSL 0.9.2
0.9.7l 2005-03-30 ssl(3)
|
