ssleay.txt

==== ssl-ciph.doc ========================================================

This is a quick high level summery of how things work now.

Each SSLv2 and SSLv3 cipher is composed of 4 major attributes plus a few extra
minor ones.

They are 'The key exchange algorithm', which is RSA for SSLv2 but can also
be Diffle-Hellman for SSLv3.

An 'Authenticion algorithm', which can be RSA, Diffle-Helman, DSS or
none.

The cipher

The MAC digest.

A cipher can also be an export cipher and is either an SSLv2 or a
SSLv3 ciphers.

To specify which ciphers to use, one can either specify all the ciphers,
one at a time, or use 'aliases' to specify the preference and order for
the ciphers.

There are a large number of aliases, but the most importaint are
kRSA, kDHr, kDHd and kEDH for key exchange types.

aRSA, aDSS, aNULL and aDH for authentication
DES, 3DES, RC4, RC2, IDEA and eNULL for ciphers
MD5, SHA0 and SHA1 digests

Now where this becomes interesting is that these can be put together to
specify the order and ciphers you wish to use.

To speed this up there are also aliases for certian groups of ciphers.
The main ones are
SSLv2	- all SSLv2 ciphers
SSLv3	- all SSLv3 ciphers
EXP	- all export ciphers
LOW	- all low strngth ciphers (no export ciphers, normally single DES)
MEDIUM	- 128 bit encryption
HIGH	- Triple DES

These aliases can be joined in a : separated list which specifies to
add ciphers, move them to the current location and delete them.

A simpler way to look at all of this is to use the 'ssleay ciphers -v' command.
The default library cipher spec is
!ADH:RC4+RSA:HIGH:MEDIUM:LOW:EXP:+SSLv2:+EXP
which means, first, remove from consideration any ciphers that do not
authenticate.  Next up, use ciphers using RC4 and RSA.  Next include the HIGH,
MEDIUM and the LOW security ciphers.  Finish up by adding all the export
ciphers on the end, then 'pull' all the SSLv2 and export ciphers to
the end of the list.

The results are
$ ssleay ciphers -v '!ADH:RC4+RSA:HIGH:MEDIUM:LOW:EXP:+SSLv2:+EXP'

RC4-SHA                 SSLv3 Kx=RSA      Au=RSA  Enc=RC4(128)  Mac=SHA1
RC4-MD5                 SSLv3 Kx=RSA      Au=RSA  Enc=RC4(128)  Mac=MD5 
EDH-RSA-DES-CBC3-SHA    SSLv3 Kx=DH       Au=RSA  Enc=3DES(168) Mac=SHA1
EDH-DSS-DES-CBC3-SHA    SSLv3 Kx=DH       Au=DSS  Enc=3DES(168) Mac=SHA1
DES-CBC3-SHA            SSLv3 Kx=RSA      Au=RSA  Enc=3DES(168) Mac=SHA1
IDEA-CBC-MD5            SSLv3 Kx=RSA      Au=RSA  Enc=IDEA(128) Mac=SHA1
EDH-RSA-DES-CBC-SHA     SSLv3 Kx=DH       Au=RSA  Enc=DES(56)   Mac=SHA1
EDH-DSS-DES-CBC-SHA     SSLv3 Kx=DH       Au=DSS  Enc=DES(56)   Mac=SHA1
DES-CBC-SHA             SSLv3 Kx=RSA      Au=RSA  Enc=DES(56)   Mac=SHA1
DES-CBC3-MD5            SSLv2 Kx=RSA      Au=RSA  Enc=3DES(168) Mac=MD5 
DES-CBC-MD5             SSLv2 Kx=RSA      Au=RSA  Enc=DES(56)   Mac=MD5 
IDEA-CBC-MD5            SSLv2 Kx=RSA      Au=RSA  Enc=IDEA(128) Mac=MD5 
RC2-CBC-MD5             SSLv2 Kx=RSA      Au=RSA  Enc=RC2(128)  Mac=MD5 
RC4-MD5                 SSLv2 Kx=RSA      Au=RSA  Enc=RC4(128)  Mac=MD5 
EXP-EDH-RSA-DES-CBC     SSLv3 Kx=DH(512)  Au=RSA  Enc=DES(40)   Mac=SHA1 export
EXP-EDH-DSS-DES-CBC-SHA SSLv3 Kx=DH(512)  Au=DSS  Enc=DES(40)   Mac=SHA1 export
EXP-DES-CBC-SHA         SSLv3 Kx=RSA(512) Au=RSA  Enc=DES(40)   Mac=SHA1 export
EXP-RC2-CBC-MD5         SSLv3 Kx=RSA(512) Au=RSA  Enc=RC2(40)   Mac=MD5  export
EXP-RC4-MD5             SSLv3 Kx=RSA(512) Au=RSA  Enc=RC4(40)   Mac=MD5  export
EXP-RC2-CBC-MD5         SSLv2 Kx=RSA(512) Au=RSA  Enc=RC2(40)   Mac=MD5  export
EXP-RC4-MD5             SSLv2 Kx=RSA(512) Au=RSA  Enc=RC4(40)   Mac=MD5  export

I would recoment people use the 'ssleay ciphers -v "text"'
command to check what they are going to use.

Anyway, I'm falling asleep here so I'll do some more tomorrow.

eric

==== ssl.doc ========================================================

SSL_CTX_sessions(SSL_CTX *ctx) - the session-id hash table.

/* Session-id cache stats */
SSL_CTX_sess_number
SSL_CTX_sess_connect
SSL_CTX_sess_connect_good
SSL_CTX_sess_accept
SSL_CTX_sess_accept_good
SSL_CTX_sess_hits
SSL_CTX_sess_cb_hits
SSL_CTX_sess_misses
SSL_CTX_sess_timeouts

/* Session-id application notification callbacks */
SSL_CTX_sess_set_new_cb
SSL_CTX_sess_get_new_cb
SSL_CTX_sess_set_get_cb
SSL_CTX_sess_get_get_cb

/* Session-id cache operation mode */
SSL_CTX_set_session_cache_mode
SSL_CTX_get_session_cache_mode

/* Set default timeout values to use. */
SSL_CTX_set_timeout
SSL_CTX_get_timeout

/* Global  SSL initalisation informational callback */
SSL_CTX_set_info_callback
SSL_CTX_get_info_callback
SSL_set_info_callback
SSL_get_info_callback

/* If the SSL_accept/SSL_connect returned with -1, these indicate when
 * we should re-call *.
SSL_want
SSL_want_nothing
SSL_want_read
SSL_want_write
SSL_want_x509_lookup

/* Where we are in SSL initalisation, used in non-blocking, perhaps
 * have a look at ssl/bio_ssl.c */
SSL_state
SSL_is_init_finished
SSL_in_init
SSL_in_connect_init
SSL_in_accept_init

/* Used to set the 'inital' state so SSL_in_connect_init and SSL_in_accept_init
 * can be used to work out which function to call. */
SSL_set_connect_state
SSL_set_accept_state

/* Where to look for certificates for authentication */
SSL_set_default_verify_paths /* calles SSL_load_verify_locations */
SSL_load_verify_locations

/* get info from an established connection */
SSL_get_session
SSL_get_certificate
SSL_get_SSL_CTX

SSL_CTX_new
SSL_CTX_free
SSL_new
SSL_clear
SSL_free

SSL_CTX_set_cipher_list
SSL_get_cipher
SSL_set_cipher_list
SSL_get_cipher_list
SSL_get_shared_ciphers

SSL_accept
SSL_connect
SSL_read
SSL_write

SSL_debug

SSL_get_read_ahead
SSL_set_read_ahead
SSL_set_verify

SSL_pending

SSL_set_fd
SSL_set_rfd
SSL_set_wfd
SSL_set_bio
SSL_get_fd
SSL_get_rbio
SSL_get_wbio

SSL_use_RSAPrivateKey
SSL_use_RSAPrivateKey_ASN1
SSL_use_RSAPrivateKey_file
SSL_use_PrivateKey
SSL_use_PrivateKey_ASN1
SSL_use_PrivateKey_file
SSL_use_certificate
SSL_use_certificate_ASN1
SSL_use_certificate_file

ERR_load_SSL_strings
SSL_load_error_strings

/* human readable version of the 'state' of the SSL connection. */
SSL_state_string
SSL_state_string_long
/* These 2 report what kind of IO operation the library was trying to
 * perform last.  Probably not very usefull. */
SSL_rstate_string
SSL_rstate_string_long

SSL_get_peer_certificate

SSL_SESSION_new
SSL_SESSION_print_fp
SSL_SESSION_print
SSL_SESSION_free
i2d_SSL_SESSION
d2i_SSL_SESSION

SSL_get_time
SSL_set_time
SSL_get_timeout
SSL_set_timeout
SSL_copy_session_id
SSL_set_session
SSL_CTX_add_session
SSL_CTX_remove_session
SSL_CTX_flush_sessions

BIO_f_ssl

/* used to hold information as to why a certificate verification failed */
SSL_set_verify_result
SSL_get_verify_result

/* can be used by the application to associate data with an SSL structure.
 * It needs to be 'free()ed' by the application */
SSL_set_app_data
SSL_get_app_data

/* The following all set values that are kept in the SSL_CTX but
 * are used as the default values when an SSL session is created.
 * They are over writen by the relevent SSL_xxxx functions */

/* SSL_set_verify */
void SSL_CTX_set_default_verify

/* This callback, if set, totaly overrides the normal SSLeay verification
 * functions and should return 1 on success and 0 on failure */
void SSL_CTX_set_cert_verify_callback

/* The following are the same as the equivilent SSL_xxx functions.
 * Only one copy of this information is kept and if a particular
 * SSL structure has a local override, it is totally separate structure.
 */
int SSL_CTX_use_RSAPrivateKey
int SSL_CTX_use_RSAPrivateKey_ASN1
int SSL_CTX_use_RSAPrivateKey_file
int SSL_CTX_use_PrivateKey
int SSL_CTX_use_PrivateKey_ASN1
int SSL_CTX_use_PrivateKey_file
int SSL_CTX_use_certificate
int SSL_CTX_use_certificate_ASN1
int SSL_CTX_use_certificate_file


==== ssl_ctx.doc ========================================================

This is now a bit dated, quite a few of the SSL_ functions could be
SSL_CTX_ functions.  I will update this in the future. 30 Aug 1996

From eay@orb.mincom.oz.au Mon Dec 11 21:37:08 1995
Received: by orb.mincom.oz.au id AA00696
  (5.65c/IDA-1.4.4 for eay); Mon, 11 Dec 1995 11:37:08 +1000
Date: Mon, 11 Dec 1995 11:37:08 +1000 (EST)
From: Eric Young <eay@mincom.oz.au>
X-Sender: eay@orb
To: sameer <sameer@c2.org>
Cc: Eric Young <eay@mincom.oz.au>
Subject: Re: PEM_readX509 oesn't seem to be working
In-Reply-To: <199512110102.RAA12521@infinity.c2.org>
Message-Id: <Pine.SOL.3.91.951211112115.28608D-100000@orb>
Mime-Version: 1.0
Content-Type: TEXT/PLAIN; charset=US-ASCII
Status: RO
X-Status: 

On Sun, 10 Dec 1995, sameer wrote:
> 	OK, that's solved. I've found out that it is saying "no
> certificate set" in SSL_accept because s->conn == NULL
> so there is some place I need to initialize s->conn that I am
> not initializing it.

The full order of things for a server should be.

ctx=SSL_CTX_new();

/* The next line should not really be using ctx->cert but I'll leave it 
 * this way right now... I don't want a X509_ routine to know about an SSL
 * structure, there should be an SSL_load_verify_locations... hmm, I may 
 * add it tonight.
 */
X509_load_verify_locations(ctx->cert,CAfile,CApath);

/* Ok now for each new connection we do the following */
con=SSL_new(ctx);
SSL_set_fd(con,s);
SSL_set_verify(con,verify,verify_callback);

/* set the certificate and private key to use. */
SSL_use_certificate_ASN1(con,X509_certificate);
SSL_use_RSAPrivateKey_ASN1(con,RSA_private_key);

SSL_accept(con);

SSL_read(con)/SSL_write(con);

There is a bit more than that but that is basically the structure.

Create a context and specify where to lookup certificates.

foreach connection
	{
	create a SSL structure
	set the certificate and private key
	do a SSL_accept
	
	we should now be ok
	}

eric
--
Eric Young                  | Signature removed since it was generating
AARNet: eay@mincom.oz.au    | more followups than the message contents :-)



==== ssleay.doc ========================================================

SSLeay: a cryptographic kitchen sink.

1st December 1995
Way back at the start of April 1995, I was looking for a mindless
programming project.  A friend of mine (Tim Hudson) said "why don't you do SSL,
it has DES encryption in it and I would not mind using it in a SSL telnet".
While it was true I had written a DES library in previous years, litle
did I know what an expansive task SSL would turn into.

First of all, the SSL protocol contains DES encryption.  Well and good.  My
DES library was fast and portable.  It also contained the RSA's RC4 stream
cipher.  Again, not a problem, some-one had just posted to sci.crypt
something that was claimed to be RC4.  It also contained IDEA, I had the
specifications, not a problem to implement.  MD5, an RFC, trivial, at most
I could spend a week or so trying to see if I could speed up the
implementation.  All in all a nice set of ciphers.
Then the first 'expantion of the scope', RSA public key
encryption.  Since I did not knowing a thing about public key encryption
or number theory, this appeared quite a daunting task.  Just writing a
big number library would be problomatic in itself, let alone making it fast.
At this point the scope of 'implementing SSL' expands eponentialy.
First of all, the RSA private keys  were being kept in ASN.1 format.
Thankfully the RSA PKCS series of documents explains this format.  So I now
needed to be able to encode and decode arbitary ASN.1 objects.  The Public
keys were embeded in X509 certificates.  Hmm... these are not only
ASN.1 objects but they make up a heirachy of authentication.  To
authenticate a X509 certificate one needs to retrieve it's issuers
certificate etc etc.  Hmm..., so I also need to implement some kind
of certificate management software.  I would also have to implement
software to authenticate certificates.  At this point the support code made
the SSL part of my library look quite small.
Around this time, the first version of SSLeay was released.

Ah, but here was the problem, I was not happy with the code so far.  As may
have become obvious, I had been treating all of this as a learning
exersize, so I have completely written the library myself.  As such, due
to the way it had grown like a fungus, much of the library was not
'elagent' or neat.  There were global and static variables all over the
place, the SSL part did not even handle non-blocking IO.
The Great rewrite began.

As of this point in time, the 'Great rewrite' has almost finished.  So what
follows is an approximate list of what is actually SSLeay 0.5.0

/********* This needs to be updated for 0.6.0+ *************/

---
The library contains the following routines.  Please note that most of these
functions are not specfic for SSL or any other particular cipher
implementation.  I have tried to make all the routines as general purpose
as possible.  So you should not think of this library as an SSL
implemtation, but rather as a library of cryptographic functions
that also contains SSL.  I refer to each of these function groupings as
libraries since they are often capable of functioning as independant
libraries

First up, the general ciphers and message digests supported by the library.

MD2	rfc???, a standard 'by parts' interface to this algorithm.
MD5	rfc???, the same type of interface as for the MD2 library except a
	different algorithm.
SHA	THe Secure Hash Algorithm.  Again the same type of interface as
	MD2/MD5 except the digest is 20 bytes.
SHA1	The 'revised' version of SHA.  Just about identical to SHA except
	for one tweak of an inner loop.
DES	This is my libdes library that has been floating around for the last
	few years.  It has been enhanced for no other reason than completeness.
	It now supports ecb, cbc, cfb, ofb, cfb64, ofb64 in normal mode and
	triple DES modes of ecb, cbc, cfb64 and ofb64.  cfb64 and ofb64 are
	functional interfaces to the 64 bit modes of cfb and ofb used in
	such a way thay they function as single character interfaces.
RC4	The RSA Inc. stream cipher.
RC2	The RSA Inc. block cipher.
IDEA	An implmentation of the IDEA cipher, the library supports ecb, cbc,
	cfb64 and ofb64 modes of operation.

Now all the above mentioned ciphers and digests libraries support high
speed, minimal 'crap in the way' type interfaces.  For fastest and
lowest level access, these routines should be used directly.

Now there was also the matter of public key crypto systems.  These are
based on large integer arithmatic.

BN	This is my large integer library.  It supports all the normal
	arithmentic operations.  It uses malloc extensivly and as such has
	no limits of the size of the numbers being manipulated.  If you
	wish to use 4000 bit RSA moduli, these routines will handle it.
	This library also contains routines to 'generate' prime numbers and
	to test for primality.  The RSA and DH libraries sit on top of this
	library.  As of this point in time, I don't support SHA, but
	when I do add it, it will just sit on top of the routines contained
	in this library.
RSA	This implements the RSA public key algorithm.  It also contains
	routines that will generate a new private/public key pair.
	All the RSA functions conform to the PKCS#1 standard.
DH	This is an implementation of the
	Diffie-Hellman protocol.  There are all the require routines for
	the protocol, plus extra routines that can be used to generate a
	strong prime for use with a specified generator.  While this last
	routine is not generally required by applications implementing DH,
	It is present for completeness and because I thing it is much
	better to be able to 'generate' your own 'magic' numbers as oposed
	to using numbers suplied by others.  I conform to the PKCS#3
	standard where required.

You may have noticed the preceeding section mentions the 'generation' of
prime numbers.  Now this requries the use of 'random numbers'. 

RAND	This psuedo-random number library is based on MD5 at it's core
	and a large internal state (2k bytes).  Once you have entered enough
	seed data into this random number algorithm I don't feel
	you will ever need to worry about it generating predictable output.
	Due to the way I am writing a portable library, I have left the
	issue of how to get good initial random seed data upto the
	application but I do have support routines for saving and loading a
	persistant random number state for use between program runs.
	
Now to make all these ciphers easier to use, a higher level
interface was required.  In this form, the same function would be used to
encrypt 'by parts', via any one of the above mentioned ciphers.

EVP	The Digital EnVeloPe library is quite large.  At it's core are
	function to perform encryption and decryption by parts while using
	an initial parameter to specify which of the 17 different ciphers
	or 4 different message digests to use.  On top of these are implmented
	the digital signature functions, sign, verify, seal and open.
	Base64 encoding of binary data is also done in this library.

PEM	rfc???? describe the format for Privacy Enhanced eMail.
	As part of this standard, methods of encoding digital enveloped
	data is an ascii format are defined.  As such, I use a form of these
	to encode enveloped data.  While at this point in time full support
	for PEM has not been built into the library, a minimal subset of
	the secret key and Base64 encoding is present.  These reoutines are
	mostly used to Ascii encode binary data with a 'type' associated
	with it and perhaps details of private key encryption used to
	encrypt the data.
	
PKCS7	This is another Digital Envelope encoding standard which uses ASN.1
	to encode the data.  At this point in time, while there are some
	routines to encode and decode this binary format, full support is
	not present.
	
As Mentioned, above, there are several different ways to encode
data structures.

ASN1	This library is more a set of primatives used to encode the packing
	and unpacking of data structures.  It is used by the X509
	certificate standard and by the PKCS standards which are used by
	this library.  It also contains routines for duplicating and signing
	the structures asocisated with X509.
	
X509	The X509 library contains routines for packing and unpacking,
	verifying and just about every thing else you would want to do with
	X509 certificates.

PKCS7	PKCS-7 is a standard for encoding digital envelope data
	structures.  At this point in time the routines will load and save
	DER forms of these structees.  They need to be re-worked to support
	the BER form which is the normal way PKCS-7 is encoded.  If the
	previous 2 sentances don't make much sense, don't worry, this
	library is not used by this version of SSLeay anyway.

OBJ	ASN.1 uses 'object identifiers' to identify objects.  A set of
	functions were requred to translate from ASN.1 to an intenger, to a
	character string.  This library provieds these translations
	
Now I mentioned an X509 library.  X509 specified a hieachy of certificates
which needs to be traversed to authenticate particular certificates.

METH	This library is used to push 'methods' of retrieving certificates
	into the library.  There are some supplied 'methods' with SSLeay
	but applications can add new methods if they so desire.
	This library has not been finished and is not being used in this
	version.
	
Now all the above are required for use in the initial point of this project.

SSL	The SSL protocol.  This is a full implmentation of SSL v 2.  It
	support both server and client authentication.  SSL v 3 support
	will be added when the SSL v 3 specification is released in it's
	final form.

Now quite a few of the above mentioned libraries rely on a few 'complex'
data structures.  For each of these I have a library.

Lhash	This is a hash table library which is used extensivly.

STACK	An implemetation of a Stack data structure.

BUF	A simple character array structure that also support a function to
	check that the array is greater that a certain size, if it is not,
	it is realloced so that is it.
	
TXT_DB	A simple memory based text file data base.  The application can specify
	unique indexes that will be enforced at update time.

CONF	Most of the programs written for this library require a configuration
	file.  Instead of letting programs constantly re-implment this
	subsystem, the CONF library provides a consistant and flexable
	interface to not only configuration files but also environment
	variables.

But what about when something goes wrong?
The one advantage (and perhaps disadvantage) of all of these
functions being in one library was the ability to implement a
single error reporting system.
	
ERR	This library is used to report errors.  The error system records
	library number, function number (in the library) and reason
	number.  Multiple errors can be reported so that an 'error' trace
	is created.  The errors can be printed in numeric or textual form.


==== ssluse.doc ========================================================

We have an SSL_CTX which contains global information for lots of
SSL connections.  The session-id cache and the certificate verificate cache.
It also contains default values for use when certificates are used.

SSL_CTX
	default cipher list
	session-id cache
	certificate cache
	default session-id timeout period
	New session-id callback
	Required session-id callback
	session-id stats
	Informational callback
	Callback that is set, overrides the SSLeay X509 certificate
	  verification
	The default Certificate/Private Key pair
	Default read ahead mode.
	Default verify mode and verify callback.  These are not used
	  if the over ride callback mentioned above is used.
	
Each SSL can have the following defined for it before a connection is made.

Certificate
Private key
Ciphers to use
Certificate verify mode and callback
IO object to use in the comunication.
Some 'read-ahead' mode information.
A previous session-id to re-use.

A connection is made by using SSL_connect or SSL_accept.
When non-blocking IO is being used, there are functions that can be used
to determin where and why the SSL_connect or SSL_accept did not complete.
This information can be used to recall the functions when the 'error'
condition has dissapeared.

After the connection has been made, information can be retrived about the
SSL session and the session-id values that have been decided upon.
The 'peer' certificate can be retrieved.

The session-id values include
'start time'
'timeout length'



==== stack.doc ========================================================

The stack data structure is used to store an ordered list of objects.
It is basically misnamed to call it a stack but it can function that way
and that is what I originally used it for.  Due to the way element
pointers are kept in a malloc()ed array, the most efficient way to use this
structure is to add and delete elements from the end via sk_pop() and
sk_push().  If you wish to do 'lookups' sk_find() is quite efficient since
it will sort the stack (if required) and then do a binary search to lookup 
the requested item.  This sorting occurs automatically so just sk_push()
elements on the stack and don't worry about the order.  Do remember that if
you do a sk_find(), the order of the elements will change.

You should never need to 'touch' this structure directly.
typedef struct stack_st
	{
	unsigned int num;
	char **data;
	int sorted;

	unsigned int num_alloc;
	int (*comp)();
	} STACK;

'num' holds the number of elements in the stack, 'data' is the array of
elements.  'sorted' is 1 is the list has been sorted, 0 if not.

num_alloc is the number of 'nodes' allocated in 'data'.  When num becomes
larger than num_alloc, data is realloced to a larger size.
If 'comp' is set, it is a function that is used to compare 2 of the items
in the stack.  The function should return -1, 0 or 1, depending on the
ordering.

#define sk_num(sk)	((sk)->num)
#define sk_value(sk,n)	((sk)->data[n])

These 2 macros should be used to access the number of elements in the
'stack' and to access a pointer to one of the values.

STACK *sk_new(int (*c)());
	This creates a new stack.  If 'c', the comparison function, is not
specified, the various functions that operate on a sorted 'stack' will not
work (sk_find()).  NULL is returned on failure.

void sk_free(STACK *);
	This function free()'s a stack structure.  The elements in the
stack will not be freed so one should 'pop' and free all elements from the
stack before calling this function or call sk_pop_free() instead.

void sk_pop_free(STACK *st; void (*func)());
	This function calls 'func' for each element on the stack, passing
the element as the argument.  sk_free() is then called to free the 'stack'
structure.

int sk_insert(STACK *sk,char *data,int where);
	This function inserts 'data' into stack 'sk' at location 'where'.
If 'where' is larger that the number of elements in the stack, the element
is put at the end.  This function tends to be used by other 'stack'
functions.  Returns 0 on failure, otherwise the number of elements in the
new stack.

char *sk_delete(STACK *st,int loc);
	Remove the item a location 'loc' from the stack and returns it.
Returns NULL if the 'loc' is out of range.

char *sk_delete_ptr(STACK *st, char *p);
	If the data item pointed to by 'p' is in the stack, it is deleted
from the stack and returned.  NULL is returned if the element is not in the
stack.

int sk_find(STACK *st,char *data);
	Returns the location that contains a value that is equal to 
the 'data' item.  If the comparison function was not set, this function
does a linear search.  This function actually qsort()s the stack if it is not
in order and then uses bsearch() to do the initial search.  If the
search fails,, -1 is returned.  For mutliple items with the same
value, the index of the first in the array is returned.

int sk_push(STACK *st,char *data);
	Append 'data' to the stack.  0 is returned if there is a failure
(due to a malloc failure), else 1.  This is 
sk_insert(st,data,sk_num(st));

int sk_unshift(STACK *st,char *data);
	Prepend 'data' to the front (location 0) of the stack.  This is
sk_insert(st,data,0);

char *sk_shift(STACK *st);
	Return and delete from the stack the first element in the stack.
This is sk_delete(st,0);

char *sk_pop(STACK *st);
	Return and delete the last element on the stack.  This is
sk_delete(st,sk_num(sk)-1);

void sk_zero(STACK *st);
	Removes all items from the stack.  It does not 'free'
pointers but is a quick way to clear a 'stack of references'.

==== threads.doc ========================================================

How to compile SSLeay for multi-threading.

Well basically it is quite simple, set the compiler flags and build.
I have only really done much testing under Solaris and Windows NT.
If you library supports localtime_r() and gmtime_r() add,
-DTHREADS to the makefile parameters.  You can probably survive with out
this define unless you are going to have multiple threads generating
certificates at once.  It will not affect the SSL side of things.

The approach I have taken to doing locking is to make the application provide
callbacks to perform locking and so that the SSLeay library can distinguish
between threads (for the error state).

To have a look at an example program, 'cd mt; vi mttest.c'.
To build under solaris, sh solaris.sh, for Windows NT or Windows 95,
win32.bat

This will build mttest which will fire up 10 threads that talk SSL
to each other 10 times.
To enable everything to work, the application needs to call

CRYPTO_set_id_callback(id_function);
CRYPTO_set_locking_callback(locking_function);

before any multithreading is started.
id_function does not need to be defined under Windows NT or 95, the
correct function will be called if it is not.  Under unix, getpid()
is call if the id_callback is not defined, for Solaris this is wrong
(since threads id's are not pid's) but under Linux it is correct
(threads are just processes sharing the data segement).

The locking_callback is used to perform locking by the SSLeay library.
eg.

void solaris_locking_callback(mode,type,file,line)
int mode;
int type;
char *file;
int line;
	{
	if (mode & CRYPTO_LOCK)
		mutex_lock(&(lock_cs[type]));
	else
		mutex_unlock(&(lock_cs[type]));
	}

Now in this case I have used mutexes instead of read/write locks, since they
are faster and there are not many read locks in SSLeay, you may as well
always use write locks.  file and line are __FILE__ and __LINE__ from
the compile and can be usefull when debugging.

Now as you can see, 'type' can be one of a range of values, these values are
defined in crypto/crypto.h
CRYPTO_get_lock_name(type) will return a text version of what the lock is.
There are CRYPTO_NUM_LOCKS locks required, so under solaris, the setup
for multi-threading can be

static mutex_t lock_cs[CRYPTO_NUM_LOCKS];

void thread_setup()
	{
	int i;

	for (i=0; i<CRYPTO_NUM_LOCKS; i++)
		mutex_init(&(lock_cs[i]),USYNC_THREAD,NULL);
	CRYPTO_set_id_callback((unsigned long (*)())solaris_thread_id);
	CRYPTO_set_locking_callback((void (*)())solaris_locking_callback);
	}

As a final note, under Windows NT or Windows 95, you have to be careful
not to mix the various threaded, unthreaded and debug libraries.
Normally if they are mixed incorrectly, mttest will crash just after printing
out some usage statistics at the end.  This is because the
different system libraries use different malloc routines and if
data is malloc()ed inside crypt32.dll or ssl32.dll and then free()ed by a
different library malloc, things get very confused.

The default SSLeay DLL builds use /MD, so if you use this on your
application, things will work as expected.  If you use /MDd,
you will probably have to rebuild SSLeay using this flag.
I should modify util/mk1mf.pl so it does all this correctly, but 
this has not been done yet.

One last warning.  Because locking overheads are actually quite large, the
statistics collected against the SSL_CTX for successfull connections etc
are not locked when updated.  This does make it possible for these
values to be slightly lower than they should be, if you are
running multithreaded on a multi-processor box, but this does not really
matter much.


==== txt_db.doc ========================================================

TXT_DB, a simple text based in memory database.

It holds rows of ascii data, for which the only special character is '\0'.
The rows can be of an unlimited length.

==== why.doc ========================================================

This file is more of a note for other people who wish to understand why
the build environment is the way it is :-).

The include files 'depend' as follows.
Each of 
crypto/*/*.c includes crypto/cryptlib.h
ssl/*.c include ssl/ssl_locl.h
apps/*.c include apps/apps.h
crypto/cryptlib.h, ssl/ssl_locl.h and apps/apps.h
all include e_os.h which contains OS/environment specific information.
If you need to add something todo with a particular environment,
add it to this file.  It is worth remembering that quite a few libraries,
like lhash, des, md, sha etc etc do not include crypto/cryptlib.h.  This
is because these libraries should be 'independantly compilable' and so I
try to keep them this way.
e_os.h is not so much a part of SSLeay, as the placing in one spot all the
evil OS dependant muck.

I wanted to automate as many things as possible.  This includes
error number generation.  A
make errors
will scan the source files for error codes, append them to the correct
header files, and generate the functions to print the text version
of the error numbers.  So don't even think about adding error numbers by
hand, put them in the form
XXXerr(XXXX_F_XXXX,YYYY_R_YYYY);
on line and it will be automatically picked up my a make errors.

In a similar vein, programs to be added into ssleay in the apps directory
just need to have an entry added to E_EXE in makefile.ssl and
everthing will work as expected.  Don't edit progs.h by hand.

make links re-generates the symbolic links that are used.  The reason why
I keep everything in its own directory, and don't put all the
test programs and header files in 'test' and 'include' is because I want
to keep the 'sub-libraries' independant.  I still 'pull' out
indervidual libraries for use in specific projects where the code is
required.  I have used the 'lhash' library in just about every software
project I have worked on :-).

make depend generates dependancies and
make dclean removes them.

You will notice that I use perl quite a bit when I could be using 'sed'.
The reason I decided to do this was to just stick to one 'extra' program.
For Windows NT, I have perl and no sed.

The util/mk1mf.pl program can be used to generate a single makefile.
I use this because makefiles under Microsoft are horrific.
Each C compiler seems to have different linker formats, which have
to be used because the retarted C compilers explode when you do
cl -o file *.o.

Now some would argue that I should just use the single makefile.  I don't
like it during develoment for 2 reasons.  First, the actuall make
command takes a long time.  For my current setup, if I'm in
crypto/bn and I type make, only the crypto/bn directory gets rebuilt,
which is nice when you are modifying prototypes in bn.h which
half the SSLeay depends on.  The second is that to add a new souce file
I just plonk it in at the required spot in the local makefile.  This
then alows me to keep things local, I don't need to modify a 'global'
tables (the make for unix, the make for NT, the make for w31...).
When I am ripping apart a library structure, it is nice to only
have to worry about one directory :-).

Having said all this, for the hell of it I put together 2 files that
#include all the souce code (generated by doing a ls */*.o after a build).
crypto.c takes only 30 seconds to build under NT and 2 minutes under linux
for my pentium100.  Much faster that the normal build :-).
Again, the problem is that when using libraries, every program linked
to libcrypto.a would suddenly get 330k of library when it may only need
1k.  This technique does look like a nice way to do shared libraries though.

Oh yes, as a final note, to 'build' a distribution, I just type
make dist.
This cleans and packages everything.  The directory needs to be called
SSLeay since the make does a 'cd ..' and renames and tars things up.

==== req.1 ========================================================

The 'req' command is used to manipulate and deal with pkcs#10
certificate requests.

It's default mode of operation is to load a certificate and then
write it out again.

By default the 'req' is read from stdin in 'PEM' format.
The -inform option can be used to specify 'pem' format or 'der'
format.  PEM format is the base64 encoding of the DER format.

By default 'req' then writes the request back out. -outform can be used
to indicate the desired output format, be it 'pem' or 'der'.

To specify an input file, use the '-in' option and the '-out' option
can be used to specify the output file.

If you wish to perform a command and not output the certificate
request afterwards, use the '-noout' option.

When a certificate is loaded, it can be printed in a human readable
ascii format via the '-text' option.

To check that the signature on a certificate request is correct, use
the '-verify' option to make sure that the private key contained in the
certificate request corresponds to the signature.

Besides the default mode, there is also the 'generate a certificate
request' mode.  There are several flags that trigger this mode.

-new will generate a new RSA key (if required) and then prompts
the user for details for the certificate request.
-newkey has an argument that is the number of bits to make the new
key.  This function also triggers '-new'.

The '-new' option can have a key to use specified instead of having to
load one, '-key' is used to specify the file containg the key.
-keyform can be used to specify the format of the key.  Only
'pem' and 'der' formats are supported, later, 'netscape' format may be added.

Finally there is the '-x509' options which makes req output a self
signed x509 certificate instead of a certificate request.

Now as you may have noticed, there are lots of default options that
cannot be specified via the command line.  They are held in a 'template'
or 'configuration file'.  The -config option specifies which configuration
file to use.  See conf.doc for details on the syntax of this file.

The req command uses the 'req' section of the config file.

---
# The following variables are defined.  For this example I will populate
# the various values
[ req ]
default_bits	= 512		# default number of bits to use.
default_keyfile	= testkey.pem	# Where to write the generated keyfile
				# if not specified.
distinguished_name= req_dn	# The section that contains the
				# information about which 'object' we
				# want to put in the DN.
attributes	= req_attr	# The objects we want for the
				# attributes field.
encrypt_rsa_key	= no		# Should we encrypt newly generated
				# keys.  I strongly recommend 'yes'.

# The distinguished name section.  For the following entries, the
# object names must exist in the SSLeay header file objects.h.  If they
# do not, they will be silently ignored.  The entries have the following
# format.
# <object_name>		=> string to prompt with
# <object_name>_default	=> default value for people
# <object_name>_value	=> Automatically use this value for this field.
# <object_name>_min	=> minimum number of characters for data (def. 0)
# <object_name>_max	=> maximum number of characters for data (def. inf.)
# All of these entries are optional except for the first one.
[ req_dn ]
countryName			= Country Name (2 letter code)
countryName_default		= AU

stateOrProvinceName		= State or Province Name (full name)
stateOrProvinceName_default	= Queensland

localityName			= Locality Name (eg, city)

organizationName		= Organization Name (eg, company)
organizationName_default	= Mincom Pty Ltd

organizationalUnitName		= Organizational Unit Name (eg, section)
organizationalUnitName_default	= MTR

commonName			= Common Name (eg, YOUR name)
commonName_max			= 64

emailAddress			= Email Address
emailAddress_max		= 40

# The next section is the attributes section.  This is exactly the
# same as for the previous section except that the resulting objects are
# put in the attributes field. 
[ req_attr ]
challengePassword		= A challenge password
challengePassword_min		= 4
challengePassword_max		= 20

unstructuredName		= An optional company name

----
Also note that the order that attributes appear in this file is the
order they will be put into the distinguished name.

Once this request has been generated, it can be sent to a CA for
certifying.

----
A few quick examples....

To generate a new request and a new key
req -new

To generate a new request and a 1058 bit key