1: 
    2: Bundle of old SSLeay documentation files [OBSOLETE!]
    3: 
    4: *** WARNING! WARNING! WARNING! WARNING! WARNING! WARNING! WARNING! ***
    5: 
    6: OBSOLETE means that nothing in this document should be trusted.  This
    7: document is provided mostly for historical purposes (it wasn't even up
    8: to date at the time SSLeay 0.8.1 was released) and as inspiration.  If
    9: you copy some snippet of code from this document, please _check_ that
   10: it really is correct from all points of view.  For example, you can
   11: check with the other documents in this directory tree, or by comparing
   12: with relevant parts of the include files.
   13: 
   14: People have done the mistake of trusting what's written here.  Please
   15: don't do that.
   16: 
   17: *** WARNING! WARNING! WARNING! WARNING! WARNING! WARNING! WARNING! ***
   18: 
   19: 
   20: ==== readme ========================================================
   21: 
   22: This is the old 0.6.6 docuementation.  Most of the cipher stuff is still
   23: relevent but I'm working (very slowly) on new docuemtation.
   24: The current version can be found online at
   25: 
   26: http://www.cryptsoft.com/ssleay/doc
   27: 
   28: ==== API.doc ========================================================
   29: 
   30: SSL - SSLv2/v3/v23 etc.
   31: 
   32: BIO - methods and how they plug together
   33: 
   34: MEM - memory allocation callback
   35: 
   36: CRYPTO - locking for threads
   37: 
   38: EVP - Ciphers/Digests/signatures
   39: 
   40: RSA - methods
   41: 
   42: X509 - certificate retrieval
   43: 
   44: X509 - validation
   45: 
   46: X509 - X509v3 extensions
   47: 
   48: Objects - adding object identifiers
   49: 
   50: ASN.1 - parsing
   51: 
   52: PEM - parsing
   53: 
   54: ==== ssl/readme =====================================================
   55: 
   56: 22 Jun 1996
   57: This file belongs in ../apps, but I'll leave it here because it deals
   58: with SSL :-)  It is rather dated but it gives you an idea of how
   59: things work.
   60: ===
   61: 
   62: 17 Jul 1995
   63: I have been changing things quite a bit and have not fully updated
   64: this file, so take what you read with a grain of salt
   65: eric
   66: ===
   67: The s_client and s_server programs can be used to test SSL capable
   68: IP/port addresses and the verification of the X509 certificates in use
   69: by these services.  I strongly advise having a look at the code to get
   70: an idea of how to use the authentication under SSLeay.  Any feedback
   71: on changes and improvements would be greatly accepted.
   72: 
   73: This file will probably be gibberish unless you have read
   74: rfc1421, rfc1422, rfc1423 and rfc1424 which describe PEM
   75: authentication.
   76: 
   77: A Brief outline (and examples) how to use them to do so.
   78: 
   79: NOTE:
   80: The environment variable SSL_CIPER is used to specify the prefered
   81: cipher to use, play around with setting it's value to combinations of
   82: RC4-MD5, EXP-RC4-MD5, CBC-DES-MD5, CBC3-DES-MD5, CFB-DES-NULL
   83: in a : separated list.
   84: 
   85: This directory contains 3 X509 certificates which can be used by these programs.
   86: client.pem: a file containing a certificate and private key to be used
   87:         by s_client.
   88: server.pem :a file containing a certificate and private key to be used
   89:         by s_server.
   90: eay1024.pem:the certificate used to sign client.pem and server.pem.
   91:         This would be your CA's certificate.  There is also a link
   92:         from the file a8556381.0 to eay1024.PEM.  The value a8556381
   93:         is returned by 'x509 -hash -noout <eay1024.pem' and is the
   94:         value used by X509 verification routines to 'find' this
   95:         certificte when search a directory for it.
   96:         [the above is not true any more, the CA cert is 
   97:          ../certs/testca.pem which is signed by ../certs/mincomca.pem]
   98: 
   99: When testing the s_server, you may get
  100: bind: Address already in use
  101: errors.  These indicate the port is still being held by the unix
  102: kernel and you are going to have to wait for it to let go of it.  If
  103: this is the case, remember to use the port commands on the s_server and
  104: s_client to talk on an alternative port.
  105: 
  106: =====
  107: s_client.
  108: This program can be used to connect to any IP/hostname:port that is
  109: talking SSL.  Once connected, it will attempt to authenticate the
  110: certificate it was passed and if everything works as expected, a 2
  111: directional channel will be open.  Any text typed will be sent to the
  112: other end.  type Q<cr> to exit.  Flags are as follows.
  113: -host arg       : Arg is the host or IP address to connect to.
  114: -port arg       : Arg is the port to connect to (https is 443).
  115: -verify arg     : Turn on authentication of the server certificate.
  116:                 : Arg specifies the 'depth', this will covered below.
  117: -cert arg       : The optional certificate to use.  This certificate
  118:                 : will be returned to the server if the server
  119:                 : requests it for client authentication.
  120: -key arg        : The private key that matches the certificate
  121:                 : specified by the -cert option.  If this is not
  122:                 : specified (but -cert is), the -cert file will be
  123:                 : searched for the Private key.  Both files are
  124:                 : assumed to be in PEM format.
  125: -CApath arg     : When to look for certificates when 'verifying' the
  126:                 : certificate from the server.
  127: -CAfile arg     : A file containing certificates to be used for
  128:                 : 'verifying' the server certificate.
  129: -reconnect      : Once a connection has been made, drop it and
  130:                 : reconnect with same session-id.  This is for testing :-).
  131: 
  132: The '-verify n' parameter specifies not only to verify the servers
  133: certificate but to also only take notice of 'n' levels.  The best way
  134: to explain is to show via examples.
  135: Given
  136: s_server -cert server.PEM is running.
  137: 
  138: s_client
  139:         CONNECTED
  140:         depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo server
  141:         issuer= /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA
  142:         verify error:num=1:unable to get issuer certificate
  143:         verify return:1
  144:         CIPHER is CBC-DES-MD5
  145: What has happened is that the 'SSLeay demo server' certificate's
  146: issuer ('CA') could not be found but because verify is not on, we
  147: don't care and the connection has been made anyway.  It is now 'up'
  148: using CBC-DES-MD5 mode.  This is an unauthenticate secure channel.
  149: You may not be talking to the right person but the data going to them
  150: is encrypted.
  151: 
  152: s_client -verify 0
  153:         CONNECTED
  154:         depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo server
  155:         issuer= /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA
  156:         verify error:num=1:unable to get issuer certificate
  157:         verify return:1
  158:         CIPHER is CBC-DES-MD5
  159: We are 'verifying' but only to depth 0, so since the 'SSLeay demo server'
  160: certificate passed the date and checksum, we are happy to proceed.
  161: 
  162: s_client -verify 1
  163:         CONNECTED
  164:         depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo server
  165:         issuer= /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA
  166:         verify error:num=1:unable to get issuer certificate
  167:         verify return:0
  168:         ERROR
  169:         verify error:unable to get issuer certificate
  170: In this case we failed to make the connection because we could not
  171: authenticate the certificate because we could not find the
  172: 'CA' certificate.
  173: 
  174: s_client -verify 1 -CAfile eay1024.PEM
  175:         CONNECTED
  176:         depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo server
  177:         verify return:1
  178:         depth=1 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA
  179:         verify return:1
  180:         CIPHER is CBC-DES-MD5
  181: We loaded the certificates from the file eay1024.PEM.  Everything
  182: checked out and so we made the connection.
  183: 
  184: s_client -verify 1 -CApath .
  185:         CONNECTED
  186:         depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo server
  187:         verify return:1
  188:         depth=1 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA
  189:         verify return:1
  190:         CIPHER is CBC-DES-MD5
  191: We looked in out local directory for issuer certificates and 'found'
  192: a8556381.0 and so everything is ok.
  193: 
  194: It is worth noting that 'CA' is a self certified certificate.  If you
  195: are passed one of these, it will fail to 'verify' at depth 0 because
  196: we need to lookup the certifier of a certificate from some information
  197: that we trust and keep locally.
  198: 
  199: SSL_CIPHER=CBC3-DES-MD5:RC4-MD5
  200: export SSL_CIPHER
  201: s_client -verify 10 -CApath . -reconnect
  202:         CONNECTED
  203:         depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo server
  204:         verify return:1
  205:         depth=1 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA
  206:         verify return:1
  207:         drop the connection and reconnect with the same session id
  208:         CIPHER is CBC3-DES-MD5
  209: This has done a full connection and then re-estabished it with the
  210: same session id but a new socket.  No RSA stuff occures on the second
  211: connection.  Note that we said we would prefer to use CBC3-DES-MD5
  212: encryption and so, since the server supports it, we are.
  213: 
  214: =====
  215: s_server
  216: This program accepts SSL connections on a specified port
  217: Once connected, it will estabish an SSL connection and optionaly
  218: attempt to authenticate the client.  A 2 directional channel will be
  219: open.  Any text typed will be sent to the other end.  Type Q<cr> to exit.
  220: Flags are as follows.
  221: -port arg       : Arg is the port to listen on.
  222: -verify arg     : Turn on authentication of the client if they have a
  223:                 : certificate.  Arg specifies the 'depth'.
  224: -Verify arg     : Turn on authentication of the client. If they don't
  225:                 : have a valid certificate, drop the connection.
  226: -cert arg       : The certificate to use.  This certificate
  227:                 : will be passed to the client.  If it is not
  228:                 : specified, it will default to server.PEM
  229: -key arg        : The private key that matches the certificate
  230:                 : specified by the -cert option.  If this is not
  231:                 : specified (but -cert is), the -cert file will be
  232:                 : searched for the Private key.  Both files are
  233:                 : assumed to be in PEM format.  Default is server.PEM
  234: -CApath arg     : When to look for certificates when 'verifying' the
  235:                 : certificate from the client.
  236: -CAfile arg     : A file containing certificates to be used for
  237:                 : 'verifying' the client certificate.
  238: 
  239: For the following 'demo'  I will specify the s_server command and
  240: the s_client command and then list the output from the s_server.
  241: s_server
  242: s_client
  243:         CONNECTED
  244:         CIPHER is CBC-DES-MD5
  245: Everything up and running
  246: 
  247: s_server -verify 0
  248: s_client  
  249:         CONNECTED
  250:         CIPHER is CBC-DES-MD5
  251: Ok since no certificate was returned and we don't care.
  252: 
  253: s_server -verify 0
  254: ./s_client -cert client.PEM
  255:         CONNECTED
  256:         depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo client
  257:         issuer= /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA
  258:         verify error:num=1:unable to get issuer certificate
  259:         verify return:1
  260:         CIPHER is CBC-DES-MD5
  261: Ok since we were only verifying to level 0
  262: 
  263: s_server -verify 4
  264: s_client -cert client.PEM
  265:         CONNECTED
  266:         depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo client
  267:         issuer= /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA
  268:         verify error:num=1:unable to get issuer certificate
  269:         verify return:0
  270:         ERROR
  271:         verify error:unable to get issuer certificate
  272: Bad because we could not authenticate the returned certificate.
  273: 
  274: s_server -verify 4 -CApath .
  275: s_client -cert client.PEM
  276:         CONNECTED
  277:         depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo client
  278:         verify return:1
  279:         depth=1 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA
  280:         verify return:1
  281:         CIPHER is CBC-DES-MD5
  282: Ok because we could authenticate the returned certificate :-).
  283: 
  284: s_server -Verify 0 -CApath .
  285: s_client
  286:         CONNECTED
  287:         ERROR
  288:         SSL error:function is:REQUEST_CERTIFICATE
  289:                  :error is   :client end did not return a certificate
  290: Error because no certificate returned.
  291: 
  292: s_server -Verify 4 -CApath .
  293: s_client -cert client.PEM
  294:         CONNECTED
  295:         depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo client
  296:         verify return:1
  297:         depth=1 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA
  298:         verify return:1
  299:         CIPHER is CBC-DES-MD5
  300: Full authentication of the client.
  301: 
  302: So in summary to do full authentication of both ends
  303: s_server -Verify 9 -CApath .
  304: s_client -cert client.PEM -CApath . -verify 9
  305: From the server side
  306:         CONNECTED
  307:         depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo client
  308:         verify return:1
  309:         depth=1 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA
  310:         verify return:1
  311:         CIPHER is CBC-DES-MD5
  312: From the client side
  313:         CONNECTED
  314:         depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo server
  315:         verify return:1
  316:         depth=1 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA
  317:         verify return:1
  318:         CIPHER is CBC-DES-MD5
  319: 
  320: For general probing of the 'internet https' servers for the
  321: distribution area, run
  322: s_client -host www.netscape.com -port 443 -verify 4 -CApath ../rsa/hash
  323: Then enter
  324: GET /
  325: and you should be talking to the https server on that host.
  326: 
  327: www.rsa.com was refusing to respond to connections on 443 when I was
  328: testing.
  329: 
  330: have fun :-).
  331: 
  332: eric
  333: 
  334: ==== a_verify.doc ========================================================
  335: 
  336: From eay@mincom.com Fri Oct  4 18:29:06 1996
  337: Received: by orb.mincom.oz.au id AA29080
  338:   (5.65c/IDA-1.4.4 for eay); Fri, 4 Oct 1996 08:29:07 +1000
  339: Date: Fri, 4 Oct 1996 08:29:06 +1000 (EST)
  340: From: Eric Young <eay@mincom.oz.au>
  341: X-Sender: eay@orb
  342: To: wplatzer <wplatzer@iaik.tu-graz.ac.at>
  343: Cc: Eric Young <eay@mincom.oz.au>, SSL Mailing List <ssl-users@mincom.com>
  344: Subject: Re: Netscape's Public Key
  345: In-Reply-To: <19961003134837.NTM0049@iaik.tu-graz.ac.at>
  346: Message-Id: <Pine.SOL.3.91.961004081346.8018K-100000@orb>
  347: Mime-Version: 1.0
  348: Content-Type: TEXT/PLAIN; charset=US-ASCII
  349: Status: RO
  350: X-Status: 
  351: 
  352: On Thu, 3 Oct 1996, wplatzer wrote:
  353: > I get Public Key from Netscape (Gold 3.0b4), but cannot do anything
  354: > with it... It looks like (asn1parse):
  355: > 
  356: > 0:d=0 hl=3 l=180 cons: SEQUENCE
  357: > 3:d=1 hl=2 l= 96 cons: SEQUENCE
  358: > 5:d=2 hl=2 l= 92 cons: SEQUENCE
  359: > 7:d=3 hl=2 l= 13 cons: SEQUENCE
  360: > 9:d=4 hl=2 l= 9 prim: OBJECT :rsaEncryption
  361: > 20:d=4 hl=2 l= 0 prim: NULL
  362: > 22:d=3 hl=2 l= 75 prim: BIT STRING
  363: > 99:d=2 hl=2 l= 0 prim: IA5STRING :
  364: > 101:d=1 hl=2 l= 13 cons: SEQUENCE
  365: > 103:d=2 hl=2 l= 9 prim: OBJECT :md5withRSAEncryption
  366: > 114:d=2 hl=2 l= 0 prim: NULL
  367: > 116:d=1 hl=2 l= 65 prim: BIT STRING
  368: > 
  369: > The first BIT STRING is the public key and the second BIT STRING is 
  370: > the signature.
  371: > But a public key consists of the public exponent and the modulus. Are 
  372: > both numbers in the first BIT STRING?
  373: > Is there a document simply describing this coding stuff (checking 
  374: > signature, get the public key, etc.)?
  375: 
  376: Minimal in SSLeay.  If you want to see what the modulus and exponent are,
  377: try asn1parse -offset 25 -length 75 <key.pem
  378: asn1parse will currently stuff up on the 'length 75' part (fixed in next 
  379: release) but it will print the stuff.  If you are after more 
  380: documentation on ASN.1, have a look at www.rsa.com and get their PKCS 
  381: documents, most of my initial work on SSLeay was done using them.
  382: 
  383: As for SSLeay,
  384: util/crypto.num and util/ssl.num are lists of all exported functions in 
  385: the library (but not macros :-(.
  386: 
  387: The ones for extracting public keys from certificates and certificate 
  388: requests are EVP_PKEY *      X509_REQ_extract_key(X509_REQ *req);
  389: EVP_PKEY *      X509_extract_key(X509 *x509);
  390: 
  391: To verify a signature on a signed ASN.1 object
  392: int X509_verify(X509 *a,EVP_PKEY *key);
  393: int X509_REQ_verify(X509_REQ *a,EVP_PKEY *key);
  394: int X509_CRL_verify(X509_CRL *a,EVP_PKEY *key);
  395: int NETSCAPE_SPKI_verify(NETSCAPE_SPKI *a,EVP_PKEY *key);
  396: 
  397: I should mention that EVP_PKEY can be used to hold a public or a private key,
  398: since for  things like RSA and DSS, a public key is just a subset of what 
  399: is stored for the private key.
  400: 
  401: To sign any of the above structures
  402: 
  403: int X509_sign(X509 *a,EVP_PKEY *key,EVP_MD *md);
  404: int X509_REQ_sign(X509_REQ *a,EVP_PKEY *key,EVP_MD *md);
  405: int X509_CRL_sign(X509_CRL *a,EVP_PKEY *key,EVP_MD *md);
  406: int NETSCAPE_SPKI_sign(NETSCAPE_SPKI *a,EVP_PKEY *key,EVP_MD *md);
  407: 
  408: where md is the message digest to sign with.
  409: 
  410: There are all defined in x509.h and all the _sign and _verify functions are
  411: actually macros to the ASN1_sign() and ASN1_verify() functions.
  412: These functions will put the correct algorithm identifiers in the correct 
  413: places in the structures.
  414: 
  415: eric
  416: --
  417: Eric Young                  | BOOL is tri-state according to Bill Gates.
  418: AARNet: eay@mincom.oz.au    | RTFM Win32 GetMessage().
  419: 
  420: ==== x509 =======================================================
  421: 
  422: X509_verify()
  423: X509_sign()
  424: 
  425: X509_get_version()
  426: X509_get_serialNumber()
  427: X509_get_issuer()
  428: X509_get_subject()
  429: X509_get_notBefore()
  430: X509_get_notAfter()
  431: X509_get_pubkey()
  432: 
  433: X509_set_version()
  434: X509_set_serialNumber()
  435: X509_set_issuer()
  436: X509_set_subject()
  437: X509_set_notBefore()
  438: X509_set_notAfter()
  439: X509_set_pubkey()
  440: 
  441: X509_get_extensions()
  442: X509_set_extensions()
  443: 
  444: X509_EXTENSIONS_clear()
  445: X509_EXTENSIONS_retrieve()
  446: X509_EXTENSIONS_add()
  447: X509_EXTENSIONS_delete()
  448: 
  449: ==== x509 attribute ================================================
  450: 
  451: PKCS7
  452:         STACK of X509_ATTRIBUTES
  453:                 ASN1_OBJECT
  454:                 STACK of ASN1_TYPE
  455: 
  456: So it is
  457: 
  458: p7.xa[].obj
  459: p7.xa[].data[]
  460: 
  461: get_obj_by_nid(STACK , nid)
  462: get_num_by_nid(STACK , nid)
  463: get_data_by_nid(STACK , nid, index)
  464: 
  465: X509_ATTRIBUTE *X509_ATTRIBUTE_new(void );
  466: void            X509_ATTRIBUTE_free(X509_ATTRIBUTE *a);
  467: 
  468: X509_ATTRIBUTE *X509_ATTRIBUTE_create_by_NID(X509_ATTRIBUTE **ex,
  469:                         int nid, STACK *value);
  470: 
  471: X509_ATTRIBUTE *X509_ATTRIBUTE_create_by_OBJ(X509_ATTRIBUTE **ex,
  472:                         int nid, STACK *value);
  473: 
  474: int             X509_ATTRIBUTE_set_object(X509_ATTRIBUTE *ex,ASN1_OBJECT *obj);
  475: int             X509_ATTRIBUTE_add_data(X509_ATTRIBUTE *ex, int index,
  476:                         ASN1_TYPE *value);
  477: 
  478: ASN1_OBJECT *   X509_ATTRIBUTE_get_object(X509_ATTRIBUTE *ex);
  479: int             X509_ATTRIBUTE_get_num(X509_ATTRIBUTE *ne);
  480: ASN1_TYPE *     X509_ATTRIBUTE_get_data(X509_ATTRIBUTE *ne,int index);
  481: 
  482: ASN1_TYPE *     X509_ATTRIBUTE_get_data_by_NID(X509_ATTRIBUTE *ne,
  483:                         ASN1_OBJECT *obj);
  484: 
  485: X509_ATTRIBUTE *PKCS7_get_s_att_by_NID(PKCS7 *p7,int nid);
  486: X509_ATTRIBUTE *PKCS7_get_u_att_by_NID(PKCS7 *p7,int nid);
  487: 
  488: ==== x509 v3 ========================================================
  489: 
  490: The 'new' system.
  491: 
  492: The X509_EXTENSION_METHOD includes extensions and attributes and/or names. 
  493: Basically everthing that can be added to an X509 with an OID identifying it.
  494: 
  495: It operates via 2 methods per object id.
  496: int a2i_XXX(X509 *x,char *str,int len);
  497: int i2a_XXX(BIO *bp,X509 *x);
  498: 
  499: The a2i_XXX function will add the object with a value converted from the
  500: string into the X509.  Len can be -1 in which case the length is calculated
  501: via strlen(str).   Applications can always use direct knowledge to load and
  502: unload the relevent objects themselves.
  503: 
  504: i2a_XXX will print to the passed BIO, a text representation of the
  505: relevet object.  Use a memory BIO if you want it printed to a buffer :-).
  506: 
  507: X509_add_by_NID(X509 *x,int nid,char *str,int len);
  508: X509_add_by_OBJ(X509 *x,ASN1_OBJECT *obj,char *str,int len);
  509: 
  510: X509_print_by_name(BIO *bp,X509 *x);
  511: X509_print_by_NID(BIO *bp,X509 *x);
  512: X509_print_by_OBJ(BIO *bp,X509 *x);
  513: 
  514: ==== verify ========================================================
  515: 
  516: X509_verify_cert_chain(
  517:         CERT_STORE *cert_store,
  518:         STACK /* X509 */ *certs,
  519:         int *verify_result,
  520:         int (*verify_error_callback)()
  521:         char *argument_to_callback, /* SSL */
  522: 
  523: app_verify_callback(
  524:         char *app_verify_arg, /* from SSL_CTX */
  525:         STACK /* X509 */ *certs,
  526:         int *verify_result,
  527:         int (*verify_error_callback)()
  528:         SSL *s,
  529: 
  530: int X509_verify_cert(
  531:         CERT_STORE *cert_store,
  532:         X509 *x509,
  533:         int *verify_result,
  534:         int (*verify_error_callback)(),
  535:         char *arg,
  536: 
  537: ==== apps.doc ========================================================
  538: 
  539: The applications
  540: 
  541: Ok, where to begin....
  542: In the begining, when SSLeay was small (April 1995), there
  543: were but few applications, they did happily cohabit in
  544: the one bin directory.  Then over time, they did multiply and grow,
  545: and they started to look like microsoft software; 500k to print 'hello world'.
  546: A new approach was needed.  They were coalessed into one 'Monolithic'
  547: application, ssleay.  This one program is composed of many programs that
  548: can all be compiled independantly.
  549: 
  550: ssleay has 3 modes of operation.
  551: 1) If the ssleay binaray has the name of one of its component programs, it
  552: executes that program and then exits.  This can be achieve by using hard or
  553: symbolic links, or failing that, just renaming the binary.
  554: 2) If the first argument to ssleay is the name of one of the component
  555: programs, that program runs that program and then exits.
  556: 3) If there are no arguments, ssleay enters a 'command' mode.  Each line is
  557: interpreted as a program name plus arguments.  After each 'program' is run,
  558: ssleay returns to the comand line.
  559: 
  560: dgst    - message digests
  561: enc     - encryption and base64 encoding
  562: 
  563: ans1parse - 'pulls' appart ASN.1 encoded objects like certificates.
  564: 
  565: dh      - Diffle-Hellman parameter manipulation.
  566: rsa     - RSA manipulations.
  567: crl     - Certificate revokion list manipulations
  568: x509    - X509 cert fiddles, including signing.
  569: pkcs7   - pkcs7 manipulation, only DER versions right now.
  570: 
  571: genrsa  - generate an RSA private key.
  572: gendh   - Generate a set of Diffle-Hellman parameters.
  573: req     - Generate a PKCS#10 object, a certificate request.
  574: 
  575: s_client - SSL client program
  576: s_server - SSL server program
  577: s_time   - A SSL protocol timing program
  578: s_mult   - Another SSL server, but it multiplexes
  579:            connections.
  580: s_filter - under development
  581: 
  582: errstr  - Convert SSLeay error numbers to strings.
  583: ca      - Sign certificate requests, and generate
  584:           certificate revokion lists
  585: crl2pkcs7 - put a crl and certifcates into a pkcs7 object.
  586: speed   - Benchmark the ciphers.
  587: verify  - Check certificates
  588: hashdir - under development
  589: 
  590: [ there a now a few more options, play with the program to see what they
  591:   are ]
  592: 
  593: ==== asn1.doc ========================================================
  594: 
  595: The ASN.1 Routines.
  596: 
  597: ASN.1 is a specification for how to encode structured 'data' in binary form.
  598: The approach I have take to the manipulation of structures and their encoding
  599: into ASN.1 is as follows.
  600: 
  601: For each distinct structure there are 4 function of the following form
  602: TYPE *TYPE_new(void);
  603: void TYPE_free(TYPE *);
  604: TYPE *d2i_TYPE(TYPE **a,unsigned char **pp,long length);
  605: long i2d_TYPE(TYPE *a,unsigned char **pp);      /* CHECK RETURN VALUE */
  606: 
  607: where TYPE is the type of the 'object'.  The TYPE that have these functions
  608: can be in one of 2 forms, either the internal C malloc()ed data structure
  609: or in the DER (a variant of ASN.1 encoding) binary encoding which is just
  610: an array of unsigned bytes.  The 'i2d' functions converts from the internal
  611: form to the DER form and the 'd2i' functions convert from the DER form to
  612: the internal form.
  613: 
  614: The 'new' function returns a malloc()ed version of the structure with all
  615: substructures either created or left as NULL pointers.  For 'optional'
  616: fields, they are normally left as NULL to indicate no value.  For variable
  617: size sub structures (often 'SET OF' or 'SEQUENCE OF' in ASN.1 syntax) the
  618: STACK data type is used to hold the values.  Have a read of stack.doc
  619: and have a look at the relevant header files to see what I mean.  If there
  620: is an error while malloc()ing the structure, NULL is returned.
  621: 
  622: The 'free' function will free() all the sub components of a particular
  623: structure.  If any of those sub components have been 'removed', replace
  624: them with NULL pointers, the 'free' functions are tolerant of NULL fields.
  625: 
  626: The 'd2i' function copies a binary representation into a C structure.  It
  627: operates as follows.  'a' is a pointer to a pointer to
  628: the structure to populate, 'pp' is a pointer to a pointer to where the DER
  629: byte string is located and 'length' is the length of the '*pp' data.
  630: If there are no errors, a pointer to the populated structure is returned.
  631: If there is an error, NULL is returned.  Errors can occur because of
  632: malloc() failures but normally they will be due to syntax errors in the DER
  633: encoded data being parsed. It is also an error if there was an
  634: attempt to read more that 'length' bytes from '*p'.  If
  635: everything works correctly, the value in '*p' is updated
  636: to point at the location just beyond where the DER
  637: structure was read from.  In this way, chained calls to 'd2i' type
  638: functions can be made, with the pointer into the 'data' array being
  639: 'walked' along the input byte array.
  640: Depending on the value passed for 'a', different things will be done.  If
  641: 'a' is NULL, a new structure will be malloc()ed and returned.  If '*a' is
  642: NULL, a new structure will be malloc()ed and put into '*a' and returned.
  643: If '*a' is not NULL, the structure in '*a' will be populated, or in the
  644: case of an error, free()ed and then returned.
  645: Having these semantics means that a structure
  646: can call a 'd2i' function to populate a field and if the field is currently
  647: NULL, the structure will be created.
  648: 
  649: The 'i2d' function type is used to copy a C structure to a byte array.
  650: The parameter 'a' is the structure to convert and '*p' is where to put it.
  651: As for the 'd2i' type structure, 'p' is updated to point after the last
  652: