doc/callback.doc

Callback functions used in SSLeay.

--------------------------
The BIO library.  

Each BIO structure can have a callback defined against it.  This callback is
called 2 times for each BIO 'function'.  It is passed 6 parameters.
BIO_debug_callback() is an example callback which is defined in
crypto/buffer/bio_cb.c and is used in apps/dgst.c  This is intended mostly
for debuging or to notify the application of IO.

long BIO_debug_callback(BIO *bio,int cmd,char *argp,int argi,long argl,
	long ret);
bio is the BIO being called, cmd is the type of BIO function being called.
Look at the BIO_CB_* defines in buffer.h.  Argp and argi are the arguments
passed to BIO_read(), BIO_write, BIO_gets(), BIO_puts().  In the case of
BIO_ctrl(), argl is also defined.  The first time the callback is called,
before the underlying function has been executed, 0 is passed as 'ret', and
if the return code from the callback is not > 0, the call is aborted
and the returned <= 0 value is returned.
The second time the callback is called, the 'cmd' value also has
BIO_CB_RETURN logically 'or'ed with it.  The 'ret' value is the value returned
from the actuall function call and whatever the callback returns is returned
from the BIO function.

BIO_set_callback(b,cb) can be used to set the callback function
(b is a BIO), and BIO_set_callback_arg(b,arg) can be used to
set the cb_arg argument in the BIO strucutre.  This field is only intended
to be used by application, primarily in the callback function since it is
accessable since the BIO is passed.

--------------------------
The PEM library.

The pem library only really uses one type of callback,
static int def_callback(char *buf, int num, int verify);
which is used to return a password string if required.
'buf' is the buffer to put the string in.  'num' is the size of 'buf'
and 'verify' is used to indicate that the password should be checked.
This last flag is mostly used when reading a password for encryption.

For all of these functions, a NULL callback will call the above mentioned
default callback.  This default function does not work under Windows 3.1.
For other machines, it will use an application defined prompt string
(EVP_set_pw_prompt(), which defines a library wide prompt string)
if defined, otherwise it will use it's own PEM password prompt.
It will then call EVP_read_pw_string() to get a password from the console.
If your application wishes to use nice fancy windows to retrieve passwords,
replace this function.  The callback should return the number of bytes read
into 'buf'.  If the number of bytes <= 0, it is considered an error.

Functions that take this callback are listed below.  For the 'read' type
functions, the callback will only be required if the PEM data is encrypted.

For the Write functions, normally a password can be passed in 'kstr', of
'klen' bytes which will be used if the 'enc' cipher is not NULL.  If
'kstr' is NULL, the callback will be used to retrieve a password.

int PEM_do_header (EVP_CIPHER_INFO *cipher, unsigned char *data,long *len,
	int (*callback)());
char *PEM_ASN1_read_bio(char *(*d2i)(),char *name,BIO *bp,char **x,int (*cb)());
char *PEM_ASN1_read(char *(*d2i)(),char *name,FILE *fp,char **x,int (*cb)());
int PEM_ASN1_write_bio(int (*i2d)(),char *name,BIO *bp,char *x,
	EVP_CIPHER *enc,unsigned char *kstr,int klen,int (*callback)());
int PEM_ASN1_write(int (*i2d)(),char *name,FILE *fp,char *x,
	EVP_CIPHER *enc,unsigned char *kstr,int klen,int (*callback)());
STACK *PEM_X509_INFO_read(FILE *fp, STACK *sk, int (*cb)());
STACK *PEM_X509_INFO_read_bio(BIO *fp, STACK *sk, int (*cb)());

#define	PEM_write_RSAPrivateKey(fp,x,enc,kstr,klen,cb)
#define	PEM_write_DSAPrivateKey(fp,x,enc,kstr,klen,cb)
#define	PEM_write_bio_RSAPrivateKey(bp,x,enc,kstr,klen,cb)
#define	PEM_write_bio_DSAPrivateKey(bp,x,enc,kstr,klen,cb)
#define	PEM_read_SSL_SESSION(fp,x,cb)
#define	PEM_read_X509(fp,x,cb)
#define	PEM_read_X509_REQ(fp,x,cb)
#define	PEM_read_X509_CRL(fp,x,cb)
#define	PEM_read_RSAPrivateKey(fp,x,cb)
#define	PEM_read_DSAPrivateKey(fp,x,cb)
#define	PEM_read_PrivateKey(fp,x,cb)
#define	PEM_read_PKCS7(fp,x,cb)
#define	PEM_read_DHparams(fp,x,cb)
#define	PEM_read_bio_SSL_SESSION(bp,x,cb)
#define	PEM_read_bio_X509(bp,x,cb)
#define	PEM_read_bio_X509_REQ(bp,x,cb)
#define	PEM_read_bio_X509_CRL(bp,x,cb)
#define	PEM_read_bio_RSAPrivateKey(bp,x,cb)
#define	PEM_read_bio_DSAPrivateKey(bp,x,cb)
#define	PEM_read_bio_PrivateKey(bp,x,cb)
#define	PEM_read_bio_PKCS7(bp,x,cb)
#define	PEM_read_bio_DHparams(bp,x,cb)
int i2d_Netscape_RSA(RSA *a, unsigned char **pp, int (*cb)());
RSA *d2i_Netscape_RSA(RSA **a, unsigned char **pp, long length, int (*cb)());

Now you will notice that macros like
#define PEM_write_X509(fp,x) \
                PEM_ASN1_write((int (*)())i2d_X509,PEM_STRING_X509,fp, \
		                        (char *)x, NULL,NULL,0,NULL)
Don't do encryption normally.  If you want to PEM encrypt your X509 structure,
either just call PEM_ASN1_write directly or just define you own
macro variant.  As you can see, this macro just sets all encryption related
parameters to NULL.


--------------------------
The SSL library.

#define SSL_set_info_callback(ssl,cb)
#define SSL_CTX_set_info_callback(ctx,cb)
void callback(SSL *ssl,int location,int ret)
This callback is called each time around the SSL_connect()/SSL_accept() 
state machine.  So it will be called each time the SSL protocol progresses.
It is mostly present for use when debugging.  When SSL_connect() or
SSL_accept() return, the location flag is SSL_CB_ACCEPT_EXIT or
SSL_CB_CONNECT_EXIT and 'ret' is the value about to be returned.
Have a look at the SSL_CB_* defines in ssl.h.  If an info callback is defined
against the SSL_CTX, it is called unless there is one set against the SSL.
Have a look at
void client_info_callback() in apps/s_client() for an example.

Certificate verification.
void SSL_set_verify(SSL *s, int mode, int (*callback) ());
void SSL_CTX_set_verify(SSL_CTX *ctx,int mode,int (*callback)());
This callback is used to help verify client and server X509 certificates.
It is actually passed to X509_cert_verify(), along with the SSL structure
so you have to read about X509_cert_verify() :-).  The SSL_CTX version is used
if the SSL version is not defined.  X509_cert_verify() is the function used
by the SSL part of the library to verify certificates.  This function is
nearly always defined by the application.

void SSL_CTX_set_cert_verify_cb(SSL_CTX *ctx, int (*cb)(),char *arg);
int callback(char *arg,SSL *s,X509 *xs,STACK *cert_chain);
This call is used to replace the SSLeay certificate verification code.
The 'arg' is kept in the SSL_CTX and is passed to the callback.
If the callback returns 0, the certificate is rejected, otherwise it
is accepted.  The callback is replacing the X509_cert_verify() call.
This feature is not often used, but if you wished to implement
some totally different certificate authentication system, this 'hook' is
vital.

SSLeay keeps a cache of session-ids against each SSL_CTX.  These callbacks can
be used to notify the application when a SSL_SESSION is added to the cache
or to retrieve a SSL_SESSION that is not in the cache from the application.
#define SSL_CTX_sess_set_get_cb(ctx,cb)
SSL_SESSION *callback(SSL *s,char *session_id,int session_id_len,int *copy);
If defined, this callback is called to return the SESSION_ID for the
session-id in 'session_id', of 'session_id_len' bytes.  'copy' is set to 1
if the server is to 'take a copy' of the SSL_SESSION structure.  It is 0
if the SSL_SESSION is being 'passed in' so the SSLeay library is now
responsible for 'free()ing' the structure.  Basically it is used to indicate
if the reference count on the SSL_SESSION structure needs to be incremented.

#define SSL_CTX_sess_set_new_cb(ctx,cb)
int callback(SSL *s, SSL_SESSION *sess);
When a new connection is established, if the SSL_SESSION is going to be added
to the cache, this callback is called.  Return 1 if a 'copy' is required,
otherwise, return 0.  This return value just causes the reference count
to be incremented (on return of a 1), this means the application does
not need to worry about incrementing the refernece count (and the
locking that implies in a multi-threaded application).

void SSL_CTX_set_default_passwd_cb(SSL_CTX *ctx,int (*cb)());
This sets the SSL password reading function.
It is mostly used for windowing applications
and used by PEM_read_bio_X509() and PEM_read_bio_RSAPrivateKey()
calls inside the SSL library.   The only reason this is present is because the
calls to PEM_* functions is hidden in the SSLeay library so you have to
pass in the callback some how.

#define SSL_CTX_set_client_cert_cb(ctx,cb)
int callback(SSL *s,X509 **x509, EVP_PKEY **pkey);
Called when a client certificate is requested but there is not one set
against the SSL_CTX or the SSL.  If the callback returns 1, x509 and
pkey need to point to valid data.  The library will free these when
required so if the application wants to keep these around, increment
their reference counts.  If 0 is returned, no client cert is
available.  If -1 is returned, it is assumed that the callback needs
to be called again at a later point in time.  SSL_connect will return
-1 and SSL_want_x509_lookup(ssl) returns true.  Remember that
application data can be attached to an SSL structure via the
SSL_set_app_data(SSL *ssl,char *data) call.

--------------------------
The X509 library.

int X509_cert_verify(CERTIFICATE_CTX *ctx,X509 *xs, int (*cb)(),
	int *error,char *arg,STACK *cert_chain);
int verify_callback(int ok,X509 *xs,X509 *xi,int depth,int error,char *arg,
	STACK *cert_chain);

X509_cert_verify() is used to authenticate X509 certificates.  The 'ctx' holds
the details of the various caches and files used to locate certificates.
'xs' is the certificate to verify and 'cb' is the application callback (more
detail later).  'error' will be set to the error code and 'arg' is passed
to the 'cb' callback.  Look at the VERIFY_* defines in crypto/x509/x509.h

When ever X509_cert_verify() makes a 'negative' decision about a
certitificate, the callback is called.  If everything checks out, the
callback is called with 'VERIFY_OK' or 'VERIFY_ROOT_OK' (for a self
signed cert that is not the passed certificate).

The callback is passed the X509_cert_verify opinion of the certificate 
in 'ok', the certificate in 'xs', the issuer certificate in 'xi',
the 'depth' of the certificate in the verification 'chain', the
VERIFY_* code in 'error' and the argument passed to X509_cert_verify()
in 'arg'. cert_chain is a list of extra certs to use if they are not
in the cache.

The callback can be used to look at the error reason, and then return 0
for an 'error' or '1' for ok.  This will override the X509_cert_verify()
opinion of the certificates validity.  Processing will continue depending on
the return value.  If one just wishes to use the callback for informational
reason, just return the 'ok' parameter.

--------------------------
The BN and DH library.

BIGNUM *BN_generate_prime(int bits,int strong,BIGNUM *add,
	BIGNUM *rem,void (*callback)(int,int));
int BN_is_prime(BIGNUM *p,int nchecks,void (*callback)(int,int),

Read doc/bn.doc for the description of these 2.

DH *DH_generate_parameters(int prime_len,int generator,
	void (*callback)(int,int));
Read doc/bn.doc for the description of the callback, since it is just passed
to BN_generate_prime(), except that it is also called as
callback(3,0) by this function.

--------------------------
The CRYPTO library.

void CRYPTO_set_locking_callback(void (*func)(int mode,int type,char *file,
	int line));
void CRYPTO_set_add_lock_callback(int (*func)(int *num,int mount,
	int type,char *file, int line));
void CRYPTO_set_id_callback(unsigned long (*func)(void));

Read threads.doc for info on these ones.