config root man

BSDftpd-ssl project  <URL: http://bsdftpd-ssl.sc.ru/ >

                              Certificates HOWTO

Author: Nick Leuta <skynick@mail.sc.ru>
3 June, 2004

Copyright (c) 2002, 2003, 2004 Nick Leuta. All Rights Reserved.

Permission is granted to copy, distribute and/or modify this document under the
terms of the full copyright statement that is included in this document.

CONTENTS
========
1. Introduction
2. How to become your own CA
3. Issuing the certificates
4. Certificate revocation
5. How to create a server certificate
6. How to create a client certificate
7. How to use the "openssl" command
8. How to enable the certificate-based user authentication
Full copyright statement

1. Introduction
---------------
This document contains some basics of X.509 certificate management with help
of OpenSSL - the popular free TLS/SSL toolkit.

ITU-T Recommendation X.509 defines a framework for public-key certificates and
attribute certificates. The well-known application of the X.509 certificates
today is the TLS/SSL security protocol that provides privacy and authentication
for a network traffic. TLS 1.0 (Transport Layer Security Version 1.0) protocol
itself is based on the SSL 3.0 (Secure Socket Layer Version 3.0) Protocol
Specification as published by Netscape Communications Corporation. TLS/SSL is
now widely adopted in many Internet applications, such as web, e-mail and LDAP
software.

Basic concepts of X.509 certificates may be obtained from the cert-basics.txt
file.

2. How to become your own CA
----------------------------
The simplest way to become your own CA is to use the CA.sh (or simple CA in
many binary distributions) shell script or CA.pl perl script (see the CA.pl(1)
man page for additional information about this program) from the OpenSSL
distribution or xCA.sh (which is based on CA.sh) from the BSDftpd-ssl
distribution. All three utilities have the same command-line syntax, except
xCA.sh, which have some additional commands, but honors all commands of
original CA.sh, so it's possible to use any of them in examples below (if
contrary assertion isn't preceded).

First of all you are required to create your own CA stuff using next commands:

cd /your/CA/location
xCA.sh -newca

All CA stuff now is located in demoCA directory. It consists of:
* files:
cacert.pem - the CA certificate;
crl.pem    - the current CRL;
index.txt  - the database index file;
serial     - the current serial number;
* subdirectories:
certs/     - the location of the issued certificates (reserved);
crl/       - the location of the issued CRL (reserved);
newcerts/  - it contains copies of signed certificates;
private/   - it contains cakey.pem file with the RSA private key of this CA,
             protected by pass phrase. It's recommended to set relevant
             permissions to whole private/ subdirectory.

It's possible now to issue certificates by this CA, but it's also required that
this CA or, rather, this CA certificate, must be presented in the trusted CA
list of any server and client which will communicate each other using this
certificates (of course, if one of connecting sides doesn't do verification of
peer than it doesn't require the trusted CA list at all).

The CA certificate has an expiration date. It's possible to renew this
certificate with help of xCA.sh script; standard OpenSSL scripts CA.sh and
CA.pl have not such possibility. The renewing of the CA certificate may be
performed with help of next commands:

cd /your/CA/location
xCA.sh -renewca

These commands replace the existing cacert.pem file by new one, which may be
included into the trusted CA lists instead of the old version of the
certificate of this CA.

The renewed CA certificate is a valid CA certificate for the verification
procedure of all certificates and CRLs those were issued by this CA.

Please read the verify.txt file for an information about how trusted CA
certificates and CRLs are stored by OpenSSL/BSDftpd-ssl; a similar information
about the third-party products (whose may not use OpenSSL) can be obtained from
their documentations.

3. Issuing the certificates
---------------------------
When CA is asked to issue a certificate, it expects that the public key and
some information about the entity are provided in form of Certificate Signing
Request (CSR). If all required information is provided correctly it's possible
to sign the CSR by this CA and so create the certificate.

CSR will be searched by xCA.sh in the newreq.pem file, the result (the new
certificate) will be stored in the newcert.pem file. Simple run "xCA.sh -sign"
in the directory where the newreq.pem file is present.

Of course, it's possible to create CSR by xCA.sh script: "xCA.sh -newreq"
command will generate new RSA private key and related CSR, and both will be
stored in newreq.pem file.

4. Certificate revocation
-------------------------
Standard OpenSSL scripts CA.sh and CA.pl have no support for the CRL
management, but BSDftpd-ssl provides an enhanced version of CA.sh, named
xCA.sh, which allows certificate revocation and CRL generation actions.

To revoke a certificate run "xCA.sh -revoke <number>", where <number> is the
certificate serial number, which is listed in the database index file
(index.txt). To generate a CRL run "xCA.sh -gencrl", which will place it into
the crl.pem file.

5. How to create a server certificate
-------------------------------------
It's required that the server RSA private key was not encrypted, otherwise
ftpd will not start without the user intervention.

The server RSA private key and CSR can be generated by the cert-nopass.sh
script from the cert/ subdirectory of BSDftpd-ssl source tree (if BSDftpd-ssl
was installed from pre-compiled package, this subdirectory was installed with
the documentation).

Simple run the cert-nopass.sh script. It will create newcert-key.pem (RSA
Private Key) and newcert-csr.pem (CSR) files. After signing the CSR by CA you
will have the certificate. You can concatenate the RSA Private Key and the
signed Certificate to one file and locate it as described in the INSTALL file.

6. How to create a client certificate
-------------------------------------
At client side is possible to use both encrypted (pass phrase protected) or
unencrypted RSA private keys.

For security reasons it's recommended to use encrypted keys, especially if it
isn't possible to set up essential file access permissions (for example, on
a floppy disk or on Windows FAT file systems). In this case the user will be
asked for the pass phrase during the application startup.

You can run the cert-pass.sh script if you require the encrypted private key or
cert-nopass.sh in other case. Both will create newcert-key.pem (RSA Private
Key) and newcert-csr.pem (CSR) files. After signing the CSR by CA you will have
the certificate. You can concatenate the RSA Private Key and the signed
Certificate to one file.

7. How to use the "openssl" command
-----------------------------------
OpenSSL's "openssl" command-line tool is a very powerful solution for the
TLS/CA/key management, but it isn't very user-friendly (for example, most of
scripts described above are front-ends for this utility).

Please remember that there are lot of settings those are located in openssl.cnf
file in OpenSSL directory, and these settings will be used either as defaults
or as fixed unchangeable values by the openssl tool.

Some useful commands for this tool are listed below.

Remove pass phrase from RSA private key:
openssl rsa -in xxxx.key -out xxxx.nopass.key

Set or change pass phrase of private key:
openssl rsa -des3 -in xxxx.old.key -out xxxx.new.key

Print out information about a certificate:
openssl x509 -in xxxx.crt -noout -text

Print out information about a CRL:
openssl crl -in xxxx.crl -noout -text

Convert PEM format certificate to DER format:
openssl x509 -in xxxx.pem -out xxxx.der -outform DER

Convert PEM format CRL to DER format:
openssl crl -in xxxx.pem -out xxxx.der -outform DER

8. How to enable the certificate-based user authentication
----------------------------------------------------------
It's required to force the FTP server to request the client's certificates, and
it's also required to specify the authentication mode, so the command line for
the ftpd must be like this:
ftpd -z verify=1 -z auth=1

In this example the server will request the client certificates if possible,
and a fallback to the standard password-based authentication is allowed if the
certificate-based one will be failed. It's possible to disallow access without
certificates and to disable the standard authenication; it's also possible to
allow only TLS/SSL-aware FTP clients. For example:
ftpd -z verify=2 -z auth=2 -z secure

After that it's required to configure the relations between the system login
names and the certficates in /etc/x509.auth file. Some examples of such
configurations may be obtained from the x509_auth.txt file.

Please note that if the certificate-based authentication was used and the
standard authentication was not, PAM modules from the authentication management
group will not be used, so if a PAM module doesn't depend on user's password,
it's recommended to put it into the account management group.

Full copyright statement
------------------------

Copyright (c) 2002, 2003, 2004 Nick Leuta. All Rights Reserved.

This document and translations of it may be copied and furnished to others, and
derivative works may be prepared, copied, published and distributed, in whole
or in part, without restriction of any kind, provided that the above copyright
notice and this paragraph are included on all such copies and derivative works.
References to this document are allowed in works of any kind without any
restrictions.

This document and the information contained herein is provided on an "AS IS"
basis and AUTHOR DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT
NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT
INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR
A PARTICULAR PURPOSE.