Suche in diesem Bereich

Skip to end of metadata
Go to start of metadata

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

Inhaltsverzeichnis dieser Seite

Grundlagen der JSON-und XML-API

Alle wichtigen Informationen für die Nutzunge der JSON- und XML-API finden Sie unter den folgenden Links:

Prozess-Übersicht

Ablaufdiagramm

Auftragstypen-Namen, Codes und Routen

AuftragstypCodeRoute
CertificatePrepareOrder400110POST /certificate/prepareOrder
CertificateRenew400106PUT /certificate/$id/_renew
PollInfo0905GET /poll
PollConfirm0906PUT /poll/$id
CertificateInfo400104

GET /certificate/$id

DNS-Validierung

Die DNS-Validierung, also die Validierung durch Zoneneintrag, wird von vielen domainvalidierten Zertifikaten unterstützt.  Dafür müssen Sie für manche CAs in der zum Zertifikatsnamen gehörenden Zone einen bestimmten TXT- oder CNAME-Record hinterlegen. Dieser wird von der austellenden Zertifikatsstelle auf Gültigkeit geprüft. Für Zonen, die von InterNetX verwaltet werden, erfolgt die Provisionierung der Zone automatisch.

Vorbereitung

SSLManager mit AutoDNS verbinden

Sind die zwei Systeme bereits verknüpft, kann dieser Schritt übersprungen werden!

Für die automatische Provisionierung der Zone, also das automatische Anstoßen der Zonen-Aktualisierung, 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 Domainverwaltungssystem verbinden. Sie werden dann auf die AutoDNS Loginseite geleitet.
Geben Sie hier zum Herstellen der Verbindung Ihre AutoDNS Zugangsdaten ein. Gebenenfalls müssen Sie die URL zu Ihrem AutoDNS selbst eingeben.


Die Laufzeit eines QuickSSLPremium-Zertifikates verlängern

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. Mit dem Auftragstyp CertificatePrepareOrder wird der bereitgestellte CSR-Schlüssel z.B. auf die richtige Bit-Länge geprüft und es werden die benötigten Authentifizierungsdaten erzeugt.

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

CertificatePrepareOrder  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\"201704071405295z34is5g0jjairsdu0v5opdw8512td8kixzvtaacu4ebrkry5q\""
                },
                {
                    "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 key was checked successfully.</text>
            <type>success</type>
        </status>
    </result>
  <stid>20170407-app1-2155</stid>
</response>

Zertifikat verlängern

Mit dem Auftragstyp CertificateRenew senden Sie die eigentliche Bestellung ans System. Dabei müssen Sie bestimmte Werte setzen:

  • Authentifizierung: Die generierten Authentifizierungsdaten
  • Laufzeit: Geben Sie eine für das Zertifikat zulässige Laufzeit an. Bei QuickSSLPremium sind dies 12 oder 24 Monate.
  • Id: Die ID des Zertifikates.  Diese können Sie über einen CertificateInfo-Auftrag ermitteln.
    XML: die ID wird im Payload des Auftrages gesetzt.
    JSON: die ID wird über den Pfad gesetzt.

Wenn bei der Laufzeitverlängerung auch Daten geändert werden sollen, z. B. der CSR, dann können Sie diese im Auftrag mitschicken.

CertificateRenew - Beispiel

Request
PUT /certificate/$id/_renew
{
  "lifetime": {
    "unit": "MONTH",
    "period": 12
  },
  "authentication": {
    "method": "DNS",
    "dns": "example.com.\t\t300\tIN\tTXT\t\"201704071405295z34is5g0jjairsdu0v5opdw8512td8kixzvtaacu4ebrkry5q\"",
    "provisioning": true
  }
}
Response
{
    "stid": "20180928-stid",
    "status": {
        "code": "N400106",
        "text": "Laufzeitverlängerung für das Zertifikat 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>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
<response>
  <result>
    <data>
      <certificate_job>
        <job>
          <id>123456</id>
          <status>RUNNING</status>
        </job>
      </certificate_job>
    </data>
    <status>
      <code>N400106</code>
      <text>Laufzeitverlängerung für das Zertifikat wurde erfolgreich gestartet.</text>
      <type>notify</type>
      <object>
        <type>certificate</type>
        <value>example.com</value>
      </object>
    </status>
  </result>
 <stid>20170407-app1-2521</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": "1819853"
    },
    "data": [
        {
            "summary": 2,
            "message": {
                "id": 1819853,
                "job": {
                    "id": 123456,
                    "certificate": {
                        "id": 13258,
                        "orderId": "2695961",
						...
                    }
                },
                "stid": "20180926-stid",
                "object": {
                    "type": "ssl",
                    "value": "example.com"
                },
                "status": {
                    "code": "S400101",
                    "type": "SUCCESS"
                }
            }
        }
    ]
}
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>
				<owner>
					<user>USER</user>
					<context>CONTEXT</context>
				</owner>
				<job>
					<certificate>
						...						
						<id>1485
						...
					</certificate>
					<job_id>123456</job_id>
					<status>
						<code>S400106</code>
						<type>success</type>
						<object>
							<type>ssl</type>
							<value>example.com</value>
						</object>
					</status>
				</job>
			</message>
		</data>
		<status>
			<code>S0905</code>
			<text>Die Benachrichtigung wurde erfolgreich abgerufen.</text>
			<type>success</type>
			<object>
				<type>message</type>
				<value>650664</value>
			</object>
		</status>
	</result>
 <stid>20180926-app1-1161</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 bestätigt.</text>
            <type>success</type>
            <object>
                <type>message</type>
                <value>650664</value>
            </object>
        </status>
    </result>
 <stid>20180926-app1-1760</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.

CertificateInfo - 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\"201809261405295z34is5g0jjairsdu0v5opdw8512td8kixzvtaacu4ebrkry5q\"",
                "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>20180926-app1-2009</stid>
</response>