From 014520247e4235b4cf8e999c2aad9aa4c1a92081 Mon Sep 17 00:00:00 2001
From: Tom Rhodes <trhodes@FreeBSD.org>
Date: Tue, 31 Aug 2004 08:46:20 +0000
Subject: [PATCH] Wow! Our OpenSSL section sucks. Rewrite it because there is
nothing else to do at 4:00 in the morning. Ensure to cover:
o How ports interact with base and port versions of OpenSSL;
o Generating certificates;
o Generating CA keys;
o Add an example of using certificates with Sendmail.
Needs severe beating for keeping me up: Brad Davis :-)
---
.../books/handbook/security/chapter.sgml | 223 +++++++++++++++---
1 file changed, 196 insertions(+), 27 deletions(-)
diff --git a/en_US.ISO8859-1/books/handbook/security/chapter.sgml b/en_US.ISO8859-1/books/handbook/security/chapter.sgml
index 4ddfe3bf87..63e2f3894a 100644
--- a/en_US.ISO8859-1/books/handbook/security/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/security/chapter.sgml
@@ -3636,44 +3636,213 @@ jdoe@example.org</screen>
</sect1>
<sect1 id="openssl">
+ <sect1info>
+ <authorgroup>
+ <author>
+ <firstname>Tom</firstname>
+ <surname>Rhodes</surname>
+ <contrib>Written by: </contrib>
+ </author>
+ </authorgroup>
+ </sect1info>
<title>OpenSSL</title>
<indexterm>
<primary>security</primary>
<secondary>OpenSSL</secondary>
</indexterm>
- <indexterm><primary>OpenSSL</primary></indexterm>
- <para>As of FreeBSD 4.0, the OpenSSL toolkit is a part of the base
- system. <ulink url="http://www.openssl.org/">OpenSSL</ulink>
- provides a general-purpose cryptography library, as well as the
- Secure Sockets Layer v2/v3 (SSLv2/SSLv3) and Transport Layer
- Security v1 (TLSv1) network security protocols.</para>
+ <para>One feature that many users overlook is the
+ <application>OpenSSL</application> toolkit included
+ in &os;. <application>OpenSSL</application> provides an
+ encryption transport layer on top of the normal communications
+ layer; thus allowing it to be intertwined with many network
+ applications and services.</para>
- <para>However, one of the algorithms (specifically IDEA)
- included in OpenSSL is protected by patents in the USA and
- elsewhere, and is not available for unrestricted use.
- IDEA is included in the OpenSSL sources in FreeBSD, but it is not
- built by default. If you wish to use it, and you comply with the
- license terms, enable the <makevar>MAKE_IDEA</makevar> switch in
- <filename>/etc/make.conf</filename> and
- rebuild your sources using <command>make world</command>.</para>
+ <para>Some uses of <application>OpenSSL</application> may include
+ encrypted authentication of mail clients, web based transactions
+ such as credit card payments and more. Many ports such as
+ <filename role="package">www/apache13-SSL</filename>, and
+ <filename role="package">mail/sylpheed-claws</filename>
+ will offer compilation support for building with
+ <application>OpenSSL</application>.</para>
- <para>Today, the RSA algorithm is free for use in USA and other
- countries. In the past it was protected by a patent.</para>
+ <note>
+ <para>In most cases the ports collection will attempt to build
+ the <filename role="package">security/openssl</filename>
+ unless the <makevar>WITH_OPENSSL_BASE</makevar> make variable
+ is explicitly set to <quote>yes</quote>.</para>
+ </note>
- <indexterm>
- <primary>OpenSSL</primary>
- <secondary>install</secondary>
- </indexterm>
+ <para>The version of <application>OpenSSL</application> included
+ in &os; supports Secure Sockets Layer v2/v3 (SSLv2/SSLv3),
+ Transport Layer Security v1 (TLSv1) network security protocols
+ and can be used as a general cryptographic library for use
+ with applications.</para>
+
+ <note>
+ <para>While <application>OpenSSL</application> supports the
+ <acronym>IDEA</acronym> algorithm, it is disabled by default
+ due to United States patents. To use it, the license should
+ be reviewed and, if the restrictions are acceptable, the
+ <makevar>MAKE_IDEA</makevar> variable must be set in
+ <filename>make.conf</filename>.</para>
+ </note>
+
+ <para>Perhaps one of the most common uses of
+ <application>OpenSSL</application> provide certificates for
+ use with software applications. These certificates ensure
+ that the credentials of the company or individual is valid
+ and are not fraudulent. If the certificate in question has
+ not been verified by one of the several Certificate Authorities,
+ or <acronym>CA</acronym>s, a warning is usually produced. A
+ Certificate Authority is a company, such as VeriSign, who will
+ sign certificates in order to validate credentials of individuals
+ or companies. This process has a cost associated with it and
+ is definitely not a requirement for using certificates; however,
+ it can put some of the more paranoid users at ease.</para>
<sect2>
- <title>Source Code Installations</title>
-
- <para>OpenSSL is part of the <literal>src-crypto</literal> and
- <literal>src-secure</literal> <application>CVSup</application> collections. See the <link
- linkend="mirrors">Obtaining FreeBSD</link> section for more
- information about obtaining and updating FreeBSD source
- code.</para>
+ <title>Generating Certificates</title>
+
+ <indexterm>
+ <primary>OpenSSL</primary>
+ <secondary>certificate generation</secondary>
+ </indexterm>
+
+ <para>To generate a certificate, the following command is
+ available:</para>
+
+ <screen>&prompt.root; <userinput>openssl req -new -nodes -out req.pem -keyout cert.pem</userinput>
+Generating a 1024 bit RSA private key
+................++++++
+.......................................++++++
+writing new private key to 'cert.pem'
+-----
+You are about to be asked to enter information that will be incorporated
+into your certificate request.
+What you are about to enter is what is called a Distinguished Name or a DN.
+There are quite a few fields but you can leave some blank
+For some fields there will be a default value,
+If you enter '.', the field will be left blank.
+-----
+Country Name (2 letter code) [AU]:<userinput><replaceable>US</replaceable></userinput>
+State or Province Name (full name) [Some-State]:<userinput><replaceable>PA</replaceable></userinput>
+Locality Name (eg, city) []:<userinput><replaceable>Pittsburgh</replaceable></userinput>
+Organization Name (eg, company) [Internet Widgits Pty Ltd]:<userinput><replaceable>My Company</replaceable></userinput>
+Organizational Unit Name (eg, section) []:<userinput><replaceable>Systems Administrator</replaceable></userinput>
+Common Name (eg, YOUR name) []:<userinput><replaceable>localhost.example.org</replaceable></userinput>
+Email Address []:<userinput><replaceable>trhodes@FreeBSD.org</replaceable></userinput>
+
+Please enter the following 'extra' attributes
+to be sent with your certificate request
+A challenge password []:<userinput><replaceable>SOME PASSWORD</replaceable></userinput>
+An optional company name []:<userinput><replaceable>Another Name</replaceable></userinput></screen>
+
+ <para>Notice the response directly after the
+ <quote>Common Name</quote> prompt shows a domain name.
+ This prompt requires a server name to be entered for
+ verification purposes; placing anything but a domain name
+ would yield a useless certificate. Other options for
+ instance expire time, alternate encryption algorithms, etc.
+ are available. A complete list may be obtained by viewing
+ the &man.openssl.1; manual page.</para>
+
+ <para>A file, <filename>cert.pem</filename> should now exist in
+ the directory which the aforementioned command was issued. This
+ is the certificate which may be sent to any one of the many
+ <acronym>CA</acronym>s for signing.</para>
+
+ <para>In cases where a signature from a <acronym>CA</acronym> is
+ not required, a self signed certificate can be created. First,
+ generate the <acronym>CA</acronym> key:</para>
+
+ <screen>&prompt.root; <userinput>openssl gendsa -des3 -out \
+<filename>myca.key</filename> 1024</userinput></screen>
+
+ <para>Use this key to create the certificate:</para>
+
+ <screen>&prompt.root; <userinput>openssl req -new -x509 -days 365 -key \
+<filename>myca.key</filename> -out <filename>new.crt</filename></userinput></screen>
+
+ <para>Two new files should appear in the directory: a certificate
+ authority signature file, <filename>myca.key</filename> and the
+ certificate itself, <filename>new.crt</filename>. These should
+ be placed in a directory, preferably under
+ <filename role="directory">/etc</filename>, which is readable
+ only by root. Permissions of 0700 should be fine for this and
+ they can be set with the <command>chmod</command>
+ utility.</para>
+ </sect2>
+
+ <sect2>
+ <title>Using Certificates, an Example</title>
+
+ <para>So what can these files do? A good use would be to
+ encrypt connections to the <application>Sendmail</application>
+ <acronym>MTA</acronym>. This would dissolve the use of clear
+ text authentication for users who send mail via the local
+ <acronym>MTA</acronym>.</para>
+
+ <note>
+ <para>This is not the best use in the world as some
+ <acronym>MUA</acronym>s will present the user with an
+ error if they have not installed the certificate locally.
+ Refer to the documentation included with the software for
+ more information on certificate installation.</para>
+ </note>
+
+ <para>The following lines should be placed inside the
+ local <filename>.mc</filename> file:</para>
+
+ <programlisting>dnl SSL Options
+define(`confCACERT_PATH',`/etc/certs')dnl
+define(`confCACERT',`/etc/certs/new.crt')dnl
+define(`confSERVER_CERT',`/etc/certs/new.crt')dnl
+define(`confSERVER_KEY',`/etc/certs/myca.key')dnl
+define(`confTLS_SRV_OPTIONS', `V')dnl</programlisting>
+
+ <para>Where <filename role="directory">/etc/certs/</filename>
+ is the directory to be used for storing the certificate
+ and key files locally. The last few requirements are a rebuild
+ of the local <filename>.cf</filename> file. This is easily
+ achieved by typing <command>make</command>
+ <parameter>install</parameter> within the
+ <filename role="directory">/etc/mail</filename>
+ directory. Follow that up with <command>make</command>
+ <parameter>restart</parameter> which should start the
+ <application>Sendmail</application> daemon.</para>
+
+ <para>If all went well there will be no error messages in the
+ <filename>/var/log/maillog</filename> file and
+ <application>Sendmail</application> will show up in the process
+ list.</para>
+
+ <para>For a simple test, simply connect to the mail server
+ using the &man.telnet.1; utility:</para>
+
+ <screen>&prompt.root; <userinput>telnet <replaceable>example.com</replaceable> 25</userinput>
+Trying 192.0.34.166...
+Connected to <hostid role="fqdn">example.com</hostid>.
+Escape character is '^]'.
+220 <hostid role="fqdn">example.com</hostid> ESMTP Sendmail 8.12.10/8.12.10; Tue, 31 Aug 2004 03:41:22 -0400 (EDT)
+<userinput>ehlo <replaceable>example.com</replaceable></userinput>
+250-pittgoth.com Hello example.com [192.0.34.166], pleased to meet you
+250-ENHANCEDSTATUSCODES
+250-PIPELINING
+250-8BITMIME
+250-SIZE
+250-DSN
+250-ETRN
+250-AUTH LOGIN PLAIN
+250-STARTTLS
+250-DELIVERBY
+250 HELP
+<userinput>quit</userinput>
+221 2.0.0 <hostid role="fqdn">example.com</hostid> closing connection
+Connection closed by foreign host.</screen>
+
+ <para>If the <quote>STARTTLS</quote> line appears in the output
+ then everything is working correctly.</para>
</sect2>
</sect1>