# kio Library API Documentation

Overview | Class Hierarchy | Classes | Classes (annotated) | Members | Source Files

# kopenssl.h

    00001 /* This file is part of the KDE libraries
    00002    Copyright (C) 2001 George Staikos <staikos@kde.org>
    00003
    00004    This library is free software; you can redistribute it and/or
    00005    modify it under the terms of the GNU Library General Public
    00006    License version 2 as published by the Free Software Foundation.
    00007
    00008    This library is distributed in the hope that it will be useful,
    00009    but WITHOUT ANY WARRANTY; without even the implied warranty of
    00010    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
    00011    Library General Public License for more details.
    00012
    00013    You should have received a copy of the GNU Library General Public License
    00014    along with this library; see the file COPYING.LIB.  If not, write to
    00015    the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
    00016    Boston, MA 02111-1307, USA.
    00017 */
    00018
    00019
    00020 // IF YOU ARE USING THIS CLASS, YOU ARE MAKING A MISTAKE.
    00021
    00022 #ifndef __KOPENSSLPROXY_H
    00023 #define __KOPENSSLPROXY_H
    00024
    00025 #define KOSSL KOpenSSLProxy
    00026 class KOpenSSLProxyPrivate;
    00027
    00028 #include "ksslconfig.h"
    00029 #include <klibloader.h>
    00030
    00031 #ifdef KSSL_HAVE_SSL
    00032 #define crypt _openssl_crypt
    00033 #include <openssl/ssl.h>
    00034 #include <openssl/x509.h>
    00035 #include <openssl/x509v3.h>
    00036 #include <openssl/pem.h>
    00037 #include <openssl/bio.h>
    00038 #include <openssl/rand.h>
    00039 #include <openssl/asn1.h>
    00040 #include <openssl/pkcs7.h>
    00041 #include <openssl/pkcs12.h>
    00042 #include <openssl/evp.h>
    00043 #include <openssl/stack.h>
    00044 #include <openssl/bn.h>
    00045 #undef crypt
    00046 #endif
    00047
    00048 #include <kstaticdeleter.h>
    00049
    00050 class KOpenSSLProxy {
    00051 friend class KStaticDeleter<KOpenSSLProxy>;
    00052 public:
    00053
    00058    static KOpenSSLProxy *self();
    00059
    00063    bool hasLibCrypto() const;
    00064
    00068    bool hasLibSSL() const;
    00069
    00074    void destroy();
    00075
    00076    // Here are the symbols that we need.
    00077 #ifdef KSSL_HAVE_SSL
    00078
    00079    /*
    00080     *   SSL_connect - initiate the TLS/SSL handshake with an TLS/SSL server
    00081     */
    00082    int SSL_connect(SSL *ssl);
    00083
    00084    /*
    00085     *   SSL_accept - initiate the TLS/SSL handshake with an TLS/SSL server
    00086     */
    00087    int SSL_accept(SSL *ssl);
    00088
    00089    /*
    00090     *   SSL_get_error - get the error code
    00091     */
    00092    int SSL_get_error(SSL *ssl, int rc);
    00093
    00094    /*
    00095     *   SSL_read - read bytes from a TLS/SSL connection.
    00096     */
    00097    int SSL_read(SSL *ssl, void *buf, int num);
    00098
    00099    /*
    00100     *   SSL_write - write bytes to a TLS/SSL connection.
    00101     */
    00102    int SSL_write(SSL *ssl, const void *buf, int num);
    00103
    00104    /*
    00105     *   SSL_new - create a new SSL structure for a connection
    00106     */
    00107    SSL *SSL_new(SSL_CTX *ctx);
    00108
    00109    /*
    00110     *   SSL_free - free an allocated SSL structure
    00111     */
    00112    void SSL_free(SSL *ssl);
    00113
    00114    /*
    00115     *   SSL_shutdown - shutdown an allocated SSL connection
    00116     */
    00117    int SSL_shutdown(SSL *ssl);
    00118
    00119    /*
    00120     *   SSL_CTX_new - create a new SSL_CTX object as framework for TLS/SSL enabled functions
    00121     */
    00122    SSL_CTX *SSL_CTX_new(SSL_METHOD *method);
    00123
    00124    /*
    00125     *   SSL_CTX_free - free an allocated SSL_CTX object
    00126     */
    00127    void SSL_CTX_free(SSL_CTX *ctx);
    00128
    00129    /*
    00130     *   SSL_set_fd - connect the SSL object with a file descriptor
    00131     */
    00132    int SSL_set_fd(SSL *ssl, int fd);
    00133
    00134    /*
    00135     *   SSL_pending - obtain number of readable bytes buffered in an SSL object
    00136     */
    00137    int SSL_pending(SSL *ssl);
    00138
    00139    /*
    00140     *   SSL_peek - obtain bytes buffered in an SSL object
    00141     */
    00142    int SSL_peek(SSL *ssl, void *buf, int num);
    00143
    00144    /*
    00145     *   SSL_CTX_set_cipher_list - choose list of available SSL_CIPHERs
    00146     */
    00147    int SSL_CTX_set_cipher_list(SSL_CTX *ctx, const char *str);
    00148
    00149    /*
    00150     *   SSL_CTX_set_verify - set peer certificate verification parameters
    00151     */
    00152    void SSL_CTX_set_verify(SSL_CTX *ctx, int mode,
    00153                          int (*verify_callback)(int, X509_STORE_CTX *));
    00154
    00155    /*
    00156     *   SSL_use_certificate - load certificate
    00157     */
    00158    int SSL_use_certificate(SSL *ssl, X509 *x);
    00159
    00160    /*
    00161     *   SSL_get_current_cipher - get SSL_CIPHER of a connection
    00162     */
    00163    SSL_CIPHER *SSL_get_current_cipher(SSL *ssl);
    00164
    00165    /*
    00166     *   SSL_set_options - manipulate SSL engine options
    00167     *   Note: These are all mapped to SSL_ctrl so call them as the comment
    00168     *         specifies but know that they use SSL_ctrl.  They are #define
    00169     *         so they will map to the one in this class if called as a
    00170     *         member function of this class.
    00171     */
    00172    /* long SSL_set_options(SSL *ssl, long options); */
    00173    long    SSL_ctrl(SSL *ssl,int cmd, long larg, char *parg);
    00174
    00175    /*
    00176     *   RAND_egd - set the path to the EGD
    00177     */
    00178    int RAND_egd(const char *path);
    00179
    00180
    00181    /*
    00182     *   RAND_file_name
    00183     */
    00184    const char *RAND_file_name(char *buf, size_t num);
    00185
    00186
    00187    /*
    00188     *   RAND_load_file
    00189     */
    00190    int RAND_load_file(const char *filename, long max_bytes);
    00191
    00192
    00193    /*
    00194     *   RAND_write_file
    00195     */
    00196    int RAND_write_file(const char *filename);
    00197
    00198
    00199    /*
    00200     *   TLSv1_client_method - return a TLSv1 client method object
    00201     */
    00202    SSL_METHOD *TLSv1_client_method();
    00203
    00204
    00205    /*
    00206     *   SSLv2_client_method - return a SSLv2 client method object
    00207     */
    00208    SSL_METHOD *SSLv2_client_method();
    00209
    00210
    00211    /*
    00212     *   SSLv3_client_method - return a SSLv3 client method object
    00213     */
    00214    SSL_METHOD *SSLv3_client_method();
    00215
    00216
    00217    /*
    00218     *   SSLv23_client_method - return a SSLv23 client method object
    00219     */
    00220    SSL_METHOD *SSLv23_client_method();
    00221
    00222
    00223    /*
    00224     *   SSL_get_peer_certificate - return the peer's certificate
    00225     */
    00226    X509 *SSL_get_peer_certificate(SSL *s);
    00227
    00228
    00229    /*
    00230     *   SSL_get_peer_cert_chain - get the peer's certificate chain
    00231     */
    00232    STACK_OF(X509) *SSL_get_peer_cert_chain(SSL *s);
    00233
    00234    /*
    00235     *   SSL_CIPHER_get_bits - get the number of bits in this cipher
    00236     */
    00237    int SSL_CIPHER_get_bits(SSL_CIPHER *c,int *alg_bits);
    00238
    00239
    00240    /*
    00241     *   SSL_CIPHER_get_version - get the version of this cipher
    00242     */
    00243    char *SSL_CIPHER_get_version(SSL_CIPHER *c);
    00244
    00245
    00246    /*
    00247     *   SSL_CIPHER_get_name - get the name of this cipher
    00248     */
    00249    const char *SSL_CIPHER_get_name(SSL_CIPHER *c);
    00250
    00251
    00252    /*
    00253     *   SSL_CIPHER_description - get the description of this cipher
    00254     */
    00255    char *SSL_CIPHER_description(SSL_CIPHER *,char *buf,int size);
    00256
    00257
    00258    /*
    00259     *   SSL_CTX_use_PrivateKey - set the private key for the session.
    00260     *                          - for use with client certificates
    00261     */
    00262    int SSL_CTX_use_PrivateKey(SSL_CTX *ctx, EVP_PKEY *pkey);
    00263
    00264
    00265    /*
    00266     *   SSL_CTX_use_certificate - set the client certificate for the session.
    00267     */
    00268    int SSL_CTX_use_certificate(SSL_CTX *ctx, X509 *x);
    00269
    00270
    00271    /*
    00272     *   d2i_X509 - Covert a text representation of X509 to an X509 object
    00273     */
    00274    X509 * d2i_X509(X509 **a,unsigned char **pp,long length);
    00275
    00276
    00277    /*
    00278     *   i2d_X509 - Covert an X509 object into a text representation
    00279     */
    00280    int i2d_X509(X509 *a,unsigned char **pp);
    00281
    00282
    00283    /*
    00284     *   X509_cmp - compare two X509 objects
    00285     */
    00286    int X509_cmp(X509 *a, X509 *b);
    00287
    00288
    00289    /*
    00290     *   X509_dup - duplicate an X509 object
    00291     */
    00292    X509 *X509_dup(X509 *x509);
    00293
    00294
    00295    /*
    00296     *   X509_STORE_CTX_new - create an X509 store context
    00297     */
    00298    X509_STORE_CTX *X509_STORE_CTX_new(void);
    00299
    00300
    00301    /*
    00302     *   X509_STORE_CTX_free - free up an X509 store context
    00303     */
    00304    void X509_STORE_CTX_free(X509_STORE_CTX *v);
    00305
    00306
    00307    /*
    00308     *   X509_STORE_CTX_set_chain - set the certificate chain
    00309     */
    00310    void X509_STORE_CTX_set_chain(X509_STORE_CTX *v, STACK_OF(X509)* x);
    00311
    00312    /*
    00313     *   X509_STORE_CTX_set_purpose - set the purpose of the certificate
    00314     */
    00315    void X509_STORE_CTX_set_purpose(X509_STORE_CTX *v, int purpose);
    00316
    00317    /*
    00318     *   X509_verify_cert - verify the certificate
    00319     */
    00320    int X509_verify_cert(X509_STORE_CTX *v);
    00321
    00322
    00323    /*
    00324     *   X509_STORE_new - create an X509 store
    00325     */
    00326    X509_STORE *X509_STORE_new(void);
    00327
    00328
    00329    /*
    00330     *   X509_STORE_free - free up an X509 store
    00331     */
    00332    void X509_STORE_free(X509_STORE *v);
    00333
    00334
    00335    /*
    00336     *   X509_free - free up an X509
    00337     */
    00338    void X509_free(X509 *v);
    00339
    00340
    00341    /*
    00342     *   X509_NAME_oneline - return the X509 data in a string
    00343     */
    00344    char *X509_NAME_oneline(X509_NAME *a, char *buf, int size);
    00345
    00346
    00347    /*
    00348     *   X509_get_subject_name - return the X509_NAME for the subject field
    00349     */
    00350    X509_NAME *X509_get_subject_name(X509 *a);
    00351
    00352
    00353    /*
    00354     *   X509_get_issuer_name - return the X509_NAME for the issuer field
    00355     */
    00356    X509_NAME *X509_get_issuer_name(X509 *a);
    00357
    00358
    00359    /*
    00360     *   X509_STORE_add_lookup - add a lookup file/method to an X509 store
    00361     */
    00362    X509_LOOKUP *X509_STORE_add_lookup(X509_STORE *v, X509_LOOKUP_METHOD *m);
    00363
    00364
    00365    /*
    00366     *   X509_LOOKUP_file - Definition of the LOOKUP_file method
    00367     */
    00368    X509_LOOKUP_METHOD *X509_LOOKUP_file(void);
    00369
    00370
    00371    /*
    00372     *   X509_LOOKUP_free - Free an X509_LOOKUP
    00373     */
    00374    void X509_LOOKUP_free(X509_LOOKUP *x);
    00375
    00376
    00377    /*
    00378     *   X509_LOOKUP_ctrl - This is not normally called directly (use macros)
    00379     */
    00380    int X509_LOOKUP_ctrl(X509_LOOKUP *ctx, int cmd, const char *argc, long argl, char **ret);
    00381
    00382
    00383    /*
    00384     *   X509_STORE_CTX_init - initialize an X509 STORE context
    00385     */
    00386    void X509_STORE_CTX_init(X509_STORE_CTX *ctx, X509_STORE *store, X509 *x509, STACK_OF(X509) *chain);
    00387
    00388
    00389    /*
    00390     *   CRYPTO_free - free up an internally allocated object
    00391     */
    00392    void CRYPTO_free(void *x);
    00393
    00394
    00395    /*
    00396     *   BIO_new_fp - nastiness called BIO - used to create BIO* from FILE*
    00397     */
    00398    BIO *BIO_new_fp(FILE *stream, int close_flag);
    00399
    00400
    00401    /*
    00402     *   BIO_free - nastiness called BIO - used to destroy BIO*
    00403     */
    00404    int BIO_free(BIO *a);
    00405
    00406
    00407    /*
    00408     *   PEM_write_bio_X509 - write a PEM encoded cert to a BIO*
    00409     */
    00410    int PEM_write_bio_X509(BIO *bp, X509 *x);
    00411
    00412
    00413    /*
    00414     *   X509_asn1_meth - used for netscape output
    00415     */
    00416    ASN1_METHOD *X509_asn1_meth();
    00417
    00418
    00419    /*
    00420     *   ASN1_i2d_fp - used for netscape output
    00421     */
    00422    int ASN1_i2d_fp(FILE *out, unsigned char *x);
    00423
    00424
    00425    /*
    00426     *   ASN1_d2i_fp - read an X509 from a DER encoded file (buf can be NULL)
    00427     */
    00428    X509 *X509_d2i_fp(FILE *out, X509** buf);
    00429
    00430
    00431    /*
    00432     *   X509_print - print the text form of an X509
    00433     */
    00434    int X509_print(FILE *fp, X509 *x);
    00435
    00436
    00437    /*
    00438     *   Read a PKCS#12 cert from fp
    00439     */
    00440    PKCS12 *d2i_PKCS12_fp(FILE *fp, PKCS12 **p12);
    00441
    00442
    00443    /*
    00444     *   Change the password on a PKCS#12 cert
    00445     */
    00446    int PKCS12_newpass(PKCS12 *p12, char *oldpass, char *newpass);
    00447
    00448
    00449    /*
    00450     *   Write a PKCS#12 to mem
    00451     */
    00452    int i2d_PKCS12(PKCS12 *p12, unsigned char **p);
    00453
    00454
    00455    /*
    00456     *   Write a PKCS#12 to FILE*
    00457     */
    00458    int i2d_PKCS12_fp(FILE *fp, PKCS12 *p12);
    00459
    00460
    00461    /*
    00462     *   Create a new PKCS#12 object
    00463     */
    00464    PKCS12 *PKCS12_new(void);
    00465
    00466
    00467    /*
    00468     *   Destroy that PKCS#12 that you created!
    00469     */
    00470    void PKCS12_free(PKCS12 *a);
    00471
    00472
    00473    /*
    00474     *   Parse the PKCS#12
    00475     */
    00476    int PKCS12_parse(PKCS12 *p12, const char *pass, EVP_PKEY **pkey,
    00477                     X509 **cert, STACK_OF(X509) **ca);
    00478
    00479
    00480    /*
    00481     *   Free the Private Key
    00482     */
    00483    void EVP_PKEY_free(EVP_PKEY *x);
    00484
    00485
    00486    /*
    00487     *   Pop off the stack
    00488     */
    00489    char *sk_pop(STACK *s);
    00490
    00491
    00492    /*
    00493     *   Free the stack
    00494     */
    00495    void sk_free(STACK *s);
    00496
    00497
    00498    /*
    00499     *  Number of elements in the stack
    00500     */
    00501    int sk_num(STACK *s);
    00502
    00503
    00504    /*
    00505     *  Value of element n in the stack
    00506     */
    00507    char *sk_value(STACK *s, int n);
    00508
    00509
    00510    /*
    00511     *  Create a new stack
    00512     */
    00513    STACK *sk_new(int (*cmp)());
    00514
    00515
    00516    /*
    00517     *  Add an element to the stack
    00518     */
    00519    int sk_push(STACK *s, char *d);
    00520
    00521
    00522    /*
    00523     *  Duplicate the stack
    00524     */
    00525    STACK *sk_dup(STACK *s);
    00526
    00527
    00528    /*
    00529     *  Convert an ASN1_INTEGER to it's text form
    00530     */
    00531    char *i2s_ASN1_INTEGER(X509V3_EXT_METHOD *meth, ASN1_INTEGER *aint);
    00532
    00533
    00534    /*
    00535     *  Get the certificate's serial number
    00536     */
    00537    ASN1_INTEGER *X509_get_serialNumber(X509 *x);
    00538
    00539
    00540    /*
    00541     *  Get the certificate's public key
    00542     */
    00543    EVP_PKEY *X509_get_pubkey(X509 *x);
    00544
    00545
    00546    /*
    00547     *  Convert the public key to a decimal form
    00548     */
    00549    int i2d_PublicKey(EVP_PKEY *a, unsigned char **pp);
    00550
    00551
    00552    /*
    00553     *  Check the private key of a PKCS bundle against the X509
    00554     */
    00555    int X509_check_private_key(X509 *x, EVP_PKEY *p);
    00556
    00557
    00558    /*
    00559     *  Convert a BIGNUM to a hex string
    00560     */
    00561    char *BN_bn2hex(const BIGNUM *a);
    00562
    00563
    00564    /*
    00565     *  Compute the digest of an X.509
    00566     */
    00567    int X509_digest(const X509 *x,const EVP_MD *t, unsigned char *md, unsigned int *len);
    00568
    00569
    00570    /*
    00571     *  EVP_md5
    00572     */
    00573    EVP_MD *EVP_md5();
    00574
    00575
    00576    /*
    00577     *  ASN1_INTEGER free
    00578     */
    00579    void ASN1_INTEGER_free(ASN1_INTEGER *x);
    00580
    00581
    00582    /*
    00583     *
    00584     */
    00585    int OBJ_obj2nid(ASN1_OBJECT *o);
    00586
    00587    /*
    00588     *
    00589     */
    00590    const char * OBJ_nid2ln(int n);
    00591
    00592    /*
    00593     * get the number of extensions
    00594     */
    00595    int X509_get_ext_count(X509 *x);
    00596
    00597    /*
    00598     *
    00599     */
    00600    int X509_get_ext_by_NID(X509 *x, int nid, int lastpos);
    00601
    00602    /*
    00603     *
    00604     */
    00605    int X509_get_ext_by_OBJ(X509 *x,ASN1_OBJECT *obj,int lastpos);
    00606
    00607    /*
    00608     *
    00609     */
    00610    X509_EXTENSION *X509_get_ext(X509 *x, int loc);
    00611
    00612    /*
    00613     *
    00614     */
    00615    X509_EXTENSION *X509_delete_ext(X509 *x, int loc);
    00616
    00617    /*
    00618     *
    00619     */
    00620    int X509_add_ext(X509 *x, X509_EXTENSION *ex, int loc);
    00621
    00622    /*
    00623     *
    00624     */
    00625    void *X509_get_ext_d2i(X509 *x, int nid, int *crit, int *idx);
    00626
    00627    /*
    00628     *
    00629     */
    00630    char *i2s_ASN1_OCTET_STRING(X509V3_EXT_METHOD *method, ASN1_OCTET_STRING *ia5);
    00631
    00632    /*
    00633     *
    00634     */
    00635    int ASN1_BIT_STRING_get_bit(ASN1_BIT_STRING *a, int n);
    00636
    00637    /*
    00638     *
    00639     */
    00640    PKCS7 *PKCS7_new(void);
    00641
    00642    /*
    00643     *
    00644     */
    00645    void PKCS7_free(PKCS7 *a);
    00646
    00647    /*
    00648     *
    00649     */
    00650    void PKCS7_content_free(PKCS7 *a);
    00651
    00652    /*
    00653     *
    00654     */
    00655    int i2d_PKCS7(PKCS7 *a, unsigned char **pp);
    00656
    00657    /*
    00658     *
    00659     */
    00660    PKCS7 *d2i_PKCS7(PKCS7 **a, unsigned char **pp,long length);
    00661
    00662    /*
    00663     *
    00664     */
    00665    int i2d_PKCS7_fp(FILE *fp,PKCS7 *p7);
    00666
    00667    /*
    00668     *
    00669     */
    00670    PKCS7 *d2i_PKCS7_fp(FILE *fp,PKCS7 **p7);
    00671
    00672    /*
    00673     *
    00674     */
    00675    PKCS7 *PKCS7_dup(PKCS7 *p7);
    00676
    00677    /*
    00678     *  Verify a PKCS7 signature.
    00679     */
    00680    int PKCS7_verify(PKCS7 *p7, STACK_OF(X509) *certs, X509_STORE *store,
    00681                                               BIO *indata, BIO *out, int flags);
    00682
    00683    /*
    00684     * Load a CA list file.
    00685     */
    00686    STACK_OF(X509_NAME) *SSL_load_client_CA_file(const char *file);
    00687
    00688    /*
    00689     * Load a file of PEM encoded objects.
    00690     */
    00691    STACK_OF(X509_INFO) *PEM_X509_INFO_read(FILE *fp, STACK_OF(X509_INFO) *sk,
    00692                            pem_password_cb *cb, void *u);
    00693
    00694    /*
    00695     * Get the number of purposes available
    00696     */
    00697    int X509_PURPOSE_get_count();
    00698
    00699
    00700    /*
    00701     * Get the ID of a purpose
    00702     */
    00703    int X509_PURPOSE_get_id(X509_PURPOSE *);
    00704
    00705
    00706    /*
    00707     * Check the existence of purpose id "id" in x.  for CA, set ca = 1, else 0
    00708     */
    00709    int X509_check_purpose(X509 *x, int id, int ca);
    00710
    00711
    00712    /*
    00713     * Get the purpose with index #idx
    00714     */
    00715    X509_PURPOSE * X509_PURPOSE_get0(int idx);
    00716
    00717
    00718    /*
    00719     * Create a new Private KEY
    00720     */
    00721    EVP_PKEY* EVP_PKEY_new();
    00722
    00723
    00724    /*
    00725     * Assign a private key
    00726     */
    00727    int EVP_PKEY_assign(EVP_PKEY *pkey, int type, char *key);
    00728
    00729
    00730    /*
    00731     * Generate a RSA key
    00732     */
    00733    RSA *RSA_generate_key(int bits, unsigned long e, void
    00734                         (*callback)(int,int,void *), void *cb_arg);
    00735
    00736
    00737    /*
    00738     * Create/destroy a certificate request
    00739     */
    00740    X509_REQ *X509_REQ_new();
    00741    void X509_REQ_free(X509_REQ *a);
    00742
    00743
    00744    /*
    00745     * Set the public key in the REQ object
    00746     */
    00747    int X509_REQ_set_pubkey(X509_REQ *x, EVP_PKEY *pkey);
    00748
    00749    /* for testing */
    00750    int i2d_X509_REQ_fp(FILE *fp, X509_REQ *x);
    00751
    00752
    00753    /* clear the current error  - use this often*/
    00754    void ERR_clear_error();
    00755
    00756    /* Print the errors to this stream */
    00757    void ERR_print_errors_fp(FILE *fp);
    00758
    00759
    00760 #endif
    00761
    00762 private:
    00763    KOpenSSLProxy();
    00764    ~KOpenSSLProxy();
    00765    KOpenSSLProxyPrivate *d;
    00766
    00767    KLibrary *_sslLib;
    00768    KLibrary *_cryptoLib;
    00769    static KOpenSSLProxy *_me;
    00770
    00771    bool _ok;
    00772 };
    00773
    00774 #endif
    00775

This file is part of the documentation for kdelibs Version 3.1.5.
Documentation copyright © 1996-2002 the KDE developers.
Generated on Wed Jan 28 13:13:51 2004 by doxygen 1.3.4 written by Dimitri van Heesch, © 1997-2001