path: root/doc/tex/programs.tex

\chapter{Included programs}

\section{The ``srptool'' program\index{srptool}}
\label{srptool}

The ``srptool'' is a very simple program that emulates the programs in the 
\emph{Stanford SRP libraries}.
It is intended for use in places where you don't expect SRP
authentication to be the used for system users.
Traditionally \emph{libsrp} used two files. One called 'tpasswd' which holds usernames 
and verifiers, and 'tpasswd.conf' which holds generators and primes.
\par
How to use srptool:

\begin{itemize}


\item To create tpasswd.conf which holds the g and n values for
SRP protocol (generator and a large prime), run:
\begin{verbatim}
$ srptool --create-conf /etc/tpasswd.conf
\end{verbatim}


\item This command will create /etc/tpasswd and will add user 'test' (you will also
be prompted for a password). Verifiers are stored by default in the
way libsrp expects.
\begin{verbatim}
$ srptool --passwd /etc/tpasswd \ 
    --passwd-conf /etc/tpasswd.conf -u test
\end{verbatim}

\item This command will check against a password. If the password matches 
the one in /etc/tpasswd you will get an ok.
\begin{verbatim}
$ srptool --passwd /etc/tpasswd \ 
    --passwd-conf /etc/tpasswd.conf --verify -u test
\end{verbatim}

\end{itemize}



\section{The ``gnutls-cli-debug'' program\index{gnutls-cli-debug}}

This program was created to assist in debugging \gnutls{}, but it
might be useful to extract a \tls{} server's capabilities. 
It's purpose is to connect onto a \tls{} server, perform
some tests and print the server's capabilities. An example output is:

\begin{verbatim}
crystal:/cvs/gnutls/src$ ./gnutls-cli-debug localhost -p 5556
Resolving 'localhost'...
Connecting to '127.0.0.1:5556'...
Checking for TLS 1.0 support... yes
Checking for SSL 3.0 support... yes
Checking for version rollback bug in RSA PMS... no
Checking for version rollback bug in Client Hello... no
Checking whether we need to disable TLS 1.0... no
Checking whether the server ignores the RSA PMS version... no
Checking whether the server can accept Hello Extensions... yes
Checking whether the server can accept cipher suites not in SSL 3.0 spec... yes
Checking whether the server can accept a bogus TLS record version in the client hello... yes
Checking for certificate information...
- Certificate type: X.509
 - Got a certificate list of 1 certificates.

 - Certificate[0] info:
 # valid since: Sat Jul  7 13:18:00 EEST 2001
 # expires at: Sun Jul  7 13:18:00 EEST 2002
 # serial number: 01 
 # fingerprint: 43 ab a2 a7 d3 6a 28 02 60 73 b4 a5 c3 84 0a 3f 
 # version: #3
 # public key algorithm: RSA
 #   Modulus: 1024 bits
 # Subject's DN: C=GR,ST=Attiki,L=Athina,O=GNUTLS,OU=GNUTLS dev.,CN=localhost,EMAIL=root@localhost
 # Issuer's DN: C=GR,ST=Attiki,L=Athina,O=GNUTLS,OU=GNUTLS dev.,CN=GNUTLS TEST CA,EMAIL=gnutls-dev@gnupg.org

 
Checking for trusted CAs...
- Server's trusted authorities:
   [0]: C=GR,ST=Attiki,L=Athina,O=GNUTLS,OU=GNUTLS dev.,CN=GNUTLS TEST CA,EMAIL=gnutls-dev@gnupg.org
 
Checking whether the server understands TLS closure alerts... yes
Checking whether the server supports session resumption... no
Checking for export-grade ciphersuite support... no
Checking for ephemeral Diffie Hellman support... no
Checking for ephemeral Diffie Hellman prime size... N/A
Checking for AES cipher support... yes
Checking for 3DES cipher support... yes
Checking for ARCFOUR cipher support... yes
Checking for MD5 MAC support... yes
Checking for SHA1 MAC support... yes
Checking for max record size (TLS extension)... yes
Checking for OpenPGP authentication support (TLS extension)... no

\end{verbatim}

\section{The ``certtool'' program\index{certtool}}

This is a program to generate X.509 certificates, certificate requests, CRLs and
private keys. The program can be used interactively or non interactively by
specifying the \emph{--template} command line option. See \emph{doc/certtool.cfg},
in the distribution, for an example of a template file.

How to use certtool interactively:

\begin{itemize}

\item To create a self signed certificate, use the command:
\begin{verbatim}
$ certtool --generate-privkey --outfile ca-key.pem
$ certtool --generate-self-signed --load-privkey ca-key.pem --outfile ca-cert.pem
\end{verbatim}
Note that a self-signed certificate usually belongs to a certificate
authority, that signs other certificates.

\item To create a private key, run:
\begin{verbatim}
$ certtool --generate-privkey --outfile key.pem
\end{verbatim}

\item To create a certificate request, run:
\begin{verbatim}
$ certtool --generate-request --load-privkey key.pem --outfile request.pem
\end{verbatim}

\item To generate a certificate using the previous request, use the command:
\begin{verbatim}
$ certtool --generate-certificate --load-request request.pem --outfile cert.pem \
   --load-ca-certificate ca-cert.pem --load-ca-privkey ca-key.pem
\end{verbatim}

\item To view the certificate information, use:
\begin{verbatim}
$ certtool --certificate-info --infile cert.pem
\end{verbatim}

\item To generate a PKCS \#12 structure using the previous key and certificate, use the command:
\begin{verbatim}
$ certtool --load-certificate cert.pem --load-privkey key.pem --to-p12 \
   --outder --outfile key.p12
\end{verbatim}


\end{itemize}
\par
Certtool's template file format:

\begin{itemize}
\item Firstly create a file named 'cert.cfg' that contains the information
about the certificate. An example file is listed below.
\item Then execute
\begin{verbatim}
$ certtool --generate-certificate cert.pem --load-privkey key.pem  \
   --template cert.cfg \
   --load-ca-certificate ca-cert.pem --load-ca-privkey ca-key.pem
\end{verbatim}
\end{itemize}
\par
An example certtool template file:

\begin{verbatim}
# X.509 Certificate options
#
# DN options

# The organization of the subject.
organization = "Koko inc."

# The organizational unit of the subject.
unit = "sleeping dept."

# The locality of the subject.
# locality = 

# The state of the certificate owner.
state = "Attiki"

# The country of the subject. Two letter code.
country = GR

# The common name of the certificate owner.
cn = "Cindy Lauper"

# A user id of the certificate owner.
#uid = "clauper"

# If the supported DN OIDs are not adequate you can set
# any OID here.
# For example set the X.520 Title and the X.520 Pseudonym
# by using OID and string pairs.
#dn_oid = "2.5.4.12" "Dr." "2.5.4.65" "jackal" 

# This is deprecated and should not be used in new
# certificates.
# pkcs9_email = "none@none.org"

# The serial number of the certificate
serial = 007

# In how many days, counting from today, this certificate will expire.
expiration_days = 700

# X.509 v3 extensions

# A dnsname in case of a WWW server.
#dns_name = "www.none.org"

# An IP address in case of a server.
#ip_address = "192.168.1.1"

# An email in case of a person
email = "none@none.org"

# An URL that has CRLs (certificate revocation lists)
# available. Needed in CA certificates.
#crl_dist_points = "http://www.getcrl.crl/getcrl/"

# Whether this is a CA certificate or not
#ca

# Whether this certificate will be used for a TLS client
#tls_www_client

# Whether this certificate will be used for a TLS server
#tls_www_server

# Whether this certificate will be used to sign data (needed
# in TLS DHE ciphersuites).
signing_key

# Whether this certificate will be used to encrypt data (needed
# in TLS RSA ciphersuites). Note that it is prefered to use different
# keys for encryption and signing.
#encryption_key

# Whether this key will be used to sign other certificates.
#cert_signing_key

# Whether this key will be used to sign CRLs.
#crl_signing_key

# Whether this key will be used to sign code.
#code_signing_key

# Whether this key will be used to sign OCSP data.
#ocsp_signing_key

# Whether this key will be used for time stamping.
#time_stamping_key
\end{verbatim}