ssleay.txt

mediastreamer2是开源的网络传输媒体流的库

==== a_verify.doc ========================================================

From [e-mail] Fri Oct  4 18:29:06 1996
Received: by orb.mincom.oz.au id AA29080
  (5.65c/IDA-1.4.4 for eay); Fri, 4 Oct 1996 08:29:07 +1000
Date: Fri, 4 Oct 1996 08:29:06 +1000 (EST)
From: Eric Young <[e-mail]>
X-Sender: eay@orb
To: wplatzer <[e-mail]>
Cc: Eric Young <[e-mail]>, SSL Mailing List <[e-mail]>
Subject: Re: Netscape's Public Key
In-Reply-To: <[e-mail]>
Message-Id: <Pine.SOL.3.91.961004081346.8018K-100000@orb>
Mime-Version: 1.0
Content-Type: TEXT/PLAIN; charset=US-ASCII
Status: RO
X-Status: 

On Thu, 3 Oct 1996, wplatzer wrote:
> I get Public Key from Netscape (Gold 3.0b4), but cannot do anything
> with it... It looks like (asn1parse):
> 
> 0:d=0 hl=3 l=180 cons: SEQUENCE
> 3:d=1 hl=2 l= 96 cons: SEQUENCE
> 5:d=2 hl=2 l= 92 cons: SEQUENCE
> 7:d=3 hl=2 l= 13 cons: SEQUENCE
> 9:d=4 hl=2 l= 9 prim: OBJECT :rsaEncryption
> 20:d=4 hl=2 l= 0 prim: NULL
> 22:d=3 hl=2 l= 75 prim: BIT STRING
> 99:d=2 hl=2 l= 0 prim: IA5STRING :
> 101:d=1 hl=2 l= 13 cons: SEQUENCE
> 103:d=2 hl=2 l= 9 prim: OBJECT :md5withRSAEncryption
> 114:d=2 hl=2 l= 0 prim: NULL
> 116:d=1 hl=2 l= 65 prim: BIT STRING
> 
> The first BIT STRING is the public key and the second BIT STRING is 
> the signature.
> But a public key consists of the public exponent and the modulus. Are 
> both numbers in the first BIT STRING?
> Is there a document simply describing this coding stuff (checking 
> signature, get the public key, etc.)?

Minimal in SSLeay.  If you want to see what the modulus and exponent are,
try asn1parse -offset 25 -length 75 <key.pem
asn1parse will currently stuff up on the 'length 75' part (fixed in next 
release) but it will print the stuff.  If you are after more 
documentation on ASN.1, have a look at www.rsa.com and get their PKCS 
documents, most of my initial work on SSLeay was done using them.

As for SSLeay,
util/crypto.num and util/ssl.num are lists of all exported functions in 
the library (but not macros :-(.

The ones for extracting public keys from certificates and certificate 
requests are EVP_PKEY *      X509_REQ_extract_key(X509_REQ *req);
EVP_PKEY *      X509_extract_key(X509 *x509);

To verify a signature on a signed ASN.1 object
int X509_verify(X509 *a,EVP_PKEY *key);
int X509_REQ_verify(X509_REQ *a,EVP_PKEY *key);
int X509_CRL_verify(X509_CRL *a,EVP_PKEY *key);
int NETSCAPE_SPKI_verify(NETSCAPE_SPKI *a,EVP_PKEY *key);

I should mention that EVP_PKEY can be used to hold a public or a private key,
since for  things like RSA and DSS, a public key is just a subset of what 
is stored for the private key.

To sign any of the above structures

int X509_sign(X509 *a,EVP_PKEY *key,EVP_MD *md);
int X509_REQ_sign(X509_REQ *a,EVP_PKEY *key,EVP_MD *md);
int X509_CRL_sign(X509_CRL *a,EVP_PKEY *key,EVP_MD *md);
int NETSCAPE_SPKI_sign(NETSCAPE_SPKI *a,EVP_PKEY *key,EVP_MD *md);

where md is the message digest to sign with.

There are all defined in x509.h and all the _sign and _verify functions are
actually macros to the ASN1_sign() and ASN1_verify() functions.
These functions will put the correct algorithm identifiers in the correct 
places in the structures.

eric
--
Eric Young                  | BOOL is tri-state according to Bill Gates.
AARNet: [e-mail]    | RTFM Win32 GetMessage().

==== x509 =======================================================

X509_verify()
X509_sign()

X509_get_version()
X509_get_serialNumber()
X509_get_issuer()
X509_get_subject()
X509_get_notBefore()
X509_get_notAfter()
X509_get_pubkey()

X509_set_version()
X509_set_serialNumber()
X509_set_issuer()
X509_set_subject()
X509_set_notBefore()
X509_set_notAfter()
X509_set_pubkey()

X509_get_extensions()
X509_set_extensions()

X509_EXTENSIONS_clear()
X509_EXTENSIONS_retrieve()
X509_EXTENSIONS_add()
X509_EXTENSIONS_delete()

==== x509 attribute ================================================

PKCS7
	STACK of X509_ATTRIBUTES
		ASN1_OBJECT
		STACK of ASN1_TYPE

So it is

p7.xa[].obj
p7.xa[].data[]

get_obj_by_nid(STACK , nid)
get_num_by_nid(STACK , nid)
get_data_by_nid(STACK , nid, index)

X509_ATTRIBUTE *X509_ATTRIBUTE_new(void );
void		X509_ATTRIBUTE_free(X509_ATTRIBUTE *a);

X509_ATTRIBUTE *X509_ATTRIBUTE_create_by_NID(X509_ATTRIBUTE **ex,
			int nid, STACK *value);

X509_ATTRIBUTE *X509_ATTRIBUTE_create_by_OBJ(X509_ATTRIBUTE **ex,
			int nid, STACK *value);

int		X509_ATTRIBUTE_set_object(X509_ATTRIBUTE *ex,ASN1_OBJECT *obj);
int		X509_ATTRIBUTE_add_data(X509_ATTRIBUTE *ex, int index,
			ASN1_TYPE *value);

ASN1_OBJECT *	X509_ATTRIBUTE_get_object(X509_ATTRIBUTE *ex);
int 		X509_ATTRIBUTE_get_num(X509_ATTRIBUTE *ne);
ASN1_TYPE *	X509_ATTRIBUTE_get_data(X509_ATTRIBUTE *ne,int index);

ASN1_TYPE *	X509_ATTRIBUTE_get_data_by_NID(X509_ATTRIBUTE *ne,
			ASN1_OBJECT *obj);

X509_ATTRIBUTE *PKCS7_get_s_att_by_NID(PKCS7 *p7,int nid);
X509_ATTRIBUTE *PKCS7_get_u_att_by_NID(PKCS7 *p7,int nid);

==== x509 v3 ========================================================

The 'new' system.

The X509_EXTENSION_METHOD includes extensions and attributes and/or names. 
Basically everthing that can be added to an X509 with an OID identifying it.

It operates via 2 methods per object id.
int a2i_XXX(X509 *x,char *str,int len);
int i2a_XXX(BIO *bp,X509 *x);

The a2i_XXX function will add the object with a value converted from the
string into the X509.  Len can be -1 in which case the length is calculated
via strlen(str).   Applications can always use direct knowledge to load and
unload the relevent objects themselves.

i2a_XXX will print to the passed BIO, a text representation of the
relevet object.  Use a memory BIO if you want it printed to a buffer :-).

X509_add_by_NID(X509 *x,int nid,char *str,int len);
X509_add_by_OBJ(X509 *x,ASN1_OBJECT *obj,char *str,int len);

X509_print_by_name(BIO *bp,X509 *x);
X509_print_by_NID(BIO *bp,X509 *x);
X509_print_by_OBJ(BIO *bp,X509 *x);

==== verify ========================================================

X509_verify_cert_chain(
	CERT_STORE *cert_store,
	STACK /* X509 */ *certs,
	int *verify_result,
	int (*verify_error_callback)()
	char *argument_to_callback, /* SSL */

app_verify_callback(
	char *app_verify_arg, /* from SSL_CTX */
	STACK /* X509 */ *certs,
	int *verify_result,
	int (*verify_error_callback)()
	SSL *s,

int X509_verify_cert(
	CERT_STORE *cert_store,
	X509 *x509,
	int *verify_result,
	int (*verify_error_callback)(),
	char *arg,

==== apps.doc ========================================================

The applications

Ok, where to begin....
In the begining, when SSLeay was small (April 1995), there
were but few applications, they did happily cohabit in
the one bin directory.  Then over time, they did multiply and grow,
and they started to look like microsoft software; 500k to print 'hello world'.
A new approach was needed.  They were coalessed into one 'Monolithic'
application, ssleay.  This one program is composed of many programs that
can all be compiled independantly.

ssleay has 3 modes of operation.
1) If the ssleay binaray has the name of one of its component programs, it
executes that program and then exits.  This can be achieve by using hard or
symbolic links, or failing that, just renaming the binary.
2) If the first argument to ssleay is the name of one of the component
programs, that program runs that program and then exits.
3) If there are no arguments, ssleay enters a 'command' mode.  Each line is
interpreted as a program name plus arguments.  After each 'program' is run,
ssleay returns to the comand line.

dgst	- message digests
enc	- encryption and base64 encoding

ans1parse - 'pulls' appart ASN.1 encoded objects like certificates.

dh	- Diffle-Hellman parameter manipulation.
rsa	- RSA manipulations.
crl	- Certificate revokion list manipulations
x509	- X509 cert fiddles, including signing.
pkcs7	- pkcs7 manipulation, only DER versions right now.

genrsa	- generate an RSA private key.
gendh	- Generate a set of Diffle-Hellman parameters.
req	- Generate a PKCS#10 object, a certificate request.

s_client - SSL client program
s_server - SSL server program
s_time	 - A SSL protocol timing program
s_mult	 - Another SSL server, but it multiplexes
	   connections.
s_filter - under development

errstr	- Convert SSLeay error numbers to strings.
ca	- Sign certificate requests, and generate
	  certificate revokion lists
crl2pkcs7 - put a crl and certifcates into a pkcs7 object.
speed	- Benchmark the ciphers.
verify	- Check certificates
hashdir - under development

[ there a now a few more options, play with the program to see what they
  are ]

==== asn1.doc ========================================================

The ASN.1 Routines.

ASN.1 is a specification for how to encode structured 'data' in binary form.
The approach I have take to the manipulation of structures and their encoding
into ASN.1 is as follows.

For each distinct structure there are 4 function of the following form
TYPE *TYPE_new(void);
void TYPE_free(TYPE *);
TYPE *d2i_TYPE(TYPE **a,unsigned char **pp,long length);
long i2d_TYPE(TYPE *a,unsigned char **pp); 	/* CHECK RETURN VALUE */

where TYPE is the type of the 'object'.  The TYPE that have these functions
can be in one of 2 forms, either the internal C malloc()ed data structure
or in the DER (a variant of ASN.1 encoding) binary encoding which is just
an array of unsigned bytes.  The 'i2d' functions converts from the internal
form to the DER form and the 'd2i' functions convert from the DER form to
the internal form.

The 'new' function returns a malloc()ed version of the structure with all
substructures either created or left as NULL pointers.  For 'optional'
fields, they are normally left as NULL to indicate no value.  For variable
size sub structures (often 'SET OF' or 'SEQUENCE OF' in ASN.1 syntax) the
STACK data type is used to hold the values.  Have a read of stack.doc
and have a look at the relevant header files to see what I mean.  If there
is an error while malloc()ing the structure, NULL is returned.

The 'free' function will free() all the sub components of a particular
structure.  If any of those sub components have been 'removed', replace
them with NULL pointers, the 'free' functions are tolerant of NULL fields.

The 'd2i' function copies a binary representation into a C structure.  It
operates as follows.  'a' is a pointer to a pointer to
the structure to populate, 'pp' is a pointer to a pointer to where the DER
byte string is located and 'length' is the length of the '*pp' data.
If there are no errors, a pointer to the populated structure is returned.
If there is an error, NULL is returned.  Errors can occur because of
malloc() failures but normally they will be due to syntax errors in the DER
encoded data being parsed. It is also an error if there was an
attempt to read more that 'length' bytes from '*p'.  If
everything works correctly, the value in '*p' is updated
to point at the location just beyond where the DER
structure was read from.  In this way, chained calls to 'd2i' type
functions can be made, with the pointer into the 'data' array being
'walked' along the input byte array.
Depending on the value passed for 'a', different things will be done.  If
'a' is NULL, a new structure will be malloc()ed and returned.  If '*a' is
NULL, a new structure will be malloc()ed and put into '*a' and returned.
If '*a' is not NULL, the structure in '*a' will be populated, or in the
case of an error, free()ed and then returned.
Having these semantics means that a structure
can call a 'd2i' function to populate a field and if the field is currently
NULL, the structure will be created.

The 'i2d' function type is used to copy a C structure to a byte array.
The parameter 'a' is the structure to convert and '*p' is where to put it.
As for the 'd2i' type structure, 'p' is updated to point after the last
byte written.  If p is NULL, no data is written.  The function also returns
the number of bytes written.  Where this becomes useful is that if the
function is called with a NULL 'p' value, the length is returned.  This can
then be used to malloc() an array of bytes and then the same function can
be recalled passing the malloced array to be written to. e.g.

int len;
unsigned char *bytes,*p;
len=i2d_X509(x,NULL);	/* get the size of the ASN1 encoding of 'x' */
if ((bytes=(unsigned char *)malloc(len)) == NULL)
	goto err;
p=bytes;
i2d_X509(x,&p);