diff options
Diffstat (limited to 'doc/callback.doc')
| -rw-r--r-- | doc/callback.doc | 240 |
1 files changed, 240 insertions, 0 deletions
diff --git a/doc/callback.doc b/doc/callback.doc new file mode 100644 index 0000000000..7ad0f7f7d2 --- /dev/null +++ b/doc/callback.doc @@ -0,0 +1,240 @@ +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. + |