Wojno: Tag apache2

Creating your own Apache SSL Certificate Signed by your Root CA

Christopher Wojno — Sat, 08 Nov 2008 15:17:00 -0800

This article is part 2 of Going SSL with Your Own Root CA

Putting your Root CA to work

Now that you have your own Root CA, it doesn’t do anyone any good unless you use it. You use it by creating certificates for services. The rule is one certificate per-IP address. If you need additional certificates, you should have an IP address for each certificate. Any domain (or sub-domain, etc.) listed in the Certificate’s CN (Common Name) should resolve to its own unique IP address. Now, nothing is set in stone. But that’s the way it should be done. I’ve used multiple certificates for different domains on the same server using Virtual Hosts (same IP) before, but Apache warned me every time I started the server that this is bad practice. If you’re using Apache, it will still work, but you’ve been warned (again).

Disclaimers

This guide is for amateur, non-production use only. I make no warranties or guarantees as to the correctness of this document. This guide involves escalating privileges and may cause irreparable damage if used improperly. You use this document at your own risk and I hereby disclaim any responsibility or liability for your actions or non-actions.

Assumptions

I’m assuming you’re using Apache 2.X with mod_ssl already installed. I’m also assuming you’ve already set-up a vhost file with the site you want to SSL already created and configured minus the specification of the server certificate, and trust chain. I realize this is a lot to assume. This can help you setup an Apache server with SSL.

Creating a Server Key

Just as with the Root CA key, you need a server key. Now, if you already have one, relax, skip this step (though I still urge you to create and migrate to the “secure” environment created in the next step). You can re-use your server key as many times as you like until you want to upgrade the private key quality (or the key is compromised). If you have not created a server key, you’ll need to do so now.

We’ll use OpenSSL again, but first, let’s create a safe place for our key. The key needs to be readable by the server upon start-up (meaning, the key cannot be encrypted) or Apache (or any other server) will be unable to use it without first asking you for a password. If you don’t mind typing it in each time, that’s your prerogative. However, for live or even development environments, it’s simply impractical.

Just as with the Root CA key, you must keep this server key confidential as well. If it is breached, anyone can masquerade as your web server; thus defeating the purpose of the certificate. If you need to move the key, you are advised to use OpenSSL to encrypt it first, however, that is a tutorial for another day.

Create the “secure” environment

Create a comfy place for your key. I like to put it in /etc/apache2/ssl with Gentoo, but the better place is likely /usr/local/etc/apache2/ssl and if you use Windows: there are no rules for file placement. With that: create your directory:

sudo mkdir /usr/local/etc/apache2
sudo mkdir /usr/local/etc/apache2/ssl
sudo chmod 0770 /usr/local/etc/apache2/ssl
sudo groupadd apache_ssl_admins
sudo chown :apache_ssl_admins /usr/local/etc/apache2/ssl
sudo usermod -a -G apache_ssl_admins YOURUSERNAME # varies by OS

Here’s what I’ve done:

Created an apache2 directory (if it didn’t exist, if this call fails, just make sure the directory is there)
Created the SSL directory where we’ll store the server key
Changed the permissions for the directory such that only root can access it
Created a group called “apache_ssl_admins”
Changed the ownership of the new directory to allow members of the apache_ssl_admins access
Added you to the new group called “apache_ssl_admins”, note that this step may vary among Operating Systems so modify this command as required.

You’ll need to log out and log back into your server for the group membership to take effect.

Now, I’ve put the word “secure” in quotes as if anyone were to compromise the server and gain access to the apache_ssl_admins group, your key is then accessible. Your key is only as secure as your server.

Once you’ve logged back in, cd to the newly created “secure” environment.

cd /usr/local/etc/apache2/ssl

Creating the server key

You will now generate a server key. I highly recommend that you study the documentation for OpenSSL. It’s very very rough, but it will help you understand the commands you’re entering. It may be necessary to update these commands as machines become faster and the encryption level becomes insufficient.

openssl genrsa -out www.pem 2048

This generates a new file called www.pem in your “secure” environment. This is an RSA private key with a bit length of 2048. This bit-length is considered to be good by today’s standards. You may use any power of two; though, be warned, larger numbers require more time to initiate SSL connections. Smaller numbers will result in a less secure SSL handshake (and vicariously a less secure SSL session).

Again, it is a good idea to encrypt this key with 3des. I’ve not done so to facilitate this demonstration. Please see the previous tutorial for instructions about encrypting your server’s private key. The instructions for encrypting your Root CA private key are applicable to this purpose.

Generate a Certificate Signing Request

The Certificate Signing Request (CSR) is used by Root CA’s to create certificates for people who need them. A CSR is a uniform way to telling Root CA’s exactly what the certificate should say. The Root CA merely signs the CSR and viola: a certificate. Well, it’s not all that simple. The Root CA also adds an expiration date to the signature or other fields deemed necessary or desired. But before it can be signed, the CSR must be generated by using the server’s key:

openssl req -new -sha1 -out www.csr -key www.pem

This command will create a file called www.csr in your “secure” environment. This file is a Certificate Signing Request. You may expose this file publicly, though that is not required if you’re signing it yourself. This new request requires that it be identified using the SHA1 hashing algorithm. This algorithm is safer than MD5 as it has been proven that MD5 collisions can be generated in a reasonable time.

You will be asked a series of questions after running this command. Answer them honestly. When you see the CN (Common Name), enter the domain name and subdomain for your certificate. I.E. for my domain: christopher.wojno.com, use as the CN: “christopher.wojno.com”

Sign your CSR and create a real server Certificate

Now that you have a CSR, we’ll use our Root CA certificate and key to sign the CSR. This creates a certificate you can use in your Apache server (or other SSL-capable web server). If you created your Root CA using my previous article, then you may use the paths I have specified here. Otherwise, you’ll need to adjust the -CA, -CAkey and -CAserial parameters to match what you have used.

openssl x509 -req -days 365 -in www.csr -CA /usr/local/etc/certificate_authority/certs/cacert.crt -CAkey /usr/local/etc/certificate_authority/private/cakey.pem -CAserial /usr/local/etc/certificate_authority/serial.srl -out www.crt

This is a lot to swallow in one step. This used to be where I became completely lost with regard to SSL Certificate generation. The command is very complex so I’ll break it down part by part:

We’re asking OpenSSL to do something
Specifically, we’re asking it to invoke it’s x509 library (SSL certificate chains)
We’re then specifying that our input will be a CSR (-req)
We want the resulting certificate to be valid for 365 days (-days 365) from date of signing
The CSR is the input (-in www.csr)
We’re using the CA public certificate created in the previous tutorial: (-CA /usr/local/etc/certificate_authority/certs/cacert.crt)
We’re using the CA’s private key created in the previous tutorial to sign this CSR: (-CAkey /usr/local/etc/certificate_authority/private/cakey.pem)
We’re using the CA’s serial file to mark the resulting certificate: (-CAserial /usr/local/etc/certificate_authority/serial.srl)
Finally, we’re outputting a new certificate for the web server: (-out ../www.crt)

That little command does quite a bit. After running it, you will be prompted for the CA Root private key password (if you created one as I recommended that you do). It should automatically increment the serial file (serial.srl) so that future certificates do not have the same serial number used to identify certificates.

Now we have an SSL certificate for your server located in /usr/local/etc/apache2. Time to tell Apache where it is.

Telling Apache about our certificate

This next step takes place in the Virtual Host configuration file (or in your httpd.conf if your OS distro has not broken that file up yet). The true location of this next step can only be described in a universal fashion by describing the purpose: website configuration. Locate that file. In Gentoo, it’s located at: /etc/apache2/vhosts.d/00_default_ssl_vhost.conf I am unsure as to its location on other operating systems.

Once you’ve located this file, you’ll need to edit it (this may require privilege escalation). Edit this file in your favorite editor (or least favorite, there is no favorite requirement).

Add or amend the following lines in the VirtualHost section of the website you wish to secure using the new SSL Certificate. The hostname of this virtual host must match the CN name you specified when you created the CSR for this site.

SSLCertificateFile /usr/local/etc/apache2/ssl/www.crt
SSLCertificateKeyFile /usr/local/etc/apache2/ssl/www.pem
SSLCertificateChainFile /usr/local/certificate_authority/certs/cacert.crt

This tells Apache:

Where our certificate can be accessed so that the server may present it to requesters
Where the server’s private key file is so that the certificate may be used to decrypt encrypted requests from requesters (these requests are encrypted using the certificate in step 1)
Where the certificate authority’s certificate is located so that Apache is able to append it to the certificate presented in step 1 (to avoid having the user’s browser look it up first)

Again, I’m assuming that you’ve already set up Apache to use SSL:

You’ve installed mod_ssl
You have enabled it in the /etc/conf.d/apache2 file
You’ve allowed access to port 443 through all firewalls (or other port you wish to use for SSL)
You’ve configured your Apache instance to listen on the SSL port

If you’ve not done so, Apache will not understand the SSL commands and will not start.

If all goes well, when you access the website at the CN name on your certificate and use the https protocol (i.e. https://CN where CN is the name used when you were asked for the Common Name when generating the CSR), you will see your website and will not be prompted to accept the authenticity of the certificate. Again, I assume you’ve completed the previous tutorial and have installed your own Root CA (used to sign this certificate) into your machine’s trusted Root certificates.

Should something go wrong

Debugging OpenSSL certificate problems is tricky and complicated. OpenSSL provides a tool for doing so over the network. I used it extensively during my first attempts at creating my certificates. Use:

openssl s_client -connect CN:PORT -debug

See the documentation# for more information. Be warned, this is a developer tool and comes with few instructions and brief explanations.

What is mod_authz_svn_db?

Christopher Wojno — Sun, 19 Aug 2007 13:31:00 -0700

Abstract

The Authorization Subversion Database Apache Module is an implementation of database driven permissions of groups and individuals for subversion repositories. Think mod_authz_svn 1 but instead of using a file to support your permissions, you can use a database. This will allow a single server repository collection the ability to host, control (via a web application with PHP/Ruby/ASP), and create permissions policies for multiple subversion repositories.

Motivation

While attending USC, Trevor Johns and I were stymied by the lack of companion collaboration software for classes which either required it or lent themselves well to practice with those tools. While most students e-mailed (or worse: shared their user accounts to share) their code, Trevor and I were the only ones with the resources to deploy a source code management server of our own. Even in our capstone classes where the use of subversion was attempted, it’s complexity quickly dazed the rest of the students and in my case, subversion fell by the wayside.

Trevor had more luck, as he spent hours developing a smiling slide presentation which explained (with more clarity than my demonstration) the benefits and use of subversion. He succeeded in getting the class to use subversion, but the deployment was still a nightmare.

History

As you may or may not be aware, Trevor and I are members of UPE, a computer science honor society. That is related only in that Ross Boucher, a fellow member, suggested that UPE create some sort of software to manage subversion projects and permissions.

I took a special interest in the project and began planning its development. I realized that we would need two separate components, the web application to provide an interface for policy setting, and the means to enforce the policies. Enforcement fell to an Apache2 (sorry Apache1 users) module. I dubbed it the mod_authz_svn_db (Module Authorization Subversion Database) after mod_authz_svn, mod_authz_mysql, mod_authz_pgsql2, mod_authz_dbd.

As a small note of interest, there was a heated battle about just using a flat file with Subversion’s mod_dav_svn module (which already existed) to manage the permissions. However, the biggest problems concern flat-file parsing for thousands of users and repositories and concurrency (writing such a huge file is bound to provoke inconsistencies in permissions). That balloons to file-system level locking. Is it ugly enough for you yet? Imagine parsing a 5,000+ line authorization file in a PHP application to figure out who has access to what. Then, imagine WRITING that data back to the file. And whatever help you if your PHP application hiccups mid-write. BYE BYE file! Better write a backup script! See why I wanted a database back-end? I’m not saying it’s impossible, it’s just not for me and maybe not for you.

Structure

I wanted this module to be useful for more than just our little web application (SwitchYard). There is no reason why other people should be forced to use our web application for use with subversion. I therefore, designed it to be as modular as possible. Mod_authz_svn_db has nothing to do with SwitchYard. You are able to use it in conjunction with other implementations.

Conforming to my modularity motif, I developed a “base” module where the bulk of the heavy lifting and programming lives. Therefore, all database specific code can be delegated to a select few functions: open, close, query. Porting this module to other databases is extremely easy. To support a new database, simply include the “base” module code and define the database specific functions. This reduces errors and speeds integration with new database technology. It also allows for database speed-up customizations (write the code optimized for your database). By far, the most difficult part is writing the SQL in C-code.

Admittedly, I used the mod_authz_svn module source code as a template (knowing nothing about Apache module programming, I figured working code is a good place to start). Some of the old structure still remains, but all of the controlling code has been gutted and replaced. I used the per-directory configuration structure to hold the database configuration. As the database configuration is flexible, it also ballooned the number of variables that are stored. Each of those had to be connected to the Apache configuration file. Because the permissions were no longer being read from a file, I had to replace the file-reading with a database call (3 of them: open, query, close).

How it works

It is an Apache2 module so it works just as those work, here’s the environment setup:

Build the module (or otherwise obtain it built)
Tell Apache where to find it (when Apache starts up, it will load that code in as a shared library and execute the hook scripts so that the module is installed and called correctly)
Build/acquire mod_auth_mysql or mod_auth_pgsql2
Configure mod_auth_pgsql2 or mod_auth_mysql in the httpd.conf or in the .htaccess (as applicable)
Configure your httpd.conf (or .htaccess files) to use the mod_dav_svn and the mod_authz_svn_db
Configure the location of your repository
Create a repository
Create the database as per the schema
Put in a user (or define the anonymous group and permissions)
(Re)Start Apache

Once you have a working environment, here is how requests are handled for anonymous users:

Browser/SVN client requests (GET) document within your repositories path; Example: svn.myserver.com/svnrepos/repositoryX/document.txt
Apache handles the GET request and passes it to the authorization chain
mod_authz_svn_db is invoked (as it sits in the aforementioned chain)
mod_authz_svn_db looks at the database for the user, in this case, since no authorization is present, the default of “anonymous” is used
Database returns a list of permissions associated with the repository and path for anonymous
Module rejects if no permissions found (permissions can be inherited from parent directories), or if permission is explicitly denied
Apache returns the success code (200 OK) if anonymous is allowed or an authorization failure (401) if anonymous is not allowed. If you are authorized in part, but not in another, you will receive a 403 (Forbidden) error, meaning you are not authorized, even if you are authorized to view other parts of the repository.

Anonymous access has two flavors: can be an explicit pseudo-user (you log-in as anonymous and supply a password, but you can explicity reject anonymous users in the database) or it can be an understood default pseudo-user (you never log-in, it automatically assumes your user name is anonymous). Either way, you can control, with very very fine detail what anonymous users can see or do. When you come to a section of the repository that needs permission beyond the anonymous user, you’ll be prompted for a password and username.

For non-anonymous users, it works EXACTLY the same as the explicit anonymous users, only you must provide a user name and password. Remember: anonymous is a special, reserved, username for anonymous users (so you can’t use it to identify a specific user).

What can you do with it?

Well, you can create a single directory for lots of repositories. That’s not novel, mod_dav_svn already lets you do that. You can also deploy permissions for your repositories. That’s not new either, mod_authz_svn lets you do that. So what can you do? You can support your permissions with a database. So you can build a web application to manage your repositories and permissions. Trevor and I are working on a Ruby on Rails version we call “SwitchYard.”

Like the name? I thought of it myself ;-). We’re using rails, so we had to go with the train theme. Real-life switch yards multiplex few tracks onto many tracks so trains can be connected with various cars and freight. In the same way, SwitchYard is the place where code can be moved, shared, and collaborated on to form a select, productive set of applications built on all the sub-components. SwitchYard, with the help of mod_authz_svn_db and friends, allows you to give wide and fine control over their own repositories. No need to get a system administrator involved.

SwitchYard talks with the database, the Apache module also talk to the database. Combined, you can do nearly anything, even develop an online community of coders… Such as CollabNet.

What databases?

Right now, the module only supports MySQL and PostgreSQL (my favorite). There is an edge version of SQLite3, but it has not been approved for the trunk build yet. While the source code is provided for each, you have the option of building only the module for the database you desire. Or you can build all and play!

How can I get it?

~~-Well, Trevor has graciously decided to host it on his server at: http://tjohns.net/svn/mod_authz_svn_db/ -~~

I’ve moved it to my own server because Trevor shouldn’t have to host my stuff. It is available here: http://svn.wojno.com/mod_authz_svn_db

I’ve decided to release this one on the FreeBSD license under the CollabNet license (I borrowed some of their code, so credit is due). I have provided basic make files, guaranteed to build on FreeBSD 6.1. I make no guarantees about other platforms (or any platform for that matter), though Michael Rodgers has informed me that it works (with minor tweaks) on SuSE 10.2. No Windows support yet. I’ll have to think about how to approach that one. I’m sure it will build and run, I just am not sure how easy it will be to configure that build script.

Anyway: please, take a look and tell me what you think. Took me about a week to code the base, and it’s been on-going development as of late for the database specific stuff. I hope that one day, this may replace mod_authz_svn! Wish us luck!

¹ This comes with subversion, you need to build it along with your subversion installation. Sorry there is no page dedicated to this module from subversion at this time (that I could find)