[deployment-guide/comm-rel: 648/727] Updated the Generating a New Key and Certificate section.
Jaromir Hradilek
jhradile at fedoraproject.org
Tue Oct 19 13:20:10 UTC 2010
commit 695d4ac5c5ea7ea173f71b6b928961945b1b4b71
Author: Jaromir Hradilek <jhradile at redhat.com>
Date: Tue Sep 14 14:23:08 2010 +0200
Updated the Generating a New Key and Certificate section.
en-US/The_Apache_HTTP_Server.xml | 368 ++++++++++++++---------------
en-US/images/apache-mod_ssl-genkey-01.png | Bin 0 -> 139602 bytes
en-US/images/apache-mod_ssl-genkey-02.png | Bin 0 -> 145185 bytes
en-US/images/apache-mod_ssl-genkey-03.png | Bin 0 -> 91440 bytes
en-US/images/apache-mod_ssl-genkey-04.png | Bin 0 -> 147106 bytes
en-US/images/apache-mod_ssl-genkey-05.png | Bin 0 -> 137555 bytes
en-US/images/apache-mod_ssl-genkey-06.png | Bin 0 -> 148690 bytes
en-US/images/apache-mod_ssl-genkey-07.png | Bin 0 -> 144241 bytes
en-US/images/genkey1.png | Bin 9587 -> 0 bytes
en-US/images/genkey10.png | Bin 16485 -> 0 bytes
en-US/images/genkey11.png | Bin 7436 -> 0 bytes
en-US/images/genkey2.png | Bin 10374 -> 0 bytes
en-US/images/genkey3.png | Bin 18324 -> 0 bytes
en-US/images/genkey4.png | Bin 6604 -> 0 bytes
en-US/images/genkey5.png | Bin 9053 -> 0 bytes
en-US/images/genkey6.png | Bin 12479 -> 0 bytes
en-US/images/genkey7.png | Bin 17567 -> 0 bytes
en-US/images/genkey8.png | Bin 10794 -> 0 bytes
en-US/images/genkey9.png | Bin 11766 -> 0 bytes
19 files changed, 176 insertions(+), 192 deletions(-)
---
diff --git a/en-US/The_Apache_HTTP_Server.xml b/en-US/The_Apache_HTTP_Server.xml
index 0fb8f10..9ccc0e6 100644
--- a/en-US/The_Apache_HTTP_Server.xml
+++ b/en-US/The_Apache_HTTP_Server.xml
@@ -3131,13 +3131,13 @@ ErrorDocument 404 /404-not_found.html</screen>
<para>
If you wish to use an existing key and certificate, move the relevant files to the <filename class="directory">/etc/pki/tls/private/</filename> and <filename class="directory">/etc/pki/tls/certs/</filename> directories respectively. You can do so by typing the following commands:
</para>
- <screen>~]# <command>mv</command> <filename><replaceable>key_file</replaceable>.key</filename> <filename>/etc/pki/tls/private/<replaceable>domain_name</replaceable>.key</filename>
-~]# <command>mv</command> <filename><replaceable>certificate</replaceable>.crt</filename> <filename>/etc/pki/tls/certs/<replaceable>domain_name</replaceable>.crt</filename></screen>
+ <screen>~]# <command>mv</command> <filename><replaceable>key_file</replaceable>.key</filename> <filename>/etc/pki/tls/private/<replaceable>hostname</replaceable>.key</filename>
+~]# <command>mv</command> <filename><replaceable>certificate</replaceable>.crt</filename> <filename>/etc/pki/tls/certs/<replaceable>hostname</replaceable>.crt</filename></screen>
<para>
Then add the following lines to the <filename>/etc/httpd/conf.d/ssl.conf</filename> configuration file:
</para>
- <screen>SSLCertificateFile /etc/pki/tls/certs/<replaceable>domain_name</replaceable>.crt
-SSLCertificateKeyFile /etc/pki/tls/private/<replaceable>domain_name</replaceable>.key</screen>
+ <screen>SSLCertificateFile /etc/pki/tls/certs/<replaceable>hostname</replaceable>.crt
+SSLCertificateKeyFile /etc/pki/tls/private/<replaceable>hostname</replaceable>.key</screen>
<para>
To load the updated configuration, restart the <systemitem class="service">httpd</systemitem> service as described in <xref linkend="s3-apache-running-restarting" />.
</para>
@@ -3150,205 +3150,189 @@ SSLCertificateKeyFile /etc/pki/tls/private/<replaceable>domain_name</replaceable
<section id="s2-apache-mod_ssl-genkey">
<title>Generating a New Key and Certificate</title>
<para>
- You must be root to generate a key.
+ In order to generate a new key and certificate pair, you must to have the <package>crypto-utils</package> package installed in your system. You can install it by typing the following at a shell prompt:
</para>
+ <screen>~]# <command>yum install crypto-utils</command></screen>
<para>
- First, use the <command>cd</command> command to change to the <filename>/etc/httpd/conf/</filename> directory. Remove the fake key and certificate that were generated during the installation with the following commands:
+ This package provides a set of tools to generate and manage <acronym>SSL</acronym> certificates and private keys, and includes <application>genkey</application>, the Red Hat Keypair Generation utility that will guide you through the key generation process. To run it, use the <command>genkey</command> command followed by the appropriate hostname (for example, <systemitem class="domainname">penguin.example.com</systemitem>):
</para>
- <screen><command>rm ssl.key/server.key</command>
-<command>rm ssl.crt/server.crt</command></screen>
+ <screen>~]# <command>genkey</command> <replaceable>hostname</replaceable></screen>
<para>
- The <filename>crypto-utils</filename> package contains the <command>genkey</command> utility which you can use to generate keys as the name implies. To create your own private key, please ensure the <filename>crypto-utils</filename> package is installed. You can view more options by typing <command>man genkey</command> in your terminal. Assuming you wish to generate keys for www.example.com using the <command>genkey</command> utility, type in the following command in your terminal:
+ You should be presented with a screen as shown in <xref linkend="figure-apache-mod_ssl-genkey-01" />.
</para>
- <screen><command>genkey www.example.com</command></screen>
- <para>
- Please note that the <command>make</command> based process is no longer shipped with RHEL 5. This will start the <command>genkey</command> graphical user interface. The figure below illustrates the first screen. To navigate, use the keyboard arrow and tab keys. This windows indicates where your key will be stored and prompts you to proceed or cancel the operation. To proceed to the next step, select <guilabel>Next</guilabel> and press the Return (Enter) key.
- </para>
- <figure float="0" id="keypair-gen">
- <title>Keypair generation</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/genkey1.png" format="PNG" scalefit="1" />
- </imageobject>
- <textobject>
- <para>
- Keypair generation
- </para>
- </textobject>
- </mediaobject>
- </figure>
- <para>
- The next screen prompts you to choose the size of your key. As indicated, the smaller the size of your key, the faster will the response from your server be and the lesser your level of security. On selecting your preferred, key size using the arrow keys, select <guilabel>Next</guilabel> to proceed to the next step. The figure below illustrates the key size selection screen.
- </para>
- <figure float="0" id="keysize-choose">
- <title>Choose key size</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/genkey2.png" format="PNG" scalefit="1" />
- </imageobject>
- <textobject>
- <para>
- Choose key size
- </para>
- </textobject>
- </mediaobject>
- </figure>
- <para>
- Selecting the next step will initiate the random bits generation process which may take some time depending on the size of your selected key. The larger the size of your key, the longer it will take to generate it.
- </para>
- <figure float="0" id="random-bits">
- <title>Generating random bits</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/genkey3.png" format="PNG" scalefit="1" />
- </imageobject>
- <textobject>
- <para>
- Generating random bits
- </para>
- </textobject>
- </mediaobject>
- </figure>
- <para>
- On generating your key, you will be prompted to send a Certificate Request (CSR) to a Certificate Authority (CA).
- </para>
- <figure float="0" id="generate-csr">
- <title>Generate CSR</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/genkey4.png" format="PNG" scalefit="1" />
- </imageobject>
- <textobject>
- <para>
- Generate CSR
- </para>
- </textobject>
- </mediaobject>
- </figure>
- <para>
- Selecting <guilabel>Yes</guilabel> will prompt you to select the Certificate Authority you wish to send your request to. Selecting <guilabel>No</guilabel> will allow you to generate a self-signed certificate. The next step for this is illustrated in <xref linkend="private-signed-cert" />.
- </para>
- <figure float="0" id="choose-cert-auth">
- <title>Choose Certificate Authority (CA)</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/genkey5.png" format="PNG" scalefit="1" />
- </imageobject>
- <textobject>
- <para>
- Choose Certificate Authority (CA)
- </para>
- </textobject>
- </mediaobject>
- </figure>
- <para>
- On Selecting your preferred option, select <guilabel>Next</guilabel> to proceed to the next step. The next screen allows you to enter the details of your certificate.
- </para>
- <figure float="0" id="enter-cert-details">
- <title>Enter details for your certificate</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/genkey6.png" format="PNG" scalefit="1" />
- </imageobject>
- <textobject>
- <para>
- Enter details for your certificate
- </para>
- </textobject>
- </mediaobject>
- </figure>
- <para>
- If you prefer to generate a self signed cert key pair, you should not generate a CSR. To do this, select <guilabel>No</guilabel> as your preferred option in the Generate CSR screen. This will display the figure below from which you can enter your certificate details. Entering your certificate details and pressing the return key will display the <xref linkend="protect-private-key" /> from which you can choose to encrypt your private key or not.
- </para>
- <figure float="0" id="private-signed-cert">
- <title>Generating a self signed certificate for your server</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/genkey8.png" format="PNG" scalefit="1" />
- </imageobject>
- <textobject>
- <para>
- Generating a self signed certificate for your server
- </para>
- </textobject>
- </mediaobject>
- </figure>
- <para>
- On entering the details of your certificate, select <guilabel>Next</guilabel> to proceed. The figure below illustrates an example of a the next screen displayed after completing the details for a certificate to be sent to Equifax. Please note that if you are generating a self signed key, for your server, this screen is not displayed.
- </para>
- <figure float="0" id="begin-cert-request">
- <title>Begin certificate request</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/genkey7.png" format="PNG" scalefit="1" />
- </imageobject>
- <textobject>
- <para>
- Begin certificate request
- </para>
- </textobject>
- </mediaobject>
- </figure>
- <para>
- Pressing the return key, will display the next screen from which you can enable or disable the encryption of the private key. Use the spacebar to enable or disable this. When enabled, a [*] character will be displayed. On selecting your preferred option, select <guilabel>Next</guilabel> to proceed to the next step.
- </para>
- <figure float="0" id="protect-private-key">
- <title>Protecting your private key</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/genkey9.png" format="PNG" scalefit="1" />
- </imageobject>
- <textobject>
- <para>
- Protecting your private key
- </para>
- </textobject>
- </mediaobject>
- </figure>
- <para>
- The next screen allows you to set your key passphase. Please do not lose this pass phase as you will not be able to run the server without it. You will need to regenerate a new private or public key pair and request a new certificate from your CA as indicated. For security, the passphase is not displayed as you type. On typing your preferred passphase, select <guilabel>Next</guilabel> to go back to your terminal.
- </para>
- <figure float="0" id="set-passphase">
- <title>Set passphase</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/genkey10.png" format="PNG" scalefit="1" />
- </imageobject>
- <textobject>
- <para>
- Set passphase
- </para>
- </textobject>
- </mediaobject>
- </figure>
+ <note>
+ <title>Note: Remove a Previously Created Key</title>
+ <para>
+ If there already is a key file for a particular hostname in your system, the utility will refuse to start. In this case, remove the existing file using the following command, and then run the utility again:
+ </para>
+ <screen>~]# <command>rm /etc/pki/tls/private/<replaceable>hostname</replaceable>.key</command></screen>
+ </note>
<para>
- If you attempt to run <command>genkey makeca</command> on a server that has an existing key pair, an error message will be displayed as illustrated below. You need to delete your existing key file as indicated to generate a new key pair.
+ To complete the key and certificate creation, take the following steps:
</para>
- <figure float="0" id="genkey-error">
- <title>genkey error</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/genkey11.png" format="PNG" scalefit="1" />
- </imageobject>
- <textobject>
- <para>
- genkey error
- </para>
- </textobject>
- </mediaobject>
- </figure>
- <itemizedlist>
- <listitem>
+ <procedure>
+ <step>
<para>
- <ulink url="http://httpd.apache.org/docs/2.2/ssl/" />
+ Review the target locations in which the key and certificate will be stored.
</para>
- </listitem>
- <listitem>
+ <figure id="figure-apache-mod_ssl-genkey-01">
+ <title>Running the <application>genkey</application> utility</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/apache-mod_ssl-genkey-01.png" format="PNG" scalefit="1" />
+ </imageobject>
+ <textobject>
+ <para>
+ Running the <application>genkey</application> utility
+ </para>
+ </textobject>
+ </mediaobject>
+ </figure>
<para>
- <ulink url="http://httpd.apache.org/docs/2.2/vhosts/" />
+ Use the <keycap>Tab</keycap> key to select the <guibutton>Next</guibutton> button, and press <keycap>Enter</keycap> to proceed to the next screen.
</para>
- </listitem>
- </itemizedlist>
+ </step>
+ <step>
+ <para>
+ Using the <keycap>Up</keycap> and <keycap>down</keycap> arrow keys, select the suitable key size. Note that while the large key increases the security, it also increases the response time of your server. Because of this, the recommended option is <literal>1024 bits</literal>.
+ </para>
+ <figure id="figure-apache-mod_ssl-genkey-02">
+ <title>Selecting the key size</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/apache-mod_ssl-genkey-02.png" format="PNG" scalefit="1" />
+ </imageobject>
+ <textobject>
+ <para>
+ Selecting the key size
+ </para>
+ </textobject>
+ </mediaobject>
+ </figure>
+ <para>
+ Once finished, use the <keycap>Tab</keycap> key to select the <guibutton>Next</guibutton> button, and press <keycap>Enter</keycap> to initiate the random bits generation process. Depending on the selected key size, this may take some time.
+ </para>
+ </step>
+ <step>
+ <para>
+ Decide whether you wish to send a certificate request to a certificate authority.
+ </para>
+ <figure id="figure-apache-mod_ssl-genkey-03">
+ <title>Generating a certificate request</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/apache-mod_ssl-genkey-03.png" format="PNG" scalefit="1" />
+ </imageobject>
+ <textobject>
+ <para>
+ Generating a certificate request
+ </para>
+ </textobject>
+ </mediaobject>
+ </figure>
+ <para>
+ Use the <keycap>Tab</keycap> key to select <guibutton>Yes</guibutton> to compose a certificate request, or <guibutton>No</guibutton> to generate a self-signed certificate. Then press <keycap>Enter</keycap> to confirm your choice.
+ </para>
+ </step>
+ <step>
+ <para>
+ Using the <keycap>Spacebar</keycap> key, enable (<literal>[*]</literal>) or disable (<literal>[ ]</literal>) the encryption of the private key.
+ </para>
+ <figure id="figure-apache-mod_ssl-genkey-04">
+ <title>Encrypting the private key</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/apache-mod_ssl-genkey-04.png" format="PNG" scalefit="1" />
+ </imageobject>
+ <textobject>
+ <para>
+ Encrypting the private key
+ </para>
+ </textobject>
+ </mediaobject>
+ </figure>
+ <para>
+ Use the <keycap>Tab</keycap> key to select the <guibutton>Next</guibutton> button, and press <keycap>Enter</keycap> to proceed to the next screen.
+ </para>
+ </step>
+ <step>
+ <para>
+ If you have enabled the private key encryption, enter an adequate passphrase. Note that for security reasons, it is not displayed as you type, and it must be at least five characters long.
+ </para>
+ <figure id="figure-apache-mod_ssl-genkey-05">
+ <title>Entering a passphrase</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/apache-mod_ssl-genkey-05.png" format="PNG" scalefit="1" />
+ </imageobject>
+ <textobject>
+ <para>
+ Entering a passphrase
+ </para>
+ </textobject>
+ </mediaobject>
+ </figure>
+ <para>
+ Use the <keycap>Tab</keycap> key to select the <guibutton>Next</guibutton> button, and press <keycap>Enter</keycap> to proceed to the next screen.
+ </para>
+ <important>
+ <title>Important: Do Not Forget the Passphrase</title>
+ <para>
+ Entering the correct passphrase is required in order for the server to start. If you lose it, you will need to generate a new key and certificate.
+ </para>
+ </important>
+ </step>
+ <step>
+ <para>
+ Customize the certificate details.
+ </para>
+ <figure id="figure-apache-mod_ssl-genkey-06">
+ <title>Specifying certificate information</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/apache-mod_ssl-genkey-06.png" format="PNG" scalefit="1" />
+ </imageobject>
+ <textobject>
+ <para>
+ Specifying certificate information
+ </para>
+ </textobject>
+ </mediaobject>
+ </figure>
+ <para>
+ Use the <keycap>Tab</keycap> key to select the <guibutton>Next</guibutton> button, and press <keycap>Enter</keycap> to finish the key generation.
+ </para>
+ </step>
+ <step>
+ <para>
+ If you have previously enabled the certificate request generation, you will be prompted to send it to a certificate authority.
+ </para>
+ <figure id="figure-apache-mod_ssl-genkey-07">
+ <title>Instructions on how to send a certificate request</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/apache-mod_ssl-genkey-07.png" format="PNG" scalefit="1" />
+ </imageobject>
+ <textobject>
+ <para>
+ Instructions on how to send a certificate request
+ </para>
+ </textobject>
+ </mediaobject>
+ </figure>
+ <para>
+ Press <keycap>Enter</keycap> to return to a shell prompt.
+ </para>
+ </step>
+ </procedure>
+ <para>
+ Once generated, add the key and certificate locations to the <filename>/etc/httpd/conf.d/ssl.conf</filename> configuration file:
+ </para>
+ <screen>SSLCertificateFile /etc/pki/tls/certs/<replaceable>hostname</replaceable>.crt
+SSLCertificateKeyFile /etc/pki/tls/private/<replaceable>hostname</replaceable>.key</screen>
+ <para>
+ Finally, restart the <systemitem class="service">httpd</systemitem> service as described in <xref linkend="s3-apache-running-restarting" />, so that the updated configuration is loaded.
+ </para>
</section>
</section>
<section id="s1-apache-resources">
diff --git a/en-US/images/apache-mod_ssl-genkey-01.png b/en-US/images/apache-mod_ssl-genkey-01.png
new file mode 100644
index 0000000..5d3952e
Binary files /dev/null and b/en-US/images/apache-mod_ssl-genkey-01.png differ
diff --git a/en-US/images/apache-mod_ssl-genkey-02.png b/en-US/images/apache-mod_ssl-genkey-02.png
new file mode 100644
index 0000000..5f0bb11
Binary files /dev/null and b/en-US/images/apache-mod_ssl-genkey-02.png differ
diff --git a/en-US/images/apache-mod_ssl-genkey-03.png b/en-US/images/apache-mod_ssl-genkey-03.png
new file mode 100644
index 0000000..ff0eb87
Binary files /dev/null and b/en-US/images/apache-mod_ssl-genkey-03.png differ
diff --git a/en-US/images/apache-mod_ssl-genkey-04.png b/en-US/images/apache-mod_ssl-genkey-04.png
new file mode 100644
index 0000000..1de182b
Binary files /dev/null and b/en-US/images/apache-mod_ssl-genkey-04.png differ
diff --git a/en-US/images/apache-mod_ssl-genkey-05.png b/en-US/images/apache-mod_ssl-genkey-05.png
new file mode 100644
index 0000000..4f2fa66
Binary files /dev/null and b/en-US/images/apache-mod_ssl-genkey-05.png differ
diff --git a/en-US/images/apache-mod_ssl-genkey-06.png b/en-US/images/apache-mod_ssl-genkey-06.png
new file mode 100644
index 0000000..35bf2f3
Binary files /dev/null and b/en-US/images/apache-mod_ssl-genkey-06.png differ
diff --git a/en-US/images/apache-mod_ssl-genkey-07.png b/en-US/images/apache-mod_ssl-genkey-07.png
new file mode 100644
index 0000000..4da6ddf
Binary files /dev/null and b/en-US/images/apache-mod_ssl-genkey-07.png differ
More information about the docs-commits
mailing list