Search in this section

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

 Instructions für complete automation of the certificate renewing process.  The QuickSSLPremium product is used here as an example and DNS is used as the authentication method.

Panel
titleColor#FFFFFF
titleBGColor#E44313
titleTable of Contents

Table of Contents
outlinetrue
stylenone

Basics of the JSON and XML API

All important information for the use of the JSON and XML API can be found under the following links:

Process Overview

Flow Chart

Tasks Names, Codes and Routes

TaskCodeRoute
CertificatePrepareOrder400110POST /certiicate/prepareOrder
CertificateRenew400106PUT /certificate/$id/renew
PollInfo0905GET /poll
PollConfirm0906PUT /poll/$id
CertificateInfo400104GET /certificate/$id

DNS Validation

DNS validation, i.e. validation by zone entry, is supported by many domain-validated certificates.  To do this, for some CAs you must store a specific TXT or CNAME record in the zone belonging to the certificate name. This is checked for validity by the issuing certificate authority. For zones managed by InterNetX, the provisioning of the zone takes place automatically.

Preparation

Info

If the two systems are already linked, this step can be skipped.

Anchor
connect
connect
Connect SSLManager to AutoDNS

For the automatic provisioning of the zone, you have to connect the SSLManager to your AutoDNS access once. In the SSL Manager go to the User Configuration and click on the menu item Connect SSL Manager to the Domain Administration System.

Info

If necessary, you must enter the URL to your AutoDNS yourself.


You will then be redirected to the AutoDNS login page. Enter your AutoDNS credentials here to establish the connection.

Prolong the Validity of a QuickSSlPremium-Certificate

Create DNS record and check CSR

QuickSSLPremium certificates are verified by TXT entries. A new TXT record with specific values must be stored in the zone belonging to the common name (CNAME). With the CertificatePrepareOrder task, the CSR key provided is checked for the correct bit length, for example, and the required authentication data is generated.

Example .TXT : 
example.com. 300 IN TXT "201704071405295z34is5g0jjairsdu0v5opdw8512td8kixzvtaacu4ebrkry5q
"

CertificatePrepareOrder - Example

SP Tabs group
dispositionhorizontal
SP Tab pane
nameJSON
Code Block
languagejs
titleRequest
linenumberstrue
collapsetrue
POST /certificate/prepareOrder
{
  "plain": "----BEGIN CERTIFICATE REQUEST----- .... -----END CERTIFICATE REQUEST-----",
  "product": "QUICKSSLPREMIUM"
}
Code Block
languagejs
titleResponse
linenumberstrue
collapsetrue
{
    "stid": "20180926-stid",
    "status": {
        "code": "S400110",
        "text": "CSR-Schlüssel wurde erfolgreich geprüft.",
        "type": "SUCCESS"
    },
    "data": [
        {
            "plain": "-----BEGIN CERTIFICATE REQUEST----- ... -----END CERTIFICATE REQUEST-----",
            "name": "example.com",
            "keySize": 2048,
            "countryCode": "DE",
            "state": "BY",
            "city": "Regensburg",
            "organization": "Company GmbH",
            "organizationUnit": "Entwicklung",
            "product": "QUICKSSLPREMIUM",
            "authentication": [
                {
                    "method": "EMAIL",
                    "approverEmails": [
                        "admin@example.com",
                        "administrator@example.com",
                        "hostmaster@example.com",
                        "webmaster@example.com",
                        "postmaster@example.com"
                    ]
                },
                {
                    "method": "DNS",
                    "dns": "example.com.\t\t300\tIN\tTXT\t\"2018092608362142n4sbul8rv8ttv7zkhjgzvyim8n1kpa9lys0uqdszxzs0pa0l\""
                },
                {
                    "method": "FILE"
                }
            ],
            "algorithm": "RSA",
            "signatureHashAlgorithm": "SHA256"
        }
    ]
}
SP Tab pane
nameXML
Code Block
languagexml
titleRequest
linenumberstrue
collapsetrue
<request>
    <auth>
        <user>USER</user>
        <context>CONTEXT</context>
        <password>PASSWORD</password>
    </auth>
    <task>
        <code>400110</code>
        <certificate_request>
            <plain><![CDATA[----BEGIN CERTIFICATE REQUEST----- .... -----END CERTIFICATE REQUEST-----]]></plain>
            <product>QUICKSSLPREMIUM</product>
        </certificate_request>
    </task>
</request>
Code Block
languagexml
titleResponse
linenumberstrue
collapsetrue
<response>
    <result>
        <data>
            <certificate_request>
                <plain><![CDATA[-----BEGIN CERTIFICATE REQUEST----- ... -----END CERTIFICATE REQUEST-----]]></plain>
                <name><![CDATA[example.com]]></name>
                <key_size>2048</key_size>
                <country_code>DE</country_code>
                <state><![CDATA[Bayern]]></state>
                <city><![CDATA[Regensburg]]></city>
                <organization><![CDATA[Company GmbH]]></organization>
                <organization_unit>Entwicklung</organization_unit>
                <email>email@example.com</email>
                <product>QUICKSSLPREMIUM</product>
                <authentication>
                    <method>DNS</method>
                    <dns>example.com. 300 IN TXT "201704071405295z34is5g0jjairsdu0v5opdw8512td8kixzvtaacu4ebrkry5q"</dns>
     				<provisioning>1</provisioning>
                </authentication>
                <authentication>
                    <method>FILE</method>
                    <file_name><![CDATA[http://example.com/.well-known/pki-validation/fileauth.txt]]></file_name>
                    <file_content><![CDATA[201704071405295z34is5g0jjairsdu0v5opdw8512td8kixzvtaacu4ebrkry5q]]></file_content>
                </authentication>
                <algorithm>RSA</algorithm>
                <signature_hash_algorithm>SHA256</signature_hash_algorithm>
            </certificate_request>
        </data>
        <status>
            <code>S400110</code>
            <text>CSR key was checked successfully.</text>
            <type>success</type>
        </status>
    </result>
 <stid>20180926-stid</stid>
</response>

Renew Certificate

With the CertificateRenew task you send the actual order to the system. You must set certain values:

  • Authentication: The generated authentication data
  • Term: Specify a term allowed for the certificate. For QuickSSLPremium, this is 12 or 24 months.
  • Id: The ID of the certificate. If necessary, you can determine the ID using a CertificateInfo request.
    • XML: The ID is set in the payload of the order.
    • JSON: the ID is set via the path.
Info

If data is also to be updated when the runtime is extended, for example, the CSR, you can include the new data in the order.

CertificateRenew - Example

SP Tabs group
dispositionhorizontal
SP Tab pane
nameJSON
Code Block
languagejs
titleRequest
linenumberstrue
collapsetrue
PUT /certificate/$id/renew
{
  "lifetime": {
    "unit": "MONTH",
    "period": 12
  },
  "authentication": {
    "method": "DNS",
    "dns": "example.com.\t\t300\tIN\tTXT\t\"201809281426510apdrobvvzyjdsvqnd80x25u1ljxfcm9oz6hsjhecyt7owh6j4\"",
    "provisioning": true
  }
}
Code Block
languagejs
titleResponse
linenumberstrue
collapsetrue
{
    "stid": "20180928-stid",
    "status": {
        "code": "N400106",
        "text": "Certificate renew was started successfully.",
        "type": "NOTIFY"
    },
    "object": {
        "type": "certificateCertificate",
        "value": "example.com"
    },
    "data": [
        {
            "id": 123456
        }
    ]
}
SP Tab pane
nameXML
Code Block
languagexml
titleRequest
linenumberstrue
collapsetrue
<request>
    <auth>
        <user>USER</user>
        <password>PASSWORD</password>
        <context>CONTEXT</context>
    </auth>
    <task>
        <code>400106</code>
        <certificate>
            <id>123456</id>
            <authentication>
                <method>DNS</method>
                <dns>example.com. 300 IN TXT "201704071405295z34is5g0jjairsdu0v5opdw8512td8kixzvtaacu4ebrkry5q"</dns> 
                <provisioning>1</provisioning>
            </authentication>
        </certificate>
    </task>
</request>
Code Block
languagexml
titleResponse
linenumberstrue
collapsetrue
<response>
  <result>
    <data>
      <certificate_job>
        <job>
          <id>123456</id>
          <status>RUNNING</status>
        </job>
      </certificate_job>
    </data>
    <status>
      <code>N400106</code>
      <text>Certificate renew was started successfully.</text>
      <type>notify</type>
      <object>
        <type>certificate</type>
        <value>example.com</value>
      </object>
    </status>
  </result>
 <stid>20180407-stid</stid>
</response>

Check and Confirm Notifications

The CertificateCreate task automatically generates a request for ordering the certificate. Once the request has been processed, a request notification is generated with information about the request. You can query this using the order type PollInfo. If the order was successful, you receive, among other things, the ID of the certificate ordered. Finally you have to confirm the order with PollConfirm.

PollInfo - Examples

SP Tabs group
dispositionhorizontal
SP Tab pane
nameJSON
Code Block
languagejs
titleRequest
linenumberstrue
collapsetrue
GET /poll
Code Block
languagejs
titleResponse
linenumberstrue
collapsetrue
{
    "stid": "20180926-stid",
    "status": {
        "code": "S0905",
        "text": "The notification was polled successfully.",
        "type": "SUCCESS"
    },
    "object": {
        "type": "message",
        "value": "1819917"
    },
    "data": [
        {
            "summary": 1,
            "message": {
                "id": 1819917,
                "job": {
                    "id": 4295609745,
                    "domain": {
                        "created": "2018-09-26T15:11:21.000+0200",
                        "owner": {},
                        "updater": {},
                        "name": "example.com",
                        "expire": "2019-09-26T15:11:20.000+0200",
                        "payable": "2019-09-26T15:11:21.000+0200",
                        "ownerc": {
                            "id": 100
                        },
                        "adminc": {
                            "id": 100
                        },
                        "techc": {
                            "id": 100
                        },
                        "registryStatus": "LOCK",
                        "nameServers": [
                            {
                                "name": "a.ns14.net"
                            },
                            {
                                "name": "b.ns14.net"
                            },
                            {
                                "name": "c.ns14.net"
                            },
                            {
                                "name": "d.ns14.net"
                            }
                        ],
                        "lastAction": "CREATE",
                        "authinfo": "gg9o3FFL/hzNbuPw",
                        "autoRenewStatus": "TRUE",
                        "registrarStatus": "ACTIVE",
                        "rddsOptIn": "NOT_SET"
                    }
                },
                "stid": "20180926-stid",
                "object": {
                    "type": "domain",
                    "value": "example.com"
                },
                "status": {
                    "code": "S0101",
                    "type": "SUCCESS"
                }
            }
        }
    ]
}
SP Tab pane
nameXML
Code Block
languagexml
titleRequest
linenumberstrue
collapsetrue
<request>
    <auth>
        <user>USER</user>
        <context>CONTEXT</context>
        <password>PASSWORD</password>
    </auth>
    <task>
        <code>0905</code>
    </task>
</request>
Code Block
languagexml
titleResponse
linenumberstrue
collapsetrue
<response>
    <result>
        <data>
            <summary>1</summary>
            <message>
                <id>1855680</id>
                <owner>
                    <user>alex_normal_plus</user>
                    <context>4</context>
                </owner>
                <job>
                    <domain>
                        <name>example.com</name>
                        <expire>2019-10-15 14:02:40</expire>
                        <payable>2019-10-15 14:02:41</payable>
                        <ownerc>100</ownerc>
                        <adminc>100</adminc>
                        <techc>100</techc>
                        <nic_member_label>VGRS-TEST</nic_member_label>
                        <registry_status>LOCK</registry_status>
                        <nserver>
                            <name>a.ns14.net</name>
                        </nserver>
                        <nserver>
                            <name>b.ns14.net</name>
                        </nserver>
                        <nserver>
                            <name>c.ns14.net</name>
                        </nserver>
                        <nserver>
                            <name>d.ns14.net</name>
                        </nserver>
                        <period>1</period>
                        <authinfo>S0Lygv+ZkNbniICm</authinfo>
                        <autorenew>true</autorenew>
                        <confirm_order>1</confirm_order>
                        <confirm_owner_consent>0</confirm_owner_consent>
                        <registrar_status>ACTIVE</registrar_status>
                        <rdds_opt_in>NOT_SET</rdds_opt_in>
                        <owner/>
                        <updater/>
                        <created>2018-10-15 14:02:41</created>
                    </domain>
                    <job_id>4295625406</job_id>
                    <status>
                        <code>S0101</code>
                        <type>success</type>
                        <object>
                            <type>domain</type>
                            <value>example.com</value>
                        </object>
                    </status>
                    <stid>20181015-app1-3788</stid>
                </job>
                <created>2018-10-15 14:03:02</created>
            </message>
        </data>
        <status>
            <code>S0905</code>
            <text>The notification was polled successfully.</text>
            <type>success</type>
            <object>
                <type>message</type>
                <value>1855680</value>
            </object>
        </status>
    </result>
    <stid>20181015-app1-3805</stid>
</response>


PollConfirm - Examples

SP Tabs group
dispositionhorizontal
SP Tab pane
nameJSON
Code Block
languagejs
titleRequest
linenumberstrue
collapsetrue
PUT /poll/{id}
Code Block
languagejs
titleResponse
linenumberstrue
collapsetrue
{
    "stid": "20180926-stid",
    "status": {
        "code": "S0906",
        "text": "The notification was confirmed successfully.",
        "type": "SUCCESS"
    },
    "object": {
        "type": "message",
        "value": "1819853"
    }
}
SP Tab pane
nameXML
Code Block
languagexml
titleRequest
linenumberstrue
collapsetrue
<request>
    <auth>
        <user>USER</user>
        <context>CONTEXT</context>
        <password>PASSWORD</password>
    </auth>
    <task>
        <code>0906</code>
       <message>
            <id>650664</id>
        </message>
    </task>
</request>
Code Block
languagexml
titleResponse
linenumberstrue
collapsetrue
<response>
    <result>
        <data>
            <summary>0</summary>
            <message>
                <id>650664</id>
            </message>
        </data>
        <status>
            <code>S0906</code>
            <text>The notification was confirmed successfully.</text>
            <type>success</type>
            <object>
                <type>message</type>
                <value>650664</value>
            </object>
        </status>
       </result>
  <stid>20181015-app1-3162<9165</stid>
	 </result>
</response>

Inquire Certificate Data

The  CertificateInfo task inquires the certificate data. The data can be queried and confirmed using the ID from the Check and Confirm Notificationsstep.

Certificate Info - Example

SP Tabs group
dispositionhorizontal
SP Tab pane
nameJSON
Code Block
languagejs
titleRequest
linenumberstrue
collapsetrue
GET /certificate/$id
Code Block
languagejs
titleResponse
linenumberstrue
collapsetrue
{
    "stid": "20180926-stid",
    "status": {
        "code": "S400104",
        "text": "Certificate data were inquired successfully.",
        "type": "SUCCESS"
    },
    "object": {
        "type": "certificateCertificate",
        "value": "example.com"
    },
    "data": [
        {
            "created": "2018-09-26T00:00:00.000+0200",
            "updated": "2018-09-26T11:38:08.000+0200",
            "id": 13258,
            "owner": {
                "user": "user",
                "context": 9
            },
            "orderId": "2695961",
            "adminContact": {
                "id": 100
				...
            },
            "technicalContact": {
                "id": 100
				...
            },
            "name": "example.com",
            "lifetime": {
                "unit": "MONTH",
                "period": 12
            },
            "software": "APACHESSL",
            "csr": "-----BEGIN CERTIFICATE REQUEST----- ... -----END CERTIFICATE REQUEST-----",
            "server": "-----BEGIN CERTIFICATE----- ... -----END CERTIFICATE-----\n",
            "serialNumber": "750C3006B23B90D0F396A3D153EB4C8",
            "product": "QUICKSSLPREMIUM",
            "expire": "2019-09-26T12:00:00.000+0200",
            "authentication": {
                "method": "DNS",
                "dns": "example.com.\t\t300\tIN\tTXT\t\"2018092608362142n4sbul8rv8ttv7zkhjgzvyim8n1kpa9lys0uqdszxzs0pa0l\"",
                "provisioning": true
            },
            "certificateTransparencyPrivacy": "PUBLIC",
            "domain": "example.com"
        }
    ]
}
SP Tab pane
nameXML
Code Block
languagexml
titleRequest
linenumberstrue
collapsetrue
<request>
    <auth>
        <user>USER</user>
        <context>CONTEXT</context>
        <password>PASSWORD</password>
    </auth>
    <task>
        <code>400104</code>
        <certificate>
            <id>100</id>
        </certificate>
    </task>
</request>
Code Block
languagexml
titleResponse
linenumberstrue
collapsetrue
<response>
  <result>
    <data>
      <certificate>
        <order_id>1003396954</order_id>
        <technical>
          <first>John</first>
            <last>Doe</last>
            <phone>+49-941-1234560</phone>
            <email>j.doe@example.com</email>
            <title>Admin</title>
            <organization>Example GmbH</organization>
            <address>Maximilianstrasse 36000</address>
            <postal_code>93047</postal_code>
            <city>Regensburg</city>
            <country>DE</country>
            <state>Bayern</state>
          <owner>
            <user>USER</user>
            <context>CONTEXT</context>
          </owner>
          <updater>
            <user>USER</user>
            <context>CONTEXT</context>
          </updater>
          <id>20398</id>
          <created>2017-01-01 10:35:22</created>
          <updated>2017-01-01 01:05:07</updated>
        </technical>
        <admin>
          <first>John</first>
            <last>Doe</last>
            <phone>+49-941-1234560</phone>
            <email>j.doe@example.com</email>
            <title>Admin</title>
            <organization>Example GmbH</organization>
            <address>Maximilianstrasse 36000</address>
            <postal_code>93047</postal_code>
            <city>Regensburg</city>
            <country>DE</country>
            <state>Bavaria</state>
          <owner>
            <user>USER</user>
            <context>CONTEXT</context>
          </owner>
          <updater>
            <user>USER</user>
            <context>CONTEXT</context>
          </updater>
          <id>20398</id>
          <created>2017-01-01 10:35:22</created>
          <updated>2017-01-01 01:05:07</updated>
        </admin> 
        <name>example.com</name><!-- ertificatecertificate name -->
        <lifetime>12</lifetime><!-- certificate runtime -->
        <software>APACHE2</software>
        <csr><![CDATA[----BEGIN CERTIFICATE REQUEST----- .... -----END CERTIFICATE REQUEST-----]]></csr>
        <server><![CDATA[----BEGIN CERTIFICATE ----- .... -----END CERTIFICATE-----]]></server>
        <serial_number>SERIALNUMBER</serial_number>
        <product>QUICKSSLPREMIUM</product>
        <sha>SHA2</sha>
        <expire>2030-01-01 23:59:59</expire><!-- certificate expire date -->
        <extension />
        <certification_authority>
          <ca_type>ICA1</ca_type>
          <ca_cert><![CDATA[----BEGIN CERTIFICATE ----- .... -----END CERTIFICATE-----]]></ca_cert>
        </certification_authority>
        <authentication>
          <method>DNS</method>
          <dns>example.com. 300 IN TXT "201704071405295z34is5g0jjairsdu0v5opdw8512td8kixzvtaacu4ebrkry5q"</dns>
        </authentication>
        <owner>
          <user>USER</user>
          <context>CONTEXT</context>
        </owner>
        <updater>
          <user>USER</user>
          <context>CONTEXT</context>
        </updater>
        <id>100</id><!-- certificate id -->
        <created>2017-01-01 00:00:00</created>
        <updated>2017-01-01 14:30:36</updated>
      </certificate>
    </data>
    <status>
      <code>S400104</code>
      <text>Certificate data were inquired successfully.</text>
      <type>success</type>
      <object>
        <type>certificate</type>
        <value>example.com</value><!-- certificate name -->
      </object>
    </status>
  </result>
 <stid>20181015-app1-7763</stid>
</response>