SSL and TLS for Humans, Part 3 (Command-Line Procedures) by Chris Pepper
In Part 1 of this article, we discussed SSL/TLS and how they work. In Part 2, we examined Apple's Certificate Assistant for working with SSL/TLS certificates. In Part 3, we discuss command-line procedures for actually using SSL/TLS certificates. In Part 4, we will look at some streamlined CA tools.
What Can You Do? -- There are a wide variety of things you might do with certificates, but the most common include:
OpenSSL can perform all the above except #2. Getting a CA to sign a CSR is normally handled through the CA's secure web site (protected using SSL/TLS, naturally!). Because the openssl command is complicated, the OpenSSL package includes CA.pl, a perl script to facilitate the more popular actions (see above). Mac OS X installs it at /System/Library/OpenSSL/misc/CA.pl:
pepperbook:~ julia:~$ /System/Library/OpenSSL/misc/CA.pl -help
usage: CA -newcert|-newreq|-newreq-nodes|-newca|-sign|-verify
The Very First Step: Think About Security -- You need to think carefully about several issues before setting up a CA. Understand that you do not necessarily need to choose the most paranoid answers, but it's important to spend some time considering how much paranoia is appropriate, which is largely determined by exactly what you will protect with the certificates signed by your new CA, and the particulars of your situation. Key questions include:
root, since the CA is likely to be the most sensitive function for the machine it runs on.Remember that there are lots of people constantly trying to break into computers all over the world, while the number of people who actually enter any particular home or office is guaranteed to be smaller.
Configure OpenSSL -- Now verify that you are using the openssl program installed by Apple (/usr/bin/openssl); if you are using another one, you probably have to configure a different copy of openssl.cnf. Then make a backup of /System/Library/OpenSSL/openssl.cnf and configure it to your requirements -- only an administrator can do this:
pepperbook:~ julia$ which openssl
/usr/bin/openssl
pepperbook:~ julia$ cd /System/Library/OpenSSL/
pepperbook:/System/Library/OpenSSL julia$ sudo cp -p openssl.cnf openssl.cnf.ORIG2
Password:
pepperbook:/System/Library/OpenSSL julia$ bbedit openssl.cnf
You can use any text editor, as long as it saves openssl.cnf with UNIX line breaks ("LF" characters). I use BBEdit because it is excellent, and its bbedit command-line tool makes illustration clearer. Customize your openssl.cnf file with the CA directory you want to use, and to reflect your organization. The diff output below shows a few changes, mostly to become a CA, ready to create TidBITS certificates. In "unified diff" output, lines beginning with a - (minus sign) were removed or modified from the original, and lines beginning with a + (plus sign) are additions or changes.
pepperbook:/System/Library/OpenSSL julia$ diff -U0 openssl.cnf.ORIG openssl.cnf
--- openssl.cnf.ORIG 2006-10-19 01:04:35.000000000 -0400
+++ openssl.cnf 2007-04-01 01:49:26.000000000 -0400
@@ -37 +37 @@
-dir = ./demoCA # Where everything is kept
+dir = /Users/julia/CA/tidbits
@@ -41,2 +41,2 @@
-#unique_subject = no # Set to 'no' to allow creation of
- # several ctificates with same subject.
+unique_subject = no # Set to 'no' to allow creation of
+ # several certificates with same subject.
@@ -45 +45 @@
-certificate = $dir/cacert.pem # The CA certificate
+certificate = $dir/ca.tidbits.com.20070401.crt # The CA certificate
@@ -50 +50 @@
-private_key = $dir/private/cakey.pem# The private key
+private_key = $dir/private/ca.tidbits.com.20070401.key # The private key
@@ -125 +125 @@
-countryName_default = AU
+countryName_default = US
@@ -130 +130 @@
-stateOrProvinceName_default = Some-State
+stateOrProvinceName_default = New York
@@ -132,0 +133 @@
+localityName_default = Ithaca
@@ -135 +136 @@
-0.organizationName_default = Internet Widgits Pty Ltd
+0.organizationName_default = TidBITS
@@ -147,0 +149 @@
+emailAddress_default = webmaster@tidbits.com
A word of warning: CA.pl uses a few standard filenames extensively, so after you run it, rename the output files before using CA.pl again; otherwise it will overwrite the files. Part 4 of this article describes some friendlier tools that avoid overwriting files.
1. Create a new Certificate Authority -- Fundamentally, a CA is a party in possession of a root certificate which can sign other certificates. Unfortunately, CA.pl -newca ignores openssl.cnf's dir setting, and always sets up a new CA in ./demoCA, so some tweaking is required for a real CA. In our example, we will work with a CA in ~julia/CA/tidbits.
When prompted for a "PEM pass phrase", enter a strong password! Someone who can read your private key can impersonate any server using one of its child certificates, or decrypt their communications. Note that "Common Name" is the most important field. If your web site's hostname doesn't match the common name in the certificate, browsers will generate a security alert. Common names should generally be the full official domain name of the site, such as www.amazon.com, rather than www or amazon.com or 72.21.206.5.
pepperbook:~ julia$ /System/Library/OpenSSL/misc/CA.pl -newca
CA certificate filename (or enter to create)
Making CA certificate ...
Generating a 1024 bit RSA private key
.................++++++
.....++++++
writing new private key to './demoCA/private/cakey.pem'
Enter PEM pass phrase:
Verifying - Enter PEM pass phrase:
-----
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) [US]:
State or Province Name (full name) [New York]:
Locality Name (eg, city) [Ithaca]:
Organization Name (eg, company) [TidBITS]:
Organizational Unit Name (eg, section) []:
Common Name (eg, YOUR name) []:ca.tidbits.com
Email Address [webmaster@tidbits.com]:
pepperbook:~ julia$ mkdir CA
pepperbook:~ julia$ mv demoCA/ CA/tidbits
pepperbook:~ julia$ cd CA/tidbits/
pepperbook:~/CA/tidbits julia$ ls -l
total 16
-rw-r--r-- 1 julia julia 1253 Apr 1 01:52 cacert.pem
drwxr-xr-x 2 julia julia 68 Apr 1 01:52 certs
drwxr-xr-x 2 julia julia 68 Apr 1 01:52 crl
-rw-r--r-- 1 julia julia 0 Apr 1 01:52 index.txt
drwxr-xr-x 2 julia julia 68 Apr 1 01:52 newcerts
drwxr-xr-x 3 julia julia 102 Apr 1 01:52 private
-rw-r--r-- 1 julia julia 17 Apr 1 01:52 serial
pepperbook:~/CA/tidbits julia$ echo 01 > serial
pepperbook:~/CA/tidbits julia$ chmod go-rx private/
pepperbook:~/CA/tidbits julia$ ls -lR
total 16
-rw-r--r-- 1 julia julia 1253 Apr 1 01:52 cacert.pem
drwxr-xr-x 2 julia julia 68 Apr 1 01:52 certs
drwxr-xr-x 2 julia julia 68 Apr 1 01:52 crl
-rw-r--r-- 1 julia julia 0 Apr 1 01:52 index.txt
drwxr-xr-x 2 julia julia 68 Apr 1 01:52 newcerts
drwx------ 3 julia julia 102 Apr 1 01:52 private
-rw-r--r-- 1 julia julia 3 Apr 1 01:53 serial
./certs:
./crl:
./newcerts:
./private:
total 8
-rw-r--r-- 1 julia julia 963 Apr 1 01:52 cakey.pem
pepperbook:~/CA/tidbits julia$ mv private/cakey.pem private/ca.tidbits.com.20070401.key
Under the hood, CA.pl creates several empty files and directories, and runs the openssl command to create a root certificate and key, something like:
openssl req -new -x509 -days 365 -keyout ./demoCA/private/cakey.pem -out ./demoCA/cacert.pem
To review your new root certificate, use the c_info command. Note that this CA certificate is only valid for a year -- a longer term seems more appropriate for a "root certificate" if you aren't just testing. To change that, edit the '$DAYS="-days 365";' line in CA.pl before using "CA.pl -newca".
Once you have your root certificate, you should make it available for people to download and trust in their browsers. Since this is a critical piece of security infrastructure, think about how people can get it, and how they can know it's legitimate. If someone hacks your web site and puts up their own bogus certificate, how would you or your users know? One option is to publicize the fingerprint of the certificate in "alternative media", like a phone answering message, or on paper, which provides a reasonably tamper-proof check (assuming it's not a digital voice-mail system!), but that's something to decide based on the specifics of your situation.
Because certificates and private keys are base-64 encoded, and the important parts (the cryptographic keys) are really just large numbers, they're hard to tell apart. To alleviate this, it's handy to embed additional information into the certificate files (OpenSSL conveniently ignores everything it doesn't want), which can make them easier to work with. I suggest something like the following (assuming you generated cacert.pem on April 1st, 2007):
pepperbook:~/CA/tidbits julia$ openssl x509 -text -fingerprint -sha1 -in ~/CA/tidbits/cacert.pem -out ~/CA/tidbits/ca.tidbits.com.20070401.crt
SHA1 Fingerprint=CB:C4:41:62:C9:36:D2:5C:92:8F:FE:3D:D6:03:6D:56:FB:E7:0D:0A
This produces ca.tidbits.com.20070401.crt, which combines the encoded certificate itself from cacert.pem with a bunch of (non-sensitive) information about the certificate, creating a new annotated root certificate file.
If you want to reset your serial number, note that serial numbers are in hexadecimal, and OpenSSL assumes they contain an even number of digits. A common way to reset the serial number is "echo 01 > serial" (serial is in the CA directory). Otherwise OpenSSL will start from a random serial number.
2. Create a new certificate signing request -- "/System/Library/OpenSSL/misc/CA.pl -newreq-nodes" creates a new CSR, ready for a CA to sign. CSRs are not usable until they have been converted into real certificates by being signed.
For more security, server keys should be encrypted, and "CA.pl -newreq" automatically encrypts the new private key it creates along with the CSR, using DES (the older US "Data Encryption Standard"). Unfortunately, encryption means software using the certificate & key cannot start unattended, because an authorized human must enter the decryption password to access the certificate. In reality, private keys for server software are routinely not encrypted to facilitate automatic restarts, and "CA.pl -newreq-nodes" ensures the private key is not encrypted. With an unencrypted private key, it is essential to protect the private key file with access controls (UNIX permissions, restricted login access to the CA computer and files, etc.). Be sure to review permissions on new server key files, as well as the root key (inside the CA's private directory) to ensure only authorized users can access them.
pepperbook:~/CA/tidbits julia$ /System/Library/OpenSSL/misc/CA.pl -newreq-nodes
Generating a 1024 bit RSA private key
............................................................................++++++
.++++++
writing new private key to 'newkey.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) [US]:
State or Province Name (full name) [New York]:
Locality Name (eg, city) [Ithaca]:
Organization Name (eg, company) [TidBITS]:
Organizational Unit Name (eg, section) []:
Common Name (eg, YOUR name) []:www.tidbits.com
Email Address [webmaster@tidbits.com]:
Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:
An optional company name []:
Request is in newreq.pem, private key is in newkey.pem
3. Create a self-signed certificate -- "CA.pl -newcert" is equivalent to creating a CSR and using the CSR to sign itself, thus creating a certificate which attests to its own validity. Self-signed certificates are extremely common for testing and private use, as they provide exactly the same encryption as CA-signed certificates for free. This command produces newkey.pem and newcert.pem, so make sure you don't have files with these names left over from a previous operation, or they would be overwritten and lost. You might also want to append the root certificate and/or add identifying information to the certificate file (see the previous section, and Part 4, for more on adding fingerprints to certificates).
4. Request that a CA sign a CSR and return a signed certificate -- This is the part OpenSSL can't do for you. On the other hand, you could sign someone else's CSR if you are a CA (see below for how).
I'm most familiar with Thawte https://www.thawte.com/, although we keep an eye out for cheaper alternatives. The last competitor we considered was GeoTrust, also bought by VeriSign before we could switch, so we're wondering how things will settle out.
5. Sign a CSR with your own root certificate -- If you are serving as your own CA, "/System/Library/OpenSSL/misc/CA.pl -sign" will sign newreq.pem in the current directory using your CA certificate, producing newcert.pem as output.
Remember that if you create a root certificate (thus becoming a certificate authority) and use that to sign another certificate, the result is not a "self-signed certificate" - "self-signed" means a certificate signs itself, so the "certificate chain" is actually a loop containing one item. A certificate signed by a different root certificate is a 'proper' certificate with a real (non-circular) chain of trust, even if the root certificate belongs to the same party as the server certificate.
6. Check a certificate -- The standard way to check a certificate is to click the lock icon in a web browser, but there are many others, particularly useful if the certificate is not for a web site, or you need to check a certificate before using it. Certificate Assistant (available from the Keychain Access menu in the Keychain Access application) is one alternative.
For local certificates, use /System/Library/OpenSSL/misc/c_info or "openssl verify" (documentation is available with "man verify").
7. Install a certificate in a server -- Every server application that can do SSL/TLS has its own configuration system, but certificates and keys in Apache httpd (both the 1.3 and 2.x flavors) are controlled by the SSL directives. The simplest way to deal with a private CA and server certificate is to append the private CA's certificate to end of the server certificate file, and specify this file for both the SSLCertificateKeyFile and SSLCertificateChainFile directives. The key (which is a secret) goes in another file, and must be protected from unauthorized access. Apple's Server Admin can configure the SSLCertificateFile and SSLCertificateKeyFile, but Server Admin doesn't handle SSLCertificateChainFile, so that must be done manually with a text editor. When done, reload the Apache configuration (sudo apachectl configtest && sudo apachectl graceful); you might also have to quit and relaunch Safari to pick up certificate changes.
pepper@www:~$ grep SSLCertificate /etc/httpd/sites/0002_66.92.104.200_443_secure.reppep.com.conf
SSLCertificateKeyFile /etc/certificates/secure.reppep.com.key
SSLCertificateFile /etc/certificates/secure.reppep.com.crt
SSLCertificateChainFile /etc/certificates/secure.reppep.com.crt
A benefit of doing it this way is that the user will see the whole certificate chain in their browser, and can accept the root certificate, thus trusting all the other certificates it has signed. Without the SSLCertificateChainFile, a browser will present the server cert, but not offer to trust the root certificate.
8. Trust a certificate in a browser -- Unfortunately, due to legitimate fears about attackers installing their own CA certificates into browsers and making users trust fraudulent sites, adding trust for a private CA has gone from an obscure task to an actively discouraged one. In Firefox 1.5, for instance, when connecting to a SSL/TLS site with an unknown root certificate, the browser allowed you to accept the root CA directly from the unknown-certificate warning window; in Firefox 2.0 this option has been removed. Now accepting a new certificate requires a visit to Firefox > Preferences > Advanced > Encryption > View Certificates > Authorities > Import, finding the certificate file, (verifying a fingerprint via the View button), selecting "Trust this certificate to identify web sites.", and finally the clicking OK button.
Fortunately trusting a new root certificate for Safari and Apple's Mail.app is simpler. Normally, when Safari finds an untrusted site, it presents a dialog asking if you wish to connect. Clicking "Show Certificate" reveals a little information about it (click the triangle by Details for the rest), and clicking "Always trust these certificates" followed by "Continue" will add them to the X509Anchors keychain, avoiding future confirmations. If the certificate chain is set up properly on the server, this trusts the root certificate, not just the server certificate.
Apple's method for trusting certificate files is relatively easy too: Open Keychain Access, click "Show Keychains" in the lower-left hand corner if necessary, drag the new certificate onto the X509Anchors keychain, and authenticate to allow the addition. Alternatively, double-click the .crt or .pem file containing the certificate, pick X509Anchors from the pop-up list, hit OK, and authenticate.
9. Test an SSL/TLS connection -- One of the most useful troubleshooting techniques for Internet communications is connecting to a troublesome server via the telnet command and poking around, requesting help or trying commands. With SSL/TLS encryption this becomes impossible, so openssl's s_client mode fills the gap. openssl s_client establishes an encrypted connection to the specified server and then allows the user to type commands, which are encrypted and sent ("GET /" in the example below); responses from the server are decrypted and displayed. In addition, openssl displays the server's certificate.
pepperbook:~ julia$ openssl s_client -showcerts -connect secure.reppep.com:443
CONNECTED(00000003)
depth=1 /C=US/ST=New York/L=Brooklyn/O=reppep/CN=ca.reppep.com/emailAddress=webmaster@reppep.com
verify error:num=19:self signed certificate in certificate chain
verify return:0
---
Certificate chain
0 s:/C=US/ST=New York/O=reppep/CN=secure.reppep.com/emailAddress=webmaster@reppep.com
i:/C=US/ST=New York/L=Brooklyn/O=reppep/CN=ca.reppep.com/emailAddress=webmaster@reppep.com
-----BEGIN CERTIFICATE-----
MIIDPTCCAqagAwIBAgIBAjANBgkqhkiG9w0BAQQFADCBgTELMAkGA1UEBhMCVVMx
ETAPBgNVBAgTCE5ldyBZb3JrMREwDwYDVQQHEwhCcm9va2x5bjEPMA0GA1UEChMG
cmVwcGVwMRYwFAYDVQQDEw1jYS5yZXBwZXAuY29tMSMwIQYJKoZIhvcNAQkBFhR3
ZWJtYXN0ZXJAcmVwcGVwLmNvbTAeFw0wNjExMTYwNTE4MDFaFw0wNzExMTYwNTE4
MDFaMHIxCzAJBgNVBAYTAlVTMREwDwYDVQQIEwhOZXcgWW9yazEPMA0GA1UEChMG
cmVwcGVwMRowGAYDVQQDExFzZWN1cmUucmVwcGVwLmNvbTEjMCEGCSqGSIb3DQEJ
ARYUd2VibWFzdGVyQHJlcHBlcC5jb20wXDANBgkqhkiG9w0BAQEFAANLADBIAkEA
ryRad29mgEvF0ai79F8RNIUlZR3zORNn9AgCCGKkHge2qTk+u2fUazW9TSjCLA1f
VADAt8Lp9eNyASQd2dYUrQIDAQABo4IBFTCCAREwCQYDVR0TBAIwADAsBglghkgB
hvhCAQ0EHxYdT3BlblNTTCBHZW5lcmF0ZWQgQ2VydGlmaWNhdGUwHQYDVR0OBBYE
FPrQRoICmYVEQFgx9kWpu1FeiAFkMIG2BgNVHSMEga4wgauAFGFWICJjxBEyl+Vw
qcaIsx3kpI1voYGHpIGEMIGBMQswCQYDVQQGEwJVUzERMA8GA1UECBMITmV3IFlv
cmsxETAPBgNVBAcTCEJyb29rbHluMQ8wDQYDVQQKEwZyZXBwZXAxFjAUBgNVBAMT
DWNhLnJlcHBlcC5jb20xIzAhBgkqhkiG9w0BCQEWFHdlYm1hc3RlckByZXBwZXAu
Y29tggkAx8tGBEbv9b0wDQYJKoZIhvcNAQEEBQADgYEAvIEWVyGLsGKtOfdOmMzT
Pceyb51mdZr9m4pw7DOb5ZIzFg+WDYYr2+WcnNY+qSCq21VzYRAi9ANP9KY1GPQq
oTG3PUZ8u9LCiB8hkdCtHwT5l5+HvetOVThf5t7ZFZqoJ532CiQmh7TsIzspY3XF
bVZMResmsy/fxG0FKphBC38=
-----END CERTIFICATE-----
1 s:/C=US/ST=New York/L=Brooklyn/O=reppep/CN=ca.reppep.com/emailAddress=webmaster@reppep.com
i:/C=US/ST=New York/L=Brooklyn/O=reppep/CN=ca.reppep.com/emailAddress=webmaster@reppep.com
-----BEGIN CERTIFICATE-----
MIIDbDCCAtWgAwIBAgIJAMfLRgRG7/W9MA0GCSqGSIb3DQEBBAUAMIGBMQswCQYD
VQQGEwJVUzERMA8GA1UECBMITmV3IFlvcmsxETAPBgNVBAcTCEJyb29rbHluMQ8w
DQYDVQQKEwZyZXBwZXAxFjAUBgNVBAMTDWNhLnJlcHBlcC5jb20xIzAhBgkqhkiG
9w0BCQEWFHdlYm1hc3RlckByZXBwZXAuY29tMB4XDTA2MTAxOTA1MzIwNVoXDTE2
MTAyNjA1MzIwNVowgYExCzAJBgNVBAYTAlVTMREwDwYDVQQIEwhOZXcgWW9yazER
MA8GA1UEBxMIQnJvb2tseW4xDzANBgNVBAoTBnJlcHBlcDEWMBQGA1UEAxMNY2Eu
cmVwcGVwLmNvbTEjMCEGCSqGSIb3DQEJARYUd2VibWFzdGVyQHJlcHBlcC5jb20w
gZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAPQ8cBEDMi6MZ8ojvNw6a9T5ossc
N+6atmAd1L+2nxP+wzS5L7SEAv7qqyQpXZjvXOGqWd5M0Ku8cfxViZnFGAgX9/Dv
BsnRLRBWKYrMgwUQLdA1+QoSV9fMMuLAb+n7IS9gCuTXQ7Wx1gbH6nr+NnUWlXRQ
MlypaTBuw7W0bNUlAgMBAAGjgekwgeYwHQYDVR0OBBYEFGFWICJjxBEyl+VwqcaI
sx3kpI1vMIG2BgNVHSMEga4wgauAFGFWICJjxBEyl+VwqcaIsx3kpI1voYGHpIGE
MIGBMQswCQYDVQQGEwJVUzERMA8GA1UECBMITmV3IFlvcmsxETAPBgNVBAcTCEJy
b29rbHluMQ8wDQYDVQQKEwZyZXBwZXAxFjAUBgNVBAMTDWNhLnJlcHBlcC5jb20x
IzAhBgkqhkiG9w0BCQEWFHdlYm1hc3RlckByZXBwZXAuY29tggkAx8tGBEbv9b0w
DAYDVR0TBAUwAwEB/zANBgkqhkiG9w0BAQQFAAOBgQDgyd8yNjLUti9TWRH2dsEH
7YtL1MGMHtEu4PtnPNuD3HQI4Y5DEHh/Kic0DUdd3AFQitduJ7kXY5rjznvMzu3B
DhZZBOkjivLwEvjKTLWMsOWTEVOkjDWGxLEYJtd3QjOl1qROz+OK9z0sz/zG9vdS
QpoHbcAh6zJJ06TRftS6qQ==
-----END CERTIFICATE-----
---
Server certificate
subject=/C=US/ST=New York/O=reppep/CN=secure.reppep.com/emailAddress=webmaster@reppep.com
issuer=/C=US/ST=New York/L=Brooklyn/O=reppep/CN=ca.reppep.com/emailAddress=webmaster@reppep.com
---
No client certificate CA names sent
---
SSL handshake has read 2216 bytes and written 316 bytes
---
New, TLSv1/SSLv3, Cipher is DHE-RSA-AES256-SHA
Server public key is 512 bit
SSL-Session:
Protocol : TLSv1
Cipher : DHE-RSA-AES256-SHA
Session-ID: E9B14E28639DC38295C8E8981345D8FFB6F583DA03E9891F13D041A2AB133431
Session-ID-ctx:
Master-Key: 3D0D67CDBCDD18BDEA7D3825DCFBF204A75910BEE02C96ECC138EC393DD415A20107152512FA57FB8FB1443FE6CAD69E
Key-Arg : None
Start Time: 1174536515
Timeout : 300 (sec)
Verify return code: 19 (self signed certificate in certificate chain)
---
GET /
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>https://secure.reppep.com/</title>
<meta http-equiv="refresh" content="1;url=https://secure.reppep.com/webmail/">
</head>
<body>
<h1>https://secure.reppep.com/webmail/</h1>
<p>You probably want <a href="https://secure.reppep.com/webmail/">https://secure.reppep.com/webmail/</a>.</p>
</body>
</html>
closed
What Comes Next? In Part 4 of this article, we will look at some simple scripts to making running a CA more convenient.