Grundlagen der JSON-und XML-API
Alle wichtigen Informationen für die Nutzung der JSON- und XML-API findest du bei den API-Grundlagen, den XML- und JSON-Grundlagen.
Die spezifischen SSL-Objekte sind hier dokumentiert, die SSL-Auftragstypen hier.
Prozessübersicht
Ablaufdiagramm

Auftragstypen, Codes und Routen
DNS-Validierung
Die DNS-Validierung, also die Validierung durch Zonen-Eintrag, wird von vielen domain-validierten Zertifikaten unterstützt. Dafür musst du für manche CAs in der zum Zertifikats-Namen gehörenden Zone einen bestimmter TXT- oder CNAME-Record hinterlegen. Dieser wird von der austellenden Zertifikats-Stelle auf Gültigkeit geprüft. Wird die dazugehörige Zone von InterNetX verwaltet, erfolgt die Provisionierung der Zone automatisch.
Vorbereitung
SSLManager mit AutoDNS verbindenFür die automatische Provisionierung der Zone, musst du einmalig den SSLManager mit deinem AutoDNS Zugang verbinden.
Gehe im SSL Manager zu den Benutzereinstellungen und klicken auf den MenüpunktSSL Manager mit dem Domain-Verwaltungssystem verbinden.

Du wirst dann auf die AutoDNS Login-Seite geleitet. Gebe hier zum Herstellen der Verbindung deine AutoDNS Zugangsdaten ein.

Info |
---|
Gegebenenfalls musst du die URL zu Ihrem Personal AutoDNS oder Registrar AutoDNS selbst eingeben. |
Info |
---|
Beachte, dass du die folgenden Aktionen mit deinem SSLManager Benutzer durchführen musst. |
Für die Bestellung eines QuickSSLPremium Zertifikats wird ein technischer und administrativer Kontakt benötigt. Du kannst bereits vorhandene Kontakte verwenden oder neue Kontakte anlegen, die du dann alle für zukünftige Bestellungen verwenden kannst.
SP Tabs group |
---|
|
SP Tab pane |
---|
| Code Block |
---|
language | js |
---|
title | Request |
---|
linenumbers | true |
---|
collapse | true |
---|
| POST /sslcontact
{
"fname": "John",
"lname": "Doe",
"phone": "+49-123-12345",
"fax": "+49-123-12345",
"email": "john.doe@example.com",
"title": "Admin",
"organization": "Company",
"address": [
"123 Main Street"
],
"pcode": "12345",
"city": "Anytown",
"country": "DE",
"state": "BY"
} |
Code Block |
---|
language | js |
---|
title | Response |
---|
linenumbers | true |
---|
collapse | true |
---|
| {
"stid": "20180926-stid",
"status": {
"code": "S400201",
"text": "Kontakt wurde erfolgreich angelegt.",
"type": "SUCCESS"
},
"object": {
"type": "contact",
"value": "100"
},
"data": [
{
"fname": "John",
"lname": "Doe",
"phone": "+49-123-12345",
"email": "john.doe@example.com",
"title": "Admin",
"organization": "Company",
"address": "123 Main Street",
"pcode": "12345",
"city": "Anytown",
"country": "DE",
"state": "BY",
"owner": {
"user": "user",
"context": 9
},
"id": 100
}
]
} |
|
SP Tab pane |
---|
| Code Block |
---|
language | xml |
---|
title | Request |
---|
linenumbers | true |
---|
collapse | true |
---|
| <request>
<auth>
<user>USER</user>
<context>CONTEXT</context>
<password>PASSWORD</password>
</auth>
<task>
<code>400201</code>
<contact>
<first>Michael</first>
<last>Mustermann</last>
<phone>+49-941-1234560</phone>
<email>michael.mustermann@example.com</email>
<title>Admin</title>
<organization>Beispiel GmbH</organization>
<address>Maximilianstrasse 36000</address>
<postal_code>93047</postal_code>
<city>Regensburg</city>
<country>DE</country>
<state>Bayern</state>
</contact>
</task>
</request> |
Code Block |
---|
language | xml |
---|
title | Response |
---|
linenumbers | true |
---|
collapse | true |
---|
| <response>
<result>
<data/>
<status>
<code>S400201</code>
<text>Kontakt wurde erfolgreich angelegt.</text>
<type>success</type>
<object>
<type>contact</type>
<value>100</value> <!-- Die ID des angelegten Kontaktes -->
</object>
</status>
</result>
</response> |
|
|
Ein QuickSSLPremium Zertifikat bestellen
DNS-Record erzeugen und CSR prüfen (Certificate Prepare Order)
QuickSSLPremium Zertifikate werden durch TXT-Einträge verifiziert. Dafür muss in der zum Common-Name (CNAME) gehörenden Zone ein neuer TXT-Record mit bestimmten Werten hinterlegt werden.
Beispiel TXT :
example.com. 300 IN TXT "201704071405295z34is5g0jjairsdu0v5opdw8512td8kixzvtaacu4ebrkry5q"
Mit dem Auftragstyp CertificatePrepareOrder wird der bereitgestellte CSR Key geprüft (z.B. auf die richtige Bit-Länge) und es werden die benötigten Authentifizierungsdaten erzeugt.
Info |
---|
Beachte, dass der CSR-Code in einer einzigen Zeile stehen muss. Evtl. vorhandene Zeilenumbrüche müssen entfernt werden. |
CertificateOrderPrepare Beispiel
SP Tabs group |
---|
|
SP Tab pane |
---|
| Code Block |
---|
language | js |
---|
title | Request |
---|
linenumbers | true |
---|
collapse | true |
---|
| POST /certificate/_prepareOrder
{
"plain": "----BEGIN CERTIFICATE REQUEST----- .... -----END CERTIFICATE REQUEST-----",
"product": "QUICKSSLPREMIUM"
} |
Code Block |
---|
language | js |
---|
title | Response |
---|
linenumbers | true |
---|
collapse | true |
---|
| {
"stid": "20180926-stid",
"status": {
"code": "S400110",
"text": "CSR Key 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 |
---|
| Code Block |
---|
language | xml |
---|
title | Request |
---|
linenumbers | true |
---|
collapse | true |
---|
| <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 |
---|
language | xml |
---|
title | Response |
---|
linenumbers | true |
---|
collapse | true |
---|
| <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 wurde erfolgreich geprüft.</text>
<type>success</type>
</status>
</result>
<stid>20170407-app1-3562</stid>
</response> |
|
|
Zertifikat bestellen (Certificate Create)
Mit dem Auftragstyp CertificateCreate sendest du die eigentliche Bestellung ans System. Dabei musst du bestimmte Werte setzen:
- Kontakt: Geben die Kontakt-ID der geforderten Kontakte an. Bei QuickSSLPremium sind dies der administrative Kontakt und der technische.
- Name: Der Name des Zertifikates
- Produkt: Der Wert für QuickSSLPremium ist QUICKSSLPREMIUM
- Authentifizierung: Die generierten Authentifizierungsdaten
- Laufzeit: Gib eine für das Zertifikat zulässige Laufzeit an. Bei QuickSSLPremium sind dies 12 oder 24 Monaten
- Software: Wähle APACHESSL oder IIS5 aus
- CSR: Der zum Zertifikat gehörende CSR
Info |
---|
Für die automatische Provisionierung der Zone, also das automatische Anstoßen der Zonen-Aktualisierung, muss sie über AutoDNS verwaltet werden und die Systeme SSL Manager und AutoDNS müssen miteinander verknüpft sein. Siehe Schritt SSLManager mit dem AutoDNS verbinden. |
CertificateCreate Beispiel
SP Tabs group |
---|
|
SP Tab pane |
---|
| Code Block |
---|
language | js |
---|
title | Request |
---|
linenumbers | true |
---|
collapse | true |
---|
| POST /certificate
{
"adminContact": {
"id": 100
},
"technicalContact": {
"id": 100
},
"name": "example.com",
"lifetime": {
"unit": "MONTH",
"period": 12
},
"software": "APACHESSL",
"csr": "-----BEGIN CERTIFICATE REQUEST----- ... -----END CERTIFICATE REQUEST-----",
"product": "QUICKSSLPREMIUM",
"authentication": {
"method": "DNS",
"dns": "example.com.\t\t300\tIN\tTXT\t\"2018092608362142n4sbul8rv8ttv7zkhjgzvyim8n1kpa9lys0uqdszxzs0pa0l\"",
"provisioning": true
}
} |
Code Block |
---|
language | js |
---|
title | Response |
---|
linenumbers | true |
---|
collapse | true |
---|
| {
"stid": "20180926-stid",
"status": {
"code": "N400101",
"text": "Zertifikatsauftrag wurde erfolgreich gestartet. ",
"type": "NOTIFY"
},
"object": {
"type": "Certificate",
"value": "example.com"
},
"data": [
{
"id": 123456
}
]
} |
|
SP Tab pane |
---|
| Code Block |
---|
language | xml |
---|
title | Request |
---|
linenumbers | true |
---|
collapse | true |
---|
| <request>
<auth>
<user>USER</user>
<password>PASSWORD</password>
<context>CONTEXT</context>
</auth>
<task>
<code>400101</code>
<certificate>
<technical>
<id>100</id>
</technical>
<admin>
<id>100</id>
</admin>
<name>example.com</name>
<product>QUICKSSLPREMIUM</product>
<authentication>
<method>DNS</method>
<dns>example.com. 300 IN TXT "201704071405295z34is5g0jjairsdu0v5opdw8512td8kixzvtaacu4ebrkry5q"</dns>
<provisioning>1</provisioning>
</authentication>
<lifetime>12</lifetime>
<software>APACHESSL</software> <!-- APACHESSL / IIS5 -->
<csr><![CDATA[---------BEGIN CERTIFICATE REQUEST----- .... -----END CERTIFICATE REQUEST-----]]></csr> <!-- Der CSR KEY -->
</certificate>
</task>
</request> |
Code Block |
---|
language | xml |
---|
title | Response |
---|
linenumbers | true |
---|
collapse | true |
---|
| <response>
<result>
<data>
<certificate_job>
<job>
<id>123456</id><!-- Die ID des angelegten Jobs -->
<status>RUNNING</status><!-- Der Status des angelegten Jobs -->
</job>
</certificate_job>
</data>
<status>
<code>N400101</code><!-- Beschreibt den Status des Tasks -->
<text>Zertifikatsauftrag wurde erfolgreich gestartet. </text>
<type>notify</type><!-- Beschreibt den Status des Tasks -->
<object>
<type>certificate</type>
<value>example.com</value><!-- Der Name des Zertifikats -->
</object>
</status>
</result>
<stid>20170407-app1-3762</stid>
</response> |
|
|
Anchor |
---|
| Auftragsbenach |
---|
| Auftragsbenach |
---|
|
Benachrichtigungen erhalten
Der Auftragstyp CertificateCreate erzeugt automatisch einen Auftrag für die Bestellung des Zertifikats. Ist der Auftrag abgearbeitet, wird eine Auftragsbenachrichtigung generiert, mit Informationen über den Auftrag. War der Auftrag erfolgreich, so erhälst du unter anderem die ID des bestellten Zertifikates. Die Systembenachrichtigung kann mit den Methoden Polling und Push abgerufen bzw. zugesendet werden.
Zertifikats-Daten ermitteln (Certificate Info)
Der Auftragstyp CertificateInfo ermittelt alle Zertifikats-Daten. Die Daten können mit Hilfe der ID aus dem Schritt Benachrichtigungen erhalten abgefragt werden.
CertificatInfo - Beispiel
SP Tabs group |
---|
|
SP Tab pane |
---|
| Code Block |
---|
language | js |
---|
title | Request |
---|
linenumbers | true |
---|
collapse | true |
---|
| GET /certificate/$id |
Code Block |
---|
language | js |
---|
title | Response |
---|
linenumbers | true |
---|
collapse | true |
---|
| {
"stid": "20180926-stid",
"status": {
"code": "S400104",
"text": "Zertifikatsdaten wurden erfolgreich ermittelt.",
"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"
}
]
} |
|
SP Tab pane |
---|
| Code Block |
---|
language | xml |
---|
title | Request |
---|
linenumbers | true |
---|
collapse | true |
---|
| <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 |
---|
language | xml |
---|
title | Response |
---|
linenumbers | true |
---|
collapse | true |
---|
| <response>
<result>
<data>
<certificate>
<order_id>1003396954</order_id>
<technical>
<first>Michael</first>
<last>Mustermann</last>
<phone>+49-941-1234560</phone>
<email>michael.mustermann@example.com</email>
<title>Admin</title>
<organization>Beispiel 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>Michael</first>
<last>Mustermann</last>
<phone>+49-941-1234560</phone>
<email>michael.mustermann@example.com</email>
<title>Admin</title>
<organization>Beispiel 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>
</admin>
<name>example.com</name><!-- Der Name des Zertifikats -->
<lifetime>12</lifetime><!-- Die Laufzeit des Zertifikats -->
<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><!-- Das Expire Datum des Zertifikats -->
<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><!-- Die ID des Zertifikats -->
<created>2017-01-01 00:00:00</created>
<updated>2017-01-01 14:30:36</updated>
</certificate>
</data>
<status>
<code>S400104</code>
<text>Zertifikatsdaten wurden erfolgreich ermittelt.</text>
<type>success</type>
<object>
<type>certificate</type>
<value>example.com</value><!-- Der Name des Zertifikats -->
</object>
</status>
</result>
<stid>20181211-app1-3892</stid>
</response>
|
|
|