DO NOT DISTRIBUTE THIS FILE. DO NOT DISTRIBUTE THESE BINARIES WITHOUT
PERMISSION. FOR INTERNAL USE ONLY.
This file contains descriptions of the tools used in the ns/cmd/security
directory. Some of these tools are outlined as follows:
keyutil-us Generating, storing, and retrieving keys
keyutil-ex Same as above, but export version (small keys)
certutil Multi-purpose certificate tool
pp Printing human-readable cert, certreq, and key info
atob, btoa Converts ASCII to binary and vice-versa
ssld-us Test SSL proxy server
ssld-ex Same as above, but export version
tstclnt-us Connects to https servers with SSL
tstclnt-ex Same as above, but export version
rsh Modified rsh that uses SSL
rshd Modified rshd that expects to be exec'd by ssld
rdist Modified rdist that expects to use secure rsh
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/Makefile
cvs co ns/cmd/Makefile
cvs co ns/cmd/security
cvs co ns/config
cvs co ns/include
cvs co ns/lib/Makefile
cvs co ns/lib/config
cvs co ns/lib/libdbm
cvs co ns/lib/libsec
cvs co ns/lib/xp
cvs co ns/nspr
Compiling
There are some problems with building the rsh and rshd sub-directories on
Solaris machines. The default cmd/security/Makefile has been modified to
not include these directories, so be sure to change this if you want to
generate those binaries. Some suggested fixes are listed in the "rsh and
rshd" section in this file for Solaris builds.
If you're working with the minimum set of files for building cmd/security, you
might have to undefine MOCHA to build successfully. There is a file
ns/lib/xp_cntxt.c that includes mocha headers if MOCHA is defined, which
is the default in ns/config/config.mk. You don't need ns/mocha, so create a
file ns/config/myconfig.mk with the following line:
NO_MOCHA = 1
One thing that might be useful for debugging ssld or rsh is to build libsec
with SSL tracing turned on. In the file ns/config/myconfig.mk, add the
following information:
ifeq ($(SRCDIR), lib/libsec)
DEFINES += -DTRACE
endif
Once everything is built, you can set the environment variable:
setenv SSLTRACE n
where n is a numeric value which indicates the level of tracing. A value
between 20 and 80 should be sufficient for most tests.
Once you've set everything up properly, you should be able to build:
cd ns
gmake -k export install
cd cmd/security
gmake -k install
After you gmake from this directory, you should have a ($ARCH).OBJ directory
which will contain all of the top-level tool binaries. The remaining binaries
should be generated in OBJ directories in ssld, rsh, and rshd.
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-us 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
cert-nameidx.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 or to use them for ssld.
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
keyutil-us -n jdoe -g -d ~/ssl
certutil -R -n jdoe -d ~/ssl -a -p 415-937-1234 -s "CN=John Doe, \
E=jdoe@netscape.com, C=US, ST=CA, L=Mountain View, \
O=Netscape Communications Corporation" > outputfile
You should see something in the output which looks like:
Certificate request generated by Netscape certutil
Phone: 415-937-1234
Common Name: John Doe
Email: jdoe@netscape.com
Organization: Netscape Communications 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 have this signed by the Netscape Test CA (which should *only* be used
for internal testing purposes), email the certificate request to Saleem
Baber (mailto: sbaber). These certificate requests should also be suitable
for submission to external CA's, such as VeriSign.
Be sure to email the entire output, including the "BEGIN NEW" and "END
NEW" lines. The certificate that is returned will have similar headers
and trailers. Leave these in the file when you add them to your database.
The certutil program expects to find them in the input.
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.
NOTE: The current implementation of libsec inserts an expired "Netscape
Test CA" certificate in the cert database. If you intend to use a certificate
that is signed by the Netscape CA, you will need to delete the existing
certificate and replace it with an unexpired version. An ASCII version of
the certificate is in ./etc/nsca_cert.
This modification is *ONLY* intended for internal testing purposes.
Here is a description of how to make the proper changes, assuming the
database in question resides in ~/ssl:
cd ns/cmd/security/etc
certutil -D -n "Netscape Test CA" -d ~/ssl
certutil -A -n "Netscape Test CA" -d ~/ssl -t S -i ./nsca_cert
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.
NOTE: as of Navigator Client 3.0b5, libsec uses a new cerificate database
format. The new file associated with this format is called `cert5.db' and
by default resides in ~/.netscape. Libsec routines automatically handle
the conversion of the old file format (`cert.db') into the new format.
HOWEVER, note that libsec also handles creation of the new file, which is
placed in ~/.netscape. Therefore, specifying `-d dir-name' containing the
old file format will force an update, whereby the contents will be moved
into the new file, `~/.netscape/cert5.db' For other functions, the
directory path specified in -d will be used.
Running ssld as a Test Server
The important things to be familiar with in order to run ssld are the
ssld configuration file and the nicknames for the key and the certificate.
See the file ./doc/ssld.html for a discussion of the setup for ssld.conf.
There is a directory ./etc which contains a sample ssld.conf file
that can be used for testing. It exec's a script (ssld.sh) which spits
out HTML to any client attempting to connect.
This version of ssld does not currently support client or auth-client modes.
It can only run as a server. It is currently intended for use as a testing
mechanism.
NOTE: You will probably want to set an environment variable, SSL_DIR, to the
directory where you are keeping your key and certficate databases, as well
as the configuration file for ssld.conf. This allows you to run tstclnt
and ssld without having to enter a mess of arguments.
To set up the configuration file to work inline with the example outlined
above for key and certificate generation, do the following:
setenv SSL_DIR ~/ssl
cp ./etc/ssld.conf ~/ssl
cp ./etc/ssld.sh ~/ssl
edit ~/ssltest/ssld.conf:
8000 server - NAME NAME exec ~/ssl/ssld.sh ssld.sh
ssld-us -D
While ssld is running, you can connect to it with the Navigator or tstclnt.
tstclnt-us -h `hostname` -p 8000
Using rsh and rshd (with ssld)
Note that the default in ns/cmd/security/Makefile is to *not* compile these
subdirectories, nor the rdist subdirectory.
See ./doc/contrib.html for a discussion of these programs.
If you are building on Solaris, you might have to make the following
modifications to successfully compile:
In cmd/security/rsh/Makefile:
OS_LIBS = /usr/ucblib/libucb.a -lsocket -lnsl -ldl
In cmd/security/rsh/rsh.c AND sslrcmd.c:
#if defined (__sun)
#define sigmask(m) (m > 32 ? 0 : ( 1 << ((m)-1)))
#endif
In cmd/security/rshd/rshd.c:
/* Comment out the declaration of ruserok */
/* int ruserok(char *, int, char *, char *); */
#ifndef _PATH_TTY
#define _PATH_TTY "/dev/tty"
#endif
Command Line Syntax
keyutil-*
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 and running ssld.
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" and "cert-nameidx.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" and "cert-nameidx.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" and "cert-nameidx.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" and "cert-nameidx.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" and "cert-nameidx.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).
ssld-*
The command syntax for ssld is:
ssld-* [-d keydir] [-i] [-D] [-c conffile] [-C chrootdir]
where * is one of 'us' or 'ex' to indicate the domestic or export versions,
respectively.
The -d option specifies the directory that contains "cert.db" and
"cert-nameidx.db". The default is /usr/etc/ssl. This can be configured with
the SSL_DIR environment variable to avoid specifying it at the command line.
The -i option specifies that ssld should run in interactive mode, so it
won't fork.
The -D option enables various debugging messages. It implies -i.
The -c option specifies the configuration file. The default is ssld.conf.
This can be set with the SSLD_CONF environment variable. If this value
begins with a '/', then it is taken as the full pathname. Otherwise it
is appended to the value for the key directory, which is /usr/etc/ssl by
default, or set with the -d option or with the SSL_DIR environment varianble.
The -C option specifies that ssld should chroot to the named directory.
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.