doc/callback.doc

   1 Callback functions used in SSLeay.
   2
   3 --------------------------
   4 The BIO library.
   5
   6 Each BIO structure can have a callback defined against it.  This callback is
   7 called 2 times for each BIO 'function'.  It is passed 6 parameters.
   8 BIO_debug_callback() is an example callback which is defined in
   9 crypto/buffer/bio_cb.c and is used in apps/dgst.c  This is intended mostly
  10 for debuging or to notify the application of IO.
  11
  12 long BIO_debug_callback(BIO *bio,int cmd,char *argp,int argi,long argl,
  13         long ret);
  14 bio is the BIO being called, cmd is the type of BIO function being called.
  15 Look at the BIO_CB_* defines in buffer.h.  Argp and argi are the arguments
  16 passed to BIO_read(), BIO_write, BIO_gets(), BIO_puts().  In the case of
  17 BIO_ctrl(), argl is also defined.  The first time the callback is called,
  18 before the underlying function has been executed, 0 is passed as 'ret', and
  19 if the return code from the callback is not > 0, the call is aborted
  20 and the returned <= 0 value is returned.
  21 The second time the callback is called, the 'cmd' value also has
  22 BIO_CB_RETURN logically 'or'ed with it.  The 'ret' value is the value returned
  23 from the actuall function call and whatever the callback returns is returned
  24 from the BIO function.
  25
  26 BIO_set_callback(b,cb) can be used to set the callback function
  27 (b is a BIO), and BIO_set_callback_arg(b,arg) can be used to
  28 set the cb_arg argument in the BIO strucutre.  This field is only intended
  29 to be used by application, primarily in the callback function since it is
  30 accessable since the BIO is passed.
  31
  32 --------------------------
  33 The PEM library.
  34
  35 The pem library only really uses one type of callback,
  36 static int def_callback(char *buf, int num, int verify);
  37 which is used to return a password string if required.
  38 'buf' is the buffer to put the string in.  'num' is the size of 'buf'
  39 and 'verify' is used to indicate that the password should be checked.
  40 This last flag is mostly used when reading a password for encryption.
  41
  42 For all of these functions, a NULL callback will call the above mentioned
  43 default callback.  This default function does not work under Windows 3.1.
  44 For other machines, it will use an application defined prompt string
  45 (EVP_set_pw_prompt(), which defines a library wide prompt string)
  46 if defined, otherwise it will use it's own PEM password prompt.
  47 It will then call EVP_read_pw_string() to get a password from the console.
  48 If your application wishes to use nice fancy windows to retrieve passwords,
  49 replace this function.  The callback should return the number of bytes read
  50 into 'buf'.  If the number of bytes <= 0, it is considered an error.
  51
  52 Functions that take this callback are listed below.  For the 'read' type
  53 functions, the callback will only be required if the PEM data is encrypted.
  54
  55 For the Write functions, normally a password can be passed in 'kstr', of
  56 'klen' bytes which will be used if the 'enc' cipher is not NULL.  If
  57 'kstr' is NULL, the callback will be used to retrieve a password.
  58
  59 int PEM_do_header (EVP_CIPHER_INFO *cipher, unsigned char *data,long *len,
  60         int (*callback)());
  61 char *PEM_ASN1_read_bio(char *(*d2i)(),char *name,BIO *bp,char **x,int (*cb)());
  62 char *PEM_ASN1_read(char *(*d2i)(),char *name,FILE *fp,char **x,int (*cb)());
  63 int PEM_ASN1_write_bio(int (*i2d)(),char *name,BIO *bp,char *x,
  64         EVP_CIPHER *enc,unsigned char *kstr,int klen,int (*callback)());
  65 int PEM_ASN1_write(int (*i2d)(),char *name,FILE *fp,char *x,
  66         EVP_CIPHER *enc,unsigned char *kstr,int klen,int (*callback)());
  67 STACK *PEM_X509_INFO_read(FILE *fp, STACK *sk, int (*cb)());
  68 STACK *PEM_X509_INFO_read_bio(BIO *fp, STACK *sk, int (*cb)());
  69
  70 #define PEM_write_RSAPrivateKey(fp,x,enc,kstr,klen,cb)
  71 #define PEM_write_DSAPrivateKey(fp,x,enc,kstr,klen,cb)
  72 #define PEM_write_bio_RSAPrivateKey(bp,x,enc,kstr,klen,cb)
  73 #define PEM_write_bio_DSAPrivateKey(bp,x,enc,kstr,klen,cb)
  74 #define PEM_read_SSL_SESSION(fp,x,cb)
  75 #define PEM_read_X509(fp,x,cb)
  76 #define PEM_read_X509_REQ(fp,x,cb)
  77 #define PEM_read_X509_CRL(fp,x,cb)
  78 #define PEM_read_RSAPrivateKey(fp,x,cb)
  79 #define PEM_read_DSAPrivateKey(fp,x,cb)
  80 #define PEM_read_PrivateKey(fp,x,cb)
  81 #define PEM_read_PKCS7(fp,x,cb)
  82 #define PEM_read_DHparams(fp,x,cb)
  83 #define PEM_read_bio_SSL_SESSION(bp,x,cb)
  84 #define PEM_read_bio_X509(bp,x,cb)
  85 #define PEM_read_bio_X509_REQ(bp,x,cb)
  86 #define PEM_read_bio_X509_CRL(bp,x,cb)
  87 #define PEM_read_bio_RSAPrivateKey(bp,x,cb)
  88 #define PEM_read_bio_DSAPrivateKey(bp,x,cb)
  89 #define PEM_read_bio_PrivateKey(bp,x,cb)
  90 #define PEM_read_bio_PKCS7(bp,x,cb)
  91 #define PEM_read_bio_DHparams(bp,x,cb)
  92 int i2d_Netscape_RSA(RSA *a, unsigned char **pp, int (*cb)());
  93 RSA *d2i_Netscape_RSA(RSA **a, unsigned char **pp, long length, int (*cb)());
  94
  95 Now you will notice that macros like
  96 #define PEM_write_X509(fp,x) \
  97                 PEM_ASN1_write((int (*)())i2d_X509,PEM_STRING_X509,fp, \
  98                                         (char *)x, NULL,NULL,0,NULL)
  99 Don't do encryption normally.  If you want to PEM encrypt your X509 structure,
 100 either just call PEM_ASN1_write directly or just define you own
 101 macro variant.  As you can see, this macro just sets all encryption related
 102 parameters to NULL.
 103
 104
 105 --------------------------
 106 The SSL library.
 107
 108 #define SSL_set_info_callback(ssl,cb)
 109 #define SSL_CTX_set_info_callback(ctx,cb)
 110 void callback(SSL *ssl,int location,int ret)
 111 This callback is called each time around the SSL_connect()/SSL_accept()
 112 state machine.  So it will be called each time the SSL protocol progresses.
 113 It is mostly present for use when debugging.  When SSL_connect() or
 114 SSL_accept() return, the location flag is SSL_CB_ACCEPT_EXIT or
 115 SSL_CB_CONNECT_EXIT and 'ret' is the value about to be returned.
 116 Have a look at the SSL_CB_* defines in ssl.h.  If an info callback is defined
 117 against the SSL_CTX, it is called unless there is one set against the SSL.
 118 Have a look at
 119 void client_info_callback() in apps/s_client() for an example.
 120
 121 Certificate verification.
 122 void SSL_set_verify(SSL *s, int mode, int (*callback) ());
 123 void SSL_CTX_set_verify(SSL_CTX *ctx,int mode,int (*callback)());
 124 This callback is used to help verify client and server X509 certificates.
 125 It is actually passed to X509_cert_verify(), along with the SSL structure
 126 so you have to read about X509_cert_verify() :-).  The SSL_CTX version is used
 127 if the SSL version is not defined.  X509_cert_verify() is the function used
 128 by the SSL part of the library to verify certificates.  This function is
 129 nearly always defined by the application.
 130
 131 void SSL_CTX_set_cert_verify_cb(SSL_CTX *ctx, int (*cb)(),char *arg);
 132 int callback(char *arg,SSL *s,X509 *xs,STACK *cert_chain);
 133 This call is used to replace the SSLeay certificate verification code.
 134 The 'arg' is kept in the SSL_CTX and is passed to the callback.
 135 If the callback returns 0, the certificate is rejected, otherwise it
 136 is accepted.  The callback is replacing the X509_cert_verify() call.
 137 This feature is not often used, but if you wished to implement
 138 some totally different certificate authentication system, this 'hook' is
 139 vital.
 140
 141 SSLeay keeps a cache of session-ids against each SSL_CTX.  These callbacks can
 142 be used to notify the application when a SSL_SESSION is added to the cache
 143 or to retrieve a SSL_SESSION that is not in the cache from the application.
 144 #define SSL_CTX_sess_set_get_cb(ctx,cb)
 145 SSL_SESSION *callback(SSL *s,char *session_id,int session_id_len,int *copy);
 146 If defined, this callback is called to return the SESSION_ID for the
 147 session-id in 'session_id', of 'session_id_len' bytes.  'copy' is set to 1
 148 if the server is to 'take a copy' of the SSL_SESSION structure.  It is 0
 149 if the SSL_SESSION is being 'passed in' so the SSLeay library is now
 150 responsible for 'free()ing' the structure.  Basically it is used to indicate
 151 if the reference count on the SSL_SESSION structure needs to be incremented.
 152
 153 #define SSL_CTX_sess_set_new_cb(ctx,cb)
 154 int callback(SSL *s, SSL_SESSION *sess);
 155 When a new connection is established, if the SSL_SESSION is going to be added
 156 to the cache, this callback is called.  Return 1 if a 'copy' is required,
 157 otherwise, return 0.  This return value just causes the reference count
 158 to be incremented (on return of a 1), this means the application does
 159 not need to worry about incrementing the refernece count (and the
 160 locking that implies in a multi-threaded application).
 161
 162 void SSL_CTX_set_default_passwd_cb(SSL_CTX *ctx,int (*cb)());
 163 This sets the SSL password reading function.
 164 It is mostly used for windowing applications
 165 and used by PEM_read_bio_X509() and PEM_read_bio_RSAPrivateKey()
 166 calls inside the SSL library.   The only reason this is present is because the
 167 calls to PEM_* functions is hidden in the SSLeay library so you have to
 168 pass in the callback some how.
 169
 170 #define SSL_CTX_set_client_cert_cb(ctx,cb)
 171 int callback(SSL *s,X509 **x509, EVP_PKEY **pkey);
 172 Called when a client certificate is requested but there is not one set
 173 against the SSL_CTX or the SSL.  If the callback returns 1, x509 and
 174 pkey need to point to valid data.  The library will free these when
 175 required so if the application wants to keep these around, increment
 176 their reference counts.  If 0 is returned, no client cert is
 177 available.  If -1 is returned, it is assumed that the callback needs
 178 to be called again at a later point in time.  SSL_connect will return
 179 -1 and SSL_want_x509_lookup(ssl) returns true.  Remember that
 180 application data can be attached to an SSL structure via the
 181 SSL_set_app_data(SSL *ssl,char *data) call.
 182
 183 --------------------------
 184 The X509 library.
 185
 186 int X509_cert_verify(CERTIFICATE_CTX *ctx,X509 *xs, int (*cb)(),
 187         int *error,char *arg,STACK *cert_chain);
 188 int verify_callback(int ok,X509 *xs,X509 *xi,int depth,int error,char *arg,
 189         STACK *cert_chain);
 190
 191 X509_cert_verify() is used to authenticate X509 certificates.  The 'ctx' holds
 192 the details of the various caches and files used to locate certificates.
 193 'xs' is the certificate to verify and 'cb' is the application callback (more
 194 detail later).  'error' will be set to the error code and 'arg' is passed
 195 to the 'cb' callback.  Look at the VERIFY_* defines in crypto/x509/x509.h
 196
 197 When ever X509_cert_verify() makes a 'negative' decision about a
 198 certitificate, the callback is called.  If everything checks out, the
 199 callback is called with 'VERIFY_OK' or 'VERIFY_ROOT_OK' (for a self
 200 signed cert that is not the passed certificate).
 201
 202 The callback is passed the X509_cert_verify opinion of the certificate
 203 in 'ok', the certificate in 'xs', the issuer certificate in 'xi',
 204 the 'depth' of the certificate in the verification 'chain', the
 205 VERIFY_* code in 'error' and the argument passed to X509_cert_verify()
 206 in 'arg'. cert_chain is a list of extra certs to use if they are not
 207 in the cache.
 208
 209 The callback can be used to look at the error reason, and then return 0
 210 for an 'error' or '1' for ok.  This will override the X509_cert_verify()
 211 opinion of the certificates validity.  Processing will continue depending on
 212 the return value.  If one just wishes to use the callback for informational
 213 reason, just return the 'ok' parameter.
 214
 215 --------------------------
 216 The BN and DH library.
 217
 218 BIGNUM *BN_generate_prime(int bits,int strong,BIGNUM *add,
 219         BIGNUM *rem,void (*callback)(int,int));
 220 int BN_is_prime(BIGNUM *p,int nchecks,void (*callback)(int,int),
 221
 222 Read doc/bn.doc for the description of these 2.
 223
 224 DH *DH_generate_parameters(int prime_len,int generator,
 225         void (*callback)(int,int));
 226 Read doc/bn.doc for the description of the callback, since it is just passed
 227 to BN_generate_prime(), except that it is also called as
 228 callback(3,0) by this function.
 229
 230 --------------------------
 231 The CRYPTO library.
 232
 233 void CRYPTO_set_locking_callback(void (*func)(int mode,int type,char *file,
 234         int line));
 235 void CRYPTO_set_add_lock_callback(int (*func)(int *num,int mount,
 236         int type,char *file, int line));
 237 void CRYPTO_set_id_callback(unsigned long (*func)(void));
 238
 239 Read threads.doc for info on these ones.
 240