Zertifikat bestellen

Anleitung zur vollständigen Automatisierung des Bestellprozesses für Zertifikate. Als Beispiel wird hier das Produkt QuickSSLPremium verwendet und als Authentifizierungsmethode DNS.

Der Bestellprozess für S/MIME-Zertifikate weicht ab und wird gesondert beschrieben.

Inhaltsverzeichnis dieser Seite

Grundlagen der JSON-und XML-API

Alle wichtigen Informationen für die Nutzung der JSON- und XML-API findest du unter folgenden Links:

JSON-API Allgemeine Informationen und weitere Artikel
SSL-XML-API

Prozessübersicht

Ablaufdiagramm

Auftragstypen, Namen und Routen

Auftragstyp	Code	Route
ContactCreate	400201	POST /sslcontact
CertificatePrepareOrder	400110	POST /certificate/_prepareOrder
CertificateCreate	400101	POST /certificate
PollInfo	0905	GET /poll
PollConfirm	0906	PUT /poll/$id
CertificateInfo	400104	GET /certificate/$id

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 verbinden

Fü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üpunkt SSL 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.

Gegebenenfalls musst du die URL zu Ihrem Personal AutoDNS oder Registrar AutoDNS selbst eingeben.

Beachte, dass du die folgenden Aktionen mit deinem SSLManager Benutzer durchführen musst.

Kontakt anlegen

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.

ContactCreate Beispiel

Request

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"
}

Response

{
    "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
        }
    ]
}

Request

<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>

Response

<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

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-Schlüssel geprüft (z.B. auf die richtige Bit-Länge) und es werden die benötigten Authentifizierungsdaten erzeugt.

Beachte, dass der CSR-Code in einer einzigen Zeile stehen muss. Evtl. vorhandene Zeilenumbrüche müssen entfernt werden.

CertificateOrderPrepare Beispiel

Request

POST /certificate/_prepareOrder
{
  "plain": "----BEGIN CERTIFICATE REQUEST----- .... -----END CERTIFICATE REQUEST-----",
  "product": "QUICKSSLPREMIUM"
}

Response

{
    "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

<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

<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-Schlüssel wurde erfolgreich geprüft.</text>
            <type>success</type>
        </status>
    </result>
  <stid>20170407-app1-3562</stid>
</response>

Zertifikat bestellen

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

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

Request

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
  }
}

Response

{
    "stid": "20180926-stid",
    "status": {
        "code": "N400101",
        "text": "Zertifikatsauftrag wurde erfolgreich gestartet. ",
        "type": "NOTIFY"
    },
    "object": {
        "type": "Certificate",
        "value": "example.com"
    },
    "data": [
        {
            "id": 123456
        }
    ]
}

Request

<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>

Response

<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>

Auftragsbenachrichtigungen abfragen und bestätigen

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. Diese kannst du über den Auftragstyp PollInfo abfragen.

War der Auftrag erfolgreich, so erhälst du unter anderem die ID des bestellten Zertifikates. Abschließend musst du den Auftrag mit PollConfirm bestätigen.

PollInfo Beispiel

Request

GET /poll

Response

{
    "stid": "20180926-stid",
    "status": {
        "code": "S0905",
        "text": "Die Benachrichtigung wurde erfolgreich abgerufen.",
        "type": "SUCCESS"
    },
    "object": {
        "type": "message",
        "value": "1405448",
        "summary": 2
    },
    "data": [
        {
            "id": 1405448,
            "job": {
                "created": "2018-12-11T15:10:43.000+0100",
                "updated": "2018-12-11T15:10:55.000+0100",
                "status": "SUCCESS",
                "execution": "2018-12-11T15:10:42.000+0100",
                "id": 9218718,
                "type": "ssl",
                "subType": "QUICKSSLPREMIUM",
                "action": "create"
            },
            "stid": "20180926-stid",
            "object": {
                "type": "Certificate",
                "value": "example.com",
                "data": {
                    "created": "2018-12-11T00:00:00.000+0100",
                    "id": 570,
                    "orderId": "2742528",
             ...
                }
            }
        }
    ]
}

Request

<request>
	<auth>
		<user>USER</user>
		<context>CONTEXT</context>
		<password>PASSWORD</password>
	</auth>
	<task>
		<code>0905</code>
	</task>
</request>

Response

<response>
	<result>
		<data>
			<summary>1</summary>
			<message>
				<id>650664</id><!-- Die ID der PollMessage -->
				<owner>
					<user>USER</user>
					<context>CONTEXT</context>
				</owner>
				<job>
					<certificate>
						...						
						<id>1485</id><!-- Die ID des Zertifikats -->
						...
					</certificate>
					<job_id>536396</job_id><!-- Die ID des Jobs -->
					<status>
						<code>S400101</code><!-- Zeigt an ob der Task CertifikateCreate erfolgreich war oder nicht -->
						<type>success</type>
						<object>
							<type>ssl</type>
							<value>example.com</value><!-- Der Name des Zertifikats -->
						</object>
					</status>
				</job>
			</message>
		</data>
		<status>
			<code>S0905</code>
			<text>Die Benachrichtigung wurde erfolgreich versendet.</text>
			<type>success</type>
			<object>
				<type>message</type>
				<value>650664</value>
			</object>
		</status>
	</result>
  <stid>20181211-app1-3572</stid>
</response>

PollConfirm Beispiel

Request

PUT /poll/{id}

Response

{
    "stid": "20180926-stid",
    "status": {
        "code": "S0906",
        "text": "Die Benachrichtigung wurde erfolgreich bestätigt.",
        "type": "SUCCESS"
    },
    "object": {
        "type": "message",
        "value": "1819853"
    }
}

Request

<request>
	<auth>
		<user>USER</user>
		<context>CONTEXT</context>
		<password>PASSWORD</password>
	</auth>
	<task>
		<code>0906</code>
    	<message>
			<id>650664</id>
		</message>
    </task>
</request>

Response

<response>
    <result>
        <data>
            <summary>0</summary>
            <message>
                <id>650664</id>
            </message>
        </data>
        <status>
            <code>S0906</code>
            <text>Die Benachrichtigung wurde erfolgreich versendet.</text>
            <type>success</type>
            <object>
                <type>message</type>
                <value>650664</value>
            </object>
        </status>
    </result>
 <stid>20181211-app1-3762</stid>
</response>

Zertifikats-Daten ermitteln

Der Auftragstyp CertificateInfo ermittelt alle Zertifikats-Daten. Die Daten können mit Hilfe der ID aus dem Schritt Auftrags-Benachrichtigungen abfragen und bestätigen abgefragt werden.

CertificatInfo - Beispiel

Request

GET /certificate/$id

Response

{
    "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"
        }
    ]
}

Request

<request>
    <auth>
        <user>USER</user>
        <context>CONTEXT</context>
        <password>PASSWORD</password>
    </auth>
    <task>
        <code>400104</code>
        <certificate>
            <id>100</id>
        </certificate>
    </task>
</request>

Response

<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>