This loads certificates from the "standard" locations and from whatever the standard environment variables point to.

The default values in rsa/location.h are:

 #define SSL_CERT_DIR           "/usr/local/ssl/certs"
 #define SSL_CERT_FILE  "/usr/local/ssl/cert.pem"
 
 #define SSL_CERT_DIR_ENV       "SSL_CERT_DIR"
 #define SSL_CERT_FILE_ENV      "SSL_CERT_FILE"

Note: the verify and x509 utility programs use X509_set_default_verify_paths() so if you want different behaviour you will have to change the calls in those programs.

2. Certificate Verification Process

Certificate verification is controlled by ssl_set_verify. This sets the verify mode and the optional callback function.

 void ssl_set_verify(SSL *s,int mode, int (*callback)() )

Supported modes are:

• SSL_VERIFY_NONE
  

• SSL_VERIFY_PEER
  

• SSL_VERIFY_FAIL_IF_NO_PEER_CERT
  

If SSL_VERIFY_PEER then the server will request a certificate from the client during initial protocol negotiation. If the client does not provide one and SSL_FAIL_IF_NO_PEER_CERT is being used then the verification process will fail and the caller will be returned an error code from ssl_accept().

From the client point of view, if SSL_VERIFY_PEER is set then the client will verify the server's certificate.

The callback function can be used to control the entire certificate hierarchy trust policy. It is called after each attempted verification of a certificate - either because the certificate was received or a certificate was referenced during traversal of the Certifying Authority hierarchy.

 int (*callback)(int ok,X509 *subj_cert,X509 *issuer_cert,
                 int depth,int errorcode)

ok is set to 1 if the X509 certificate is syntactically "valid" and has been verified (i.e. the checksum is okay, date range correct, etc). The callback function can return either 1 to accept, or 0 to reject - i.e. the return value would have been ok if there was no callback function registered.

subj_cert is the certificate of the subject

issuer_cert is the certificate of the issuer (the signer of the subjects certificate). It may be NULL (if there is an error).

depth is the recursion depth. A depth of 1 indicates that you are attempting to verify the issuer of the subjects certificate. If you do not wish to traverse the CA hierarchy simply return 1 when the depth is greater than or equal to 1.

errorcode is one of the VERIFY_ERR_ defines from rsa/X509.h. VERIFY_OK indicates that there is no error.

TODO: There are lots of X509 interface routines that you will have to look at if you actually want to do anything useful with certificates :-)

Have a look at rsa/verify.c for a decent example usage of this stuff.

The following are probably of the most imediate use in the callback function:

2.0.1 X509_NAME_oneline

To turn a X509_NAME encoding into a "normal" string:

 char *X509_NAME_oneline(X509_NAME *name)

It is the responsibility of the caller to free() the returned string.

3. Generating and Signing Certificates

There are five programs in the rsa directory that are required for generating and managing certificates.

The following two environment variables influence the behaviour of the certificate verification process in verify and x509.

• SSL_CERT_DIR
  

• SSL_CERT_FILE
  

It is considered a good idea for all implementations to standarise on usage of these environment variables.

3.1 genrsa

Used to generate RSA private keys.

 genrsa [-des|-idea] [-rand file:file:file] [-F4|-3] [numbits] > key

Number of bits to make the RSA private key, default of 512. writes to stdout when finished, in PEM format. If the des or idea option are used you will be prompted for a pass phrase.

The random number generator can be seeded with a series of files. Each file will have the stat(2) information and the contents of the complete file used.

The public exponent can be set using -F4 or -3 if you desire to deviate from the SSLeay default of F4.

3.2 verify

To verify that a certificate is "okay"

 verify [-CApath path] [-CAfile filename] file1 [file2 ...]

verify will attempt to verify a certificate via either looking through a directory or simply a single file - this behaviour is compiled into the program and you really should decide what your "site" default for this is.

verify requires the arguments to be in PEM format and the lookup files also must be in PEM format.

You may want to tailor this program (or rsa/location.h as it has hard coded paths for the location for the certificates used to verify. Note that you can use the environment variables SSL_CERT_DIR and SSL_CERT_FILE or the command line args CApath and CAfile to influence the location used.

3.3 rsa

Convert keys from one format to another - i.e. rsa is a filter.

 rsa [-des|-idea] [-inform format] [-outform format]
     [-in infile] [-out outfile]

 rsa -des < in >out

 x509
     [-inform format]
     [-outform format]
     [-keyform format]
     [-CAform format]
     [-CAkeyform format]
     [-in input-filename]
     [-out output-filename]
     [-signkey self-signing-key-filename]
     [-CA certifying-authority-certificate-filename]
     [-CAkey certifying-authority-key-filename]
     [-CAcreateserial]
     [-RSAreq private-key-filename]
     [-days]
     [-CAserial filename]
 
 Output options:
     [-serial]     prints the serial number
     [-hash]       prints the hash vaulue used to dir lookups
     [-subject]    prints the cert's subject DN
     [-issuer]     prints the cert's issuer DN
     [-startdate]  prints the cert's notBefore field
     [-enddate]    prints the cert's notAfter field
     [-noout]      do not display the certificate

 x509 -noout -subject -issuer -enddate < filename

 req -newkey 512 -new  > MINCOM.pem

 req -in MINCOM.pem -verify -noout

 # generate your private+public key
 req -newkey 512 -new  > MINCOM.pem
 
 # check that we can at least verify the checksum ourselves
 req -in MINCOM.pem -verify -noout

 # SSLeay 0.5.0b+ (21-Dec-95) supports a quick mechanism for 
generating
 #                            "dummy" certificates
 cd /usr/local/ssl/certs
 req -new -x509 -nodes -out telnetd.pem -keyout telnetd.pem
 ln -s telnetd.pem `x509 -noout -hash < telnetd.pem`.0