GeoCerts Reseller REST API

Transcription

1 GeoCerts Reseller REST API Product Description and Interface Definitions Revision 1.0 April 2010

2 Section 1: Table of Contents Section 1: Table of Contents... i Section 2: Overview Release Notes Previous Release Notes Deprecated Commands...1 Section 3: Using the API SSL Server Certificate Product Orders Web-based Domain Vetted Ordering Scenario Web-based Organization Vetted Product Ordering Scenario Web-based Domain and Organization Vetted Product Ordering Scenario API-based Ordering Scenario Testing Information Register for a sandbox test account Test Root certificates...6 Section 4: API Endpoints Hello POST create - /1/hello Agreements GET - index - /1/products/SKU/agreement Orders Get index /1/orders Get show - /1/orders/ORDER_ID POST - resend - /1/orders/ORDER_ID/resend PUT - - /1/orders/ORDER_ID/ PUT - modify - /1/orders/ORDER_ID/modify GET - approvers - /1/orders/approvers POST - validate - /1/orders/validate POST - create - /1/orders Certificates GET - index - /1/certificates GET - show - /1/orders/ORDER_ID/certificate POST - reissue - /1/orders/ORDER_ID/certificate/reissue Events GET - index - /1/events GET - show - /1/orders/ORDER_ID/events...22 Section 5: Other API Information Errors and Warnings Error Codes Warning Codes Field Definitions...27 GeoCerts Confidential i

3 5.5 Additional Description of fields Approver <approver- > Midterm Upgrade Country Certificate Signing Request (CSR) DNS Names Modify Order Operation Order State Price Computation Products Renewal Behavior Certificate Validity Period <years>...39 Appendix A - Glossary Appendix B - Additional Resources A.1. Ruby GEM B.1. curl...43 GeoCerts Confidential ii

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 us at [email protected] or call if you have questions or need assistance with integration. 2.2 Previous Release Notes None 2.3 Deprecated Commands None GeoCerts Confidential 1

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. Illustration Legend: 1 2 API Message Non-API Message 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 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. GeoCerts 11 2 GeoCerts Partner Figure 1 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. GeoCerts 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 Figure 2 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 21 GeoCerts Partner GeoCerts Confidential 2

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 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 , accepts the subscriber agreement and submits the order. 2. An acknowledgement is sent to the requestor and other order contacts confirming placement of the order. 3. An is sent to the Approver requesting that the Approver review the submitted order. 4. The Approver follows the link in the , reviews the order information and either approves or rejects the order. 5. If the order is approved, the requestor receives the certificate via . GeoCerts Requestor Approver 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 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 GeoCerts Confidential 3

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 , accepts the subscriber agreement and submits the order. 2. An acknowledgement 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 is sent to the Approver requesting that the Approver review the submitted order. 5. The Approver follows the link in the , 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 API-based Ordering Scenario GeoCerts Requestor Approver 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 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 addresses. GeoCerts GeoCerts Partner Partner Processing the Order Once the order information is ready for processing: 2 1. GeoTrust Partner uses the Order Create command to submit all order information including organization info, contact info, the CSR and the approver (for applicable products only). When the approver address is required it must be one that that is authorized to approve the order. GeoCerts 3 Requestor 6 GeoCerts Confidential 4 4 Approver 5

8 2. The remainder of the ordering process is like the UI-based ordering scenarios. An acknowledgement 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 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 , 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 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 s can be disabled, if it s preferable for a Partner to send this information to the requestor from their systems. The approver 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 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: 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. GeoCerts Confidential 5

9 3.2.2 Test Root certificates GeoTrust Pre-Production CA 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 edh END CERTIFICATE 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 GeoCerts Confidential 6

10 /0fnE34/rr7oUC4JAqF4mEw/95kID001yb5oTxiV7fLnZE+lG9u2LoLO2XCwzBx9 w9cogg58xqkx2dduv77csru8wudyrcmiykswzwggy3xizfyira6faoexiuydgm73 HFUV -----END CERTIFICATE GeoTrust Pre-Production CA 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 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----- GeoCerts Confidential 7

11 Section 4: API Endpoints Sandbox Test URL: Production URL: 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 <!-- comments here --> 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 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> curl Example GeoCerts Confidential 8

12 $ curl H "Content-type: application/xml" -d "<hello>hi there</hello>" ID:[email protected]/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 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 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 s, change and re-send approval s and includes actions to cancel, approve, and validate orders. Actions Action Method Endpoint index GET /1/orders create POST /1/orders GeoCerts Confidential 9

13 validate POST /1/orders/validate approvers GET /1/orders/approvers show GET /1/orders/ORDER_ID resend POST /1/orders/ORDER_ID/resend PUT /1/orders/ORDER_ID/ modify PUT /1/orders/ORDER_ID/modify 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= T19:07:51-04:00&end_at= T19:37:51-04:00 Response <?xml version='1.0' encoding='utf-8'?> <orders> <order start_at=" t19:07:51-04:00" end_at=" t19:37:51-04:00"> <id type="integer">12345</id> <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 GeoCerts Confidential 10

14 $ curl 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> <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'?> <errors> <error> GeoCerts Confidential 11

15 -1234 <message>error occurred</message> </error> <error>...</error> <warning> 3456 <message>this is a warning</message> </warning> <warning>...</warning> </errors> curl Example $ curl POST - resend - /1/orders/ORDER_ID/resend Instructs GeoTrust to re-send the approval verification required to complete the order process. This should be used when the original was not received or mistakenly deleted prior to approval. Response See the show response for reference. curl Example $ curl -X POST ID:[email protected]/1/orders/ORDER_ID/resend" PUT - - /1/orders/ORDER_ID/ Instructs GeoTrust to update the approver associated with the order with the new address given. The new address must be one of the pre-approved s returned from the GET approvers request. Request <?xml version='1.0' encoding='utf-8'?> <order> <approver- >[email protected]</approver- > </order> Response See the show response for reference. curl Example GeoCerts Confidential 12

16 $ curl -X PUT -H "Content-type: application/xml" -d 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 Request <?xml version='1.0' encoding='utf-8'?> <order> <state>cancel</state> </order> Response See the show response for reference. curl Example $ curl -X PUT -H "Content-type: application/xml" -d "<order><state>cancel</state></order>" " ID:[email protected]/1/orders/ORDER_ID/modify" GET - approvers - /1/orders/approvers Returns a complete collection of valid approver addresses for a specified domain. Request /1/orders/approvers?domain=example.com GeoCerts Confidential 13

17 Response <?xml version='1.0' encoding='utf-8'?> < s> </ s> curl Example $ curl ID:[email protected]/1/orders/approvers?domain=example.com" 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> <csr> <body> -----BEGIN CERTIFICATE REQUEST----- abcde END CERTIFICATE REQUEST----- </body> </csr> <product> <sku>qp</sku> </product> GeoCerts Confidential 14

18 </order> Optional Parameters years: Number of years the CSR request is covering (defaults to 1) licenses: Number of licenses (1 per server) you are requesting (defaults to 1) dns-names: A comma separated list of DNS names used in a multi-domain CSR request (e.g., " 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> <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> </geotrust-order-id> <expiration-date type="datetime"> </expiration-date> </renewal-info> <errors/> <warnings/> </order> Note that <renewal-info><geotrust-order-id> </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 GeoCerts Confidential 15

19 $ curl H "Content-type: application/xml" -X POST -d "<order>approver >[email protected]</approver- > <csr><body>...csr_request_body...</body></csr><product><sku>q</sku></product> </order>" 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 protected]</approver- > <csr> <body> -----BEGIN CERTIFICATE REQUEST----- MIIBnDCCAQUCAQAwXDELMAkGA1UEBhMCVVMxEDAOBgNVBAgTB0Zsb3JpZGExEDAO BgNVBAcTB09ybGFuZG8xEzARBgNVBAoTClJhaWxzIEVudnkxFDASBgNVBAMTC3d 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 s 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 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: <order> GeoCerts Confidential 16

20 ... <admin> <first-name>jane</first-name> <last-name>smith</last-name> <phone> </phone> </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> </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>... <licenses>2</licenses> </order> Organization Info Required for all True BusinessID organization-vetted orders (Wildcard and Extended Validation). <order> GeoCerts Confidential 17

21 ... <organization> <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> </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 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> </phone> < >[email protected]</ > </ev-approver> </order> curl Example $ curl H "Content-type: application/xml" -X POST -d "<order><approver >[email protected]</approver ><csr><body>...csr_request_body...</body></csr><product><sku>q</sku></pr oduct></order>" Certificates The Certificates resource gives access to reading and reissuing previously ordered certificates. Actions Action Method Endpoint index GET /1/certificates GeoCerts Confidential 18

22 show GET /1/orders/ORDER_ID/certificate reissue POST /1/orders/ORDER_ID/certificate/reissue 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= T19:07:51-04:00&end_at= T19:37:51-04:00 Response <?xml version='1.0' encoding='utf-8'?> <certificates start_at=" t19:07:51-04:00" end_at=" T19: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> <serial-number>...</serial-number> <start-date type="datetime"> t19:07:51-04:00</start-date> <end-date type="datetime"> t19: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 protected]</approver- > <trial type="boolean">false</trial> <url> </certificate> </certificates> curl Example $ curl GET - show - /1/orders/ORDER_ID/certificate Returns information about a single certificate. GeoCerts Confidential 19

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> <serial-number>...</serial-number> <start-date type="datetime"> t19:07:51-04:00</start-date> <end-date type="datetime"> t19:07:51-04:00</end-date> <locality>atlanta</locality> <state>ga</state> <organization>example</organization> <organizational-unit>example Unit</organizational-unit> <country>us</country> <trial type="boolean">false</trial> <url> </certificate> curl Example $ curl ID:[email protected]/1/orders/ORDER_ID/certificate 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 that will be sent immediately following a successful reissue API request. Request <?xml version='1.0' encoding='utf-8'?> <certificate> <csr> <body> -----BEGIN CERTIFICATE REQUEST data END CERTIFICATE REQUEST----- </body> </csr> </certificate> Response GeoCerts Confidential 20

24 See show for reference. $ curl H "Content-type: application/xml" -X POST -d "<certificate><csr><body>...csr_request_body...</body></csr></certificate>" ID:[email protected]/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 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: Order Created Approver Confirmed Approver Rejected Certificate Created Certificate Cancelled Certificate Revoked Order Completed Order Cancelled Actions Action Method Endpoint index GET /1/events show GET /1/orders/ORDER_ID/events 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= T19:07:51-04:00&end_at= T19:37:51-04:00 Response <?xml version='1.0' encoding='utf-8'?> GeoCerts Confidential 21

25 <events start_at=" t19:07:51-04:00" end_at=" t19:37:51-04:00"> <event> <event-id> </event-id> <order-id type="integer">12345</order-id> <name>order Cancelled</name> <created-at type="datetime"> t19:07:51-04:00</created-at> </event> <event>... </event> </events> curl Example $ curl 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= T19:07:51-04:00&end_at= T19:37:51-04:00 Response <?xml version='1.0' encoding='utf-8'?> <events start_at=" t19:07:51-04:00" end_at=" t19: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"> t19:07:51-04:00</created-at> </event> <event>... </event> </events> curl Example $ curl GeoCerts Confidential 22

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> <code type="integer">-2025</code> <message>csr invalid CN Appears to be an IP address</message> </error> </errors> <warnings> <warning> <code type="integer">2006</code> <message>csr Key Size Too Small </message> </warning> </warnings> Within the <error> or <warning> structure there are two fields: <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. <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 General System Error Required Field Missing The return text is of the format: Required Field Missing: <name of GeoCerts Confidential 23

27 field> -Please supply required field and resubmit request Invalid PartnerOrderID An invalid ProductCode will receive error (Missing or invalid field: ProductCode) 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 Error getting OrderStatus Invalid Replay Token Authentication Failure CSR Invalid General CSR error 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 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 Other General error ModifyOrderOperation is invalid Order type not valid for this operation can t resend fulfillment for this type of order (Resend Type is invalid for this order type) 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 Wildcard not allowed Wildcard specification is not allow for specified Product SKU Missing or invalid field Specific reason returned in the error message CSR can not be parsed Unable to Parse the CSR CSR signature invalid Can parse the CSR but the signature is invalid CSR Country code invalid Country code is not in the list of supported country codes CSR contains unsupported extensions Unsupported extension found in the GeoCerts Confidential 24

28 CSR CSR Invalid CN invalid characters Invalid characters were specified in the CN CSR invalid CN Appears to be an IP address CSR invalid CN does not contain at least one period 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 Invalid field in CSR Required field missing in CSR CSR invalid N - CN ends with a dot CSR invalid N - CN is too short CSR invalid - maximum field length exceeded Order already in process for the domain If an order is currently in process for a domain, a duplicate order is rejected Incorrect status ID for status=requested Error encountered approving order Required Order Attribute tag not found A required Order Attribute tag was not specified Order Attribute missing required tag Cannot locate certificate by Partner Order ID No certificate match was found for the specified Partner Order ID Cannot locate certificate to revoke A certificate could be located for the specified revocation parameters Certificate is already revoked The certificate to be revoked has already been revoked Error revoking certificate Revoke not allowed for product SKU Revocation is not allowed for the specified product code for this environment Invalid InviteDuration specified 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 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 GeoTrust s system has detected that your CSR CSR submitted contains a weak key has a weak public key. For more information, please read the advisory at e-base/index?page=content&id=ad The requested feature is not supported for this Unsupported feature product ASL - General Error Original Partner Order ID Midterm upgrade unavailable. Reason: The order is still within the cancellation period Cannot locate Original Partner Order ID Bad ASL - Invalid Original Partner Order ID. GeoCerts Confidential 25

29 Order ID For midterm upgrade: Midterm upgrade unavailable. Reason: The order is in the renewal period Original Partner Order ID For midterm upgrades: Midterm upgrade unavailable. Reason: The order has already been upgraded Original Partner Order ID Midterm upgrade unavailable. Reason: The order is an upgrade order Original Partner Order ID Midterm upgrade unavailable. Reason: The product to upgrade to is not in an active contract Original Partner Order ID Midterm upgrade unavailable. Reason: The order has been canceled Original Partner Order ID Midterm upgrade unavailable. Reason: Upgrade to specified product not allowed Original Partner Order ID Midterm upgrade unavailable. Reason: The order is not completed Original Partner Order ID The Common Name you specified, bosxp4970.geotest8.com, does not match the one in the original order Insufficient Remaining Reissues Reissue with Insufficient Remaining Reissues, includes reissue of Free Trial, which is not allowed The common name in the CSR does not match the site s domain name Reissue with SLDN not matching the original order The common name in the CSR does not match the site s domain name Reissue with SLDN not matching the original order 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 Parameter Less Than Minimum This error is returned when a field has a minimum length requirement that hasn t been supplied Invalid Scripting Tag Returned when our system detects scripting code in one of the data fields 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 Domain CDN Hard Block Similar to Domain Hard Block error HTTPS is required All API connections require HTTPS Unrecognized product code requested Product SKU submitted is not recognized You must supply a domain name Order is in the wrong state for cancellation A request to cancel and order that is not in a cancelable state. GeoCerts Confidential 26

30 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 Invalid order identifier requested An order ID cannot be found for this reseller You must supply an approver An order has been submitted that requires an approver field (e.g., All QuickSSL type orders) 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) 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 Warning: Problem getting Order Status 2002 No rows returned for query The query completed successfully, but no rows were found for the query parameters CSR Key Size Too Small Warning for key sizes less than 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 CSR unsupported CSR is not supported for the product 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 GeoCerts Confidential 27

31 <address-2> <address-3> <admin> <first-name> <last-name> <phone> < > </admin> <agreement> <approver- > <ca-root> first line of an Organization s address. Part of the Address structure. Contains the second line Organization s address. Part of the Address structure. Contains the third line Organization s address. This is the contact data for the admin contact in an order. This is the User Agreement for the specified product. This must be displayed to all users prior to submitting the order to GeoTrust. This is the of the Approver in the Domain vetted line of products this is the person responsible for approving the order. It must be an authoritative as defined in GeoTrust s certificate practice statement. (See info about QuickSSL process at beginning of this document) This is the content of a CA certificate in the certificate chain for the server certificate in Base64 encoded format. String/100 String/100 String/No limit String/255 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- >)? <trial> </certificate>)? This structure contains all of the fields stored related to the certificate in various Query operations. <certificate> <status> </certificate> 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> <country> 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. Part of the Organization structure. The Country of the Organization and the twoletter country code in the parsed CSR and Certificate. See section Country Codes. String String/2 GeoCerts Confidential 28

32 <created-at> <csr> <body> </csr> <dns-names> The time of an event or time of resource creation. 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. 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. DateTime String/4000 String/300 <domain> <duns> < s> < > </ s> < > <end-date> <errors> (<error> <code> <message> </error>)+ </errors> <code> <message> 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. The domain name for an Order. For an SSL Order this can be a fully qualified Domain (e.g., 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. but it would include For True Site, all subdomains are automatically included, for example, if geotrust.com is submitted all subdomains are qualified under the order. The Dunn and Bradstreet number for a company. In the approver context. Each < > returned the < s> structure is valid as the approver in domain-vetted orders. From the Contact structures. The Address of the contact. This is the date the end entity certificate will expire on. 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. A unique code identifying the error. Error messages have a negative error code, Warning messages have a positive error code. See section Error Codes. A message describing an error in more detail. Message is a part of the Error Structure <fax> From the Organization Address structure. The Fax number for the organization. <first-name> From one of the Contact structures. The First Name of the contact. <geotrust-order-id> This is the Order ID assigned by GeoTrust to the order and provided to the person String/255 String/50 String/320 Date Int String/ String/30 String/100 Int GeoCerts Confidential 29

33 requesting the certificate. This Order ID is used in all 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. <licenses> This is the number of servers the ordered certificate will be installed on. <locality> The Locality (aka city) field from the Certificate <event> <name> <events> (<event> <name> <created-at> <order-id> </event>)+ </events> <order> (<approver- >)? <csr> <product> (<admin>)? (<years>)? (<licenses>)? (<organization>)? (<dns-names>)? (<ev-approver>)? (<years>)? One event in the set of events The name of the event. Examples include: Approver Confirmed Approver Rejected Certificate Cancelled Certificate Created Certificate Revoked Order Cancelled Order Completed Order Created 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. String/100 Int String/ String/50 </order> <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> <organizational-unit> <phone> The legally-registered name of the Organization applying for the product. This applies to Organization Vetted products. The Organizational Unit name from the CSR and the Certificate. From one of the Contact or Organization Address structures. Current valid character set for this field is: ( String/64 String/300 String/30 GeoCerts Confidential 30

34 ). x X / space <postal-code> <serial-number> <certificate> <sku> <start-date> <state> <state> <state> <state> <success-code> <status-major> <status-minor> From the Address structure. The Postal Code (e.g., Zip Code in the U.S.) for the Address The serial number of a certificate specified as a hex string. The Base64 encoded server certificate from a completed order. The SKU of an SSL product (e.g., Q, QP, EV). See Products. This is the date the end entity certificate or seal will be valid from. 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 This is the current Order State. See section Order State. Used in the modify order request to change the state of an order. Only two value are possible: CANCEL and APPROVE. The value of the State in the Parsed CSR Response. Code in the Order validate Response that indicates the success of failure of the request. A zero Success Code indicates a success with no warnings. A positive Success Code indicates a success with warnings. 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. 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. 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 String/20 String/4 String/4000 Date String/64 String/50 String/ Int String/20 String/50 GeoCerts Confidential 31

35 <years> 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. 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 Approver <approver- > The approver 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 address is entered, it will be rejected. Trying again may resolve the problem. Generic - For every domain, a list of generic addresses is supported. The values in the following list are pre-appended to the domain supplied in the request: admin administrator hostmaster root webmaster postmaster For example, the following approver addresses are valid for the domain [email protected] [email protected] [email protected] [email protected] [email protected] GeoCerts Confidential 32

36 Manual - As a last resort, the address [email protected] may be used (or [email protected] 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 address in accordance with the Certificate Practices Statement (CPS). NOTE: This may take several business days when used Midterm Upgrade The following table below defines which products you may upgrade from and to. New product ---> Expiring product below TrueBizID EV TruBizID QuickSSL Premium QuickSSL TruBizID WC TrueBizID EV TruBizID Y QuickSSL Premium Y Y QuickSSL Y Y TruBizID Wildcard 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 Y EMIRATES AF AFGHANISTAN Y AG ANTIGUA AND Y BARBUDA AI ANGUILLA Y AL ALBANIA Y AM ARMENIA Y AN NETHERLANDS Y ANTILLES 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 Y HERZEGOVINA 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 Y DARUSSALAM 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 GeoCerts Confidential 33

37 Code Name CC COCOS (KEELING) Y ISLANDS CD CONGO, THE Y DEMOCRATIC REPUBLIC OF THE CF CENTRAL AFRICAN Y REPUBLIC 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 Y REPUBLIC 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 Y (MALVINAS) FM MICRONESIA, Y FEDERATED STATES OF 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 Y GUINEA GR GREECE Y GS SOUTH GEORGIA Y AND THE SOUTH SANDWICH ISLANDS GT GUATEMALA Y Code Name GU GUAM Y GW GUINEA-BISSAU Y GY GUYANA Y HK HONG KONG Y HM HEARD ISLAND AND Y MCDONALD ISLANDS 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 Y OCEAN TERRITORY IQ IRAQ Y IR IRAN, ISLAMIC N REPUBLIC OF 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 Y NEVIS KP NORTH KOREA N (DEMOCRATIC PEOPLE S REPUBLIC OF KOREA) KR KOREA, REPUBLIC Y OF KW KUWAIT Y KY CAYMAN ISLANDS Y KZ KAZAKSTAN Y LA LAO PEOPLE S Y DEMOCRATIC REPUBLIC 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 N JAMAHIRIYA MA MOROCCO Y MC MONACO Y MD MOLDOVA, Y REPUBLIC OF ME Montenegro Y Code Name MF Saint Martin Y MG MADAGASCAR Y MH MARSHALL Y ISLANDS MK MACEDONIA, THE Y FORMER YUGOSLAV REPUBLIC OF ML MALI Y MM MYANMAR Y MN MONGOLIA Y MO MACAU Y MP NORTHERN Y MARIANA ISLANDS 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 Y POLYNESIA PG PAPUA NEW Y GUINEA PH PHILIPPINES Y PK PAKISTAN Y PL POLAND Y PM SAINT PIERRE AND Y MIQUELON PN PITCAIRN Y PR PUERTO RICO Y PS PALESTINIAN Y TERRITORY, OCCUPIED PT PORTUGAL Y PW PALAU Y PY PARAGUAY Y QA QATAR Y RE REUNION Y RO ROMANIA Y RU RUSSIAN Y FEDERATION RS Serbia Y RW RWANDA Y GeoCerts Confidential 35

38 Code Name SA SAUDI ARABIA Y SB SOLOMON ISLANDS Y SC SEYCHELLES Y SD SUDAN N SE SWEDEN Y SG SINGAPORE Y SH SAINT HELENA Y SI SLOVENIA Y SJ SVALBARD AND Y JAN MAYEN SK SLOVAKIA Y SL SIERRA LEONE N SM SAN MARINO Y SN SENEGAL Y SO SOMALIA Y SR SURINAME Y ST SAO TOME AND Y PRINCIPE SV EL SALVADOR Y SY SYRIAN ARAB N REPUBLIC SZ SWAZILAND Y TC TURKS AND Y CAICOS ISLANDS TD CHAD Y Code Name TF FRENCH Y SOUTHERN TERRITORIES TG TOGO Y TH THAILAND Y TJ TAJIKISTAN Y TK TOKELAU Y TM TURKMENISTAN Y TN TUNISIA Y TO TONGA Y TL Timor-Leste Y TR TURKEY Y TT TRINIDAD AND Y TOBAGO TV TUVALU Y TW TAIWAN, PROVINCE Y OF CHINA TZ TANZANIA, UNITED Y REPUBLIC OF UA UKRAINE Y UG UGANDA Y UM UNITED STATES Y MINOR OUTLYING ISLANDS US UNITED STATES Y Code Name UY URUGUAY Y UZ UZBEKISTAN Y VA HOLY SEE Y (VATICAN CITY STATE) VC SAINT VINCENT Y AND THE GRENADINES VE VENEZUELA Y VG VIRGIN ISLANDS, Y BRITISH VI VIRGIN ISLANDS, Y U.S. VN VIET NAM Y VU VANUATU Y WF WALLIS AND Y FUTUNA WS SAMOA Y YE YEMEN Y YT MAYOTTE Y YU YUGOSLAVIA N ZA SOUTH AFRICA Y ZM ZAMBIA Y ZW ZIMBABWE Y GG Guernsey Y Certificate Signing Request (CSR) The CSR is a base64 encoded data (text) item that contains the public key to be inserted into the certificate. GeoTrust performs several validation checks on this before it is accepted as a valid CSR. The following checks are performed: There are some unsupported extensions that cause the CSR to be invalid. The most common one is the Challenge Password. If this is in the CSR, we reject it as invalid and the user must re-generate the CSR without this instruction. The Challenge Password is an option when using OpenSSL. True BusinessID CSRs may contain IP addresses; however GeoTrust does not allow these for Quick type orders. The CSR will be rejected as invalid for Quick orders. Some products allow the ordering of Wildcard certificates (Domains that begin with *.). The CSR will be rejected as invalid for products that do not support Wildcard certificate orders. All domain names must consist of numbers, letters, the dash character, and must have at least one period (GeoTrust does not accept host names as valid domain names). If the domain name contains any other characters it will be rejected as invalid. Country Code The country field must be populated with a valid country code (see section Country Codes). Note: UK is not a valid country code customers must use GB when generating CSRs. GeoTrust scans fields in the CSR for possible fraudulent data and will reject a CSR if any such data is found. Some companies have registered their names with GeoTrust to assure that no certificates will be issued with their name unless special approval has been previously received. Detection of these values anywhere in the CSR will result in the CSR being rejected as invalid. GeoCerts Confidential 36

39 Signature validation GeoTrust verifies the signature on the CSR and reject it if the signature is not valid. Restricted Strings GeoTrust maintains a set of values that are not allowed to be in the certificate. If one of these is detected, then the CSR will be rejected as invalid. State and Locale (city) fields No validation on these fields is performed as part of CSR validation DNS Names QuickSSL Premium certificates can be ordered with from one to three <dns-names> values in the SubjectAltName extension of the Certificate. If supplied in the Order request, these values will be inserted into the certificate. The values included in the SubjectAltName extension must be a FQDN where the 2 nd level domain matches the domain name in the Common Name (CN) or server names only without any periods. The <dns-names> field accepts a comma-separated list of DNS Names. Additionally, GeoTrust now allows up to 24 values be included in the SubjectAltName extension for True BusinessID Multidomain certificates (non-ev). The values must be submitted using the <dns-names> field and may include FQDNs with different 2 nd level domains than the primary domain in the CN, Private IP addresses, intranet and.local names, and server names. This feature is especially useful for web servers that are configured to supply content for external and internal users. Internally the host may be known as finance where as externally it must have a fully qualified domain name (finance.corp.geotrust.com). A <dns-names> entry of finance will allow internal IE users to securely access this site as and they will not receive the domain name mismatch error. The following products support DNS Names: Product True BusinessID Multidomain (MD) QuickSSL Premium QuickSSL Free Trial SSL TrueBizID EV Supports DNS names Yes Yes No No No Modify Order Operation The following table defines the supported command values for Order Modify operation. These commands are all supported on the test system to allow Partners to place orders, approve, cancel, etc. so that orders can be fully processed to simulate the production environment where orders change states. Value Production support Test support APPROVE Allowed for TC, TCX. Not allowed for SSL. Can be used to approve orders over the API to allow partners to perform automated testing. CANCEL Allowed if order has not been completed and for Verisign and thawte SSL certs issued within refund period. Supported for all orders to allow partners to simulate normal order scenarios for testing purposes. Allowed for Verisign and thawte SSL certs issued within 30 days. GeoCerts Confidential 36

40 5.5.7 Order State The new SSL Ordering architecture is based on an order state matching to assist in order processing. Depending on the product, different order states are possible and the following table contains all of the possible states. The non-transient order states are in bold the other states will rarely be encountered. Order State Status Minor State Description WF_DOMAIN_APPROVAL_ADDRESS <ORDER_WAITING_FOR_APPROVAL> Waiting for change of WHOIS approval address WF_DOMAIN_APPROVAL_ <ORDER_WAITING_FOR_APPROVAL> Waiting for sending of WHOIS approval DOMAIN_APPROVAL_ _FAILED <ORDER_WAITING_FOR_APPROVAL> Failed sending WHOIS approval WF_DOMAIN_APPROVAL <ORDER_WAITING_FOR_APPROVAL> Order Waiting For Approval WF_SECURITY_REVIEW <ORDER_QUEUED> Waiting for Security review SECURITY_REVIEW_FAILED <ORDER_QUEUED> Failed Security Review WF_MANUAL_VETTING <WAITING_FOR_GT_APPROVAL> Waiting for Manual Vetting WF_VETTING_REVIEW <WAITING_FOR_GT_APPROVAL> Waiting for Vetting Review This means that the applicant chose the Other Approver option for the WHOIS approver address. Customer support needs to change the approver address to a real approver address and then kick the order to move it to the next state. Orders usually don t stay in this state for long, either. As soon as the order gets into this state, the system tries to send the approval . If successful, the order moves into the WF_DOMAIN_APPROVAL state. Otherwise, order will be in the DOMAIN_APPROVAL_ _FAILED state. Something went wrong when system tried to send the domain approval . Normally this indicates an mis-configuration that needs to be resolved by Customer support. The order is waiting for the domain/whois approver to review and approve the order. The approver should have received an with a link to the approval page Orders don t normally spend any time in this state. When an order gets into this state, the system automatically tries to kick the order to the next state. If any violations are found the order is put into the SECURITY_REVIEW_FAILED state. One or more resource control violations was found when doing security checks. Orders requiring Business vetting by the GeoTrust Customer support team end up in this state when the order is ready to be vetted. Orders can be in this state for as much as several days for EV certificates. After the initial manual vetting is done, the order is placed into this state for a second support person to review and approve. GeoCerts Confidential 37

41 WF_CERTGEN <NONE> Waiting for Cert generation CERTGEN_FAILED <ORDER_QUEUED> Failed cert generation WF_FINALIZATION <NONE> Waiting for Finalization Order is ready for requesting a cert from the CMS. This is done automatically once the order gets into this state. If a cert is obtained successfully, then the order is put into the WF_PAYMENT state. Otherwise, the order is put into the CERTGEN_FAILED state. Usually either a bad CSR, or the CMS was down. The order needs to be processed by GeoTrust Customer support. Finalization is basically everything else that needs to be done after the cert has been obtained: Update the database, send out the receipt and fulfillment s, etc. If any of this fails, the order will remain in this state. The most likely thing to fail is the sending of an because of a configuration problem. COMPLETED <ORDER_COMPLETE> Completed This means that the order was fulfilled successfully and the fulfillment was sent out. Once an order is in this state, it can be reissued. REJECTED <ORDER_CANCELLED> Rejected Either A) One of the approvers/vetters has disapproved this order somewhere along the ordering process, or B) The order has been cancelled. Order has been marked as cancelled and put in the REJECTED state, meaning that no further processing is allowed on this order. Once it has been rejected, it can not be un-rejected Price Computation This is the algorithm for computing the multi-year price. For example, if your 1-year price for QuickSSL is $99 and you want it for 3-years the price would be $99 x 2.5 = $ Years Price Default 1-year price 1 As agreed to 2 1-year price * year price * year price * year price * year price * 4.75 GeoCerts Confidential 38

42 5.5.9 Products The following table defines the supported product SKUs: SKU Value Definition Includes Dynamic Icon QP QuickSSL Premium Yes Q QuickSSL No TBID True BusinessID Yes EV True BusinessID with EV Yes TW True BusinessID Wildcard Yes TBIDMD10 True Biz Multi-Domain 10 Yes TBIDMD15 True Biz Multi-Domain 15 Yes TBIDMD20 True Biz Multi-Domain 20 Yes TBIDMD25 True Biz Multi-Domain 25 Yes T Free Trial (QP) No Renewal Behavior Renewal notices are sent out automatically for the following date intervals. You may elect to disable ALL automatic renewal notices from your Reseller SSL Manager portal and send out your own renewal notices. All reseller s are customizable so that we remain anonymous to your end customers. You may also elect to turn ON or OFF any single date interval (e.g., turn off 90 and -14 days but keep the others). For further granular control you can turn off renewal notices for a single certificate. This is useful for your customers that request not to receive further renewal notices. GeoCerts will send out the standard set of renewal notifications to the certificate order s Admin contact at 89, 60, 30, 14, 7, 1 days before expiration and -7 and -14 days after expiration (if not renewed) Certificate Validity Period <years> The following table defines the supported values for the <years> for each SSL product. SKU Value Definition Max Years QP QuickSSL Premium 6 Q QuickSSL 6 TBID True BusinessID 5 EV True BusinessID with EV 2 TW True BusinessID Wildcard 5 TBIDMD10 True Biz Multi-Domain 10 5 TBIDMD15 True Biz Multi-Domain 15 5 TBIDMD20 True Biz Multi-Domain 20 5 TBIDMD25 True Biz Multi-Domain 25 5 T Free Trial (QP) 1 month GeoCerts Confidential 39

43 GeoCerts Confidential 40

44 Appendix A - Glossary Approver Applicable only for Domain Vetted Orders. The Approver is differentiated from the Requestor. The Approver is an individual who has domain control and has the responsibility for approving the Requestor s request for a Domain Vetted product (such as QuickSSL and EV). Certificate Signing Request (CSR) The Certificate Signing Request (CSR) is a block of information typically generated by the Web Server software that is meant to be submitted to a Certificate Authority (CA) in return for a SSL certificate. The CSR provide the Certificate Authority with the information necessary to generate the SSL Digital Certificate. When the Web Server generates the CSR it is actually generating a Private and Public Key pair. The private key is kept secret and the public key is bundled into the CSR. The CSR is digitally signed by the private key which proves to the CA that the Web Server has possession of the private key (called proof of possession ). Domain Vetting Domain vetting is the GeoTrust patented process for verifying that a Requestor has permission from an Approver to order the product. The Approver must demonstrate control of the domain. QuickSSL is a Domain Vetted product as is EV. The GeoTrust Domain Vetting philosophy is to prove that a server legally represents its domain. What needs to be established is that the domain being ordered (as listed in the certificate request) is legally registered, and that the order is reviewed and approved by an individual that has administrative control over the management or use of the domain. Because domain registrar databases are online, and since the authorized individuals established with the domain registrar are typically the same ones that would apply for a digital certificate, this process can be completely automated. Here is how the patented GeoTrust Domain Vetting process works: 1. The user enters their Certificate Signing Request (CSR), contact information, and billing information into the enrollment form. 2. The user then selects the individual to approve this order. The list of possible addresses is computed dynamically based on the domain name. This list of addresses contains the registered domain administrator and technical contacts as registered with the Registrar (if available). The user can also select from one of the other standard administrative addresses like [email protected] or [email protected]. This works on the theory that more than 95% of the time this is the individual that is requesting the certificate, or is in the loop with this request process and can approve the order in a timely manner. The third option is to select a Manual approval method which results in a GeoTrust individual determining the appropriate address on behalf of the requestor. When this option there will be a delay in fulfilling the order. 3. The system validates the data and sends out the approval message to the specified individual. Typically, the individual enrolling receives the immediately upon submission of the order. 4. When the approver receives the , they can view the special URL that allows them to come to the order approval site to approve the order. Once approved, GeoTrust immediately initiates fulfillment processing unless flagged for a manual security/vetting review. 5. notification is sent to the order Admin. For certificate orders, the GeoTrust-issued certificate is included in the . GeoCerts Confidential 41

45 Operation A function within a Web Service. Synonymous with API function, or method. Organization Vetting Vetting process where verification of corporate identity and ownership of the associated domain is verified as a basis for providing the product to the requestor. Examples of Organization Vetted products include True Business ID. As part of the vetting process, GeoTrust may require the customer to fax their Proof of Organization information and InterNIC record to GeoTrust. This must include the domain name and GeoTrust order ID number on the cover letter. If any of the above items do not match or are not submitted, the processing of the certificate request may be delayed. Acceptable documents for Proof of Organization include: - DUNS number (Dun and Bradstreet) - Articles of Incorporation - Business License - Doing Business As (DBA) registration - Partnership documentation - Sole Proprietorship documentation Government Department, Non-Government Organization, or University, organizations will be asked to generate to provide a special letter in lieu of Proof of Organization documents. For these two products, Organizational information must consistently match between these 3 sources: 1. The Organization appearing in your "Proof of Organization" documents, DUNS number, or Department of state records. 2. The Registrant listed in the InterNIC/WHOIS records for the domain name in question 3. The Organization entered into the CSR (Certificate Signing Request) if you ordered a True BusinessID certificate Once a request has successfully passed the authentication process, the certificate is generated and issued to the Admin contact listed in the order. Requestor Most applicable in Domain Vetted orders. The Requestor is the end user requesting the SSL certificate. This role is differentiated from the Approver. In Domain Vetted Orders the Requestor selects the approver address from a list of authoritative addresses. Vetting The process of verifying something. For example, with the GeoTrust True Business ID product, GeoTrust vets the validity of the organization name. GeoCerts Confidential 42

46 Appendix B - Additional Resources This appendix includes additional resources that may assist API client development. This is provided for informational usage only; GeoCerts cannot provide development support for API integrators. A.1. GeoCerts Ruby GEM The GeoCerts Ruby GEM library provides a Ruby interface to the GeoCerts REST API. This API allows you to manage (lookup, create, and verify) your GeoCerts orders, events, certificates, and more. It makes developing your own branded SSL store super easy. Visit for more information. The source code is available at B.1. curl curl is a free and open source command line tool for transferring a data file with URL syntax. It can be useful for testing your API interface and validating API request data. Visit for more information. C.1. OpenSSL OpenSSL is a free and open source command line tool useful for generating and reading private keys, CSRs, and self-signed certificates. Visit for more information. GeoCerts Confidential 43