GeoCerts Reseller REST API

(1)

GeoCerts Reseller REST API

Product Description and Interface Definitions

Revision 1.0

(2)

Section 1: Table of Contents

Section 1:

Table of Contents ... i

Section 2:

Overview... 1

2.1 Release Notes ...1

2.2 Previous Release Notes...1

2.3 Deprecated Commands ...1

Section 3:

Using the API ... 2

3.1 SSL Server Certificate Product Orders...2

3.1.1 Web-based Domain Vetted Ordering Scenario...3

3.1.2 Web-based Organization Vetted Product Ordering Scenario ...3

3.1.3 Web-based Domain and Organization Vetted Product Ordering Scenario ...4

3.1.4 API-based Ordering Scenario ...4

3.2 Testing Information ...5

3.2.1 Register for a sandbox test account...5

3.2.2 Test Root certificates ...6

Section 4:

API Endpoints ... 8

4.1 Hello...8

4.1.1 POST – create - /1/hello...8

4.2 Agreements...9

4.2.1 GET - index - /1/products/SKU/agreement ...9

4.3 Orders...9

4.3.1 Get – index – /1/orders...10

4.3.2 Get – show - /1/orders/ORDER_ID ...11

4.3.3 POST - resend - /1/orders/ORDER_ID/resend ...12

4.3.4 PUT - email - /1/orders/ORDER_ID/email...12

4.3.5 PUT - modify - /1/orders/ORDER_ID/modify...13

4.3.6 GET - approvers - /1/orders/approvers ...13

4.3.7 POST - validate - /1/orders/validate ...14

4.3.8 POST - create - /1/orders...16

4.4 Certificates ...18

4.4.1 GET - index - /1/certificates...19

4.4.2 GET - show - /1/orders/ORDER_ID/certificate...19

4.4.3 POST - reissue - /1/orders/ORDER_ID/certificate/reissue...20

4.5 Events...21

4.5.1 GET - index - /1/events ...21

4.5.2 GET - show - /1/orders/ORDER_ID/events...22

Section 5:

Other API Information ... 23

5.1 Errors and Warnings ...23

5.2 Error Codes...23

5.3 Warning Codes ...27

(3)

5.5 Additional Description of fields ...32

5.5.1 Approver Email <approver-email> ...32

5.5.2 Midterm Upgrade ...33

5.5.3 Country ...33

5.5.4 Certificate Signing Request (CSR)...36

5.5.5 DNS Names ...36

5.5.6 Modify Order Operation...36

5.5.7 Order State ...37

5.5.8 Price Computation...38

5.5.9 Products...39

5.5.10 Renewal Email Behavior...39

5.5.11 Certificate Validity Period <years> ...39

Appendix A -

Glossary ... 41

Appendix B -

Additional Resources... 43

A.1. Ruby GEM... 43

B.1. cURL ...43

(4)

Section 2: Overview

We offer a REST API for our Partners to directly order and manage their certificate and web site identity offerings. API clients can perform functions such as ordering the different products, canceling and fulfilling orders, and querying for order data. This API document contains all of the data necessary to integrate with the entire suite of GeoCerts’ certificate and web site identity products.

2.1 Release Notes

Our REST API is officially released! Any and all feedback is welcome. Please feel free to email us at sslsupport@geocerts.com or call 800-892-7075 if you have questions or need assistance with integration.

2.2 Previous Release Notes

None

2.3 Deprecated Commands

None

(5)

Section 3: Using the API

Different API commands are used for initiating or placing an order for server products. The following sections detail the command and process flows for each product category.

3.1 SSL Server Certificate Product Orders

Using the API offers additional workflow flexibility beyond the basic UI-based ordering flow. Utilized in conjunction with selectively enabling or disabling different automated email communications to a customer, a Partner can perform varying levels of the ordering workflow. This allows the integration with our API to be tailored to best suit the needs of the Partner’s overall provisioning process.

Ordering state changes for SSL certificates and server web identity products are asynchronous - an API client initiates an order and then later checks the server for the completed order after the vetting process has been completed.

The general approach for an API client is to (1) place orders, then (2) periodically query the API server for all orders that have changed status during a specified time interval (for example, the last four hours) using the Events operation (see Figure 1). This returns a list of all orders events for those orders that have changed status in the specified time interval. The status of all returned orders can then be updated locally and used as necessary.

An alternative to the general approach is to specifically request the status of a specific order. In this case (Figure 2), the ordering flow consists of the following operations:

(1) place an order, and then (2) periodically check the status of the specific order (Events Show). Once the order has been completed, the certificate fulfillment information is returned with the Certificate Show operation. This approach is generally less efficient, but might be more appropriate when there is a low volume of certificates being managed.

How an order is processed by GeoTrust is dictated by the vetting process employed for a given product. GeoTrust employs a suite of advanced techniques to vet orders to ensure the authenticity of the requestor. This axiom applies to the API as well. While the

same API commands are used to initiate orders for all server products, specific field usages for a given 1 2 Illustration Legend: API Message Non-API Message GeoCerts GeoCerts Partner 2 Figure 1 1 1

GeoCerts GeoCerts _Partner

Figure 2 1 1

(6)

command are also dictated by the vetting requirements of the specified product. To best understand how the API is used to initiate an order, the following subsections provide an overview of the basic process flows for Domain Vetting, Organization Vetting and Domain and Organization Vetting, and how the API is used in conjunction with these vetting approaches.

3.1.1 Web-based Domain Vetted Ordering Scenario

GeoTrust patented Domain Vetting process ensures that a registered contact for a domain approves a request for a server product for that domain. QuickSSL, QuickSSL Premium, and the GeoTrust Free Trial SSL are products that are Domain Vetted. The Web based ordering process for requesting, approving and issuing certificates is described below:

1. Requestor supplies the CSR, and order contact information. Requestor then chooses an Approver email, accepts the subscriber agreement and submits the order.

2. An acknowledgement email is sent to the requestor and other order contacts confirming placement of the order. 3. An email is sent to the Approver requesting that the

Approver review the submitted order.

4. The Approver follows the link in the email, reviews the order information and either approves or rejects the order.

5. If the order is approved, the requestor receives the certificate via email.

3.1.2 Web-based Organization Vetted Product Ordering Scenario

With Organization Vetting only, validation of the Organizational data submitted with the order is also performed before completing a product order. GeoTrust’s True BusinessID (EV and Wildcard) certificates are Organization Vetted products where the organization and domain authentication are done manually using

GeoTrust/VeriSign’s authentication practices.

1. Requestor supplies the CSR, organization information, and the order contact information. Requestor then accepts the subscriber agreement and submits the order. 2. An acknowledgement email is sent to the requestor and

other order contacts confirming placement of the order. 3. Customer sends corporate documents and other

information necessary to verify the organization to the GeoTrust, thawte or Verisign authentication team. This may be an iterative process with GeoTrust and/or Verisign sending out requests for additional information. 4. Once all the authentication steps have been successfully

completed, the certificate is issued.

GeoCerts Requestor Approver 1 2 5 3 4 GeoCerts Requestor 1 2 3 4 5

(7)

3.1.3 Web-based Domain and Organization Vetted Product Ordering Scenario

With Domain and Organization Vetting, extensive validation of the requestor’s Organizational information is also performed before completing a product order. True BusinessID with Extended Validation is a Domain and Organization Vetted product.

1. Requestor supplies the CSR, organization information, and the order contact information. Requestor then chooses an Approver email, accepts the subscriber agreement and submits the order.

2. An acknowledgement email is sent to the requestor and other order contacts confirming placement of the order. 3. Customer sends corporate documents and other information

necessary to verify the organization. This may be an iterative process with GeoTrust sending out requests for additional information.

4. An email is sent to the Approver requesting that the Approver review the submitted order.

5. The Approver follows the link in the email, reviews the order information and either approves or rejects the order. 6. Upon completion of the vetting and approval process, the

admin contact receive the certificate via email. 3.1.4 API-based Ordering Scenario

If a Partner collects all of the information necessary to place an

order, the order can be placed on behalf of the end customer. In this approach, there are two main steps: collecting the data needed to place the order, and the actual processing of the order.

3.1.4.1 Collecting and Validating Order Data

The collection and validation of all fields needed to place an order can be non-trivial. A good way to collect and validate this information is as follows:

1. The Order Validate operation can be used to validate the CSR and other information, like renewal benefits. In addition, the CSR is parsed and the domain name (Common Name) and other CSR data is returned.

2. Using the returned Domain Name, for domain vetted and True BusinessID with EV orders Order Approvers command is used to retrieve the list of valid approver email addresses.

3.1.4.2 Processing the Order

Once the order information is ready for processing:

1. GeoTrust Partner uses the Order Create command to submit all order information including organization info, contact info, the CSR and the approver email (for applicable products only). When the approver email address is required it must be one that that is authorized to approve the order.

GeoCerts Requestor Approver 1 2 3 4 5 6

GeoCerts GeoCerts _Partner

1 2 GeoCerts _Requestor 2 3 6 1 Partner 7

(8)

2. The remainder of the ordering process is like the UI-based ordering scenarios. An acknowledgement email is sent to the requestor and other order contacts confirming placement of the order.

3. For products that require Organization Vetting, a GeoTrust or Verisign representative may contact the Administrative Contact to obtain appropriate corporate documents and other information necessary to verify the organization.

4. An email is sent to the Approver requesting that the approver review the submitted order (for domain vetted and True BusinessID with EV products only).

5. The Approver follows the link in the email, reviews the order information and either approves or rejects the order (for domain vetted and True BusinessID with EV products only).

6. Upon completion of the vetting and approval process, the certificate is issued via email.

7. The Partner receives the updated order status and information by performing the Events, Orders and Certificates operations.

Note, the automated sending of the acknowledgement and fulfillment emails can be disabled, if it’s preferable for a Partner to send this information to the requestor from their systems. The approver email sent by GeoTrust is a required part of the domain control validation process and cannot be disabled.

3.2 Testing Information

This section contains important information about how to establish a sandbox account and perform testing. 3.2.1 Register for a sandbox test account

If you do not already have a GeoCerts Reseller sandbox account set up, you should do so to aid in your API client development. To register on our test system, use the following process:

Go to this URL and register for a Reseller sandbox portal account: https://sandbox.geocerts.com/resellers/signup

Enter all of the applicable Business and contact information and accept the Reseller Agreement.

Login to the reseller sandbox test portal with your login and password. Next obtain your Partner ID and API Token. Click the Account Settings tab and then the API Access sub-tab. Click on the Show link to reveal your API access token. This token can be regenerated by the user at this same page, in case you need to revoke access to existing applications or fear a loss of token secrecy. You will need both your Partner ID and API Token to authenticate using the API. Remember that if you regenerate this token you will no longer be able to access the API with your previous token.

(9)

3.2.2 Test Root certificates 3.2.2.1 GeoTrust Pre-Production CA 1 ---BEGIN CERTIFICATE--- MIICbzCCAdigAwIBAgIBATANBgkqhkiG9w0BAQUFADBLMQswCQYDVQQGEwJVUzEV MBMGA1UEChMMR2VvVHJ1c3QgSW5jMSUwIwYDVQQDExxHZW9UcnVzdCBQcmUtUHJv ZHVjdGlvbiBDQSAxMB4XDTA0MDgyNjA0MDAwMFoXDTI0MDgyNjA0MDAwMFowSzEL MAkGA1UEBhMCVVMxFTATBgNVBAoTDEdlb1RydXN0IEluYzElMCMGA1UEAxMcR2Vv VHJ1c3QgUHJlLVByb2R1Y3Rpb24gQ0EgMTCBnzANBgkqhkiG9w0BAQEFAAOBjQAw gYkCgYEA15z6NnGdvC1CPDbAA4ytyBPQhm15rDWwPIGXyDWGUo6fqv2BLTDP/Q8t WBgAPFO5FYqiA5bKh+lttcPqsD38on5bKUZT/eYwlf9LGwvFHM8h6Sr0eySyTbJ0 Jmo0CfzTDBpZo3V4Q0XclZSzt+0ycCEQEv1ou07JeEQb10amOJkCAwEAAaNjMGEw DwYDVR0TAQH/BAUwAwEB/zAdBgNVHQ4EFgQUSu1cZmsN8sJTHAsEc92rVZadv4cw HwYDVR0jBBgwFoAUSu1cZmsN8sJTHAsEc92rVZadv4cwDgYDVR0PAQH/BAQDAgGG MA0GCSqGSIb3DQEBBQUAA4GBAHfFX7h7NNqwLQ5tQMQv7VVWSqQ12X49wuF5wy/C HcWmyqkCN9ZtEGpvB0X/+x9QJsK1Zkgo7dDYbAExgrHlmhlFPYUvypabLkPaLqwK 9B74SUH2rXMT+pkvZqUPSSjDpJmMF/rzAMH1K0sOFT3mIF4zBVYAsVwpRlUDZLJV eDH0 ---END CERTIFICATE--- 3.2.2.2 GeoTrust Pre-Production CA 2

This is the root certificate used on the test system “GeoTrust Pre-Production CA 2”: ---BEGIN CERTIFICATE--- MIICbzCCAdigAwIBAgIBATANBgkqhkiG9w0BAQQFADBLMQswCQYDVQQGEwJVUzEV MBMGA1UEChMMR2VvVHJ1c3QgSW5jMSUwIwYDVQQDExxHZW9UcnVzdCBQcmUtUHJv ZHVjdGlvbiBDQSAyMB4XDTA0MDkwMTA0MDAwMFoXDTI0MDkwMTA0MDAwMFowSzEL MAkGA1UEBhMCVVMxFTATBgNVBAoTDEdlb1RydXN0IEluYzElMCMGA1UEAxMcR2Vv VHJ1c3QgUHJlLVByb2R1Y3Rpb24gQ0EgMjCBnzANBgkqhkiG9w0BAQEFAAOBjQAw gYkCgYEAwm65FeMCb7YqLO+zNcNT9KtpL7TweeGKhQUrEclKvrICQ4JsEgsIf+PI /a3Js0at4Q31ZTecBo8muGJPBQs1nG2LG/5CdcDUTeuzKd6C8H9iri4aaURv7OS9 2t0VUmXlqZb8+i+l741lnYsZTtyX5b69IkHMZeShp2Cf3SwZWXsCAwEAAaNjMGEw DwYDVR0TAQH/BAUwAwEB/zAdBgNVHQ4EFgQUccNqlHo5RuaBuZm/HDRbdZr/K/8w HwYDVR0jBBgwFoAUccNqlHo5RuaBuZm/HDRbdZr/K/8wDgYDVR0PAQH/BAQDAgGG MA0GCSqGSIb3DQEBBAUAA4GBAJ3/rTJchy1DdH3YA9Ipc0R+yet8SbPiqnudxOjo

(10)

/0fnE34/rr7oUC4JAqF4mEw/95kID001yb5oTxiV7fLnZE+lG9u2LoLO2XCwzBx9 w9cOGG58xQkx2ddUV77Csru8wudYRcMIyksWzwGGy3xIZfYirA6FAoeXIuYdgM73 HFUV ---END CERTIFICATE--- 3.2.2.3 GeoTrust Pre-Production CA 3 ---BEGIN CERTIFICATE--- MIIDdDCCAlygAwIBAgIBATANBgkqhkiG9w0BAQUFADBLMQswCQYDVQQGEwJVUzEV MBMGA1UEChMMR2VvVHJ1c3QgSW5jMSUwIwYDVQQDExxHZW9UcnVzdCBQcmUtUHJv ZHVjdGlvbiBDQSAzMB4XDTA0MDkwMTA0MDAwMFoXDTI0MDkwMTA0MDAwMFowSzEL MAkGA1UEBhMCVVMxFTATBgNVBAoTDEdlb1RydXN0IEluYzElMCMGA1UEAxMcR2Vv VHJ1c3QgUHJlLVByb2R1Y3Rpb24gQ0EgMzCCASIwDQYJKoZIhvcNAQEBBQADggEP ADCCAQoCggEBANEURLniUuckqNfBdQla163FMAwThOy4/x5tqDj13/iYcDLm5LA8 JRKpqxwpXsh6ZxAIkM998l3R6re9zC9poTJgo9hNGSLETjVlmvshZ+zXwVX0l8K4 6MhN66brb+O3K51E4p3NTHMekAy4qIRuptDj1YDiBjthZiafP/AVmUAU0ic/HXcP RNYWZ/0V8ceDRPsKfYmnqFXJB+aDixYAtLcbOdcSH2tFBnhFf99HqTD+y+kTHDJI NEmA8DdkrsabsOJLmCpsQZYC2MtLlIhF8mPaukBZ7ZhLJBUFH6WyYCj0sX2rTb+G MrqGFgoy32EH/kH3XQzCX2recdBAH1m75kkCAwEAAaNjMGEwDwYDVR0TAQH/BAUw AwEB/zAdBgNVHQ4EFgQUTj+LgYCHiLOc5ElUroYqSMSpOyowHwYDVR0jBBgwFoAU Tj+LgYCHiLOc5ElUroYqSMSpOyowDgYDVR0PAQH/BAQDAgGGMA0GCSqGSIb3DQEB BQUAA4IBAQBq9aYMZEiR/+bzPNg9T/qXF6RcyWxQWczGD1D6XpLjTmL+IB37Sfno qxrYsLvYLkMXYmha7r8L7DTurLW2fRH/6meJWl0AIQozNNgYSC253hzyx85j3eES RG39rbO4x4NULvDjvCij6BhAxR6LmirNGRXf+Wa7KtW0drvnTbJHOecUL2PTMieI Gv4Z7FjdfhRKsvmO8uxLbxjTqBzrcl3nfvtqORf695uPHRLazLrYCUXGGTuNZNRn efQpt98aRDJEszq1cmCIUhisXcSloaF5cfWYebXjUYZa70uvXZSVXafn46ukVdVS HGE0FZMTWLM6BT5Qpa3+M5FfPPeSqtzD ---END CERTIFICATE--- 3.2.2.4 GeoTrust Pre-Production Sub CA 1

This certificate is issued under the GeoTrust Pre-production CA 2 and is used when a chained hierarchy is needed in the test environment.

---BEGIN CERTIFICATE--- MIICuTCCAiKgAwIBAgIBBDANBgkqhkiG9w0BAQQFADBLMQswCQYDVQQGEwJVUzEV MBMGA1UEChMMR2VvVHJ1c3QgSW5jMSUwIwYDVQQDExxHZW9UcnVzdCBQcmUtUHJv ZHVjdGlvbiBDQSAyMB4XDTA0MDkwMTE4MjQzOVoXDTI0MDIyODE4MjQzOVowTzEL MAkGA1UEBhMCVVMxFTATBgNVBAoTDEdlb1RydXN0IEluYzEpMCcGA1UEAxMgR2Vv VHJ1c3QgUHJlLVByb2R1Y3Rpb24gU1VCIENBIDEwgZ8wDQYJKoZIhvcNAQEBBQAD gY0AMIGJAoGBAN0lERi90nbl3mioTh6MqgVFifSY9QdEWsCBOkniGAQvAQAV0uQh 2FqcACsYsMsVKYsYanrl5WgBNz0NJyzWo8YPe8GIRQwpzdBkfIxhEPCPMQqiP5RC t1f14BA+Pnw8BRnjPxnETcB1cpopZkIDGCs8xCtCg7UTqcYXslX1/9f5AgMBAAGj gagwgaUwHwYDVR0jBBgwFoAUccNqlHo5RuaBuZm/HDRbdZr/K/8wHQYDVR0OBBYE FBlSafmWwAqkGoucFS8Wk7ZGzwWAMA8GA1UdEwEB/wQFMAMBAf8wDgYDVR0PAQH/ BAQDAgEGMEIGA1UdHwQ7MDkwN6A1oDOGMSBodHRwOi8vdGVzdC1jcmwuZ2VvdHJ1 c3QuY29tL2NybHMvcHJlcHJvZGNhMi5jcmwwDQYJKoZIhvcNAQEEBQADgYEAJS03 4J+Su0pmsvQwqR6vW17D9psDzg8m9R5vYJpl0hz1aaVttriyg3CSQ48Yf/l5/fqO PFNUEzX+S1t4IUuIkzFK3R+vAz9BzejhAhkggBTRZqKrCIf11e1bC6I42G1G1L3N nweixRi6P+ZrR7r6QCrVe7NHpYNzce/se2BjJPw= ---END CERTIFICATE---

(11)

Section 4: API Endpoints

Sandbox Test URL: https://sandbox.geocerts.com Production URL: https://www.geocerts.com

The following XML notation conventions are used in this document:

( ) must be followed by *, ? or + to denote cardinality ? 0 or 1

* 0 or more + 1 or more

NOTE: fields marked with a ‘()?’ are optional for that command.

4.1 Hello

This resource provides only one action, create, which is only accessible via HTTP POST.

Actions

Action Method Endpoint create POST /1/hello

4.1.1 POST – create - /1/hello

The hello create action is one of the most straightforward actions available. This action should be used for initial API testing. The purpose of the action is to simply validate user credentials (partner id + api token), take the posted data, and then return it back. Any value entered into the Input field will be echoed out into the hello result field.

Input

<?xml version ='1.0' encoding 'UTF-8'?> <hello>

Any valid XML content I want. </hello>

Response

<?xml version ='1.0' encoding 'UTF-8'?> <hello>

Any valid XML content I want. </hello>

(12)

$ curl –H "Content-type: application/xml" -d "<hello>Hi there</hello>" https://PARTNER-ID:TOKEN@sandbox.geocerts.com/1/hello

4.2 Agreements

The Agreements resource allows the Partner to request the appropriate User Agreement for a particular SSL product.

Actions

The Agreements resource provides only one available action, index. It is primarily used to allow Partners to download the appropriate GeoTrust order agreement based on their desired product SKU.

Action Method Endpoint

index GET /1/products/SKU/agreement

4.2.1 GET - index - /1/products/SKU/agreement Response

<?xml version='1.0' encoding='UTF-8' ?> <agreement>

GeoTrust(R) SSL Certificate Subscriber Agreement... </agreement>

cURL Example

$ curl https://PARTNER-ID:TOKEN@sandbox.geocerts.com/1/products/QP/agreement

4.3 Orders

The Orders resource provides access to the creation and modification of orders within the system. It allows a Partner to request a list of valid approver emails, change and re-send approval emails and includes actions to cancel, approve, and validate orders.

Actions

Action Method Endpoint

index GET /1/orders

(13)

validate POST /1/orders/validate approvers GET /1/orders/approvers show GET /1/orders/ORDER_ID resend POST /1/orders/ORDER_ID/resend email PUT /1/orders/ORDER_ID/email modify PUT /1/orders/ORDER_ID/modify

4.3.1 Get – index – /1/orders

This returns a collection of order data for the Partner. Request

By default, this request will return all of your orders for the past 30 days. If you'd like to adjust the search window, you may pass optional query parameters (start_at and end_at) on your request.

/1/orders /1/orders?start_at=2009-04-27T19:07:51-04:00&end_at=2009-04-27T19:37:51-04:00 Response <?xml version='1.0' encoding='UTF-8'?> <orders>

<id type="integer">12345</id> <domain>www.example.com</domain>

<geotrust-order-id>765432</geotrust-order-id> <status-major>Pending</status-major>

<status-minor>Order Waiting For Approval</status-minor> <years type="integer">1</years> <licenses type="integer">1</licenses> <created-at type="datetime">...</created-at> <completed-at type="datetime">...</completed-at> <renewal type="boolean">false</renewal> <trial type="boolean">false</trial> <sans>...</sans> <state>WF_DOMAIN_APPROVAL</state> <total-price type="float">0.00</total-price> <flagged type="boolean">false</pending-audit> <product> <sku>QP</sku> </product> </order> <order>...</order> </orders> cURL Example

(14)

$ curl https://PARTNER-ID:TOKEN@sandbox.geocerts.com/1/orders

4.3.2 Get – show - /1/orders/ORDER_ID Returns information about a specific order. Valid Response

A successful response will return HTTP 200 with the following content: <?xml version='1.0' encoding='UTF-8'?> <order> <id type="integer">12345</id> <domain>www.example.com</domain> <geotrust-order-id>765432</geotrust-order-id> <status-major>...</status-major> <status-minor>...</status-minor> <years type="integer">1</years> <licenses type="integer">1</licenses> <created-at type="datetime">...</created-at> <completed-at type="datetime">...</completed-at> <renewal type="boolean">false</renewal> <trial type="boolean">false</trial> <sans>...</sans> <state>...</state> <total-price type="float">0.00</total-price> <flagged type="boolean">false</pending-audit> <product> <sku>QP</sku> </product> </order> Invalid Response

An invalid response will return a HTTP 4XX (400, 404, 422, etc.) code with the following error response format: <?xml version='1.0' encoding='UTF-8'?>

(15)

-1234 <message>Error occurred</message> </error> <error>...</error> <warning> 3456 <message>This is a warning</message> </warning> <warning>...</warning> </errors> cURL Example $ curl https://PARTNER-ID:TOKEN@sandbox.geocerts.com/1/orders/ORDER_ID

4.3.3 POST - resend - /1/orders/ORDER_ID/resend

Instructs GeoTrust to re-send the approval verification email required to complete the order process. This should be used when the original email was not received or mistakenly deleted prior to approval.

Response

See the show response for reference. cURL Example

$ curl -X POST

“https://PARTNER-ID:TOKEN@sandbox.geocerts.com/1/orders/ORDER_ID/resend"

4.3.4 PUT - email - /1/orders/ORDER_ID/email

Instructs GeoTrust to update the approver email associated with the order with the new email address given. The new email address must be one of the pre-approved emails returned from the GET approvers request. Request <?xml version='1.0' encoding='UTF-8'?> <order> <approver-email>ssladmin@example.com</approver-email> </order> Response

(16)

$ curl -X PUT -H "Content-type: application/xml" -d "<order><approver-email>ssladmin@example.com</approver-email></order>" “https://PARTNER-ID:TOKEN@sandbox.geocerts.com/1/orders/ORDER_ID/email"

4.3.5 PUT - modify - /1/orders/ORDER_ID/modify

Modifies the requested order's status. Available operations are: CANCEL and APPROVE. The operative actions that are enabled for the modify command are dependent upon the API server environment.

In the test environment, any order may be approved or cancelled via the modify command. This can be a useful feature to facilitate automated testing. The APPROVE operation can only be used in the test environment and simulates the Domain Control or Organization vetting approval process. In the production environment, only the CANCEL operation may be used.

The modify CANCEL operation can only be used with the API if the certificate order is still in an in-processing state. That is the certificate has not been issued. To cancel a certificate after a certificate has been issued and is still within the certificate cancellation and refund period, you must login to your reseller SSL Manager portal to initiate a cancellation request (this may change in the near future as GeoTrust has plans to allow cancellations via the API in a future release).

Review GeoTrust’s cancellation and refund policy at http://www.geotrust.com/support/refund-policy.html Request <?xml version='1.0' encoding='UTF-8'?> <order> <state>CANCEL</state> </order> Response

$ curl -X PUT -H "Content-type: application/xml" -d "<order><state>CANCEL</state></order>" "http://PARTNER-ID:TOKEN@sandbox.geocerts.com/1/orders/ORDER_ID/modify"

4.3.6 GET - approvers - /1/orders/approvers

Returns a complete collection of valid approver e-mail addresses for a specified domain. Request

(17)

Response <?xml version='1.0' encoding='UTF-8'?> <emails> <email>user@whois.com</email> <email>admin@example.com</email> <email>administrator@example.com</email> <email>hostmaster@example.com</email> <email>root@example.com</email> <email>ssladmin@example.com</email> <email>sysadmin@example.com</email> <email>webmaster@example.com</email> <email>info@example.com</email> <email>is@example.com</email> <email>it@example.com</email> <email>mis@example.com</email> <email>ssladministrator@example.com</email> <email>sslwebmaster@example.com</email> <email>postmaster@example.com</email> </emails> cURL Example $ curl “https://PARTNER-ID:TOKEN@sandbox.geocerts.com/1/orders/approvers?domain=example.com"

4.3.7 POST - validate - /1/orders/validate

Allows Partners to validate a number of order fields in one API message. This allows the Partner to perform validation prior to submission of the order to provide a better UI experience to the user. If any of the fields are invalid, then a collection of errors and/or warnings will be returned with an unprocessable entity (HTTP 422) response . If there are no errors, a success (HTTP 200) response is returned along with parsed CSR info, pricing, and renewal info (if any).

Optionally, validate can also be used to parse a CSR and to test its validity. Request

<?xml version='1.0' encoding='UTF-8'?> <order>

---BEGIN CERTIFICATE REQUEST--- abCdE....

---END CERTIFICATE REQUEST--- </body>

</csr> <product>

(18)

</order> Optional Parameters

x years: Number of years the CSR request is covering (defaults to 1)

x licenses: Number of licenses (1 per server) you are requesting (defaults to 1)

x dns-names: A comma separated list of DNS names used in a multi-domain CSR request (e.g., "www.example.com,www1.example.com,www3.example.net"). Note: The product requested must support multi-domain requests.

Valid Response

Note: This does not attempt to create the order with GeoTrust and you therefore may get a valid order validate response which is later DECLINED when created.

<?xml version='1.0' encoding='UTF-8'?> <order> <success-code>0</success-code> <total-price>129</total-price> <csr> <common-name>www.example.com</common-name> <city>Atlanta</city> <state>Georgia</state> <country>US</country> <organization>GeoCerts</organization> <org-unit>Internet</org-unit> </csr> <renewal-info> <indicator>true</indicator> <months>3</months> <serial-number>abC12dE...</serial-number> <geotrust-order-id>1234533</geotrust-order-id> <expiration-date type="datetime">2009-01-20</expiration-date> </renewal-info> <errors/> <warnings/> </order>

Note that <renewal-info><geotrust-order-id>1234533</order-id></renewal-info> is the old GeoTrust order ID that this CSR will be renewing.

Invalid Response

Returned as the standard error response (HTTP 422) with details. See show for reference. cURL Example

(19)

$ curl –H "Content-type: application/xml" -X POST -d "<order>approver-email>admin@example.com</approver-email>

<csr><body>...CSR_REQUEST_BODY...</body></csr><product><sku>Q</sku></product> </order>" “https://PARTNER-ID:TOKEN@sandbox.geocerts.com/1/orders/validate"

4.3.8 POST - create - /1/orders

Creates a new order with the given options.

More information about each order type and optional parameters are detailed below. Request <?xml version='1.0' encoding='UTF-8'?> <order> <approver-email>admin@example.com</approver-email> <csr> <body>

---BEGIN CERTIFICATE REQUEST---

MIIBnDCCAQUCAQAwXDELMAkGA1UEBhMCVVMxEDAOBgNVBAgTB0Zsb3JpZGExEDAO BgNVBAcTB09ybGFuZG8xEzARBgNVBAoTClJhaWxzIEVudnkxFDASBgNVBAMTC3d3 ...

---END CERTIFICATE REQUEST--- </body> </csr> <product> <sku>QP</sku> </product> </order> Response

See show for reference. Optional Order Parameters

Order Administrator

Every SSL certificate has an Administrative contact. Ordinarily the admin contact will be your customer but it can be you (the reseller). The admin contact is the person who is applying for and will "own" the certificate. The admin contact receives all emails for the certificate including order confirmation, fulfillment, and renewal notices (unless these options are disabled in your reseller web interface). The information you provide here is NOT viewable by the general public and is not part of the issued SSL certificate. GeoTrust/VeriSign staff may contact the admin contact submitted here by email and/or phone to aid in vetting and completing SSL orders.

By default, the reseller will become the certificate administrator. If you do not wish for this to occur, you may provide administrator details:

(20)

... <admin> <first-name>Jane</first-name> <last-name>Smith</last-name> <phone>9876543210</phone> <email>admin@example.com</email> </admin> </order> Multiple Years

You may extend the years purchased by sending an explicit YEARS value. Otherwise, it defaults to 1 year.

Note: Trial orders are restricted to 30 days availability, regardless of the number of years requested. <order> ... <years>3</years> </order> Multiple Domains

You may define multiple domains for a certificate by providing a dns-names entry. The product being purchased must support multiple domains and you must provide them as comma-separated values.

<order> ...

<dns-names>www.example.com,www2.example.com</dns-names> </order>

Multiple Licenses

You may purchase multiple licenses that will allow you to install this certificate on more than one physical machine. Each additional license costs the same as the first. If <license> is not included In your request it defaults to 1 license.

<order> ...

Organization Info

Required for all True BusinessID organization-vetted orders (Wildcard and Extended Validation). <order>

(21)

...

<organization-name>Example Inc.</organization-name> <address>123 Test Drive</address>

<address-2>Suite 25</address-2> <address-3>Suite 25</address-3> <city>Atlanta</city> <state>GA</state> <postal-code>12345</postal-code> <phone>1234567890</phone> </organization> </order>

Extended Validation (EV) Approver

The EV Approver is required for all True BusinessID Extended Validation (EV) orders. The EV Approver is a person who has the authority on behalf of the applicant to approve EV Certificate requests. This person must be employed by or be an authorized agent who has express authority to represent the Organization listed in the certificate request. GeoTrust/VeriSign staff will contact the EV Approver submitted here by email and/or phone to aid in vetting and completing SSL orders.

<order> ... <ev-approver> <first-name>John</first-name> <last-name>Smith</last-name> <title>President</title> <phone>800-555-1212</phone> <email>john@example.com</email> </ev-approver> </order> cURL Example

$ curl –H "Content-type: application/xml" -X POST -d "<order><approver-

email>admin@example.com</approver-email><csr><body>...CSR_REQUEST_BODY...</body></csr><product><sku>Q</sku></pr oduct></order>" “https://PARTNER-ID:TOKEN@sandbox.geocerts.com/1/orders"

4.4 Certificates

The Certificates resource gives access to reading and reissuing previously ordered certificates.

Actions

Action Method Endpoint index GET /1/certificates

(22)

show GET /1/orders/ORDER_ID/certificate reissue POST /1/orders/ORDER_ID/certificate/reissue

4.4.1 GET - index - /1/certificates

Returns a data collection of the Partners certificates. Request

By default this will return those certificates which had an initial validation date (start date) within the past 30 days. You can adjust this search window by passing optional query parameters (start_at and end_at).

/1/certificates

/1/certificates?start_at=2009-04-27T19:07:51-04:00&end_at=2009-04-27T19:37:51-04:00

Response

<?xml version='1.0' encoding='UTF-8'?>

<certificates start_at="2009-04-27T19:07:51-04:00" end_at="2009-04-27T19:37:51-04:00"> <certificate> <order-id type="integer">12345</order-id> <geotrust-order-id>ab1234</geotrust-order-id> <status>Active</status> <certificate>---BEGIN CERTIFICATE---\r\n...</certificate> <ca-root>...</ca-root> <common-name>www.example.com</common-name> <serial-number>...</serial-number> <start-date type="datetime">2009-04-27T19:07:51-04:00</start-date> <end-date type="datetime">2009-04-27T19:07:51-04:00</end-date> <locality>Atlanta</locality> <state>GA</state> <organization>Example</organization> <organizational-unit>Example Unit</organizational-unit> <country>US</country> <approver-email>example@example.com</approver-email> <trial type="boolean">false</trial> <url>http://api.geocerts.com/1/order/12345/certificate</url> </certificate> </certificates> cURL Example $ curl https://PARTNER-ID:TOKEN@sandbox.geocerts.com/1/certificates 4.4.2 GET - show - /1/orders/ORDER_ID/certificate

(23)

Response <?xml version='1.0' encoding='UTF-8'?> <certificate> <order-id type="integer">12345</order-id> <geotrust-order-id>ab1234</geotrust-order-id> <status>Active</status> <certificate>---BEGIN CERTIFICATE---\r\n...</certificate> <ca-root>...</ca-root> <common-name>www.example.com</common-name> <serial-number>...</serial-number> <start-date type="datetime">2009-04-27T19:07:51-04:00</start-date> <end-date type="datetime">2009-04-27T19:07:51-04:00</end-date> <locality>Atlanta</locality> <state>GA</state> <organization>Example</organization> <organizational-unit>Example Unit</organizational-unit> <country>US</country> <approver-email>example@example.com</approver-email> <trial type="boolean">false</trial> <url>http://api.geocerts.com/1/order/12345/certificate</url> </certificate> cURL Example $ curl https://PARTNER-ID:TOKEN@sandbox.geocerts.com/1/orders/ORDER_ID/certificate

4.4.3 POST - reissue - /1/orders/ORDER_ID/certificate/reissue

Sends a re-issue request to GeoTrust. A valid CSR request for the same FQDN as the original order must be submitted. Domain-authenticated certificates (e.g., QuickSSL, QuickSSL Premium, EV) will require the original domain approver to re-approve the reissue via an automated email that will be sent immediately following a successful reissue API request.

Request

<?xml version='1.0' encoding='UTF-8'?> <certificate>

---BEGIN CERTIFICATE REQUEST--- .... data ....

---END CERTIFICATE REQUEST--- </body>

</csr>

</certificate>

(24)

See show for reference.

$ curl –H "Content-type: application/xml" -X POST -d

"<certificate><csr><body>...CSR_REQUEST_BODY...</body></csr></certificate>"

“https://PARTNER-ID:TOKEN@sandbox.geocerts.com/1/orders/ORDER_ID/certificate/reissue"

4.5 Events

The Events resource gives access to a Partner’s order modification events in the system. Modification Events are major changes to an order. An example of an Event might be “Certificate Created”. In this case a Partner would then want to collect the certificate data and email the completed certificate to the customer.

It’s suggested that this operation be run on a periodic basis (e.g., every 10 or 15 minutes) so all order statuses can be maintained up to date in the Partner’s system.

The major event names are: x Order Created x Approver Confirmed x Approver Rejected x Certificate Created x Certificate Cancelled x Certificate Revoked x Order Completed x Order Cancelled

Actions

Action Method Endpoint index GET /1/events

show GET /1/orders/ORDER_ID/events

4.5.1 GET - index - /1/events

Returns all order modification data across all orders within the specified date range. If no range is given, the start time defaults to 15 minutes ago and the end time defaults to the current system time.

Request

/1/events?start_at=2009-04-27T19:07:51-04:00&end_at=2009-04-27T19:37:51-04:00 Response

(25)

<events start_at="2009-04-27T19:07:51-04:00" end_at="2009-04-27T19:37:51-04:00"> <event> <event-id>7654321</event-id> <order-id type="integer">12345</order-id> <name>Order Cancelled</name> <created-at type="datetime">2009-04-27T19:07:51-04:00</created-at> </event> <event> ... </event> </events> cURL Example $ curl https://PARTNER-ID:TOKEN@sandbox.geocerts.com/1/events

4.5.2 GET - show - /1/orders/ORDER_ID/events

Returns all order modification event data for the specified order within the specified date range. If no range is given, the start time defaults to 15 minutes ago and the end time defaults to the current system time.

Request

/1/orders/12345/events?start_at=2009-04-27T19:07:51-04:00&end_at=2009-04-27T19:37:51-04:00

Response

<?xml version='1.0' encoding='UTF-8'?>

<events start_at="2009-04-27T19:07:51-04:00" end_at="2009-04-27T19:37:51-04:00"> <event> <event-id>abc123</event-id> <order-id type="integer">12345</order-id> <name>Order Cancelled</name> <created-at type="datetime">2009-04-27T19:07:51-04:00</created-at> </event> <event> ... </event> </events> cURL Example $ curl https://PARTNER-ID:TOKEN@sandbox.geocerts.com/1/orders/12345/events

(26)

Section 5: Other API Information

5.1 Errors and Warnings

Any errors or warnings generated by GeoTrust will be passed through via the API. For any locally generated errors or warnings, each message will be accompanied by a unique code to allow you to customize your own messages.

Errors & Warnings

Errors will only be returned if the request is unprocessable, malformed, or fails to meet system requirements. These requests should be modified and re-attempted to succeed. Failing requests do not alter any system data. Warnings may be returned with either successful or unsuccessful requests. Warnings do not indicate a failure of the request. Requests which receive warnings may have successfully altered system data.

Response with Errors and Warnings

<?xml version="1.0" encoding="UTF-8"?> <errors>

<error>

<message>CSR invalid CN – Appears to be an IP address</message> </error>

</errors> <warnings> <warning>

<message>CSR Key Size Too Small </message> </warning>

</warnings>

Within the <error> or <warning> structure there are two fields:

x <code> - This is a numeric code that defined the type of error. A list of error and warning codes is provided in the tables below.

x <message> - A text message with additional information regarding the error or warning. This is not intended for automated processing.

5.2 Error Codes

Error codes will always be a negative integer.

Code Type Description

-1001 General System Error

-2001 Required Field Missing The return text is of the format: “Required Field Missing: <name of

(27)

field> -Please supply required field and resubmit request”

-2003 Invalid PartnerOrderID

An invalid ProductCode will receive error -2019 (Missing or invalid field: ProductCode)

-2006 Invalid field in an order Invalid field data of some type. The ErrorField returned contains the name of the problematic field. This error will be returned for fields that exceed the maximum length.

-2007 Error getting OrderStatus -2008 Invalid Replay Token -2009 Authentication Failure

-2010 CSR Invalid General CSR error

-2011 General ModifyOrder Error PartnerOrderID was not found due to the order associated with the

PartnerOrderID was cancelled. PARTNER-ID did not match any records in DB Order type doesn’t support approve method

-2012 Other General error Function not available in production. - Unable to cancel completed orders in production.

- Unable to approve True BusinessID order

- Unable to approve QSSL orders in production

- Unable to revoke certificates in production

- Unable to deactivate order

-2013 Other General error ModifyOrderOperation is invalid

-2014 Order type not valid for this operation –

can’t resend fulfillment e-mail for this type of order (ResendEmailType is invalid for this order type)

-2017 Field has exceeded maximum length. The Error Field returned contains the name of the problematic field. The return text is of the format: The maximum field length has been exceeded.

-2018 Wildcard not allowed Wildcard specification is not allow for specified Product SKU

-2019 Missing or invalid field Specific reason returned in the error message

-2020 CSR can not be parsed Unable to Parse the CSR

-2021 CSR signature invalid Can parse the CSR but the signature is

invalid

-2022 CSR Country code invalid Country code is not in the list of supported country codes.

(28)

CSR.

-2024 CSR Invalid CN – invalid characters Invalid characters were specified in the CN

-2025 CSR invalid CN – Appears to be an IP address -2026 CSR invalid CN – does not contain at least one

period

-2027 CSR invalid CN – Wildcard not supported For QuickSSL, reject if it looks like a CSR for a wildcard cert.

This check is no longer performed when the order is being submitted so it has been removed.

-2029 Invalid field in CSR

-2030 Required field missing in CSR -2031 CSR invalid –N - CN ends with a dot -2032 CSR invalid –N - CN is too short.

-2033 CSR invalid - maximum field length exceeded

-2040 Order already in process for the domain If an order is currently in process for a domain, a duplicate order is rejected. -2042 Incorrect status ID for status=REQUESTED

-2044 Error encountered approving order

-2064 Required Order Attribute tag not found A required Order Attribute tag was not specified

-2065 Order Attribute missing required tag

-2072 Cannot locate certificate by Partner Order ID No certificate match was found for the specified Partner Order ID

-2073 Cannot locate certificate to revoke A certificate could be located for the specified revocation parameters -2074 Certificate is already revoked The certificate to be revoked has

already been revoked -2075 Error revoking certificate

-2076 Revoke not allowed for product SKU Revocation is not allowed for the specified product code for this environment.

-2081 Invalid InviteDuration specified

-2083 Cannot Locate order by Partner Code The PartnerCode submitted with the request is invalid either due to it does not exist in the system or the order was cancelled.

-2084 Reissue Not Available for Order The order you are trying to do a reissue for is not eligible for a Reissue request via the API.

-2089 GeoTrust’s system has detected that your CSR has a weak public key. For more information, please read the advisory at

https://knowledge.geotrust.com/support/knowledg e-base/index?page=content&id=AD92

CSR submitted contains a weak key

-2091 The requested feature is not supported for this

product Unsupported feature

-2100 ASL - General Error

-2101 Original Partner Order ID Midterm upgrade unavailable. Reason: The order is still within the cancellation period

(29)

Order ID For midterm upgrade: Midterm upgrade unavailable. Reason: The order is in the renewal period

-2103 Original Partner Order ID For midterm upgrades: Midterm

upgrade unavailable. Reason: The order has already been upgraded -2104 Original Partner Order ID Midterm upgrade unavailable. Reason:

The order is an upgrade order

-2105 Original Partner Order ID Midterm upgrade unavailable. Reason: The product to upgrade to is not in an active contract

-2106 Original Partner Order ID Midterm upgrade unavailable. Reason: The order has been canceled

-2107 Original Partner Order ID Midterm upgrade unavailable. Reason: Upgrade to specified product not allowed

-2108 Original Partner Order ID Midterm upgrade unavailable. Reason: The order is not completed

-2110 Original Partner Order ID The Common Name you specified,

bosxp4970.geotest8.com, does not match the one in the original order -3005 Insufficient Remaining Reissues Reissue with Insufficient Remaining

Reissues, includes reissue of Free Trial, which is not allowed

-3010 The common name in the CSR does not match

the site’s domain name The common name in the CSR does not match the site’s domain name -3011 Reissue with SLDN not matching the original

order Reissue with SLDN not matching the original order -3013 Cannot reissue to a wildcard domain This error is returned when the value in

the CN of the new CSR used for a reissue is a wildcard and the value in the original CSR was not.

-4001 Parameter Less Than Minimum This error is returned when a field has a minimum length requirement that hasn’t been supplied.

-4002 Invalid Scripting Tag Returned when our system detects

scripting code in one of the data fields.

-4003 Domain Hard Block This error is returned when an order is

placed for a domain owned by one of our enterprise level customers that has requested all orders be placed through their account.

-4004 Domain CDN Hard Block Similar to Domain Hard Block error.

-99999 HTTPS is required All API connections require HTTPS

-90000 Unrecognized product code requested Product SKU submitted is not recognized.

-90001 You must supply a domain name

-90002 Order is in the wrong state for cancellation A request to cancel and order that is not in a cancelable state.

(30)

-90003 Desired order state must be provided (CANCEL,

APPROVE) A request has been made to modify an order but a valid state change operation has not been submitted. -90004 Invalid order identifier requested An order ID cannot be found for this

reseller.

-90009 You must supply an approver email An order has been submitted that requires an approver email field (e.g., All QuickSSL type orders).

-90010 Certificate is not in the correct state for reissue A reissue request has been submitted but the certificate is not in a reissuable state (e.g., a certificate that is already pending reissue may not be reissued).

-90011 You must provide a CSR A request has been submitted that

requires a CSR (e.g., order validate, order create, and order reissue). nil Authentication Failed

5.3 Warning Codes

Waning codes will always be a positive integer.

Code Type Description

1001 Deprecated operation warning This is a warning that the API command used will be removed from the specification and the application in the next major revision.

2001 Warning: Problem getting Order Status

2002 No rows returned for query The query completed successfully, but no rows were found for the query parameters.

2006 CSR Key Size Too Small Warning for key sizes less than 1024

2015 Order is not eligible for renewal This warning is returned when the Renewal Indicator is set to ‘true’ and the domain is not validated as eligible.

2016 CSR unsupported CSR is not supported for the product. 3012 Hostname for the CSR has changed

for this order

4005 Domain Soft Block This is a warning that the domain is owned by one of GeoTrust’s enterprise level customers that may want the organization contact to place the order through their account.

5.4 Field Definitions

This table lists all of the data types used in the API specification in alphabetical order.

XML Structure Description Type/Max

length <address> Part of the Address structure. Contains the String/100

(31)

first line of an Organization’s address. <address-2> Part of the Address structure. Contains the

second line Organization’s address. String/100 <address-3> Part of the Address structure. Contains the

third line Organization’s address.

String/100 <admin> <first-name> <last-name> <phone> <email> </admin>

This is the contact data for the admin contact in an order.

<agreement> This is the User Agreement for the specified product. This must be displayed to all users prior to submitting the order to GeoTrust.

String/No limit <approver-email> This is the email of the Approver – in the

Domain vetted line of products this is the person responsible for approving the order. It must be an authoritative email as defined in GeoTrust’s certificate practice

statement. (See info about QuickSSL process at beginning of this document)

String/255

<ca-root> This is the content of a CA certificate in the certificate chain for the server certificate in Base64 encoded format.

String/4000

<certificate> A Base64-encoded certificate String/4000

<certificate> <order-id> <status> <geotrust-order-id> <certificate> <ca-root> <common-name> <serial-number> <start-date> <end-date> (<locality>)? (<state>)? <organization> <country> (<organizational-unit>)? (<approver-email>)? <trial> </certificate>)?

This structure contains all of the fields stored related to the certificate in various Query operations.

Indicates the status of the end entity certificate ordered. For an SSL certificate this would be the Web server certificate. Possible values include ACTIVE, REVOKED, CANCELLED, RENEWED, and PENDING_REISSUE.

<city> The city field from the CSR or Contact String/64

<common-name> This field is part of the subject DN of the end entity certificate and distinguishes the certificate. For an SSL certificate this will most likely be the fully qualified domain name the certificate will be used to secure.

String

<country> Part of the Organization structure. The

Country of the Organization and the two-letter country code in the parsed CSR and Certificate. See section Country Codes.

(32)

<created-at> The time of an event or time of resource

creation. DateTime

Certificate Signing Request. This is the

Base64 encoded X.509 digital certificate signing request typically generated by the end user on their target web server. This is a critical element for all SSL orders.

String/4000

<dns-names> Contains one or more DNS Name values to be put into the certificate SubjectAltName extension. Each can be up to 64 characters. Values are comma delimited.

For True BusinessID up to 25 values may be submitted to be put into the SAN fields. These values can be FQDNs with different domains than the primary, Intranet

and .local domains, server and machine names and private IPs.

String/300

<domain> The domain name for an Order. For an SSL

Order this can be a fully qualified Domain (e.g., www.geotrust.com) or possibly a wildcard domain (e.g., *.geotrust.com). Note that wildcards for SSL pertain only to the node that is wildcarded not to sub-nodes of the wildcarded node (e.g., *.geotrust.com would not include test.www.geotrust.com but it would include www.geotrust.com). For True Site, all subdomains are automatically included, for example, if geotrust.com is submitted all subdomains are qualified under the order.

String/255

<duns> The Dunn and Bradstreet number for a

company. String/50

In the approver email context. Each <email> returned the <emails> structure is valid as the approver email in domain-vetted orders.

<email> From the Contact structures. The Email

Address of the contact.

String/320 <end-date> This is the date the end entity certificate

will expire on. Date

A list of the errors returned from a request. An Errors structure can have multiple Error elements. Errors is a part of the OrderResponseHeader structure. If present, this structure contains one or more errors.

<code> A unique code identifying the error. Error

messages have a negative error code, Warning messages have a positive error code. See section Error Codes.

Int

<message> A message describing an error in more

detail. Message is a part of the Error Structure

String/

<fax> From the Organization Address structure.

The Fax number for the organization.

String/30 <first-name> From one of the Contact structures. The

First Name of the contact. String/100

<geotrust-order-id> This is the Order ID assigned by GeoTrust to the order and provided to the person Int

(33)

requesting the certificate. This Order ID is used in all e-mail communication with the users.

<id> The GeoCerts order ID (different from the

GeoTrust ID).

<last-name> From one of the Contact structures. The

Last Name of the contact. String/100

<licenses> This is the number of servers the ordered

certificate will be installed on. Int <locality> The Locality (aka city) field from the

Certificate

String/

<event> One event in the set of events

<name> The name of the event. Examples include:

Approver Confirmed Approver Rejected Certificate Cancelled Certificate Created Certificate Revoked Order Cancelled Order Completed Order Created String/50 <events> (<event> <name> <created-at> <order-id> </event>)+ </events>

The set of events for the order that caused the status to be changed within the

specified time period.

This structure is in many order request messages and contains basic order

information common to all types of orders.

<organization> The Organization field from the certificate String/255 The address of the organization. Applies to

Organization Vetted products and SSL123. A type of Address element. This is in order request operations, and in query response messages.

<organization-name> The legally-registered name of the

Organization applying for the product. This applies to Organization Vetted products.

String/64 <organizational-unit> The Organizational Unit name from the CSR

and the Certificate. String/300

<phone> From one of the Contact or Organization

Address structures.

Current valid character set for this field is: 0123456789 + - ( String/30

(34)

) . x X / space

<postal-code> From the Address structure. The Postal Code

(e.g., Zip Code in the U.S.) for the Address String/20 <serial-number> The serial number of a certificate specified

as a hex string. String/4

<certificate> The Base64 encoded server certificate from a

completed order. String/4000

<sku> The SKU of an SSL product (e.g., Q, QP, EV).

See Products.

<start-date> This is the date the end entity certificate or seal will be valid from.

Date

<state> State/prov or region.

From the Address structure. This is the region of the address such as state or province. If this is a U.S. state it must have a valid 2 character abbreviation

String/64

<state> This is the current Order State. See

section Order State.

String/50

<state> Used in the modify order request to change

the state of an order. Only two value are possible: CANCEL and APPROVE.

<state> The value of the State in the Parsed CSR

Response. String/

<success-code> Code in the Order validate Response that indicates the success of failure of the request.

x A zero Success Code indicates a success with no warnings.

x A positive Success Code indicates a success with warnings.

x A negative Success Code indicates a failure due to one or more errors. Note that if the Success Code is non-zero an accompanying Errors structure will be

present.

Int

<status-major> This is the high level status of an Order. It is a sub-element of the OrderStatus structure.

Valid Order Status Major values:

INVITEPENDING – Invite has been sent and

is waiting

PENDING – Order is in process (if an

order is in PENDING then an Order Status Minor structure will be present)

COMPLETE – Order has been completed. CANCELLED – Order has been completed and

cancelled.

String/20

<status-minor> This is the status code that is unique to a particular product line. As opposed to OrderStatus Major which is a high level status, Order Status Minor provides specific status information unique to the workflow of

(35)

the specific product.

QuickSSL and other Quick Orders

ORDER_INIT – Order waiting for phone

authentication, or order in a state

ORDER_WAITING_FOR_APPROVAL – Order

waiting to be approved.

ORDER_QUEUED – Order queued for GeoTrust

problem resolution

ORDER_COMPLETE – Order complete ORDER_CANCELLED – Order cancelled DEACTIVATED – Order has been

deactivated.

True BusinessID and True Site

CANCELLED – Order Cancelled FULFILLED – order fulfilled

INITIAL – Initial state of order (not

normally used)

QUEUED – Order being processed by

GeoTrust

QUEUED_ENT – An Enterprise SSL request

queued for review by the Enterprise.

<years> The number of years that a certificate will

be valid for. Defaults to 1 if not present. See section Certificate Validity Period.

Int

5.5 Additional Description of fields

5.5.1 Approver Email <approver-email>

The approver email must be one of the following:

Domain – One of the registered domain contacts (admin or tech) found in the WHOIS database for the associated domain. GeoTrust’s system does not have 100% access to all the WHOIS databases, so it’s possible that even if a valid email address is entered, it will be rejected. Trying again may resolve the problem. Generic - For every domain, a list of generic e-mail addresses is supported. The values in the following list are pre-appended to the domain supplied in the request:

x admin x administrator x hostmaster x root x webmaster x postmaster

For example, the following approver e-mail addresses are valid for the domain www.domain.com: x admin@domain.com

x administrator@domain.com x hostmaster@domain.com x root@domain.com x webmaster@domain.com

(36)

x postmaster@domain.com

Manual - As a last resort, the email address support@geotrust.com may be used (or

support_preprod@geotrust.com on the test system). This final option is to be used when no other option will work. GeoTrust will contact the customer and determine an alternate approver email address in accordance with the Certificate Practices Statement (CPS). NOTE: This may take several business days when used.

5.5.2 Midterm Upgrade

The following table below defines which products you may upgrade from and to.

5.5.3 Country Codes

The following table defines the supported values for the <country> variable defined above. The right most column identifies this as a country that GeoTrust can do business with (or not) based on current US export laws. Codes marked with N will not be accepted in orders or CSRs.

Note: UK is not a valid country code. The value of GB should be used instead.

Code Name AD ANDORRA Y AE UNITED ARAB EMIRATES Y AF AFGHANISTAN Y AG ANTIGUA AND BARBUDA Y AI ANGUILLA Y AL ALBANIA Y AM ARMENIA Y AN NETHERLANDS ANTILLES Y AO ANGOLA N AQ ANTARCTICA Y AR ARGENTINA Y AS AMERICAN SAMOA Y Code Name AT AUSTRIA Y AU AUSTRALIA Y AW ARUBA Y AX Aland Islands AZ AZERBAIJAN Y BA BOSNIA AND HERZEGOVINA Y BB BARBADOS Y BD BANGLADESH Y BE BELGIUM Y BF BURKINA FASO Y BG BULGARIA Y BH BAHRAIN Y BI BURUNDI Y Code Name BJ BENIN Y BL Saint Barthelemy Y BM BERMUDA Y BN BRUNEI DARUSSALAM Y BO BOLIVIA Y BR BRAZIL Y BS BAHAMAS Y BT BHUTAN Y BV BOUVET ISLAND Y BW BOTSWANA Y BY BELARUS Y BZ BELIZE Y CA CANADA Y New product --->

Expiring product below

True BizID EV TruBizID QuickSSL Premium QuickSSL TruBizID WC TrueBizID EV - - - - -TruBizID Y - - - -QuickSSL Premium Y Y - - -QuickSSL Y Y - - -TruBizID Wildcard - - - -

(37)

-Code Name CC COCOS (KEELING) ISLANDS Y CD CONGO, THE DEMOCRATIC REPUBLIC OF THE Y CF CENTRAL AFRICAN REPUBLIC Y CG CONGO Y CH SWITZERLAND Y CI COTE D’IVOIRE Y CK COOK ISLANDS Y CL CHILE Y CM CAMEROON Y CN CHINA Y CO COLOMBIA Y CR COSTA RICA Y CU CUBA N CV CAPE VERDE Y CX CHRISTMAS ISLAND Y CY CYPRUS Y CZ CZECH REPUBLIC Y DE GERMANY Y DJ DJIBOUTI Y DK DENMARK Y DM DOMINICA Y DO DOMINICAN REPUBLIC Y DZ ALGERIA Y EC ECUADOR Y EE ESTONIA Y EG EGYPT Y EH WESTERN SAHARA Y ER ERITREA Y ES SPAIN Y ET ETHIOPIA Y FI FINLAND Y FJ FIJI Y FK FALKLAND ISLANDS (MALVINAS) Y FM MICRONESIA, FEDERATED STATES OF Y FO FAROE ISLANDS Y FR FRANCE Y GA GABON Y GB UNITED KINGDOM Y GD GRENADA Y GE GEORGIA Y GF FRENCH GUIANA Y GH GHANA Y GI GIBRALTAR Y GL GREENLAND Y GM GAMBIA Y GN GUINEA Y GP GUADELOUPE Y GQ EQUATORIAL GUINEA Y GR GREECE Y GS SOUTH GEORGIA

AND THE SOUTH SANDWICH ISLANDS Y GT GUATEMALA Y Code Name GU GUAM Y GW GUINEA-BISSAU Y GY GUYANA Y HK HONG KONG Y

HM HEARD ISLAND AND

MCDONALD ISLANDS Y HN HONDURAS Y HR CROATIA Y HT HAITI Y HU HUNGARY Y ID INDONESIA Y IE IRELAND Y IL ISRAEL Y IM Isle of Man Y IN INDIA Y IO BRITISH INDIAN OCEAN TERRITORY Y IQ IRAQ Y IR IRAN, ISLAMIC REPUBLIC OF N IS ICELAND Y IT ITALY Y JE Jersey Y JM JAMAICA Y JO JORDAN Y JP JAPAN Y KE KENYA Y KG KYRGYZSTAN Y KH CAMBODIA Y KI KIRIBATI Y KM COMOROS Y

KN SAINT KITTS AND NEVIS Y KP NORTH KOREA (DEMOCRATIC PEOPLE’S REPUBLIC OF KOREA) N KR KOREA, REPUBLIC OF Y KW KUWAIT Y KY CAYMAN ISLANDS Y KZ KAZAKSTAN Y LA LAO PEOPLE’S DEMOCRATIC REPUBLIC Y LB LEBANON Y LC SAINT LUCIA Y LI LIECHTENSTEIN Y LK SRI LANKA Y LR LIBERIA Y LS LESOTHO Y LT LITHUANIA Y LU LUXEMBOURG Y LV LATVIA Y LY LIBYAN ARAB JAMAHIRIYA N MA MOROCCO Y MC MONACO Y MD MOLDOVA, REPUBLIC OF Y ME Montenegro Y Code Name MF Saint Martin Y MG MADAGASCAR Y MH MARSHALL ISLANDS Y MK MACEDONIA, THE FORMER YUGOSLAV REPUBLIC OF Y ML MALI Y MM MYANMAR Y MN MONGOLIA Y MO MACAU Y MP NORTHERN MARIANA ISLANDS Y MQ MARTINIQUE Y MR MAURITANIA Y MS MONTSERRAT Y MT MALTA Y MU MAURITIUS Y MV MALDIVES Y MW MALAWI Y MX MEXICO Y MY MALAYSIA Y MZ MOZAMBIQUE Y NA NAMIBIA Y NC NEW CALEDONIA Y NE NIGER Y NF NORFOLK ISLAND Y NG NIGERIA Y NI NICARAGUA Y NL NETHERLANDS Y NO NORWAY Y NP NEPAL Y NR NAURU Y NU NIUE Y NZ NEW ZEALAND Y OM OMAN Y PA PANAMA Y PE PERU Y PF FRENCH POLYNESIA Y PG PAPUA NEW GUINEA Y PH PHILIPPINES Y PK PAKISTAN Y PL POLAND Y

PM SAINT PIERRE AND MIQUELON Y PN PITCAIRN Y PR PUERTO RICO Y PS PALESTINIAN TERRITORY, OCCUPIED Y PT PORTUGAL Y PW PALAU Y PY PARAGUAY Y QA QATAR Y RE REUNION Y RO ROMANIA Y RU RUSSIAN FEDERATION Y RS Serbia Y RW RWANDA Y