callback
advertisement
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); 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. -------------------------The X509 library. int X509_cert_verify(CERTIFICATE_CTX *ctx,X509 *xs, int (*cb)(), int *error,char *arg); int verify_callback(int ok,X509 *xs,X509 *xi,int depth,int error,char *arg); 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'. 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.
