NAV Navbar
RESTful Java Javascript Python cURL
  • Introduction
  • Basics
  • Getting Started
  • Register as Enigma Client
  • Get API Key
  • Use
  • Errors
  •  
  • --- --- Extended APIs --- ---
  • Enrolment Overview
  • Client Endpoint - RESTful API
  • APIkey Endpoint - RESTful API
  • Authorizations - RESTful API
  •  
  • --- --- KeyChest API --- ---
  • KeyChest
  • 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:

    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:

    1. user enrolment - creating user account;
    2. API key creation - obtaining API key with authorizations and also network connection details to a suitable Enigma Bridge instance;
    3. operation enrolment - introduction of a new use request into Enigma Bridge; and
    4. 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:

    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

    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.

    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

    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:

    1. hut3.enigmabridge.com
    2. hut6.enigmabridge.com
    3. hut8.enigmabridge.com

    Data Flow

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

    1. 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).
    2. 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.
    3. Once the client ID and authentication details are available, the client process can request a new API key.
    4. 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:

    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