vcert A web-based certificate authority management system built atop
Django 1.8.5 and OpenSSL.
Open Source License: GPL v2
Copyright Videntity 2013-201
This document describes a developer install. For a quicker start check out INSTALL.md instructions.
vcert is a web-based (Django) Certificate Authority (or CA) that uses OpenSSL
under the hood. The site DirectCA.org runs vcert. It was built specifically to
build x509 certificates compatible with the Direct Project. It is written in
Python and Django and can run atop Apache2 or other webserver.
vcert can be used to manage a trust anchors (i.e. a registration authority or
HISP) or a root CA.
vcert supports revocation via certificate revocation lists (CRLs). A CRL is
created for each trust anchor and is published to a URL.
This software was designed to assist in testing for compliance with the Direct Project's Applicability Statement. Perhaps you are not working in Health IT at all and are just looking for a simple way to manage certificates. You may be able to be able to use this for that purpose.
CODE CONTRIBUTIONS & PULL REQUEST WELCOME!
Installation Part 1 - Download and Initial Setup
vcert has a number of dependencies including OpenSSL, Python,
and Django. This software was tested with OpenSSL version 1.0.1, Python 2.7
and Django 1.5. SQLite is the default database and it was tested
with SQLite version 3. The following instructions assume Ubuntu 13.04 is the
operating system, but it is possible to use others. (If anyone wants to
contribute Windows, Mac, or other operating system instructions please do so.)
Here is how to get started on Ubuntu 13.04. From the terminal, start by installing OpenSSL. This is likely already installed, but installation instructions are added here for clarity.
sudo apt-get install openssl zip
Now install pip and make sure its up to date.
sudo apt-get install python-pip sudo pip install --upgrade pip
Install git and then clone the master repository.
sudo apt-get install git-core git clone https://github.com/videntity/vcert.git
Now change into the project's directory.
Let's install the necessary python libraries including Django from the project's requirements file.
sudo pip install -r vcert/requirements.txt
Now that Django is installed lets setup our database. Be sure and say yes when asking to create an administrative account as this will be used in the CA's administration.
python manage.py syncdb
A directory for OpenSSL's CA must be created. We will do so by creating a
symbolic link between
sudo ln -s vcert/apps/certificates/ca /opt/
Now copy settings_local_example.py to settings_example.py.
cp settings_local_example.py settings_example.py
You can at this point try out the server at this point with
python manage.py runserver, but your settings_local.py settings will need to
be customized before everything will work as expected.
Installation Part 2 - Django Settings
settings.py contains default settings, where the file
settings_local.py add and overwrites what is in
settings.py via Python
One of the main changes is replacing
examaple.com with your own domain. You'll
also want to setup email settings for outgoing email notifications and setup web
locations for publishing certificates and CRLs.
Certificates and CRLs get published via Amazon Web Service's (AWS) Simple
Storage Service (S3) and email notifications are sent via Simple Email Service
(SES). The email setup is easily changed, but the certificate and CRL
publishing requires S3.
vcert assumes you create three S3 buckets with "vanity"
URLs. They are
ca for CRLs and the CA's public certificate,
pubcerts for public
certificates issued, and
privcerts for private certificates. For illustration,
if you want to host your CA on the domain
example.com, then you would create the
You need to map the DNS entries accordingly to create the "vanity" URL. This is
accomplished within AWS management console for S3 and in your DNS provider's
Please see the in-line comments inside
settings_local.py for instructions
on what the various settings do.
Installlation Part 3 - OpenSSL CA Configuration
There are still a few of items that need to be addressed:
Most notably you need to do the following:
Create and/or install the root CA's (or subordinate certificate's) private
certificate and change settings_local.py accordingly. Here is how to generate a
new CA keypair with a password on the private key. It assumes the domain
ca.example.com and uses the configuration file
/opt/ca/conf/ca.example.com.cnf. Before this next step, You will likely want
to make adjustment there such the changing "example.com" to your domain, setting
organizational name, city, state, and so on. Here are the steps:
cd /opt/ca openssl genrsa -out private/ca.example.comKey.pem 2048 openssl req -sha256 -new -x509 -days 1826 -key private/ca.example.comKey.pem -out public/ca.example.com.pem openssl rsa -des3 -in ./private/ca.example.comKey.pem -out ./private/ca.example.comKey.pem
You will end up with the CA's public key in
/opt/ca/public and the private key
You need to publish the CA's public certificate and CRL somehere.
ca.example.com) is a reasonable place. In the above example, we used
the configuration file
ca.example.com.cnf. You can use openssl command line
to create the CRL for your CA.
Installation Part 4 - Setting up Cron for CRL Updates
In order to make the CRL updates automatic, we will use cron to execute a script to perform the update. Edit your crontab like so.
Now add the following line to your cron file.
0 */2 * * * /home/ubuntu/django-apps/vcert/scripts/buildcrl.sh >> /home/ubuntu/crl.log
This assumes your
vcert project is located at
and the output of this operation is written to
these paths to fit your local environment. With this setting we are updating
the CRLs every 30 minutes. Note that each "Trust Anchor" has its own CRL.
Run the Application
Now you can run the
vcert in development mode:
python manage.py runserver
The convention is to deploy
vcert on server named
Please refer to Django's documentation for more information on deploying Django
vcert makes no security claims and is provided AS-IS with NO WARRANTY. Django
has a number of security features that 'vcert' uses. It is recommended that you
use a unique
SECRET_KEY and that you host the service on HTTPS using a valid
certificate. User authentication is accomplished via django's standard
which uses salted and hashed passwords. Use up to date OpenSSL software.
In order to enable a user to act as an administraor (i.e. verify/approve
certificates) you need to give set the user's
is_staff flag to
There are other configuration via the
http://127.0.0.1:8000/admin in a development
configuration). You can so this in two ways:
- Make this user a superuser (with access to all models).
- Set the is_staff flag and enable access on the
See https://docs.djangoproject.com/en/dev/topics/auth/ for more information on authentication in Django.
vcert operation is quite simple. Any user with a CA account can create a new
"Trust anchor". A trust anchor is the child certificate of the
certificate with signing authority. (Remember this is configured in
settings_local.py) After the Trust anchor request is made an email is sent to
the CA's verifier (
What you do for "verification" is up to you. After the
verifier verifies the information, then the verifier finds the certificate in
question within the Django admin, checks the "verify" box and then clicks save.
(How you do verification is up to you). When this happens, certificates are published and an email notification is sent to the person requesting the certificate. Then the user may create leaf nodes off of the Trust Archor from his or her account. These, too, go through the same verification notification and verification process before they may be accessed by the requestor.
vcert requires an invitation code to create an account. This is
accomplished in the Django admin. Click the section that says "Invitations"
under "Accounts", then click "Add invitation", then provide an invitation code
and the email to which it should be sent. Click "Save" and an email with the
code will be sent. Anyone can use the invitation code. In other words, it does
not require the new user to use the email in the invitation to register.