** HOWTO Clearing some Confusions about SSL Certs locations on WHM server **
In dealing with SSL Certificates, I found some confusions. The actual sequence of how to get a certificate made up is described clearly in RedHat's online manual here:
Although the manual is clear, several confusing things turned up along the way, including:
a) The directories for holding the keys and matching certificates, as described in the online RedHat manual, are different from the directories which are actually used in the RedHat 7.3 server!
b) The WHM's SSL Manager section makes a distinction between the "Install the SSL Certificate and set up the Domain" script ("installssl") and the "Change CPanel/WHM Certificate" script ("installcpssl"), but what's the difference?
c) The ca-bundle which I received from my certificate vendor came in different versions, and the name it came under is not the name under which it must be installed.
e) In certain directories, there exist apparent KEYs and CRTs for 'snakeoil'. And there are also some symlinks with names like e0f43512 pointing at snakeoil. So what the hell is that?
The purpose of this HOWTO is to clear up these four confusions, as they relate to RedHat 7.3 servers being administred with WHM.
The directory which is being used to hold the KEYs is /usr/share/ssl/private.
The directory which is being used to hold the CRTs is /usr/share/ssl/certs.
The RedHat document describes the use of /etc/httpd/conf/ssl.key directory and /etc/httpd/conf/ssl.crt directory for your KEYs and CRTs. Although these directories exist on the server (and contain the 'snakeoil' certificates), as far as I can tell, these directories and the stuff in them will not be used by you or by WHM in installing SSL certificates for your clients, or for your server itself.
The RedHat document describes using a file called 'server.key' and another called 'server.crt'. I found files with these names in the (unused) /etc/httpd/conf/ssl.key and /etc/httpd/conf/ssl.crt directories. However, the files themselve are just textfiles and inside they say "THIS FILE HAS TO BE REPLACED BY A REAL SERVER CERTIFICATE! (SKIPME)" . So we can assume that server.key and server.crt are not in use.
On my server, I also found another, similar set of directories at /usr/local/apache/conf/ssl.key and /usr/local/apache/conf/ssl.crt! These also contain the snakeoil 'keys' and the 'server.key' files! And the server.key file there also says "THIS FILE HAS TO BE REPLACED BY A REAL SERVER CERTIFICATE! (SKIPME)"
I don't know why we have these different locations. I don't know why we have 'server.key' files that aren't server keys. But I do know this:
The directory which is actually used to hold the KEYs is /usr/share/ssl/private.
The directory which is actually used to hold the CRTs is /usr/share/ssl/certs.
That's the first useful thing to know. Will the *real* directories please stand up?
OK. The *real* directories are /usr/share/ssl/private and /usr/share/ssl/certs.
The difference between "Install SSL Certificate" and "Change Cpanel Certificate"
These two commands in WHM's SSL section are different, and the scripts they call are different. (To see script names, place the mouse pointer over the link, and see the scriptname in the browser status bar.)
Maybe cpanel does some extra stuff when it's installing for cpanel (your server), I don't know. But I do know this:
The directory where *client* keys and *server* keys are kept, is the same: /usr/share/ssl/private.
The directory where *client* certs and *server* certs are kept, is the same: /usr/share/ssl/certs.
What would happen if you just plugged your keys and certs into this folder? Would it work? I don't know. But since WHM makes a point to spell out a different script to install the client certs and the server certs, I would guess that it is safer to install your keys and certs via WHM.
Ca-bundle names and usage
In RedHat's Manual (link above), the process of getting a key and certificate is pretty straightforward. You can make a 'self-signed' certificate, which will function fine providing encryption for your server and visiting browsers. Only problem is, the browsers will whine and complain, and tell their owners that you and your server are untrustworthy rascals and out to steal people's money! Well, maybe the visiting browsers don't go that far, but they do complain and call you 'untrusted'.
If you're just making a certificate for your own use, you don't care if your browser complains.
But if you're making a certificate to use in accepting money, or making your hosting customers feel safe when accessing cpanel securely, then you'll have to pay money to a Big Flapdoodle Authority to make you an "OFFICIAL" certificate, and the browsers will be so happy they will not complain and worry the customers.
The RedHat Manual explains clearly the three step process in that event: 1) make yourself a key; 2) make yourself a special coded 'application form' called a CSR (certificate signing request) and send it with money to a Big Flapdoodle Authority; and 3) receive from the Big Flapdoodle Authority a CRT (certificate) which matches the key you made.
The point is: Now you have a KEY (for you) and a CRT (for visitors browsers).
And, more to the point, this new CRT, due to the effect of paying money, has information inside about the Big Flapdoodle Authority, and this information makes browsers feel all safe.
Now we come to a fork in the road.
First, there are Big Flapdoodle Authorities who are really impressive to browsers. Such as Verisign. When a browser sees the information that it's Verisign, the browser is immediately happy.
Then there are other Big Flapdoodle Authorities who are not quite so impressive to browsers. In this case, the BFA has to show it's badge to the browser, to make the browser happy. This badge is a separate textfile containing more human-unreadable gobblygook, but it tells the browser what it needs to hear.
The name for this additional 'badge' that needs to be shown is the 'CA-bundle'. That means the 'Certificate Authority - bundle'. Take, for example, the Comodo company who sell the Instant SSL brand of certificates. Comodo isn't a big enough BFA to impress the browsers all on their own, but they've made a deal with a company called GTECyberTrust which *is* impressive to browsers, and because Comodo/InstantSSL has a badge issued by GTE, then that makes the browser happy. So depending on who your BFA is, you may have to install a 'ca-bundle' (badge) as well as your key and certificate.
Next confusion: When I received my certificate and the ca-bundle from Comodo/InstantSSL there were not two files sent to me, but four files sent to me. They sent:
1) nameof_ourserver_com.crt (our certificate);
2) the ComodoSecurityServicesCA.crt (a certificate authority file);
3) the GTECyberTrustRootCA.crt (another certificate authority file); and
4) the ca-bundle (the Comodo and the GTE certificate authority files bundled together);
That's too many files!
Running an apache server, you only need your key, plus #1 and #4 from the BFA. That is, you need your own certificate, and you need the bundled version of the Certificate Authorities.
So when installing, for example, your server's certificate in WHM, you'll copy and paste the key that you originally made into the 'key' box. You'll copy and paste the certificate that the BFA send you into the 'certificate' box. And you'll copy and paste the bundled version into the 'ca-bundle' box.
Here's what happens next. Let's assume your server is named bear at your domain naked.com. That is, your server's name is 'bear.naked.com'. From the key information you pasted into the 'key' box, WHM will make a textfile containing that same information. The name of this textfile will be bear.naked.com.key. This file will be found in the /usr/share/ssl/private directory. Likewise, you'll find bear.naked.com.crt in the /usr/share/ssl/certs directory.
And in the /usr/share/ssl/certs directory, you should also find bear.naked.com.cabundle.
Important Note #1: What do you do if you just find ca-bundle there?
Answer: Change its name to bear.naked.com.cabundle.
I had a difficulty changing the server's certificate. Being cheap, I'd installed a self-signed certificate originally. And this went fine. But when I came back with a paid certificate, I had trouble getting it installed. Oh the cert seemed to work OK, but the browser couldn't see the 'badge' and so the browser whined about the site being 'untrusted'. When I looked in the folder I found 'ca-bundle', and also 'bare.naked.com.cabundle'. That seemed odd to me, so I moved bare.naked.com.cabundle out -- that was the old ca-bundle, still somehow left over -- and then I renamed ca-bundle to bare.naked.com.cabundle. That did the trick. (Perhaps WHM has a bug with *changing* the ca-bundle.)
What are the 'snakeoil' certificates and keys? And what are the numerical symlinks pointing to snakeoil certificates? I don't know.
However, I do know that the snakeoil certificates and these symlinks do not appear in the directories where your actual certificates and keys are kept. That is, in the /usr/share/ssl/private and /usr/share/ssl/certs directories, there are no snakeoil files and no numbered symlinks.
Since I don't know what the snakeoil files are for, I leave them alone, and they leave me alone.
-- Arthur Cronos from Voltos