Search in this section

Child pages
  • Ordering S/MIME Certificates
Skip to end of metadata
Go to start of metadata

Instructions for completely automating the order process for S/MIME certificates. In our example we are using the GlobalSign - PersonalSign Class 1 product.

Table of contents

S/MIME Introduction

S/MIME certificates are intended for encryption and signing of emails. At this time InterNetX offers S/MIME products from Globalsign.

Preparation

Contact Create (400201)

To be able to order a S/MIME 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 is 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>Joe</first>
            <last>Sample</last>
            <phone>+49-941-1234560</phone>
            <email>joe.sample@testdomain.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 successfully created.</text>
            <type>success</type>
            <object>
                <type>contact</type>
                <value>100</value> <!-- The ID of the created contact -->
            </object>
        </status>
    </result>
</response>

Ordering a S/MIME Certificate

Certificate Create (400101)

The actual order for the certificate is accomplished with the CertificateCreate (400101) task. Certain attributes must be set:

  • Certificate Type: The attribute MAIL must be used for S/MIME certificates.
  • Admin: ID of the administrative contact.
  • Name: The name of the certificate.  For S/MIME an email address is used.
  • Product: Value of the Product. For our example, GLOBALSIGN_PERSONALSIGN_1 has to be used.
  • First Name: First name
  • Last Name: Last name
  • Term: Desired certificate runtime. Globalsign offers  a term of 12 or 36 months for S/MIME certificates at this time.
  • Password: Password to be used to download the S/MIME certificate from Globalsign.
  • Organisational Unit: A value such as "marketing department".
  • CSR: Value which indicates whether an own CSR is used. The XML tag <has_csr> must be set to true.


CertificateCreate 400101 Request
<request>
    <auth>
        <user>USER</user>
        <context>CONTEXT</context>
        <password>PASSWORD</password>
    </auth>
    <task>
        <certificate>
            <certificate_type>MAIL</certificate_type><!-- Certificate Type -->
            <product>GLOBALSIGN_PERSONALSIGN_1</product><!-- The product -->
            <lifetime>36</lifetime><!-- The term -->
            <name><![CDATA[joe.sample@testdomain.com]]></name><!-- The name of the certificate -->
            <approver_email><![CDATA[joe.sample@testdomain.com]]></approver_email>
            <password>****</password><!-- The password that was set and will be used for the download -->
            <firstname>Joe</firstname><!-- First name for the certificate -->
            <lastname>Sample</lastname><!-- Last name for the certificate -->
            <organization_unit_name>Development Department</organization_unit_name><!-- Organisational unit -->
            <has_csr>false</has_csr><!-- Use your own CSR yes or no -->
            <admin>
                <id>100</id><!-- The ID of the administrative contact -->
            </admin>
        </certificate>
        <code>400101</code>
    </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 started successfully.</text>
      <type>notify</type><!-- Describes the status of the task -->
      <object>
        <type>certificate</type>
        <value>joe.sample@testdomain.com</value><!-- The name of the certificate -->
      </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.

PollMessageList 0905 Request
<request>
	<auth>
		<user>USER</user>
		<context>CONTEXT</context>
		<password>PASSWORD</password>
	</auth>
	<task>
		<code>0905</code>
	</task>
</request>
PollMessageList 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 of the task Certificate Create was successful or not -->
						<type>success</type><!-- Displays of the task Certificate Create was successful or not -->
						<object>
							<type>ssl</type>
							<value>joe.sample@testdomain.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 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>150</id>
        </certificate>
    </task>
</request>
CertificateInfo 400104 Response
<response>
  <result>
    <data>
      <certificate>
        <order_id>PC201607129800</order_id><!-- The order number generated by the CA -->
        <admin>
          <first>Joe</first>
          <last>Sample</last>
          <phone>+49-0-0</phone>
          <fax>+49-0-0</fax>
          <email>joe.sample@testdomain.com</email>
          <title>Herr</title>
          <organization>InterNetX GmbH</organization>
          <address>Maximilianstrasse 6</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>100</id>
          <created>2015-11-25 10:35:41</created>
          <updated>2015-11-25 10:50:28</updated>
        </admin>
        <name>joe.sample@testdomain.com</name><!-- The name of the certificate -->
        <approver_email>joe.sample@testdomain.com</approver_email>
        <lifetime>36</lifetime><!-- Term -->
        <software>NOT_SET</software>
        <server>-----BEGIN CERTIFICATE----- ... -----END CERTIFICATE-----</server><!-- The S/MIME certificate -->
        <product>GLOBALSIGN_PERSONALSIGN_1</product>
        <sha>SHA2</sha>
        <expire>2017-12-31 23:59:59</expire><!-- Expiration date of the certificate -->
        <password>test1234</password><!-- The password that was set by the customer which is used to download the certificate from the CA -->
        <firstname>Joe</firstname><!-- First name for the certificate -->
        <lastname>Sample</lastname><!-- Last name for the certificate -->
        <organization_unit_name>Entwicklung</organization_unit_name><!-- The organisational unit of the customer -->
        <owner>
          <user>USER</user>
          <context>CONTEXT</context>
        </owner>
        <updater>
          <user>USER</user>
          <context>CONTEXT</context>
        </updater>
        <id>150</id>
        <created>CREATED</created><!-- Date on which this data was created -->
        <updated>UPDATED</updated><!-- Date on which this data was updated -->
      </certificate>
    </data>
    <status>
      <code>S400104</code>
      <text>Certificate details were successfully inquired.</text>
      <type>success</type>
      <object>
        <type>certificate</type>
        <value>joe.sample@testdomain.com</value>
      </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.
      • PollConfirm (0906)= Confirms a poll message.