simpleca

README

SimpleCA

Overview

Server

Configuration

Usage

  -cert string
        path to web server certificate
  -certkey string
        path to key for web certificate
  -dir string
        path to directory for the CA files (default "ca")
  -domain string
        DNS domain for CA certificates (default "test")
  -listen string
        listen address for server (default ":80")

cert

The path to the certificate to use for HTTPS connections to the API.

certkey

The corresponding private key to the 'cert' option when serving the API with HTTPS.

dir

The path to the base directory for the file backed certificate authority.

domain

The DNS domain for the certificate authority. The CA's root certificate limits itself to only being valid for this domain when it is created on first instantiation.

listen

This is the address ([hostname]:[port]) on which the server should listen. The server application does not handle permissions on its own so the caller is responsible for ensuring it is called with sufficient privileges/capabilities if binding to a privileged port (i.e. 80 or 443). Additionally, the default port remains 80 even when invoked with TLS certificates.

API

/authorize (POST)

Authorize a new certificate: Uses the admin credentials to create a token for adding a new client/endpoint. If successful, the server will return a 200 OK status along with a body containing the single use token for registering a new certificate. On error, the server will return the most appropriate status code along with a short error summary in the body.

{
    "names": ["name1.test", "name2.test", "name3.test"],
    "signature": "[base64 encoded signature]"
}

/register (POST)

Register a new certificate: Consumes an authorization token (generated by_/authorize_) to add a new endpoint for certificate management. If successful, the server will return a 200 OK status along with the body containing the new certificate in DER encoding. On error, the server will return the most appropriate status code along with a short error summary in the body.

{
    "authkey": "[base64 encoded token from server]",
    "publickey": "[base64 encoding of DER public key for new certificate]",
    "signature": "[base64 encoded signature]"
}

/register/[token].p12 (GET)

Register a new certificate: Consumes an authorization token (generated by /authorize) to add a new endpoint for certificate management. If successful, the server will return a 200 OK status along with a PKCS12 file of the new certificate and associated private key encrypted using the token as the password. On error, the server will return the most appropriate status code along with a short error summary in the body.

/serial/[serial].crt (GET)

Lookup a certificate: Looks up a certificate by the hexadecimal representation of its serial number. If successful, the server will return a 200 OK status along with the body containing the certificate in DER encoding. On error, the server will return the most appropriate status code along with a short error summary in the body.

/serial/[common name].crt (GET)

Lookup a certificate: Looks up a certificate by its common name. If successful, the server will return a 200 OK status along with the body containing the certificate in DER encoding. On error, the server will return the most appropriate status code along with a short error summary in the body.

/serial/ca.crt (GET)

Root certificate: Retrieves a copy of the root certificate. If successful, the server will return a 200 OK status along with the body containing the certificate in DER encoding. On error, the server will return the most appropriate status code along with a short error summary in the body.

/serial/ca.crl (GET)

Certificate revocation list: Retrieves a copy of the current certificate revocation list (CRL). If successful, the server will return a 200 OK status along with the CRL in DER encoding. On error, the server will return the most appropriate status code along with a short error summary in the body.

/renew (POST)

Renew an certificate: (Not implemented) Uses an existing (and valid) certificate to get a new certificate for the allowed names.

/revoke (POST)

Revoke an certificaet: (Not implemented) Uses the admin credentials to revoke an certificate by serial number.

Client

Configuration