Introduction

Last update: 29 September

This column shows examples of API functions, or details that are language specific. Use the tab names above to switch to the language / syntax you are interested in.

Welcome to Enigma Bridge API documentation and congratulations on taking steps to properly secure your systems from cyberattacks.

Enigma Bridge provides managed hardware encryption for a variety of applications. Our service is built on top of our game-changing encryption system fir secure hardware processors. This design ensures that your secrets can’t be extracted using any logical nor physical attacks. This protection of your data is provided by processors validated according to the FIPS 140-2 standard on Level 3. The Level 3 means that the hardware device will erase secrets it stores when it detects an attack.

Side-channel, and logical attacks are also significantly limited. Assurance of this protection is provided by Common Criteria certifications on EAL5 (EAL5 explained on Wikipedia).

You can use our API to access Enigma Bridge encryption service directly or transparently via production integrations. The set of operations available via the API includes:

encryption - just encrypt, MAC, sign, ...;
re-encryption - atomic re-encryption from transport (data in transit) to storage (data at rest) keys;
key management - generate, unwrap, manage keys;
payment systems - re-encryption between transport and database keys, tokenization;
cloud migration - use any subset of supported operations or one of our services built on top of the Enigma Bridge platform;
user authentication - create user context, verify passwords and one-time passwords, reset passwords; or
random data generation - using FIPS140-2 certified generators.

The native API is REST web-service. We also provide language bindings for simple integration. We currently support Javascript (client and node.js), Python and Java. This site provides a description of API functions, including code examples in the dark area to the right. Tabs in the top right allow switching between the programming language of the examples.

Basics

Use of Enigma Bridge consists of four phases, irrespective of operations you want to use:

user enrolment - creating user account;
API key creation - obtaining API key with authorizations and also network connection details to a suitable Enigma Bridge instance;
operation enrolment - introduction of a new use request into Enigma Bridge; and
data processing - operational use.

Depending on the use case and limits on usage, all steps can be completed fully automatically within seconds. If a particular use case requires more strict control, step 1 will require manual approval.

Each of the steps can be represented by a single API command, regardless of the operation you request. The result of the enrolment is a configuration string that uniquely identifies a new user object.

Getting Started

"sudo pip install ebclient.py"

"npm install -g ebclient.js"
or
"git clone https://github.com/EnigmaBridge/client.js"

# nothing required

"git clone https://github.com/EnigmaBridge/client.java"

"nothing required"

We provide several language bindings.

We have also implemented a PKCS#11 wrapper that uses Enigma Bridge for hardware security:

SoftHSM - SoftHSMv1 at GitHub

Our goal is to make any library installation as simple as possible, and using standard deployment mechanisms wherever possible.

Register as Enigma Client

The first step in using the EB service is to create a client account. The client account forms the basis for your authorization towards Enigma Bridge. Once you obtain an account, you will learn your authentication details you can use to obtain API keys.

Unless you intend to use an automation tool that takes care of the enrolment process. Please raise a support ticket at:

Enigma Bridge Support System

We always require manual approval (via our support system) when you request access to higher transactions rates, or when a formal audit requirements are in place (e.g., payment applications subject to PCI audits).

Automation

This section can only be used in certain cases, when it is possible to automate enrolment to the Enigma Bridge service.

// coming soon

"coming soon"

curl -i \
  -H "Content-Type: application/json" \
  -H "X-Auth-Token: public" \
  -X POST
  -d '{
         "nonce":"arbitrary string that will be included in the response",
         "version":1,
         "function":"create",
         "environment":"dev",
         "client":{
             "name":"name of the client - it should be unique",
             "authentication":"type",
             "type":"pre-defined type of clients",
             "token":"initial type authentication token"
         }
    }'\
  https://hut3.enigmabridge.com:8445/api/v1/client

// JS coming soon

from ebclient.eb_configuration import *
from ebclient.eb_registration import *
from ebclient.registration import *

cfg = Configuration()
cfg.endpoint_register = Endpoint.url('https://hut3.enigmabridge.com:8445')

client_data_reg = {
    'name': 'name of the client - it should be unique',
    'authentication': 'type',
    'type': 'pre-defined type of clients',
    'token': 'initial type authentication token'
    'email': self.email
}

regreq = RegistrationRequest(client_data=client_data_reg, \
                             env=ENVIRONMENT_DEVELOPMENT, config=cfg)
regresponse = regreq.call()

# results
username = regresponse['username']
password = regresponse['password']

print(regresponse)

We have created three end-points for client registration. We named them in memory of wartime sections of the Government Code and Cypher School (GC&CS) at Bletchley Park

hut3.enigmabridge.com - Hut 3 translated, interpretated and distributed German Army (Heer) and Air Force (Luftwaffe) messages deciphered by Hut 6.
hut6.enigmabridge.com - Hut 6's task was to break German Army and Air Force Enigma machine cyphers.
hut8.enigmabridge.com - Hut 8 was solving German naval (Kriegsmarine) Enigma messages. The section was led initially by Alan Turing.

Automated registration requires knowledge of your use-case. In certain cases, we pre-define types of clients for automated deployments. For example, AMI available from Amazon AWS Marketplace will be assigned such a client type.

Get API Key

Once you have a client ID and authentication data, you are ready to create your first API key (one client ID will typically have several API keys to separate software clients). All operational requests need a valid API key, even though it is usually hidden in client-side libraries.

The automation code is only available if Enigma Bridge provides automation for particular use case or application. All operational requests need a valid ClientID, even though it is usually hidden in client-side libraries.

Automation

curl -i \
  -H "Content-Type: application/json" \
  -H "X-Auth-Token: public" \
  -X POST
  -d '{
         "nonce":"arbitrary string that will be included in the response",
         "version":1,
         "function":"addapi",
         "authentication":("name" | "type" | "password" | "hotp" | "totp" | "ocra" | "challenge" | "signature"),
         "client":{
             "username":"as provided by function create",
             "authentication":"type",
             "password":"as provided",
         },
         "endpoint":{
             "ipv4":"IPv4",
             "ipv6":"IPv6",
             "email":"contact@mail",
             "country":"2 letter code, e.g. gb, us",
             "network":"network or IP space",
             "location":[0.34,10],
             "datacenter":"name",
             "hostid":"hostid",
             "productcode":"product code",
             "instancetype":"instance type"
         },
         "operations":["name","name2","nameX"]
    }'\
  https://hut3.enigmabridge.com:8445/api/v1/client

"comming soon"

from ebclient.eb_configuration import *
from ebclient.eb_registration import *
from ebclient.registration import *

cfg = Configuration()
cfg.endpoint_register = Endpoint.url('https://hut3.enigmabridge.com:8445')

client_api_req = {
    'authentication': 'password',
    'username': username,
    'password': password
}

endpoint = {
    "ipv4": "123.23.23.23",
    "ipv6": "fe80::2e0:4cff:fe68:bcc2/64",
    "country": "gb",
    "network": "plusnet",
    "location": [0.34,10]
}

apireq = ApiKeyRequest(client_data=client_api_req, endpoint=endpoint, \
                       env=ENVIRONMENT_DEVELOPMENT, config=cfg)
apiresponse = apireq.call()

# Results
apikey = apiresponse['apikey']
servers = apiresponse['servers']

Make sure to replace default values with proper ones.

Automation is enabled with the RESTful API of our user management server. It means that requests are still being sent to one of the huts.

A successful response to a request for an API key will also return network connection details for operational requests. The user management server will automatically select the most suitable location of Enigma Bridge servers to provide required functionality and also to optimize network performance.

Query Parameters

Parameter	Type	Optional	Description
ipv4	string	true	IPv4 address provided by the client software
ipv6	string	true	IPv6 address provided by the client software
email	string	true	contact email address
country	string	true	2 character ISO country code
network	string	true	string - name or IP space
location	array	true	geographic location as an array of two float numbers
datacenter	string	true	name / identification of the datacenter
hostid	string	true	host ID - e.g. AMI name (Amazon), server fqdn
productcode	string	true	identification of the client host if a VM
instancetype	string	true	another identification

Enigma Bridge servers require API keys to allow access to the API. You can register a new API key either programmaticaly or via our support portal at support portal.

You must replace default key with your personal API key.

Use

ProcessData

" POST request:"
"    https://hut:11180/1.0/TEST_API0000001dcb0000300006/ProcessData/f2044d875bdef29d"
"    parameters are an Enigma Bridge handle, command (ProcessData), and a nonce"
"    Data has to be encrypted, see the text to the left for details."
" POST data:"
{
  "data": "0000BCFAADB2FC41A300961AE8741463B676954515B07456681E1E180A9B5FCE7BC93F5A49328DD79CCD96F995F345E3E60674DCA06FE4B1B39E164E08E713C0DB58CBF3EDBF73BADB78BA116418704E52EEB75F575F032BD082AF2585A5F5D3119AF8ACB5C2BAB9C982A7068BD7CB6EA4B9EE84126E1B0E5FE58D6567F1595CCDB6D1B43338DF87E582C50C6A0A0479E40DD63A4E36BD7A1066E8E4293076BF513DD2AE450307A571B5D11D965910074511CCE9FEDBFDF646EFF69B42BAF6A0A8A995A46EEC223D3E595AF40BA4DB1CC0E3D29E06E05DC835A7EF4166BFC4D281F249607D6B913A46B5F69C44BFCA35D5F53AEB6A048E38C064B837C99E571A5A928B2C8C83BB467FDB76BC76F3BECB944F24EEF9B376D6A7D9977AAF59770287F2",
  "function": "ProcessData",
  "version": "1.0",
  "nonce": "06AEAEADE624C651",
  "objectid": "TEST_API0000001dcb0000300006"
}


"RESPONSE"
" Typical `ProcessData` response is a JSON object like the following one."
" The communication encryption is in place - decryption has to be performed" 
"  in order to get the response clear text. Status 0x9000 stands for OK - result completed successfully."
{
  "function": "ProcessData",
  "result": "0000d81cadea2e6499fdd1095988be916e0a3b3d706fd3a5b42b2ad6cdb751ac6a831fa030fc1f2885248388355ee5977cad",
  "nonce": "89c14e8802c42151",
  "status": "9000",
  "statusdetail": "success (ok)",
  "version":"1.0"
}

from ebclient.process_data import ProcessData
from ebclient.uo import Configuration, Endpoint, SimpleRetry, UO
from ebclient.crypto_util import *

cfg = Configuration()
cfg.endpoint_process = Endpoint.url('https://site2.enigmabridge.com:11180')
cfg.api_key = 'API_TEST'

uo_aes = UO(uo_id=0xee01,
            uo_type=0x4,
            enc_key=from_hex('e134567890123456789012345678901234567890123456789012345678901234'),
            mac_key=from_hex('e224262820223456789012345678901234567890123456789012345678901234'),
            configuration=cfg)

pd = ProcessData(uo=self.uo_aes, config=cfg)
result = pd.call(from_hex('6bc1bee22e409f96e93d7e117393172a'))
print(from_hex('95c6bb9b6a1c3835f98cc56087a03e82') == result)

# Process data uses a communication encryption preprocessing.
# For more details please refer to the Communication encryption documentation. 
# Pure shell client is not yet planned.

"use strict";
var eb = require("ebclient.js");
var sjcl = eb.misc.sjcl;

// Define basic EB configuration - shared among many requests
var config = new eb.client.Configuration({
    endpointProcess: 'https://site2.enigmabridge.com:11180',
    endpointEnroll: 'https://site2.enigmabridge.com:11182',
    apiKey: 'TEST_API',

    timeout: 30000,
    retry: {
        maxAttempts: 2
    }
});

// Define UserObject to operate with, for particular operation.
var settings = {
    config: config,
    uoId: 'EE01',
    uoType: '4',
    aesKey: 'e134567890123456789012345678901234567890123456789012345678901234',
    macKey: 'e224262820223456789012345678901234567890123456789012345678901234'
};

// Input can be either hex-coded string or SJCL bitArray (array of 32bit words / integers).
var input = '6bc1bee22e409f96e93d7e117393172a';
var cl = new eb.client.processData(settings);
var promise = cl.call(input);

promise.then(function(data){
    console.log(eb.misc.inputToHex(data.data) == '95c6bb9b6a1c3835f98cc56087a03e82');
}).catch(function(error){
    console.log(error);
});

// Coming soon

ProcessData is the operational call of the Enigma Bridge service. It performs an operation that is identified by a handle, e.g., TEST_API000000ee010000000004. The only other parameter it takes is data for processing.

As the data should be typically protected between the client application and EB servers, it has to be encrypted with communication keys. The actual protocol is again defined by its handle, which is a text string.

For more details of the communication encryption, please refer to the Communication encryption documentation - Link coming soon, or use one of the client implementations at Enigma Bridge GitHub.

" Typical ProcessData response is a JSON object like the following one." " The communication encryption is in place - decryption has to be performed" " in order to get the response clear text. Status 0x9000 stands for OK - result completed successfully."

ProcessData call can be tested also online in ProcessData-demo.

See links to implementations in Javascript, Python, and Java above.

Create User Object

The first step before working with EnigmaBridge is creation of User Object.
User object can hold e.g., RSA-2048 private key or AES encryption/decryption key.
Each UserObject has one operation associated with it. For RSA-2048 key it is typically a decryption.
Symmetric encryption key - e.g. AES encryption key has also one operation thus you need two user objects, with the same AES key inside, to perform both encryption and decryption.
You can either import a key into the User Object if you have it (e.g., AES key known to you, RSA key) or you can let EnigmaBridge generate a new key in the secure hardware so you benefit from the secure RNG and the fact you don't really know the secret value thus nobody can steal it from you - it never leaves the secure hardware.

from ebclient.process_data import ProcessData
from ebclient.create_uo import TemplateFields, KeyTypes, Environment, Gen
from ebclient.eb_create_uo import *
from ebclient.uo import Configuration, Endpoint, SimpleRetry, UO
from ebclient.crypto_util import *
from ebclient.eb_consts import UOTypes

cfg = Configuration()
cfg.endpoint_process = Endpoint.url('https://site2.enigmabridge.com:11180')
cfg.endpoint_enroll = Endpoint.url('https://site2.enigmabridge.com:11182')
cfg.api_key = 'API_TEST'

# Prepare key template - settings
tpl = {
    TemplateFields.environment: Environment.DEV
}

# AES key - provided by the client
# It is also possible to let EB generate the key.
keys = {
    KeyTypes.APP_KEY: from_hex('0123456789123456789012345678901234567890123456789012345678901234')
}


# Create AES-128 key for decryption - UOTypes.PLAINAESDECRYPT
cuo = CreateUO(configuration=self.cfg, tpl=tpl, \
              obj_type=UOTypes.PLAINAESDECRYPT, \
              keys=keys)
uo = cuo.create_uo()

# Process data - prepare object to use the new AES key
pd = ProcessData(uo=uo, config=cfg)

# Call the operation
result = pd.call(from_hex('95c6bb9b6a1c3835f98cc56087a03e82'))

"use strict";
var eb = require("ebclient.js");
var sjcl = eb.misc.sjcl;

// Define basic EB configuration - shared among many requests
var config = new eb.client.Configuration({
    endpointProcess: 'https://site2.enigmabridge.com:11180',
    endpointEnroll: 'https://site2.enigmabridge.com:11182',
    apiKey: 'TEST_API',

    timeout: 30000,
    retry: {
        maxAttempts: 2
    }
});

// Create randomly generated AES-128 key, with DECRYPT operation associated
// with it, in development environment.
var cfg = {
    config: config,
    tpl: {
        "environment": eb.comm.createUO.consts.environment.DEV
    },
    keys: {
        app: {
            key: sjcl.random.randomWords(4)
        }
    },
    objType: eb.comm.createUO.consts.uoType.PLAINAESDECRYPT
};

var cl = new eb.client.createUO(cfg);
var promise = cl.call();

promise.then(function(data){
    // Call ProcessData on the input data - here we verify
    // it works as we expect.
    var aes = new sjcl.cipher.aes(cfg.keys.app.key);
    var input2 = '6bc1bee22e409f96e93d7e117393172a';

    // Pass data to the process data function - contains UserObject
    // which ProcessData parses and uses.
    var cfg2 = eb.misc.extend(true, {}, data);
    var cl2 = new eb.client.processData(cfg2);
    var promise2 = cl2.call(input2);

    promise2.then(function(data){
        var desiredOutput = aes.decrypt(eb.misc.inputToBits(input2));
        console.log(eb.misc.inputToHex(data.data));
        console.log(eb.misc.inputToHex(desiredOutput));
    }).catch(function(error){
        console.log(error);
    });

}).catch(function(error){
    console.log(error);
});

// Coming soon

" Not supported with RAW JSON. Please, take a look at clients"

# Not supported in shell. Please, take a look at clients

Create User Object - RSA

RSA user object is a bit more specific as it returns the public part.

from ebclient.process_data import ProcessData
from ebclient.create_uo import TemplateFields, KeyTypes, Environment, Gen
from ebclient.eb_create_uo import *
from ebclient.uo import Configuration, Endpoint, SimpleRetry, UO
from ebclient.crypto_util import *

cfg = Configuration()
cfg.endpoint_process = Endpoint.url('https://site2.enigmabridge.com:11180')
cfg.endpoint_enroll = Endpoint.url('https://site2.enigmabridge.com:11182')
cfg.api_key = 'API_TEST'

# Prepare key template - settings
tpl = {
    TemplateFields.environment: Environment.DEV
}

cuo = CreateUO(configuration=self.cfg, tpl=tpl)

# Create RSA-2048 private key
# Communication keys are not specified here -> will be generated now, returned in the response.
rsa_key = cuo.create_rsa(2048)

# Process data - prepare object to use the new RSA-2048 key for decryption
pd = ProcessData(uo=rsa_key.uo, config=cfg)

# Prepare data - 000..1. RAW operation is performed - padding has to be done
# localy on the client side. You can use PKCS1.5 padding implemented in the package.
input = ("\x00"*255) + "\x01"
result = pd.call(input)

"use strict";
var eb = require("ebclient.js");
var sjcl = eb.misc.sjcl;

// Define basic EB configuration - shared among many requests
var config = new eb.client.Configuration({
    endpointProcess: 'https://site2.enigmabridge.com:11180',
    endpointEnroll: 'https://site2.enigmabridge.com:11182',
    apiKey: 'TEST_API',

    timeout: 30000,
    retry: {
        maxAttempts: 2
    }
});

// Specification: Create a new RSA-1024 key in the hardware, devel environment.
var cfg = {
    config: config,
    tpl: {
        "environment": eb.comm.createUO.consts.environment.DEV
    },
    bits: 1024
};

var cl = new eb.client.createUO(cfg);
var promise = cl.createRSA();

promise.then(function(data){
    // ProcessData demo: RSA decryption of the 00000..1
    // For RSA it holds: 1 ^ e mod N = 1
    var input2 = '0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001';
    var cfg2 = eb.misc.extend(true, {}, data);
    var cl2 = new eb.client.processData(cfg2);

    // rsaPrivateKey object contains also the public part of
    // the key: modulus and public exponent
    console.log(data.rsaPrivateKey);

    var promise2 = cl2.call(input2);
    promise2.then(function(data){
        console.log(eb.misc.inputToHex(data.data));
    }).catch(function(error){
        console.log(error);
    });

}).catch(function(error){
    console.log(error);
});

// Coming soon

" Not supported with RAW JSON. Please, take a look at clients"

# Not supported in shell. Please, take a look at clients

Errors

Clients using Enigma Bridge API may encounter the following error codes:

Error Code	Meaning
4101 (0x1005)	object capacity reached
4102 (0x1006)	timeout
4111 (0x100F)	service shutting down
4213 (0x1075)	object processing limit reached
4262 (0x10A6)	processing queues full
4304 (0x10D0)	no authorization tokens left
8364 (0x20AC)	integrity error / attack detected
8380 (0x20BC)	request not authorized
16504 (0x4078)	object already exists
16512 (0x4080)	public key not available
32769 (0x8001)	unknown operation
32772 (0x8004)	operation not available
32818 (0x8032)	input data length incorrect
32819 (0x8033)	invalid key provided
32820 (0x8034)	invalid handle/APIkey
32822 (0x8036)	missing or invalid argument
32823 (0x8037)	request JSON parsing failed
32824 (0x8038)	request JSON version not supported
32825 (0x8039)	request JSON data invalid
32826 (0x803A)	request JSON missing nonce
32827 (0x803B)	invalid object
32828 (0x803C)	unsupported operation
32829 (0x803D)	incorrect data padding
32830 (0x803E)	object format error
32833 (0x8041)	object format error
32835 (0x8043)	object format error
32839 (0x8047)	data is incorrect
32840 (0x8048)	object format error
32841 (0x8049)	MAC length incorrect
32842 (0x804A)	object format error
32844 (0x804C)	object format error
32846 (0x804E)	encrypt data padding error
32847 (0x804F)	encrypt data padding error
32851 (0x8053)	incorrect key length
32852 (0x8054)	data too long
32853 (0x8055)	malformed data
32856 (0x8058)	authorization cards required
32866 (0x8062)	invalid user context
32871 (0x8067)	object classification is incorrect
32872 (0x8068)	invalid API key
32873 (0x8069)	unrecognized client
32899 (0x8083)	invalid operation type
32909 (0x808D)	key component length incorrect
32910 (0x808E)	key component index incorrect
32911 (0x808F)	key component already set
32912 (0x8090)	key component not set
32918 (0x8096)	length of application key is incorrect
32919 (0x8097)	length of communication key is incorrect
32921 (0x8099)	incorrect usage flags or keys not generated
32943 (0x80AF)	data encryption error
32948 (0x80B4)	OTP code length request incorrect
32953 (0x80B9)	authentication method not allowed
36864 (0x9000)	Success
41046 (0xA056)	incorrect length of OTP key
41059 (0xA063)	too many password tries
41060 (0xA064)	incorrect password length
41061 (0xA065)	incorrect password
41062 (0xA066)	too many HOTP tries
41121 (0xA0A1)	wrong MAC on data
41136 (0xA0B0)	incorrect HOTP code
41137 (0xA0B1)	too many account tries
41138 (0xA0B2)	keys stored in the user object are incorrect
41139 (0xA0B3)	OTP counter overflow
41142 (0xA0B6)	incorrect user ID / malicious request
41146 (0xA0BA)	unknown authentication method
41170(0xA0D2)	no authorization credits left
61458(0xF012)	processor failure
61465(0xF019)	server not ready
61488(0xF030)	invalid authorization token
61489(0xF031)	input data too long
61493(0xF035)	invalid object

--- --- Extended APIs --- ---

This part is not needed by clients as it is implemented by Enigma Bridge and their automation tools. A safe fallback is to use our support system to request enrolment to our encryption service.

Enrolment Overview

User Manager domain names to replace hut in the text below are:

hut3.enigmabridge.com
hut6.enigmabridge.com
hut8.enigmabridge.com

Data Flow

The usual data-flow and sequence of actions is as follows:

New client (computer, server, software package) will get an Enigma Bridge client type - this can be done automatically, e.g., for virtual machines configured by Enigma Bridge, or when you use a provided enrolment tool (script, application).
This step requests creation of an Enigma Bridge client - i.e., a legal entity that will own API keys and will be authorized to use the Enigma Bridge service.
1. The client process will use its EB type to request a new client account: this always involves a register client API call; optionally also Get Client Auth Type and Get Client Auth.
2. The customer will request a new client account via our support system at: https://enigmabridge.freshdesk.com.
Once the client ID and authentication details are available, the client process can request a new API key.
The API key allows create of new user objects according to the client type definition.

Client Endpoint - RESTful API

Get Client Authentication

see the RESTful column

see the RESTful column

see the RESTful column

see the RESTful column

{
    "nonce":"nonce",
    "version":1,
    "function":"getauth",
    "environment":"dev",
    "client":{
        "type":"test"
    }
}

This is a simple API call that returns the type of authentication required for a particular client type.

The request uses the following URL:

https://hut:8445/api/v1/client

Parameters

name	optional	type	note
nonce	NO	string	random string that will be returned back
version	NO	integer	must be 1
function	NO	string	must be "create"
environment	NO	string	must be "dev", "test", or "prod"
client	NO	sequence	must contain "type" of the new client that will be registered

see the RESTful column

see the RESTful column

see the RESTful column

see the RESTful column

{
  "version": 1,
  "error": "success (ok)",
  "status": 36864,
  "nonce": "my nonce",
  "timestamp": 1475077216548,
  "response": {
    "type": "test",
    "authentication": [
      {
        "method": "authentication type1",
        "init": false,
        "initdata": []
      }, 
      {
        "method": "authentication type2",
        "init": true,
        "initdata": [ "data required in initialization" ]
      }
    ]
  }
}

Response

Response shows allowed authentication methods and lists data items required for each of the authentication methods for the "Init Client Authentication" method.

name	optional	type	description
method	NO	string	one of the values from the table below
init	NO	boolean	true if Init Client Authentication is required
initdata	NO	array of strings	values can be from the set of "email", "mobile", and "rsa"

The response will return an array of possible authentication types. It has to contain at least one element. Possible values are listed in the following table. Please note, that the requestor always has to know its type.

name	description
type	client has to know its type and a token, which is fixed for all new requestors of the given type
name	authentication is done via a correct name; the requestor has to know the client type it wants to be
token	the `type`, `name`, and a `token` are required; the `token` is unique to a particular requestor and it remains constant during repeated registrations
password	authentication requires a correct `type`, `name`, and `password`
challenge	authentication requires a correct one-time challenge, which is provided to the requestor via a separate channel
hotp	using an HOTP value, according to IETF RFC 4226
totp	using an TOTP value, according to IETF RFC 6238
ocra	using an OCRA value, according to IETF RFC 6287
signature	authentication with a digital signature

Init Client Authentication

see the RESTful column

see the RESTful column

see the RESTful column

see the RESTful column

{
    "nonce":"nonce",
    "version":1,
    "function":"initauth",
    "environment":"dev",
    "client":{
        "type": "test",
        "method": "name of authentication method",
        "email": "email@address",
        "mobile": "mobile phone number with country code",
        "rsa": "RSA public key"
    }
}

If registration of a new client requires the server to provide or initialize an authentication process, this API call will provide the server with all the necessary information.

name	optional	type	note
type	NO	string	a client type
method	NO	string	one of the names returned by "Get Client Authentication"
email	YES	string - email	email address for authentication
mobile	YES	string - number	mobile number with country code, only digits and whitespaces
rsa	YES	string	base64 public key

Response

see the RESTful column

see the RESTful column

see the RESTful column

see the RESTful column

{
  "version": 1,
  "error": "success (ok)",
  "status": 36864,
  "nonce": "my nonce",
  "timestamp": 1475077234509,
  "response": {
    "authdata": {"if appropriate, otherwise an empty sequence"},
    "clientid": "fqwbev0cid5hxmgt90nk1it0osr98ama0ey1bc10"
  }
}

Response can be two-fold:

input for creating authentication data, if any;
requesting the server to use an alternative communication channel to provide the requestor with data out-of-band

Register Client

see the RESTful column

see the RESTful column

see the RESTful column

see the RESTful column

{
    "nonce":"nonce",
    "version":1,
    "function":"create",
    "environment":"dev",
    "client":{
        "name":"my test name",
        "clientid":"fqwbev0cid5hxmgt90nk1it0osr98ama0ey1bc10 - from initauth API call",
        "authentication":"type",
        "type":"test",
        "token":"token-assigned-to-client-type"
    }
}

The request uses the following URL:

https://hut:8445/api/v1/client

Parameters

name	optional	type	note
nonce	NO	string	random string that will be returned back
version	NO	integer	must be 1
function	NO	string	must be "create"
environment	NO	string	must be "dev", "test", or "prod"
client	NO	sequence	contains information about the new client

Structure of 'client'

name	optional	type	note
name	NO	string	name provided by the user
clientid	YES	string	string provided by Init Client Authentication, if called
authentication	NO	string	must be "type"
type	NO	string	Name of EB client type (pre-defined)
token	YES	string	authentication token for the client type

see the RESTful column

see the RESTful column

see the RESTful column

see the RESTful column

{
  "version": 1,
  "error": "success (ok)",
  "status": 36864,
  "nonce": "my nonce",
  "timestamp": 1475077216548,
  "response": {
    "username": "dc5c2081-2a13-4566-ac8d-592ee955dc48",
    "password": "106..............571e0f53",
    "max_api_keys": 5,
    "authenticationType": "PASSWORD",
    "status": "ENABLED",
    "maxobjects": 5
  }
}

This is a typical response. The new items are:

name	optional	type	note
status	NO	integer	status code - see Error codes
error	NO	string	text explaining the error code
timestamp	NO	long	timestamp of the response
response	NO	sequence	data returned to the request

Structure of 'response'

name	optional	type	note
username	NO	string	authentication username
password	YES	string	authentication password, depends on authenticationmethod
max_api_keys	NO	integer	max number of API keys the client can create
authenticationtype	NO	string	one of methods
status	NO	string	enabled, disabled, or removed
maxobjects	NO	integer	max number of objects this client can create

Add API to Client

see the RESTful column

see the RESTful column

see the RESTful column

see the RESTful column

{
    "nonce":"d",
    "version":1,
    "function": "addapi",
    "environment":"dev",
    "client":{
        "authentication": "password",
        "username": "dc5c2081-2a13-4566-ac8d-592ee955dc48",
        "password": "1067...................71e0f53"
    },
    "endpoint":{
        "country":"gb"
    }
}

The request uses the following URL:

https://hut:8445/api/v1/client

name	optional	type	note
nonce	NO	string
version	NO	integer	must be 1
function	NO	must be "addapi"
environment	NO	must be "dev", "test", or "prod"
client	NO	sequence
endpoint	NO	sequence	properties of the client server to identify best Enigma Bridge servers

Structure of 'client'

name	optional	type	note
authentication	NO	string	at the moment must be "password"
username	NO	string	as provided during registration
password	NO	string	as provided during registration

Structure of 'endpoint'

name	optional	type	note
country	YES	string	ISO country code
email	YES	string
productcode	YES	string
instancetype	YES	string
network	YES	string
location	YES	pair of float
ipv4	YES	string
ipv6	YES	string
hostid	YES	string

see the RESTful column

see the RESTful column

see the RESTful column

see the RESTful column

{
  "version": 1,
  "error": "success (ok)",
  "status": 36864,
  "nonce": "d",
  "timestamp": 1475078668177,
  "response": {
    "apikey": "0b75.................d057593b",
    "servers": [
      {
        "name": "gb_cambridge_damselfly",
        "domain": "default",
        "environment": "dev",
        "enrolEndpoints": [
          {
            "protocol": "tcp",
            "port": 11112
          },
          {
            "protocol": "https",
            "port": 11182
          }
        ],
        "useEndpoints": [
          {
            "protocol": "tcp",
            "port": 11110
          },
          {
            "protocol": "https",
            "port": 11180
          }
        ],
        "fqdn": "site2.enigmabridge.com"
      }
    ],
    "operations": [
      {
        "status": "enabled",
        "operation": 4,
        "operationname": "basic_aes128_encrypt"
      },
      {
        "status": "enabled",
        "operation": 5,
        "operationname": "basic_rsa1024_decrypt"
      },
      {
        "status": "enabled",
        "operation": 6,
        "operationname": "basic_rsa2048_decrypt"
      }
    ],
    "status": "enabled"
  }
}

A response example is on the right. The new items are:

name	optional	type	note
apikey	NO	string	apikey used to authenticate requests
servers	NO	array	connection details for Enigma Bridge servers
operations	NO	array	list of operations available for the API key

Structure of 'servers' each item

name	optional	type	note
name	NO	string
domain	NO	string	name of Enigma Bridge security domain
environment	NO	string	"dev" or "test" or "prod"
enrolendpoints	NO	array	array of {protocol,port}
useendpoints	NO	array	array of {protocol,port}

View API of Client

see the RESTful column

see the RESTful column

see the RESTful column

see the RESTful column

{
    "nonce":"my nonce",
    "version":1,
    "function": "showapi",
    "environment":"dev",
    "client":{
        "authentication": "password",
        "username": "dc5c2081-2a13-4566-ac8d-592ee955dc48",
        "password": "1067....................1e0f53"
    },
    "apidata":{
        "apikey":"0b75f...............d057593b"
    }
}

The request uses the following URL:

https://hut:8445/api/v1/client

Clients can repeatedly request information about their API keys.

name	optional	type	note
nonce	NO	string
version	NO	integer	must be 1
function	NO	must be "showapi"
environment	NO	must be "dev", "test", or "prod"
client	NO	sequence
apidata	NO	string	sequence of just "apikey" - string

Structure of 'client'

name	optional	type	note
authentication	NO	string	at the moment must be "password"
username	NO	string	as provided during registration
password	NO	string	as provided during registration

Responses have the same format as for "addapi" requests.

APIkey Endpoint - RESTful API

Client IP Address

see the RESTful column

see the RESTful column

see the RESTful column

see the RESTful column

{
    "nonce":"nonce",
    "version":1,
    "function":"clientip"
}

The request uses the following URL:

https://hut:8445/api/v1/apikey

This function is generally available, it doesn't require any authentication of the client.

Response

see the RESTful column

see the RESTful column

see the RESTful column

see the RESTful column

{
  "version": 1,
  "error": "success (ok)",
  "status": 36864,
  "nonce": "my nonce",
  "timestamp": 1475077216548,
  "response": {
      "ipv4":"11.11.11.11",
      "ipv6":"fe80::bae8:56ff:fe2e:ce68"
  }
}

This is a typical response. The new items are:

name	optional	type	note
ipv4	NO	string	it can be NULL
ipv6	NO	string	it can be NULL

List Operations

see the RESTful column

see the RESTful column

see the RESTful column

see the RESTful column

{
    "nonce":"nonce",
    "version":1,
    "function":"listops",
    "environment":"dev",
    "apidata":{
        "username":"dc5c2081-2a13-4566-ac8d-592ee955dc48",
        "apikey":"0b75f...............d057593b"
    }
}

The request uses the following URL:

https://hut:8445/api/v1/apikey

Parameters

name	optional	type	note
username	NO	string	client username as provided during registration
apikey	NO	string	apikey as provided during registration
function	NO	string	must be "listops"
environment	NO	string	must be "dev", "test", or "prod"

see the RESTful column

see the RESTful column

see the RESTful column

see the RESTful column

{
  "version": 1,
  "error": "success (ok)",
  "status": 36864,
  "nonce": "my nonce",
  "timestamp": 1475077216548,
  "response": {
      "operations":{
        "name": {
            #sequence with the operation definition
            #actual content is beyond the scope of
            #this documentation at the moment
        }
      }
  }
}

This is a typical response. The new items are:

name	optional	type	note
status	NO	integer	status code - see Error codes
error	NO	string	text explaining the error code
timestamp	NO	long	timestamp of the response
response	NO	sequence	operations

Structure of 'operations'

name	optional	type	note
name	NO	sequence	definition for new operations

Enrol for DNS Domain

see the RESTful column

see the RESTful column

see the RESTful column

see the RESTful column

{
    "nonce":"my nonce",
    "version":1,
    "function": "enroldomain",
    "environment":"dev",
    "apidata":{
        "username":"dc5c2081-2a13-4566-ac8d-592ee955dc48",
        "apikey":"0b75f...............d057593b",
        "certificate":"base64 encoded X.509 certificate"
    }
}

The request uses the following URL:

https://hut:8445/api/v1/apikey

Structure of 'apidata'

name	optional	type	note
username	NO	string	client username as provided during registration
apikey	NO	string	apikey as provided during registration
certificate	NO	string	base64 encoded certificate - vehicle to provide public key

Response

see the RESTful column

see the RESTful column

see the RESTful column

see the RESTful column

{
    "version": 1,
    "error": "success (ok)",
    "status": 36864,
    "nonce": "my nonce",
    "timestamp": 1475078668177,
    "response": {
        "domain": "pki.enigmabridge.com",
        "controllers": [
            {
                "name": "ns.enigmabridge.com"
            }
        ],
        "status":"enabled"
    }
}

Get Challenge

see the RESTful column

see the RESTful column

see the RESTful column

see the RESTful column

{
    "nonce":"my nonce",
    "version":1,
    "function": "getdomainchallenge",
    "environment":"dev",
    "apidata":{
        "ipv4":"IPv4 provided by the client",
        "ipv6":"IPv6 provided by the client",
        "private": true,
        "username":"dc5c2081-2a13-4566-ac8d-592ee955dc48",
        "apikey":"0b75f...............d057593b"
    }
}

The request uses the following URL:

https://hut:8445/api/v1/apikey

name	optional	type	note
username	NO	string	client username as provided during registration
ipv4	YES	string	ipv4 that will be tested
ipv6	YES	string	ipv6 that will be tested
private	NO	boolean	default value is "false"; if true, the supplied IP addresses are private and will not be used for any verification

If IP addresses are marked as private, we will check whether they are from the expected range. I.e., fc00::/7 for IPv6 and 10.0.0.0/8, 172.16.0.0/12, or 192.168.0.0/16 for IPv4.

see the RESTful column

see the RESTful column

see the RESTful column

see the RESTful column

{
    "version": 1,
    "error": "success (ok)",
    "status": 36864,
    "nonce": "my nonce",
    "timestamp": 1475078668177,
    "response": {
        "challenge": "a random string for authenticated requests",
        "authentication": "signature"
    }
}

The response to these requests provides a challenge that has to be used to authenticate requests like Update Domain.

Update Domain

see the RESTful column

see the RESTful column

see the RESTful column

see the RESTful column

{
    "nonce":"my nonce",
    "version":1,
    "function": "updatedomain",
    "environment":"dev",
    "apidata":{
        "username":"dc5c2081-2a13-4566-ac8d-592ee955dc48",
        "apikey":"0b75f...............d057593b",
        "dnsdata": [{
                        "type":"txt",
                        "domain":"walsall1.pki.enigmabridge.com", 
                        "name":"_acme-challenge", 
                        "value":"random string"},
                    {
                        "type":"cname",
                        "domain":"walsall1.pki.enigmabridge.com",
                        "name":"cloud"}
                   ],
        "authentication":"signature",
        "response":"value derived from previously requested challenge"
    },
    "signature":{
        "payload":"apidata-base64",
        "value":"string-base64-signature"
    }
}

The request uses the following URL:

https://hut:8445/api/v1/apikey

name	optional	type	note
apidata	YES	string	not needed if signature is present
signature	YES	string	only if method is "signature";

Structure of 'apidata'

name	optional	type	note
username	NO	string	as assigned
apikey	NO	string	as assigned
dnsdata	YES	array	an array of new DNS records that will be added to the domain, each record is defined by a name, type, and value
authentication	NO	string	as requested with a challenge
response	NO	string	either the challenge itself or a derived value (e.g., OCRA)

Structure of 'dnsdata'

We currently support "TXT" and "CNAME" DNS records only.

name	optional	type	note
type	NO	string	"TXT"
name	NO	string	name of the new record
value	NO	string	value of the new record,
domain	YES	string	a particular domain to be updated, if not present, all relevant domains will be udpated, if none matches -> error

name	optional	type	note
type	NO	string	"CNAME"
name	NO	string	name of the new subdomain
domain	YES	string	a particular domain to be updated, if not present, all relevant domains will be udpated, if none matches -> error

see the RESTful column

see the RESTful column

see the RESTful column

see the RESTful column

{
    "version": 1,
    "error": "success (ok)",
    "status": 36864,
    "nonce": "my nonce",
    "timestamp": 1475078668177,
    "response": {
        "domains": ["assigned domain name"],
        "addresses": ["registered IP addresses "],
        "privateIP": false,
        "status": "enabled"
    }
}

Structure of 'response'

name	optional	type	note
domains	NO	array of DNS names	a list of domain names registered for the API key
addresses	NO	array of IP addresses	a list of IPv6 and IPv4 IP addresses associated with the API key
privateIP	NO	boolean	returns true if the API key host is inside a private network
status	NO	string	a status of the DNS registration (disabled, enabled, removed, created, unlocked, not_assigned

Install Status

This function allows the API key announce its current status and communicate any additional context information that may be needed for support or communication requiring an independent channel for security.

see the RESTful column

see the RESTful column

see the RESTful column

see the RESTful column

{
    "nonce":"my nonce",
    "version":1,
    "function": "installstatus",
    "environment":"dev",
    "apidata":{
        "username":"dc5c2081-2a13-4566-ac8d-592ee955dc48",
        "apikey":"0b75f...............d057593b"
    },
    "statusdata":{
        "password":"very secret password",
        "status":36864,
        "error":"success (ok)",
        "duration":1800,
        "detail":"logs, details as a JSON message",
        "key":"base64encoded key blob",
        "email":"important@top.world"
    }
}

The request uses the following URL:

https://hut:8445/api/v1/apikey

This function will update status of the APIkey consumer/host. This information can be used for further communication with clients or contact clients.

The structure and particular meaning of items in "statusdata" depends on the client type.

name	optional	type	note
username	NO	string	as assigned
apikey	NO	string	as assigned

Structure of 'statusdata'

name	optional	type	note
password	YES	string	generated on the apikey host
status	NO	integer	status code
error	NO	string	provided by the apikey
duration	YES	integer	duration of an operation in seconds
key	YES	string	any key that we need to pass on
detail	YES	string	JSON message with details we need to store
email	YES	email	contact details of whoever will be contacted

see the RESTful column

see the RESTful column

see the RESTful column

see the RESTful column

{
    "version":1,
    "error": "success (ok)",
    "status": 36864,
    "nonce":"my nonce",
    "timestamp": 1475078668177,
    "response": null
}

The response to this query is just a result of the processing.

Unlock Domain

see the RESTful column

see the RESTful column

see the RESTful column

see the RESTful column

{
    "nonce":"my nonce",
    "version":1,
    "function": "unlockdomain",
    "environment":"dev",
    "apidata":{
        "username":"dc5c2081-2a13-4566-ac8d-592ee955dc48",
        "apikey":"0b75f...............d057593b"
    }
}

The request uses the following URL:

https://hut:8445/api/v1/apikey

This function will "unlock" the domain record for the given API key so it can be assigned to a new IP address.

name	optional	type	note
apidata	NO	string	authentication of the client

Structure of 'apidata'

name	optional	type	note
username	NO	string	as assigned
apikey	NO	string	as assigned

see the RESTful column

see the RESTful column

see the RESTful column

see the RESTful column

{
    "version": 1,
    "error": "success (ok)",
    "status": 36864,
    "nonce": "my nonce",
    "timestamp": 1475078668177,
    "response": {
        "status": "status of the domain in EB backend"
    }
}

Send Log Data

see the RESTful column

see the RESTful column

see the RESTful column

see the RESTful column

{
    "nonce":"my nonce",
    "version":1,
    "function": "sendlog",
    "environment":"dev",
    "apidata":{
        "username":"dc5c2081-2a13-4566-ac8d-592ee955dc48",
        "apikey":"0b75f...............d057593b"
    },
    "effort":{
        "preimage":"407696;1487584132;34.249.220.146;Trunk;854843",
        "secondpreimage":"hex value",
        "collision": 20
    },
    "log": "text data, with log events"
}

The request uses the following URL:

https://hut:8445/api/v1/apikey

This function will store log data from the endpoint. If the endpoint has its API key, it should be used as it may be used as a protection against DDoS attacks. However, its presence is optional.

If the "apidata" is not present or invalid, the "effort" item must be present. Otherwise the request will be unsuccessful. The "effort" is not required if valid "apidata" is provided. The effort's goal is to slow down DDoS attacks by requiring clients to comput SHA-1 function collisions.

name	optional	type	note
apidata	YES	string	authentication of the client
effort	NO	sequence

Structure of 'apidata'

name	optional	type	note
username	NO	string	as assigned
apikey	NO	string	as assigned

Structure of 'effort'

name	optional	type	note
preimage	NO	string	unique identifier of the request, the format is random-number ";" timestamp ";" IP_address ";" client_version ";" nonce. All numbers are in decadic form.
collision	YES	int	how many bits of collision have been computed

The server will compare the strength of the collision and if not satisfactory, the request will be declined.

see the RESTful column

see the RESTful column

see the RESTful column

see the RESTful column

{
    "version": 1,
    "error": "success (ok)",
    "status": 36864,
    "nonce": "my nonce",
    "timestamp": 1475078668177,
    "response": {
        "collision": integer,
        "reference": "reference number of the log record"
    }
}

name	optional	type	note
collision	YES	string	the length of the collision required, only present if provided collision is not sufficient
reference	NO	string	it canbe empty string if errir

If the request is declined because of insufficent collision strength, the required length/strength is present in the result

Authorizations - RESTful API

Following sections are for internal use by Enigma Bridge. The APIs are not currently available to clients.

The request uses the following URL:

https://hut:8445/api/v1/business

Authorize Create

see the RESTful column

see the RESTful column

see the RESTful column

see the RESTful column

{
    "nonce":"nonce",
    "version":1,
    "function":"authorizecreate",
    "environment":"dev",
    "request":{
        "apikey": "0b75f...............d057593b",
        "objecttype":<integer type ID>,
        "objectpolicy":{
            /* copy the definition as provided by the client */
        }
    }
}

Response

see the RESTful column

see the RESTful column

see the RESTful column

see the RESTful column

{
    "nonce":"nonce",
    "version":1,
    "function":"authorizecreate",
    "environment":"dev",
    "request":{
        "apikey": "0b75f...............d057593b",
        "objecttype":<integer type ID>,
        "objectpolicy":{
            /* copy the definition as provided by the client */
        }
    }
}

Submit new Object

see the RESTful column

see the RESTful column

see the RESTful column

see the RESTful column

{
    "nonce":"nonce",
    "version":1,
    "function":"authorizecreate",
    "environment":"dev",
    "request":{
        "apikey": "0b75f...............d057593b",
        "objecttype":<integer type ID>,
        "objectpolicy":{
            /* copy the definition as provided by the client */
        }
    }
}

Response

--- --- KeyChest API --- ---

KeyChest

Calls of the KeyChest API require an API key. Each client has to create its API key themselves but it can also request the KeyChest to generate one. We do not require this request to be authenticated to simplify automated enrolments.

Register/check API key - GET

This call requests KeyChest to generate a suitable API key for a client. This key will be associated with an email address provided.

"no data required"

"no data required"

"no data required"

curl https://keychest.net/api/v1.0/access/claim/me@myemail.com

https://keychest.net/api/v1.0/access/claim/me@myemail.com

The endpoint of this call is:

https://keychest.net/api/v1.0/access/claim/{email}

Parameters

name	optional	type	note
email	NO	string	it must be a valid email address

see the RESTful column

see the RESTful column

see the RESTful column

{
    "status": "created",
    "user": "your@email.com",
    "api_key": "5b9b6aceb95011e7bb9f7fca73a26228"
}

{
    "status": "created",
    "user": "your@email.com",
    "api_key": "5b9b6aceb95011e7bb9f7fca73a26228"
}

Response

Response provides an api_key the client shall store and use for subsequent use of the KeyChest's API.

name	optional	type	description
status	NO	string	the result of processing - "created" if successful
user	NO	string	email address as provided by the client
api_key	NO	string	a new API key - the length is between 16 and 64 characters and can contain digits, letters, and '-'

Register/check API key - POST

This call requests KeyChest to check a provided API key, and register it if it is a new API key. This key will be associated with an email address provided.

{
    "email":"your@email.com",
    "api_key":"5b9b6aceb95011e7bb9f7fca73a26228"
}

see the RESTful column

see the RESTful column

curl -s -X POST -H "Content-Type: application/json" -d '{"email":"your@email.com", "api_key":"5b9b6aceb95011e7bb9f7fca73a26228"}' https://keychest.net/api/v1.0/access/claim

{
    "email":"your@email.com",
    "api_key":"5b9b6aceb95011e7bb9f7fca73a26228"
}

The endpoint of this call is:

https://keychest.net/api/v1.0/access/claim

Parameters

name	optional	type	note
email	NO	string	it must be a valid email address
api_key	NO	string	it must only contain letters, digits, and '-' and the length to be between 16 and 64 characters

see the RESTful column

see the RESTful column

see the RESTful column

{
    "status": "created",
    "user": "your@email.com",
    "api_key": "5b9b6aceb95011e7bb9f7fca73a26228"
}

{
    "status": "created",
    "user": "your@email.com",
    "api_key": "5b9b6aceb95011e7bb9f7fca73a26228"
}

Response

Response provides an api_key the client shall store and use for subsequent use of the KeyChest's API.

name	optional	type	description
status	NO	string	the result of processing - "created" if successful
user	NO	string	email address as provided by the client
api_key	NO	string	a new API key - the length is between 16 and 64 characters and can contain digits, letters, and '-'

Add domain name

This API call adds a new domain name for monitoring. It can be used repeatedly for the same domain name and email address without any side-effects.

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

see the RESTful column

see the RESTful column

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

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

The POST endpoint of this call is:

https://keychest.net/api/v1.0/servers/add

Parameters

name	optional	type	note
domain	NO	string	it must be a valid domain name
api_key	NO	string	a valid and registered API key

see the RESTful column

see the RESTful column

see the RESTful column

{
    "status": "success",
    "id": "671d1b10-bb1d-11e7-bae1-571d93cf1c53",
    "key": "da70d5e4864f57e910e66bd21c685b26",
    "domain": "fish.enigmabridge.com
}

{
    "status": "success",
    "id": "671d1b10-bb1d-11e7-bae1-571d93cf1c53",
    "key": "da70d5e4864f57e910e66bd21c685b26",
    "domain": "fish.enigmabridge.com
}

Response

Response returns the result of the processing and an additional information.

name	optional	type	description
status	NO	string	"success" means a successful processing
id	NO	string	a handle for repeated calls if asynchronous integration is implemented
key	NO	string	internal representation of the domain name
domain	NO	string	cleaned domain name that was registered

Check certificate expiration

This API call returns information about certificate expiration for a given domain name. It will return detailed information for all IP addresses known for the given domain name.

see the RESTful column

see the RESTful column

see the RESTful column

curl -s https://keychest.net/api/v1.0/servers/expiration/{domain}&api_key={api-key}

see the RESTful column

The GET endpoint of this call is:

https://keychest.net/api/v1.0/servers/expiration/{domain}

Parameters

name	optional	type	note
domain	NO	string	it must be a valid domain name
api_key	NO	string	a valid and registered API key

see the RESTful column

see the RESTful column

see the RESTful column

{
    "domain": "fish.enigmabridge.com",
    "certificate_found":true,
    "renewal_due":false,
    "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"
}

{
    "domain": "fish.enigmabridge.com",
    "certificate_found":true,
    "renewal_due":false,
    "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"
}

Response

Response returns the result of the processing and detailed information for all IP addresses known for a given domain name.

name	optional	type	description
domain	NO	string	requested domain name
certificate_found	NO	boolean	true if at least one certificate found for the domain name
renewal_due	NO	boolean	true if at least one certificate expires within 28 days
expired_found	NO	booean	true if at least one certificate expired
results	NO	JSON array	an array of records for each IP address
status	NO	string	"success" when processing was successful