You are viewing an old version of this page. View the current version.
Compare with Current
View Page History
« Previous
Version 19
Next »
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.
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
| Task | Code | Route |
|---|
| CertificatePrepareOrder | 400110 | POST /certiicate/prepareOrder |
| CertificateRenew | 400106 | PUT /certificate/$id/renew |
| PollInfo | 0905 | GET /poll |
| PollConfirm | 0906 | PUT /poll/$id |
| CertificateInfo | 400104 | GET /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
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.
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
POST /certificate/prepareOrder
{
"plain": "----BEGIN CERTIFICATE REQUEST----- .... -----END CERTIFICATE REQUEST-----",
"product": "QUICKSSLPREMIUM"
}
{
"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"
}
]
}
<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>
<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>
</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.
CertificateRenew - Example
PUT /certificate/$id/renew
{
"lifetime": {
"unit": "MONTH",
"period": 12
},
"authentication": {
"method": "DNS",
"dns": "example.com.\t\t300\tIN\tTXT\t\"201809281426510apdrobvvzyjdsvqnd80x25u1ljxfcm9oz6hsjhecyt7owh6j4\"",
"provisioning": true
}
}
{
"stid": "20180928-stid",
"status": {
"code": "N400106",
"text": "Certificate renew was started successfully.",
"type": "NOTIFY"
},
"object": {
"type": "certificate",
"value": "example.com"
},
"data": [
{
"id": 123456
}
]
}
<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>
<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>
</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
{
"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"
}
}
}
]
}
<request>
<auth>
<user>USER</user>
<context>CONTEXT</context>
<password>PASSWORD</password>
</auth>
<task>
<code>0905</code>
</task>
</request>
<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
{
"stid": "20180926-stid",
"status": {
"code": "S0906",
"text": "The notification was confirmed successfully.",
"type": "SUCCESS"
},
"object": {
"type": "message",
"value": "1819853"
}
}
<request>
<auth>
<user>USER</user>
<context>CONTEXT</context>
<password>PASSWORD</password>
</auth>
<task>
<code>0906</code>
<message>
<id>650664</id>
</message>
</task>
</request>
<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>
<stid>20181015-app1-3162</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 Renew Certificate step.
Certificate Info - Example
{
"stid": "20180926-stid",
"status": {
"code": "S400104",
"text": "Certificate data were inquired successfully.",
"type": "SUCCESS"
},
"object": {
"type": "certificate",
"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"
}
]
}
<request>
<auth>
<user>USER</user>
<context>CONTEXT</context>
<password>PASSWORD</password>
</auth>
<task>
<code>400104</code>
<certificate>
<id>100</id>
</certificate>
</task>
</request>
<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><!-- ertificate 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>
</response>