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
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(
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 ========================================================
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.
EXAMPLES.
-So lets play at being a wierd SSL server.
+So lets play at being a weird SSL server.
/* setup a context */
ctx=SSL_CTX_new();
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 IRIX it is correct
+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.
projects / openssl.git / blobdiff