Search in this section

Child pages
  • Ordering SSL Certificates
Skip to end of metadata
Go to start of metadata

Instructions for completely automating the order process for certificates. In our example we are using the product QuickSSLPremium and as authentication method DNS.

Table of Contents

Introduction to DNS Validation

Many domain validated certificates support validation by means of a zone record in the DNS. The zone which corresponds to the certificate name must edited and a specific TXT or CNAME record must be added. This record is then validated by the issuing certificate authority. If the corresponding zone is managed by InterNetX, the provisioning of the zone can be completely automated with no further action required on your part.

Preparation

Connect the SSLManager to the Domain Management System (AutoDNS) 

In order to use the automatic zone provisioning, the SSL Manager and the AutoDNS must be connected together in a one-time process. In the SSL Manager within the User Configuration you will find the option Connect SSL Manager to the Domain Management System. Click on this option and enter the login details of the AutoDNS account.

Notice

Under certain conditions you may be asked for the URL of your AutoDNS. In this case an additional input field for the URL is displayed. Enter the URL of your AutoDNS system to continue.

Create Contact (400201)

To order a QuickSSLPremium certificate, a technical and administrative contact is required. These must be created beforehand and can then be used for future orders. In case one or more contacts are already present, you can skip this step and use the contact for future tasks.

ContactCreate 400201 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@domain.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>
ContactCreate 400201 Response
<response>
    <result>
        <data/>
        <status>
            <code>S400201</code>
            <text>Contact was created successfully.</text>
            <type>success</type>
            <object>
                <type>contact</type>
                <value>100</value> <!-- The ID of the created contact -->
            </object>
        </status>
    </result>
</response>

Order a QuickSSLPremium Certificate

Generate DNS Record and Check CSR (400110)

QuickSSLPremium certificates are validated using TXT records. For this purpose, the zone which is also the common name of the certificate (CNAME), must be edited to contain a TXT record containing very specific values. By using the CertificatePrepareOrder (400110) task, the provided CSR Key is checked for the correct bit-length. In addition, the required validation (authentication) data is generated.

Example TXT: 
domain.com. 300 IN TXT "201704071405295z34is5g0jjairsdu0v5opdw8512td8kixzvtaacu4ebrkry5q
"


CertificatePrepareOrder 400110 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>
CertificatePrepareOrder 400110 Response
<response>
    <result>
        <data>
            <certificate_request>
                <plain><![CDATA[-----BEGIN CERTIFICATE REQUEST----- ... -----END CERTIFICATE REQUEST-----]]></plain>
                <name><![CDATA[domain.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@domain.com</email>
                <product>QUICKSSLPREMIUM</product>
                <authentication>
                    <method>DNS</method>
                    <dns>domain.com. 300 IN TXT "201704071405295z34is5g0jjairsdu0v5opdw8512td8kixzvtaacu4ebrkry5q"</dns>
     				<provisioning>1</provisioning>
                </authentication>
                <authentication>
                    <method>FILE</method>
                    <file_name><![CDATA[http://domain.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>

Order Certificate (400101)

The actual certificate order is accomplished with the CertificateCreate (400101) task. You must provide and set the same details as when using the user interface:

  • Contact: QuickSSLPremium requires a technical as well as a administrative contact. The ID of a contact must be used.
  • Name: The name of the certificate
  • Product: For QuickSSLPremium product the value QUICKSSLPREMIUM must be set.
  • Authentication: The generated authentication (validation) data.
  • Term: QuickSSLPremium supports a maximum term of 12 or 24 months.
  • Software: Choose either APACHESSL or IIS5 
  • CSR: The CSR for the certificate

Notice

The automatic zone provisioning only functions if the zone is managed by AutoDNS and if the SSL Manager and AutoDNS are connected to one another. See the step Connecting the SSL Manager to the AutoDNS.

CertificateCreate 400101 Request
<request>
    <auth>
        <user>USER</user>
        <password>PASSWORD</password>
        <context>CONTEXT</context>
    </auth>
    <task>
        <code>400101</code>
        <certificate>
            <technical>
                <id>100</id><!-- The ID from the preparation -->
            </technical>
            <admin>
                <id>100</id><!-- The ID from the preparation -->
            </admin> 
            <name>domain.com</name><!-- CommonName of the certificate -->
            <product>QUICKSSLPREMIUM</product><!-- The product -->
            <authentication>
                <method>DNS</method><!-- The authentication method -->
                <dns>domain.com. 300 IN TXT "201704071405295z34is5g0jjairsdu0v5opdw8512td8kixzvtaacu4ebrkry5q"</dns> <!-- The generated DNS record -->
                <provisioning>1</provisioning><!-- This value initiates the automatic zone provisioning. If the value is set to 0 or is missing, no automatic zone provisioning is started. -->
            </authentication>
            <lifetime>12</lifetime><!-- The term in months. 12 or 24 months are possible for this example -->
            <software>APACHESSL</software> <!-- APACHESSL / IIS5 -->
            <csr><![CDATA[---------BEGIN CERTIFICATE REQUEST----- .... -----END CERTIFICATE REQUEST-----]]></csr> <!-- The CSR key -->
        </certificate>
    </task>
</request>
CertificateCreate 400101 Response
<response>
  <result>
    <data>
      <certificate_job>
        <job>
          <id>123456</id><!-- The ID of the created job -->
          <status>RUNNING</status><!-- The status of the created job -->
        </job>
      </certificate_job>
    </data>
    <status>
      <code>N400101</code><!-- Describes the status of the task -->
      <text>Certificate request was successfully started. </text>
      <type>notify</type><!-- Describes the status of the task -->
      <object>
        <type>certificate</type>
        <value>domain.com</value><!-- The certificate name -->
      </object>
    </status>
  </result>
</response>

Inquire (0905) and confirm (0906) Poll Messages

By using the CertificateCreate task a job is automatically generated which takes care of the certificate order. As soon as the job is completed, a poll message is generated which needs to be inquired with the PollInfo (0905)  task. The poll message contains information about the job. If the job was successful, the ID of the ordered certificate is returned. The job then has to be confirmed with the PollConfirm (0906) task.

PollInfo 0905 Request
<request>
	<auth>
		<user>USER</user>
		<context>CONTEXT</context>
		<password>PASSWORD</password>
	</auth>
	<task>
		<code>0905</code>
	</task>
</request>
PollInfo 0905 Response
<response>
	<result>
		<data>
			<summary>1</summary>
			<message>
				<id>650664</id><!-- The ID of the Poll Message -->
				<owner>
					<user>USER</user>
					<context>CONTEXT</context>
				</owner>
				<job>
					<certificate>
						...						
						<id>1485</id><!-- The ID of the certificate -->
						...
					</certificate>
					<job_id>536396</job_id><!-- The ID of the Job -->
					<status>
						<code>S400101</code><!-- Displays if the Certificate Create task was successful or not. -->
						<type>success</type><!-- Displays if the Certificate Create task was successful or not. -->
						<object>
							<type>ssl</type>
							<value>domain.com</value><!-- The name of the certificate -->
						</object>
					</status>
				</job>
			</message>
		</data>
		<status>
			<code>S0905</code>
			<text>The notification was polled successfully.</text>
			<type>success</type>
			<object>
				<type>message</type>
				<value>650664</value>
			</object>
		</status>
	</result>
</response>

Inquire Certificate Information (400104)

The CertificateInfo (400104) task displays all the certificate details. The information can inquired by sending the ID from the previous step Inquire (0905) and Confirm (0906) Poll Messages.

CertificateInfo 400104 Request
<request>
    <auth>
        <user>USER</user>
        <context>CONTEXT</context>
        <password>PASSWORD</password>
    </auth>
    <task>
        <code>400104</code>
        <certificate>
            <id>100</id>
        </certificate>
    </task>
</request>
CertificateInfo 400104 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@domain.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@domain.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>domain.com</name><!-- The name of the certificate -->
        <lifetime>12</lifetime><!-- The term of the certificate -->
        <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><!-- The expiration date of the certificate -->
        <extension />
        <certification_authority>
          <ca_type>ICA1</ca_type>
          <ca_cert><![CDATA[----BEGIN CERTIFICATE ----- .... -----END CERTIFICATE-----]]></ca_cert>
        </certification_authority>
        <authentication>
          <method>DNS</method>
          <dns>domain.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><!-- The ID of the certificate -->
        <created>2017-01-01 00:00:00</created>
        <updated>2017-01-01 14:30:36</updated>
      </certificate>
    </data>
    <status>
      <code>S400104</code>
      <text>Certificate information was inquired successfully.</text>
      <type>success</type>
      <object>
        <type>certificate</type>
        <value>domain.com</value><!-- The name of the certificate -->
      </object>
    </status>
  </result>
</response>


Additional Information

Flowchart

Task Codes and Names

  • CertificateCreate (400101)= Orders a certificate
  • ContactCreate (400201)= Creates a new contact
  • CertificateInfo (400104)= Displays the certificate details
  • PollInfo (0905)= Inquires the details of a poll message.
  • Pollinfo (0906)= Confirms a poll message.