diff options
Diffstat (limited to 'doc/ssleay.txt')
-rw-r--r-- | doc/ssleay.txt | 407 |
1 files changed, 407 insertions, 0 deletions
diff --git a/doc/ssleay.txt b/doc/ssleay.txt index c905f6a0d6..094e28ce48 100644 --- a/doc/ssleay.txt +++ b/doc/ssleay.txt @@ -35,6 +35,286 @@ ASN.1 - parsing PEM - parsing +==== ssl/readme ===================================================== + +22 Jun 1996 +This file belongs in ../apps, but I'll leave it here because it deals +with SSL :-) It is rather dated but it gives you an idea of how +things work. +=== + +17 Jul 1995 +I have been changing things quite a bit and have not fully updated +this file, so take what you read with a grain of salt +eric +=== +The s_client and s_server programs can be used to test SSL capable +IP/port addresses and the verification of the X509 certificates in use +by these services. I strongly advise having a look at the code to get +an idea of how to use the authentication under SSLeay. Any feedback +on changes and improvements would be greatly accepted. + +This file will probably be gibberish unless you have read +rfc1421, rfc1422, rfc1423 and rfc1424 which describe PEM +authentication. + +A Brief outline (and examples) how to use them to do so. + +NOTE: +The environment variable SSL_CIPER is used to specify the prefered +cipher to use, play around with setting it's value to combinations of +RC4-MD5, EXP-RC4-MD5, CBC-DES-MD5, CBC3-DES-MD5, CFB-DES-NULL +in a : separated list. + +This directory contains 3 X509 certificates which can be used by these programs. +client.pem: a file containing a certificate and private key to be used + by s_client. +server.pem :a file containing a certificate and private key to be used + by s_server. +eay1024.pem:the certificate used to sign client.pem and server.pem. + This would be your CA's certificate. There is also a link + from the file a8556381.0 to eay1024.PEM. The value a8556381 + is returned by 'x509 -hash -noout <eay1024.pem' and is the + value used by X509 verification routines to 'find' this + certificte when search a directory for it. + [the above is not true any more, the CA cert is + ../certs/testca.pem which is signed by ../certs/mincomca.pem] + +When testing the s_server, you may get +bind: Address already in use +errors. These indicate the port is still being held by the unix +kernel and you are going to have to wait for it to let go of it. If +this is the case, remember to use the port commands on the s_server and +s_client to talk on an alternative port. + +===== +s_client. +This program can be used to connect to any IP/hostname:port that is +talking SSL. Once connected, it will attempt to authenticate the +certificate it was passed and if everything works as expected, a 2 +directional channel will be open. Any text typed will be sent to the +other end. type Q<cr> to exit. Flags are as follows. +-host arg : Arg is the host or IP address to connect to. +-port arg : Arg is the port to connect to (https is 443). +-verify arg : Turn on authentication of the server certificate. + : Arg specifies the 'depth', this will covered below. +-cert arg : The optional certificate to use. This certificate + : will be returned to the server if the server + : requests it for client authentication. +-key arg : The private key that matches the certificate + : specified by the -cert option. If this is not + : specified (but -cert is), the -cert file will be + : searched for the Private key. Both files are + : assumed to be in PEM format. +-CApath arg : When to look for certificates when 'verifying' the + : certificate from the server. +-CAfile arg : A file containing certificates to be used for + : 'verifying' the server certificate. +-reconnect : Once a connection has been made, drop it and + : reconnect with same session-id. This is for testing :-). + +The '-verify n' parameter specifies not only to verify the servers +certificate but to also only take notice of 'n' levels. The best way +to explain is to show via examples. +Given +s_server -cert server.PEM is running. + +s_client + CONNECTED + depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo server + issuer= /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA + verify error:num=1:unable to get issuer certificate + verify return:1 + CIPHER is CBC-DES-MD5 +What has happened is that the 'SSLeay demo server' certificate's +issuer ('CA') could not be found but because verify is not on, we +don't care and the connection has been made anyway. It is now 'up' +using CBC-DES-MD5 mode. This is an unauthenticate secure channel. +You may not be talking to the right person but the data going to them +is encrypted. + +s_client -verify 0 + CONNECTED + depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo server + issuer= /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA + verify error:num=1:unable to get issuer certificate + verify return:1 + CIPHER is CBC-DES-MD5 +We are 'verifying' but only to depth 0, so since the 'SSLeay demo server' +certificate passed the date and checksum, we are happy to proceed. + +s_client -verify 1 + CONNECTED + depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo server + issuer= /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA + verify error:num=1:unable to get issuer certificate + verify return:0 + ERROR + verify error:unable to get issuer certificate +In this case we failed to make the connection because we could not +authenticate the certificate because we could not find the +'CA' certificate. + +s_client -verify 1 -CAfile eay1024.PEM + CONNECTED + depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo server + verify return:1 + depth=1 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA + verify return:1 + CIPHER is CBC-DES-MD5 +We loaded the certificates from the file eay1024.PEM. Everything +checked out and so we made the connection. + +s_client -verify 1 -CApath . + CONNECTED + depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo server + verify return:1 + depth=1 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA + verify return:1 + CIPHER is CBC-DES-MD5 +We looked in out local directory for issuer certificates and 'found' +a8556381.0 and so everything is ok. + +It is worth noting that 'CA' is a self certified certificate. If you +are passed one of these, it will fail to 'verify' at depth 0 because +we need to lookup the certifier of a certificate from some information +that we trust and keep locally. + +SSL_CIPHER=CBC3-DES-MD5:RC4-MD5 +export SSL_CIPHER +s_client -verify 10 -CApath . -reconnect + CONNECTED + depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo server + verify return:1 + depth=1 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA + verify return:1 + drop the connection and reconnect with the same session id + CIPHER is CBC3-DES-MD5 +This has done a full connection and then re-estabished it with the +same session id but a new socket. No RSA stuff occures on the second +connection. Note that we said we would prefer to use CBC3-DES-MD5 +encryption and so, since the server supports it, we are. + +===== +s_server +This program accepts SSL connections on a specified port +Once connected, it will estabish an SSL connection and optionaly +attempt to authenticate the client. A 2 directional channel will be +open. Any text typed will be sent to the other end. Type Q<cr> to exit. +Flags are as follows. +-port arg : Arg is the port to listen on. +-verify arg : Turn on authentication of the client if they have a + : certificate. Arg specifies the 'depth'. +-Verify arg : Turn on authentication of the client. If they don't + : have a valid certificate, drop the connection. +-cert arg : The certificate to use. This certificate + : will be passed to the client. If it is not + : specified, it will default to server.PEM +-key arg : The private key that matches the certificate + : specified by the -cert option. If this is not + : specified (but -cert is), the -cert file will be + : searched for the Private key. Both files are + : assumed to be in PEM format. Default is server.PEM +-CApath arg : When to look for certificates when 'verifying' the + : certificate from the client. +-CAfile arg : A file containing certificates to be used for + : 'verifying' the client certificate. + +For the following 'demo' I will specify the s_server command and +the s_client command and then list the output from the s_server. +s_server +s_client + CONNECTED + CIPHER is CBC-DES-MD5 +Everything up and running + +s_server -verify 0 +s_client + CONNECTED + CIPHER is CBC-DES-MD5 +Ok since no certificate was returned and we don't care. + +s_server -verify 0 +./s_client -cert client.PEM + CONNECTED + depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo client + issuer= /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA + verify error:num=1:unable to get issuer certificate + verify return:1 + CIPHER is CBC-DES-MD5 +Ok since we were only verifying to level 0 + +s_server -verify 4 +s_client -cert client.PEM + CONNECTED + depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo client + issuer= /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA + verify error:num=1:unable to get issuer certificate + verify return:0 + ERROR + verify error:unable to get issuer certificate +Bad because we could not authenticate the returned certificate. + +s_server -verify 4 -CApath . +s_client -cert client.PEM + CONNECTED + depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo client + verify return:1 + depth=1 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA + verify return:1 + CIPHER is CBC-DES-MD5 +Ok because we could authenticate the returned certificate :-). + +s_server -Verify 0 -CApath . +s_client + CONNECTED + ERROR + SSL error:function is:REQUEST_CERTIFICATE + :error is :client end did not return a certificate +Error because no certificate returned. + +s_server -Verify 4 -CApath . +s_client -cert client.PEM + CONNECTED + depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo client + verify return:1 + depth=1 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA + verify return:1 + CIPHER is CBC-DES-MD5 +Full authentication of the client. + +So in summary to do full authentication of both ends +s_server -Verify 9 -CApath . +s_client -cert client.PEM -CApath . -verify 9 +From the server side + CONNECTED + depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo client + verify return:1 + depth=1 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA + verify return:1 + CIPHER is CBC-DES-MD5 +From the client side + CONNECTED + depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo server + verify return:1 + depth=1 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA + verify return:1 + CIPHER is CBC-DES-MD5 + +For general probing of the 'internet https' servers for the +distribution area, run +s_client -host www.netscape.com -port 443 -verify 4 -CApath ../rsa/hash +Then enter +GET / +and you should be talking to the https server on that host. + +www.rsa.com was refusing to respond to connections on 443 when I was +testing. + +have fun :-). + +eric + ==== a_verify.doc ======================================================== From eay@mincom.com Fri Oct 4 18:29:06 1996 @@ -121,6 +401,100 @@ eric Eric Young | BOOL is tri-state according to Bill Gates. AARNet: eay@mincom.oz.au | 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( @@ -1562,6 +1936,10 @@ char *cb_arg callback(1,round++,cb_arg). Each successful 'round' in BN_is_prime(). callback(2,round,cb_arg). For each successful BN_is_prime() test. +Hints +----- + +DSA wants 64*32 to use word mont mul, but RSA wants to use full. ==== callback.doc ======================================================== @@ -4518,6 +4896,35 @@ int (*cmp)()); normal system bsearch(3) if it is present. This version also has tolerance of being passed NULL pointers. +==== keys =========================================================== + +EVP_PKEY_DSA +EVP_PKEY_DSA2 +EVP_PKEY_DSA3 +EVP_PKEY_DSA4 + +EVP_PKEY_RSA +EVP_PKEY_RSA2 + +valid DSA pkey types + NID_dsa + NID_dsaWithSHA + NID_dsaWithSHA1 + NID_dsaWithSHA1_2 + +valid RSA pkey types + NID_rsaEncryption + NID_rsa + +NID_dsaWithSHA NID_dsaWithSHA DSA SHA +NID_dsa NID_dsaWithSHA1 DSA SHA1 +NID_md2 NID_md2WithRSAEncryption RSA-pkcs1 MD2 +NID_md5 NID_md5WithRSAEncryption RSA-pkcs1 MD5 +NID_mdc2 NID_mdc2WithRSA RSA-none MDC2 +NID_ripemd160 NID_ripemd160WithRSA RSA-pkcs1 RIPEMD160 +NID_sha NID_shaWithRSAEncryption RSA-pkcs1 SHA +NID_sha1 NID_sha1WithRSAEncryption RSA-pkcs1 SHA1 + ==== rand.doc ======================================================== My Random number library. |