API-Grundlagen

Suche in diesem Bereich

Skip to end of metadata
Go to start of metadata

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 finden Sie unter den folgenden Links:

Prozessübersicht

Ablaufdiagramm

Auftragstypen, Namen und Routen

AuftragstypCodeRoute
ContactCreate400201POST /sslcontact
CertificatePrepareOrder

400110

POST /certificate/_prepareOrder
CertificateCreate400101POST /certificate
PollInfo0905GET /poll
PollConfirm0906PUT /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 müssen Sie 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, müssen Sie einmalig den SSLManager mit Ihrem AutoDNS Zugang verbinden.
Gehen Sie im SSL Manager zu den Benutzereinstellungen und klicken Sie auf den Menüpunkt SSL Manager mit dem Domain-Verwaltungssystem verbinden. Sie werden dann auf die AutoDNS Login-Seite geleitet.
Geben Sie hier zum Herstellen der Verbindung Ihre AutoDNS Zugangsdaten ein.

Gegebenenfalls müssen Sie die URL zu Ihrem Personal AutoDNS oder Registrar AutoDNS selbst eingeben.


Beachten Sie, dass Sie die folgenden Aktionen mit Ihrem SSLManager Benutzer durchführen müssen.

Kontakt anlegen

Für die Bestellung eines QuickSSLPremium Zertifikats wird ein technischer und administrativer Kontakt benötigt. Sie können bereits vorhandene Kontakte verwenden oder neue Kontakte anlegen. Sie können neu angelegte Kontakte für zukünftige Bestellungen verwenden.

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.

Beachten Sie, 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 senden Sie die eigentliche Bestellung ans System. Dabei müssen Sie bestimmte Werte setzen:

  • Kontakt:  Geben Sie 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: Geben Sie eine für das Zertifikat zulässige Laufzeit an. Bei QuickSSLPremium sind dies 12 oder 24 Monaten
  • Software: Wählen Sie 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 können Sie über den Auftragstyp PollInfo abfragen.

War der Auftrag erfolgreich, so erhalten Sie unter anderem die ID des bestellten Zertifikates. Abschließend müssen Sie 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>