Instructions for the complete automation of the ordering process for S/MIME certificates. The product GlobalSign - PersonalSign Class 1 is used here as an example. S/MIME Certificates are certificates for the encryption and signing of Email. Currently the S/MIME products are offered by Globalsign.

Panel

titleColor	#FFFFFF
titleBGColor	#E44313
title	Table of Contentscontents

Table of Contents

maxLevel	3
outline	true
style	none

Basics of the JSON and XML API

All important information for the use of the JSON and XML API you can find in the General API Basics and the XML API Basics and JSON API Basics. The specific SSL objects are documented here, the SSL tasks here.

Overview

Flowchart

Flow chart

Task

Names

names,

Codes

codes and

Routes

routes

Task	Task

Code

code	Route
CertificateCreate	400101	POST /certificate
SSLContactCreate	400201	POST /sslcontact
CertificateInfo	400104	GET /certificate/$id
PollInfo	0905	GET /poll
PollConfirm	0906	PUT /poll/$id
CertificatePrepareOrder	400110	POST /certiicate/prepareOrder

Order

Preparation

preparation

Contact

Create

create

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.

Example for

Contacte Create

contact create

SP Tabs group

disposition	horizontal

SP Tab pane

anchor	2286824
name	JSON

Code Block

language	js
title	Request
linenumbers	true
collapse	true

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

Code Block

language	js
title	Response
linenumbers	true
collapse	true

{
    "stid": "20180926-stid",
    "status": {
        "code": "S400201",
        "text": "Contact was created successfully",
        "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
        }
    ]
}

SP Tab pane

anchor	87031
name	XML

Code Block

language	xml
title	Request
linenumbers	true

<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@example.com</email>
            <title>Admin</title>
            <organization>ExampleGmbH</organization>
            <address>Example Street 36000</address>
            <postal_code>12345</postal_code>
            <city>Example City</city>
            <country>DE</country>
            <state>Bayern</state>
        </contact>
    </task>
</request>

Code Block

language	xml
title	Response
linenumbers	true

<response>
    <result>
        <data/>
        <status>
            <code>S400201</code>
            <text>Contact was successfully created.</text>
            <type>success</type>
            <object>
                <type>contact</type>
                <value>100</value>
            </object>
        </status>
    </result>
</response>

Ordering a S/MIME Certificate

Certificate

Create

create

With the CertificateCreate task you send the order to the system. You have to set certain values:

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 certificates, this is the email for which the certificate is used.
Product = Value of the S/MIME certificate, for our example this is GLOBALSIGN_PERSONALSIGN_1
First Name = First name
Last Name = Last name
Term = Desired certificate runtime. The possible runtimes depend on the certificate product.
Password = Password to be used to download the S/MIME certificate from Globalsign.
Organisational Unit = The responsible organizational unit, e.g. "marketing department".
CSR = Value which indicates whether an own CSR is used. The XML tag <has_csr> must be set to true.

Example for certificate create

SP Tabs group

disposition	horizontal

SP Tab pane

anchor	2286824
name	JSON

Route: POST /certificate

Code Block

language	js
title	Request
linenumbers	true
collapse	true

{
   "adminContact": {
      "id": 100
   },
   "technicalContact": {
      "id": 100
   },
   "name": "example.com",
   "lifetime": {
      "unit": "MONTH",
      "period": 36
   },
   "software": "APACHESSL",
   "csr": "-----BEGIN CERTIFICATE REQUEST-----MIICujCCAaICAQAwdTELMAkGA1UEBhMCREUxDzANBgNVBAgMBmJhdmFyaTETMBEGA1UEBwwKcmVnZW5zYnVyZzERMA8GA1UECgwIc3VwZXJkZXYxFDASBgNVBAsMC2RldmVsb3BtZW50MRcwFQYDVQQDDA5qdW5rZHJhZ29ucy5kZTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAMSMhi30bENDqWeXp7SfHhi2epocJeuI6bBeqGYyQCM5yuoUyAC6wuQ5xudC+hJ6dnDp8p8l8ObkcLrU8/vZJCVmfHxkQpOy6oIsz8uvNA7VcLqOQfxINxe0lqAD0SAWYUaB2W+4CVqyFxaKIn/1c2Isg+8d8Y/3l/t0lI0CF7Y4Q/EmIh1Rl2cr1ONQd4P+3mx2V0ExYN69zPRIsEHt1bV9Mo3l7QpMybHKANMK4BHVL+F5oL8vyGElLCScm3ryrl4W+C0N5V1SSGLNTfNiDxkPx9dwCc5iBy/X8FfhZ7z3+JdjluWo513wvdwZH+jbWhvQ7wsmnV0lGQoe4jHwF+UCAwEAAaAAMA0GCSqGSIb3DQEBCwUAA4IBAQCzQXKkBJWdaGtHLdI9/pqJ/zVCISGsH8lXo8tMBUyZk9cCYdH0hvsVduqNJRpBzNi07ivK/T3+Ru3SUYl0DKlsfHm5IEjf2lYJgJORXS5SRMkr7sYfYSAeGsoUIXc1GC4hBnSFmKN6NoLLbHaAItNDo9AWKVr/1ZqPy9v5vaJpTSzYidrTcZth4lF+i4QqcchorIPq4hSMKWkhZs5tzd/+hAR0XV2hcH1RGcuHTWOJmAvk0Nw2eVxUgNJSmiU0OneyRO4qQoWC/1khDFI0/xt0apn0OeYpcu8rA3aXsHCbcCqpjLUSBZ45szn60KL5sW9/S4y2oUjUbUQb3NW4TFgw-----END CERTIFICATE REQUEST-----",
   "product": "QUICKSSLPREMIUM",
   "authentication": {
      "method": "EMAIL",
      "approverEmails": [
         "admin@example.com",
         "administrator@example.com",
         "hostmaster@example.com",
         "webmaster@example.com",
         "postmaster@example.com"
      ]
   }
}

Code Block

title	Response
linenumbers	true
collapse	true

{
   "stid": "20190702-app3-dev-10171",
   "status": {
      "code": "N400101",
      "text": "Certificate order was started successfully.",
      "type": "NOTIFY"
   },
   "object": {
      "type": "Certificate",
      "value": "example.com"
   },
   "data": [
      {
         "id": 4297543967
      }
   ]
}

SP Tab pane

anchor	87031
name	XML

Code Block

language	xml
title	Request
linenumbers	true

<request>
    <auth>
        <user>USER</user>
        <context>CONTEXT</context>
        <password>PASSWORD</password>
    </auth>
    <task>
        <certificate>
            <certificate_type>MAIL</certificate_type>
            <product>GLOBALSIGN_PERSONALSIGN_1</product>
            <lifetime>36</lifetime>
            <name><![CDATA[joe.sample@example.com]]></name>
            <approver_email><![CDATA[joe.sample@example.com]]></approver_email>
            <password>****</password>
            <firstname>Joe</firstname>
            <lastname>Sample</lastname>
            <organization_unit_name>Development Department</organization_unit_name>
            <has_csr>false</has_csr>
            <admin>
                <id>100</id>
            </admin>
        </certificate>
        <code>400101</code>
    </task>
</request>

Code Block

language	xml
title	Response
linenumbers	true

<response>
  <result>
    <data>
      <certificate_job>
        <job>
          <id>123456</id>
          <status>RUNNING</status>
        </job>
      </certificate_job>
    </data>
    <status>
      <code>N400101</code>
      <text>Certificate orderwas started successfully.</text>
      <type>notify</type>
      <object>
        <type>certificate</type>
        <value>joe.sample@example.com</value>
      </object>
    </status>
  </result>
</response>

Anchor
inquire
inquire
Receiving

Notifcations

notifications

By using the CertificateCreate task a job is automatically generated which takes care of the certificate order. If the job was successful, the ID of the ordered certificate is returned. The system notification can be retrieved using the Polling and Push methods.

Inquiring

Certificate Information

certificate information

The CertificateInfo task displays all the certificate details. The information can be inquired by sending the ID from the step Receiving Notifications.

Certificate info - example

SP Tabs group

disposition	horizontal

SP Tab pane

anchor	2286824
name	JSON

Code Block

language	js
title	Request
linenumbers	true
collapse	true

GET /certificate/$id

Code Block

language	js
title	Response
linenumbers	true
collapse	true

{
    "stid": "20180926-stid",
    "status": {
        "code": "S400104",
        "text": "Certificate data were inquired successfully.",
        "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"
        }
    ]
}

SP Tab pane

anchor	87031
name	XML

Code Block

language	xml
title	Request
linenumbers	true

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

Code Block

language	xml
title	Response
linenumbers	true

<response>
  <result>
    <data>
      <certificate>
        <order_id>PC201607129800</order_id>
        <admin>
          <first>Joe</first>
          <last>doe</last>
          <phone>+49-0-0</phone>
          <fax>+49-0-0</fax>
          <email>joe.doe@example.com</email>
          <title>Herr</title>
          <organization>example company</organization>
          <address>example street 6</address>
          <postal_code>93047</postal_code>
          <city>example city</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.doe@example.com</name>
        <approver_email>joe.doe@example.com</approver_email>
        <lifetime>36</lifetime>
        <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>
        <password>test1234</password><!-- The password that was set by the customer which is used to download the certificate from the CA -->
        <firstname>Joe</firstname>
        <lastname>doe</lastname>
        <organization_unit_name>marketing</organization_unit_name>
        <owner>
          <user>USER</user>
          <context>CONTEXT</context>
        </owner>
        <updater>
          <user>USER</user>
          <context>CONTEXT</context>
        </updater>
        <id>150</id>
        <created>CREATED</created>
        <updated>UPDATED</updated><
      </certificate>
    </data>
    <status>
      <code>S400104</code>
      <text>Certificate data were inquired successfully.</text>
      <type>success</type>
      <object>
        <type>certificate</type>
        <value>joe.sample@example.com</value>
      </object>
    </status>
  </result>
</response>

Versions Compared

Old Version 67

New Version Current

Key

Basics of the JSON and XML API

Overview

Flow chart

Task

names,

codes and

routes

Order

preparation

Contact

create

Example for

contact create

Certificate

create

Example for certificate create

Anchor
inquire
inquire
Receiving

notifications

Inquiring

certificate information

Certificate info - example

Page History

Versions Compared

Old Version 67

New Version Current

Key

Basics of the JSON and XML API

Overview

Flow chart

Task

names,

codes and

routes

Order

preparation

Contact

create

Example for

contact create

Certificate

create

Example for certificate create

AnchorinquireinquireReceiving

notifications

Inquiring

certificate information

Certificate info - example

Anchor
inquire
inquire
Receiving