minicert

A tiny identity and certificate management API, written in Django.

This API supports:

• Creating/Deleting Customers
• Creating Certificates
• Listing all of a Customer’s Active Certificates
• Activating/Deactivating Certificates. If a certificate is either activated or de-activated, it can notify an external system (via an HTTP call) about that fact.
• Persistence (data is stored in a DB and survives computer restarts)

Prerequisites

This documentation assumes you have Docker and Git installed.

Depending on your usecase, you may also want Python (3.6+), pip, and virtualenv installed.

In development, minicert uses a SQLite (3.8.3+) database for simplicity.

In production, minicert uses PostgreSQL for scale, but any SQL database can be used instead. See Django's documentation on database setup.

Scaling minicert

This API and associated docker application have the following scaling properties

• In production, the PostgreSQL database scales to terabytes of data.
• In development, the SQLite database scales to gigabytes of data.
• Because the main application runs in a single container on a single host behind the nginx container, it may not scale well with the number of concurrent requests. In production this application should be multiplexed behind a load balancer.
• The backing data stores are limited by the size of the host. If you run the PostgreSQL container on a small host, it will fill up your disk quickly. In a scaled production setting, the database should be located on dedicated hosts.

Getting Started

Clone the repository

$ git clone https://github.com/hcourt/minicert.git

... with Docker

$ docker-compose up

... without Docker

Start a virtualenv

$ python -m venv ~/.virtualenvs/minicertenv

$ source ~/.virtualenvs/minicertenv/bin/activate

Install requirements

$ pip install -r requirements/py3.txt

Web App

Visit the Django console for the API at http://localhost:8000/api/

Production

... with Docker

$ CONFIG_ENV=production docker-compose up

... without Docker

Run the server

$ python manage.py runserver --settings=minicert.settings.production

Development

Database changes

Create database migrations for model updates

$ python manage.py makemigrations app

Run migrations against the database

$ python manage.py migrate

Shell

Start a python shell in the Django environment

$ python manage.py shell

Run a development build

... with Docker

$ CONFIG_ENV=development docker-compose up

... without Docker

Run a dummy http server for certificate authority mocking. We use httpbin.

$ sudo docker run -p 80:80 kennethreitz/httpbin

Run the server

$ python manage.py runserver

API Specification

You are encouraged to visit the API via a browser. The UI makes it simple to navigate between endpoints.

The examples below are accomplished with curl, but you could visit these in-browser as well.

Index

/api/

Allowed: OPTIONS, GET

List all API endpoints

Example

$ curl http://localhost:8000/api/

{
 "customer_list": "http://localhost:8000/api/customers/",
 "customer_index": "http://localhost:8000/api/customer/1/",
 "customer_certificates": "http://localhost:8000/api/customer/1/certs/",
 "customer_active_certificates": "http://localhost:8000/api/customer/1/active-certs/",
 "certificates": "http://localhost:8000/api/certificates/",
 "certificate_index": "http://localhost:8000/api/certificate/1/",
 "certificate_activate": "http://localhost:8000/api/certificate/1/activate/"
}

Customers

/api/customers/

Allowed: GET, HEAD, OPTIONS

List all certificates

Example

$ curl http://localhost:8000/api/customers/

[
    {
        "id": 1,
        "name": "Jane Smith",
        "email": "jane.smith@cloudflare.com",
        "password": "pbkdf2_sha256$150000$Aucc0qAMptVW$bFp3p9kb7sNN5fnNbPdkFG+I4nnzWyGO1lWkrxrHnyA="
    }
]

/api/customer/<int:pk>

Allowed: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS

Perform CRUD operations on customers.

All attributes are readable. Passwords are stored hashed, and are viewable only as such.

All attributes are writable. Passwords are hashed before storing.

Example

$ curl http://localhost:8000/api/customer/1/

{
    "id": 1,
    "name": "Jane Smith",
    "email": "jane.smith@cloudflare.com",
    "password": "pbkdf2_sha256$150000$Aucc0qAMptVW$bFp3p9kb7sNN5fnNbPdkFG+I4nnzWyGO1lWkrxrHnyA="
}

/api/customer/<int:pk>/certs/

Allowed: GET, HEAD, OPTIONS

List all certificates owned by a customer.

Example

$ curl http://localhost:8000/api/customer/1/certs/

{
    "results": [
        {
            "id": 1,
            "private_key": "<memory at 0x7fcec77efdc8>",
            "active": true,
            "cert_body": "this-is-a-cert-body",
            "customer": 1
        }
    ]
}

/api/customer/<int:pk>/active-certs/

Allowed: GET, HEAD, OPTIONS

List all certificates owned by a customer.

Example

$ curl http://localhost:8000/api/customer/1/active-certs/

{
    "results": [
        {
            "id": 1,
            "private_key": "<memory at 0x7fcec77efdc8>",
            "active": true,
            "cert_body": "this-is-a-cert-body",
            "customer": 1
        }
    ]
}

Certificates

/api/certificates/

Allowed: GET, HEAD, OPTIONS

List all certificates

Example

$ curl http://localhost:8000/api/certificates/

[
    {
        "id": 1,
        "private_key": "<memory at 0x7fcec77efe88>",
        "active": true,
        "cert_body": "this-is-a-cert-body",
        "customer": 1
    }
]

/api/certificate/<int:pk>

Allowed: GET, POST, HEAD, OPTIONS

Perform CRD operations on certificates.

All attributes are readable. Private keys are binary blobs and are rendered to strings.

No attributes are writable. To update a certificate's active state, see /api/certificate/<int:pk>/activate.

Example

$ curl http://localhost:8000/api/certificate/1/

{
    "id": 1,
    "private_key": "<memory at 0x7fcec77efe88>",
    "active": true,
    "cert_body": "this-is-a-cert-body",
    "customer": 1
}

/api/certificate/<int:pk>/activate/

Allowed: PUT, PATCH, OPTIONS

Activate or deactivate a certificate.

Example

$ curl http://localhost:8000/api/certificate/1/activate

{
    "id": 1,
    "private_key": "<memory at 0x7fcec77efe88>",
    "active": true,
    "cert_body": "this-is-a-cert-body",
    "customer": 1
}

{
    "active": true
}