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.
- Java - client.java at GitHub
- Javascript - client.js at GitHub
- Python - client.py at GitHub
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:
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 |
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.
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.
- 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
andGet Client Auth
. - The customer will request a new client account via our support system at: https://enigmabridge.freshdesk.com.
- The client process will use its EB type to request a new client account: this always involves a register client API call; optionally also
- 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" |
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 |
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 |
YES | 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 |
---|---|---|---|
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 |
---|---|---|---|
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 |