Automate certificate monitoring with free API – KeyChest

print
Our certificate monitoring KeyChest has an initial RESTful API for remote enrolment of new certificates and for checking certificate expiry. Its design supports automation without any initial security/authorization setup.

The API functions use authorization keys, but we use them to manage access control. It means clients can generate their own, or receive a new API key on the fly from the KeyChest server.

KeyChest – design prototypes of the new version coming in June.

It means you don’t need to do any personalization for new clients and integrations can be built into the images, dockers you use to spawn new virtual machines or into simple wrappers for Let’s Encrypt clients.

What does this integration give you? There are several advantages:

  1. We link all API keys and your clients via an email address they provide; which means you can see expirations, configuration problems, and so on in one view in the KeyChest web interface.
  2. You can start using a new email address without registering an account – we treat such email addresses as unverified, which means we only start monitoring your servers, if we detect a relevant certificate shortly after it’s been enrolled via our API.
  3. You get monitoring data from “user’s point of view”, i.e., whether their browsers will verify your servers as secure. This provides a real end-to-end validation of your server, ISP, and network configuration.

The API Logic

There are three types of calls, and three steps, you need to implement for full integration:

  • Step 1: Claim API key – one-off call, where your client requests its own unique API key (we need to make sure this API key is unique). There are two versions – POST and GET. The difference is whether the client generates its own API key (POST) or KeyChest creates one and sends it back.
  • Step 2: Add server – submit a domain name for monitoring.
  • Step 3: Check expiration – check whether a certificate needs to be renewed. This is an optional call, which provides your code with data for e.g., triggering certbot renewal.

We recommend the client keeps two pieces of information as its state. The first item is its API key. The second is a timestamp of its last execution, which can be compared against “last scan” timestamps returned by the “Check expiration” API call.

If you’re interested in more details, please have a look further down, or at our online documentation: https://api.enigmabridge.com/api

Examples using curl

Step 1: get an API key

curl https://keychest.net/api/v1.0/access/claim/[email protected]

If you are familiar with jq, you can get a new API key with the following command:

curl -s https://keychest.net/api/v1.0/access/claim/[email protected] | jq -r '.api_key'

Step 2: register for monitoring

curl -s -X POST -H "Content-Type: application/json" -d '{"api_key":"5b9b6aceb95011e7bb9f7fca73a26228", "domain":"fish.enigmabridge.com"}' https://keychest.net/api/v1.0/servers/add

Step 3: check expiration

curl -s https://keychest.net/api/v1.0/servers/expiration/fish.enigmabridge.com?api_key=da70d5e4864f57e910e66bd21c685b26

List of basic API functions

 

Register/check API key
GET request – The client requests KeyChest to generate an API key for a user account identified with the email.
Request
https://keychest.net/api/v1.0/access/claim/[email protected]
Response

{
    "status": "created",
    "user": "[email protected]",
    "api_key": "5b9b6aceb95011e7bb9f7fca73a26228"
}
Notes
email – a mandatory parameter, it will be used to access an existing account, or to create a new account.A successful response returns the “status” value of “created”.

 

Register/check API key
POST request – the client has to create its api_key and send it to the KeyChest with an email identifying a user account.
Request
https://keychest.net/api/v1.0/access/claim
The content-type header must be: application/json, and the body contains JSON data.

{
    "email":"[email protected]",
    "api_key":"5b9b6aceb95011e7bb9f7fca73a26228"
}
Response

{
    "status": "created",
    "user": "[email protected]",
    "api_key": "5b9b6aceb95011e7bb9f7fca73a26228"
}

or

{
    "status":"success"
}
Notes
api_key – a mandatory parameter, the value must be at least 16 characters and no more than 64 characters, allowed characters are lower and upper case letters, digits, and “-“. (i.e., [a-zA-Z0-9-]* )
email – a mandatory parameter, it will be used to access an existing account, or to create a new account.A successful response returns the “status” value of “created”, or “success” – depending on whether a new API key was created (former), or it was already in the KeyChest database.

 

Register domain name
POST request – This API call adds a new domain name for monitoring. It can be used repeatedly for the same domain name.
Request
https://keychest.net/api/v1.0/servers/add
The content-type header must be: application/json, and the body contains JSON data.

{
    "api_key":"5b9b6aceb95011e7bb9f7fca73a26228",
    "domain":"fish.enigmabridge.com"
}
Response

{
    "status": "success",
    "id": "671d1b10-bb1d-11e7-bae1-571d93cf1c53",
    "key": "da70d5e4864f57e910e66bd21c685b26",
    "domain": "fish.enigmabridge.com
}
Notes
api_key – a valid API key registered with the KeyChest.domain – a domain name for monitoring; it can include a port number in the usual syntax (e.g., fish.enigmabridge.com:25).Responses contain an id, which can be used for asynchronous processing, key which is an internal representation of the domain name, and the status.
Check expiration
GET request – this is a request to return the latest status information for a given domain name. Responses contain the timestamp of the lastest status update to allow clients check freshness.
Request
https://keychest.net/api/v1.0/servers/expiration/fish.enigmabridge.com?api_key=da70d5e4864f57e910e66bd21c685b26
Response

{
    "domain": "fish.enigmabridge.com",
    "certificate_found":true,
    "renewal_due":true,
    "expired_found":false,
    "results": [
        {
            "ip": "2001:41c9:1:41d::131",
            "certificate_found": false,
            "certificate_sha256": null,
            "renewal_due": null,
            "expired": null,
            "renewal_utc": null,
            "last_scan_utc": 1509094412
        },
        {
            "ip": "46.43.0.131",
            "certificate_found": true,
            "certificate_sha256": "1aa7cda60ba61810321bedc4793fadc80f7ca6a3e328d484b0d5eb8a9ef230de",
            "renewal_due": true,
            "expired": false,
            "renewal_utc": 1510216500,
            "last_scan_utc": 1509099907
        }
    ],
    "status": "success"
}
Notes
api_key – a valid API key registered with the KeyChest.domain – is included as a part of the end point’s URL.

The response contains an array of IP addresses detected for a given domain name. Each entry in the array contains information for one IP address, with particular items of: certificate_found, renewal_due, expired, and the time of the last update last_scan_utc.

The top-level data items certificate_found, renewal_due, expired summarize the detailed results for simplistic processing.

The values of renewal_due, expired are true if at least one entry in the array has this value.

 

If you have difficulties or encounter unexpected errors, please let us know at [email protected].