TheSSLStore REST API The SSL Store REST API v2.18 This Document is for interacting with theSSLStore.com API using REST interface. The REST API allows you to manage all thesslstore.com Products under one roof. 11/27/2017 INDEX Contents INDEX ............................................................................................................................................................ 1 Introduction .................................................................................................................................................. 5 Release Notes ............................................................................................................................................... 9 Basic Integration ......................................................................................................................................... 14 API REFERENCE............................................................................................................................................ 16 CSR Validation Service ............................................................................................................................ 16 Check CSR ............................................................................................................................................ 16 SSL Validation Service ............................................................................................................................. 19 SSL Checker ......................................................................................................................................... 19 WHOIS CHECK Service ............................................................................................................................. 25 Whois Check Service ........................................................................................................................... 25 FREE PRODUCT Service ........................................................................................................................... 28 Claim Free Products ............................................................................................................................ 28 Competitive Upgrade Info ................................................................................................................... 39 HEALTH Service ....................................................................................................................................... 49 Service Status ...................................................................................................................................... 49 Validate Credentials ............................................................................................................................ 51 Validate Token .................................................................................................................................... 53 READY ISSUANCE ORDER Service ............................................................................................................ 58 Ready Issuance: A more efficient way to authenticate and issue SSL certificates ............................. 58 Validate PreAuth Order ....................................................................................................................... 59 New PreAuth Order............................................................................................................................. 79 Get PreAuth Order Status ................................................................................................................... 98 Query PreAuth Order ........................................................................................................................ 110 ORDER Service ....................................................................................................................................... 115 Product Agreement ........................................................................................................................... 115 Approver List ..................................................................................................................................... 124 Download Certificate ........................................................................................................................ 133 1 Download Certificate As ZIP .............................................................................................................. 138 Invite Order ....................................................................................................................................... 143 New Order ......................................................................................................................................... 153 Mid-Term Upgrade............................................................................................................................ 176 Query Order ...................................................................................................................................... 199 Refund Request ................................................................................................................................. 209 Refund Status .................................................................................................................................... 222 Re-Issue ............................................................................................................................................. 235 Resend Email ..................................................................................................................................... 252 Change Approver Email ..................................................................................................................... 256 Order Status ...................................................................................................................................... 259 Validate Order Parameters ............................................................................................................... 274 Vulnerability Scan Request ............................................................................................................... 287 Certificate Revoke Request ............................................................................................................... 291 Certificate PMR Request ................................................................................................................... 295 Get Modified Order Summary .......................................................................................................... 299 Get Symantec Replacement Orders .................................................................................................. 303 PRODUCT Service .................................................................................................................................. 310 Query - Products ............................................................................................................................... 310 SETTINGS Service .................................................................................................................................. 315 SET ORDER CALLBACK ....................................................................................................................... 315 SET PRICE CALLBACK ......................................................................................................................... 317 SET CANCEL NOTFICATION ................................................................................................................ 320 SET EMAIL TEMPLATES ...................................................................................................................... 322 USERS Query Service ............................................................................................................................. 325 Add New User ................................................................................................................................... 325 Add Sub User ..................................................................................................................................... 328 Edit Sub User ..................................................................................................................................... 332 Activate Sub User .............................................................................................................................. 335 Deactivate Sub User .......................................................................................................................... 338 Query Sub Users ................................................................................................................................ 342 User Account Detail .......................................................................................................................... 344 2 SSL Tools Service ................................................................................................................................... 348 SSL Checker ....................................................................................................................................... 348 CSR Decoder ...................................................................................................................................... 352 Certificate Decoder ........................................................................................................................... 354 Certificate Key Matcher .................................................................................................................... 357 SSL Converter .................................................................................................................................... 359 CSR Generator ................................................................................................................................... 362 Why No Pad Lock? ............................................................................................................................ 365 CAA Record Generator ...................................................................................................................... 368 Server Checker .................................................................................................................................. 370 Callback URLs ............................................................................................................................................ 376 Order CallBack ................................................................................................................................... 376 Pricing Callback ................................................................................................................................. 376 Cancel Notification ............................................................................................................................ 377 APPENDIX .................................................................................................................................................. 377 DV Authentication ................................................................................................................................. 377 File Based Authentication ................................................................................................................. 377 DNS Based Authentication ................................................................................................................ 378 E-Mail Based Authentication ............................................................................................................ 380 Product Codes ....................................................................................................................................... 380 Error Codes ........................................................................................................................................... 383 Web Server Types ................................................................................................................................. 384 Date Time Culture List ........................................................................................................................... 386 Test CSRs ................................................................................................................................................... 397 GeoTrust Pre-Production CA 1 .............................................................................................................. 397 GeoTrust Pre-Production CA 2 .............................................................................................................. 398 GeoTrust Pre-Production CA 3 .............................................................................................................. 398 GeoTrust Pre-Production Sub CA 1 ....................................................................................................... 399 Verisign Class 3 Secure Server CA ......................................................................................................... 399 www.verisign.com/CPS Incorp.by Ref.Liability LTD. (c)97 VeriSign ...................................................... 400 Class 3 Public Primary Certificate Authority ......................................................................................... 400 COMODO-[Root] AddTrustExternalCARoot .......................................................................................... 401 3 [Intermediate] Comodo High-Assurance Secure Server CA .................................................................. 401 Glossary ..................................................................................................................................................... 403 4 INTRODUCTION TheSSLStore.com REST API works perfectly over HTTP Protocol. Generally speaking, an API on REST has the following components: 1. URL – A url suggests the action that you want to take over a specific resource 2. HTTP VERBS – GET, POST, PUT, DELETE, etc. – Usually indicates the operation you want to perform over a specific resource. 3. PARAMETERS - Whether it is in GET or POST, it signifies the parameters that need to be passed as arguments over the action you wish to take. 4. RESPONSE – Indicates the response that you can expect after performing a specific action over a specific resource with said collection of parameters. TheSSLStore.com provides 2 URLs for interfacing with it. One for the SANDBOX API, which returns dummy products and the other, is for the LIVE API which actually interacts with your live API. SANDBOX URL: https://sandbox-wbapi.thesslstore.com/rest/ LIVE URL: https://api.thesslstore.com/rest/ If you do not have a Sandbox Environment PartnerCode and AuthToken, please request one at: [email protected] For any comments/suggestions or help, please email [email protected]. For technical samples, please visit our wiki at https://www.thesslstore.com/api/ Common Terms: 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 SSL123). 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 5 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 process for verifying that a Requestor has permission from an Approver to order the product. The Approver must demonstrate control of the domain. For eg : GeoTrust QuickSSL is a Domain Vetted product. Vetting philosophy is to prove that a server legally represents its domain. What needs to be established is that the domain being ordered (either as part of a certificate request, or as a Verified Domain) 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 or Verified Domain site seal, this process can be completely automated. Here is how general Domain Vetting process works : 1. The user enters their Certificate Signing Request (CSR) or requested domain, contact information, and billing information into the enrollment form. 2. The user then selects the individual to approve this order. The list of possible email addresses is computed dynamically based on the domain name. This list of email 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 email 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 email 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 email message to the specified individual. Typically, the individual enrolling receives the email immediately upon submission of the order. 4. When the approver receives the email, 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. 5. Email notification is sent to the order contacts and to the approver (as confirmation). For certificate orders, the GeoTrust-issued certificate is included in the email Operation : A function within a Web Service. Synonymous with API function, or method. 6 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 and all the Verisign products. As part of the vetting process, some vendors may require the customer to fax their Proof of Organization information and InterNIC record to them. This must include the domain name and 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. Generally Acceptable documents for Proof of Organization include: 1. DUNS number (Dun and Bradstreet) 2. Articles of Incorporation 3. Business License 4. Doing Business As (DBA) registration 5. Partnership documentation 6. 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 Organization vetted certificate. Once a request has successfully passed the authentication process, the certificate is generated and issued to the contacts listed in the order REST : REST-style architectures consist of clients and servers. Clients initiate requests to servers; servers process requests and return appropriate responses. Requests and responses are built around the transfer of representations of resources. A resource can be essentially any coherent and meaningful 7 concept that may be addressed. A representation of a resource is typically a document that captures the current or intended state of a resource. The client begins sending requests when it is ready to make the transition to a new state. While one or more requests are outstanding, the client is considered to be in transition. The representation of each application state contains links that may be used next time the client chooses to initiate a new state transition. The name “Representational State Transfer” is intended to evoke an image of how a well-designed Web application behaves: a network of web pages (a virtual state-machine), where the user progresses through the application by selecting links (state transitions), resulting in the next page (representing the next state of the application) being transferred to the user and rendered for their use. REST was initially described in the context of HTTP, but is not limited to that protocol. RESTful architectures can be based on other Application Layer protocols if they already provide a rich and uniform vocabulary for applications based on the transfer of meaningful representational state. RESTful applications maximize the use of the pre-existing, well-defined interface and other built-in capabilities provided by the chosen network protocol, and minimize the addition of new application-specific features on top of it. 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 email address from a list of authoritative email addresses. Vetting : The process of verifying something. For example, with the GeoTrust True Business ID product, GeoTrust “vets” the validity of the organization name. Web Service : A logical grouping of Operations (see definition above). A Web Service can be directly addressed via a URL endpoint. Web Service Description Language (WSDL) : This is the XML that describes the Web Service’s Operations, including the data for input and output. WSDL is not particularly readable by humans and is typically used by development tools to assist the developer when calling a Web Service. For any comments/suggestions or help, please send us an email to [email protected]. For technical samples, please visit our Getting Started section at https://www.thesslstore.com/api/getting- started 8 RELEASE NOTES Ver 2.18 Nov 27, 2017 o The following services have been added: o Server Checker o Get Symantec Replacement Orders o The following product has been added: o Comodo EV Code Signing (comodoevcsc) o Symantec increasing SAN fields maximum to 250 o The following services has been suspended temporarily by Symantec : o Validate PreAuth Order o New PreAuth Order Ver 2.17 Sep 13, 2017 o The following service has been added in SSLTools: o CAA Record Generator Ver 2.16 Jul 12, 2017 o Added the following field to the New Order and Re-Issue request: o CSRUniqueValue o Added the following field to the CSR Validation Service response: o sha256 o DV Authentication process changes for Comodo certificates. For more details Click Here Ver 2.15 Apr 26, 2017 o The following products have been added: o PositiveSSL EV(positiveevssl) o Positive SSL EV Multi-Domain(positiveevmdc) 9