

This file contains descriptions of the tools used in the ns/cmd/security
directory. Some of these tools are outlined as follows:

	keyutil 	Generating, storing, and retrieving keys
	
	certutil	Multi-purpose certificate tool
	
	pp		Printing human-readable cert, certreq, and key info

	atob, btoa	Converts ASCII to binary and vice-versa

	tstclnt-us	Connects to https servers with SSL
	tstclnt-ex	Same as above, but export version


Code Checkout


The security directory has a few dependencies on other directories. Here
is an example of a bare minimum cvs checkout that should get you started:

        cd ns/..

	cvs co ns/coreconf
	cvs co ns/security


Compiling

Once you've set everything up properly, you should be able to build:

	cd ns/coreconf

	gmake

	cd ../cmd/security

	gmake import
	gmake


After you gmake from this directory, you should have a ($ARCH).OBJ directory
which will contain all of the top-level tool binaries.






Generating Keys and Certificates


In order to create keys and a certificate to use, there are two programs
that you will need to run: keyutil and certutil. These will
require key and certificate databases. It would be useful to create a 
testing directory to hold these files, such as ~/ssltest. 

You will end up generating three databases files: key.db, cert.db, and 
secmod.db. 

NOTE: It is *very* important that you remember the nicknames you ascribe
to your keys and certificates. You will need these in order to access your
keys and certs to print out information about them.  There are currently no 
tools you can use to list out all of the nicknames in the key database. 
Additionally, it is helpful to give the same nickname to a certificate as to 
the key with which it is bound.

Here is an example of a user 'jdoe' generating a key and a certficate for
personal use:

	mkdir ~/ssl
	certutil -G -n jdoe -d ~/ssl
	certutil -R -n jdoe -d ~/ssl -a -p 123-456-7890 -s "CN=John Doe, \
	     E=jdoe@com.com, C=US, ST=CA, L=Somewhere, \
	     O=Some Corporation" > outputfile

You should see something in the output which looks like:

    Certificate request generated by certutil
    Phone: 123-456-7890

    Common Name: John Doe
    Email: jdoe@com.com
    Organization: Some Corporation
    State: CA
    Country: US

    -----BEGIN NEW CERTIFICATE REQUEST-----
    MIIB1DCCAT0CAQAwgZUxETAPBgNVBAMTCEpvaG4gRG9lMSAwHgYJKoZIhvcNAQkB
    FhFqZG9lQG5ldHNjYXBlLmNvbTELMAkGA1UEBhMCVVMxCzAJBgNVBAgTAkNBMRYw
    FAYDVQQHEw1Nb3VudGFpbiBWaWV3MSwwKgYDVQQKEyNOZXRzY2FwZSBDb21tdW5p
    Y2F0aW9ucyBDb3Jwb3JhdGlvbjCBnTANBgkqhkiG9w0BAQEFAAOBiwAwgYcCgYEA
    uYidwIwFpDnGmhibk5/l8HdIIShvoFxiRPinNHzl0MVUZuWPmTtdoFvp6WycTpgX
    UsXNeLFjFHgpNibupGOsgGP7zt51wXHGFXNnbPl66CbKR9pqwTjlhJiCfImUb173
    3FmzBZdBlbVKsqSBP0lHEQIduO7jHYBgQ53HjyIlJMUCAQOgADANBgkqhkiG9w0B
    AQQFAAOBgQB3cFRxrJsEMyEmwaveqN66cHoy7sudf62i0EWEmfMQXUsZjyDgGcsD
    Svh+3Tav65biX1dJMiMjmsndBQI+X8OMByE7NEEteoBDLNRMS6eq+1DKsvj7g3XW
    RWbjqC/yIW31/NPczrsSubVkHhIGDgxElEbZyz/bSP7pELnmUlAo5A==
    -----END NEW CERTIFICATE REQUEST-----

To create certificate from this request, have it signed by a CA cert.

	certutil -C -c issuer.crt -i outputfile -o inputfile

To add the cert to the cert database,

	certutil -A -n jdoe -d ~/ssl -t u -i inputfile


In the example above, John Doe has a new key and a new certficate which
binds his key to his identity, and his certificate is tagged as a "user"
or personal certificate.

Depending on whether you are using the certificate database as a server or
as a client, you will probably need to set up your trust attributes
differently on your CA certificates. 

In the case of a client, any CA certificates you wish to set as trusted 
should have the 'S' flag set, meaning the CA is trusted for issuing server
certificates. Any user certs should have the 'u' flag set.

In the case of a server, any CA certificates you wish to set as trusted for
client authentication should have the 'C' flag set, meaning the CA is 
trusted for issuing client certificates.

Note that you can have more than one trust flag set for a certificate. In
this way, it is possible for both a client and a server to access the same
database.




Command Line Syntax


keyutil

(NOTE:  keyutil functionality moved to certutil.  See usage for more
 information.)

keyutil is a program that can create a new key, modify the password for an
existing key, or print the contents of a key. 

The command syntax for key is:

	keyutil -n name -g [-s num] [-e prime] [-d keydir]
	keyutil -n name [-p|-P] [-d keydir]
	keyuitl [-c|-l] [-d keydir]

where * is one of 'us' or 'ex' to indicate whether the domestic or export
version should be used.

The -n argument is the nickname for the key. This value is used for 
accessing the key at later times by name, as well as for generating
certificates.

The -g option generates a new key.

The -c option changes the password for an existing database.

The -l option lists all of the nicknames in the key database.

The -p option prints out the contents of a public key.

The -P option prints out the contents of a private key.

The -s option sets the key size in bits. The minimum is 256, and the
maximum is the default setting of 1024. 

The -e option sets the public exponent value to prime. Valid numbers
are 3, 17, and 65537. The default is 3.

The -d option specifies the directory where key will access the
"key.db" database. The default is .netscape in the user's home
directory.





certutil

certutil is a utility program that can help with managing certificates and
the certificate database.

The command syntax for certutil is:

	certutil -R -n key-name -s subj [-d keydir] [-p phone] [-a]
        certutil -N [-d certdir]
        certutil -A -n cert-name -t trustargs [-d certdir] [-i input]
        certutil -D -n cert-name [-d certdir]
        certutil -L [-n cert-name] [-d certdir] [-r] [-a]
        certutil -M -n cert-name -t trustargs [-d certdir]


Certificate Requests

  The -R option specifies to generate a certificate request.

  -n key-name
	Specify the nickname for the key to use to build the request.

  -s subj
	Specify the subject name, using RFC1485 format.

  -d keydir
	Specify that the directory keydir contains the "key.db" database
	file. The default is ~/.netscape.

  -p phone
	Specify the contact phone number. This should be in the format
	"123-456-7890."

  -a	The request should be generated in ASCII. This is useful for creating
	cert reqs that can be easily emailed to be signed.


Creating New Database

  The -N option specifies to create a new certificate database.

  -d certdir
        Specify the directory to contain "cert.db".
        The default is ~/.netscape.


Certificate Addition

  The -A option specifies to add a certificate to the database from a file.

  -n cert-name
	Specify that the new certificate should be nicknamed 'cert-name'.

  -t trustargs
	Set the certificate trust attributes:
		p	valid peer
		P	trusted peer (implies p)
		c	valid CA
		C	trusted CA to issue client certs (implies c)
		S	trusted CA to issue server certs (implies c)
		u	user cert
		w	send warning on connect

  -d certdir
	Specify the directory that contains "cert.db".
	The default is ~/.netscape. If these databases do not exist, they
	will be generated for you.

  -i input
	Specify the ASCII certificate file for input. The default is stdin.


Certificate Deletion

  The -D option deletes a named certificate from the database.

  -n cert-name
	Specify the nickname of the certificate to delete.

  -d certdir
	Specify the directory that contains "cert.db".
	The default is ~/.netscape.


Certficate Listing and Printing

  The -L option lists and prints out information on certificates.

  -n cert-name
	The nickname of a particular certificate to print out, in long
	listing. Without this option, all certificate names are listed.

  -d certdir
	Specify the directory that contains "cert.db".
	The default is ~/.netscape.

  -r    For a single certificate, this prints the binary DER encoding.

  -a    For a single certificate, this prints the ASCII encoding (RFC1113).


Modifying Trust Attributes

  The -M option specifies modification of a certificate's trust attributes.

  -n cert-name
        The nickname of the certificate.

  -t trustargs
        Sets the certificate trust attributes. See the -A option above.

  -d certdir
        Specify the directory that contains "cert.db".
        The default is ~/.netscape.




pp

pp is a utility program that can pretty print certificates and keys.

The command syntax for pp is:

        pp -t type [-a] [-i input] [-o output]

The -t option specifies the input type of the data. This "type" string must be
one of four options: 

       private-key            The input is private key data.
       public-key             The input is public key data.
       certificate            The input is a certificate.
       certificate-request    The input is a certificate request.

The -a option specifies that the input data is ascii encoded (RFC1113).

The -i option specifies the input file to use (default is stdin).

The -o option specifies the output file to use (default is stdout).





tstclnt-*

This is a test client program that connects to secure servers with SSL.

The command syntax for tstclnt is:

	tstclnt-* -h host -p port [-n nickname] [-d certdir]

where * is one of 'us' or 'ex' to indicate whether the domestic or export
version should be used.

The -h argument specifies the hostname to connect to as host.

The -p argument specifies the port to connect to. Typically, secure http
transfers use port 443. 

The -n argument specifies the nickname of the key and certificate to use
for client authentication. Note that the key and cert should both have the
same name.

The -d option specifies the directory that contains the certificate database
"cert.db". If this is not specified, tstclnt will assume it exists in
.netscape in the user's home directory.


