DigiCert® SSLTools API

VERSION 1.0
Table of Contents
Change Log .............................................................................................................................4
DigiCert SSLTools API Reference Guide ............................................................................5
Legal Notice ........................................................................................................................5
Introduction .............................................................................................................................6
API Basics ...........................................................................................................................6
Usage Guidelines ...............................................................................................................6
Requests..............................................................................................................................6
Base URL .........................................................................................................................6
Method .............................................................................................................................6
Endpoint...........................................................................................................................6
Body..................................................................................................................................6
Validation .........................................................................................................................7
Example cURL request..................................................................................................7
Responses...........................................................................................................................7
Headers ...........................................................................................................................7
Successful Response........................................................................................................8
Error Response ...................................................................................................................8
Endpoints .................................................................................................................................9
Certificate Information ......................................................................................................9
Endpoint Location ..........................................................................................................9
URL Parameters .............................................................................................................9
Response Body ..............................................................................................................9
Sample Request and Response ............................................................................... 10
Server Configuration ...................................................................................................... 11
Endpoint Location ....................................................................................................... 11
URL Parameters .......................................................................................................... 11
Response Body ........................................................................................................... 11
Sample Request and Response ............................................................................... 12
Vulnerability Checks ....................................................................................................... 13
Endpoint Location ....................................................................................................... 13
URL Parameters .......................................................................................................... 13
 Response Body ........................................................................................................... 13
Sample Request and Response ............................................................................... 14
Domain Validation .......................................................................................................... 15
Endpoint Location ....................................................................................................... 15
URL Parameters .......................................................................................................... 15
Response Body ........................................................................................................... 15
Sample Request and Response ............................................................................... 15
Object Details ....................................................................................................................... 17
certList .............................................................................................................................. 17
info ..................................................................................................................................... 18
protocols........................................................................................................................... 18
extensions ........................................................................................................................ 18
Errors and Alerts.................................................................................................................. 20
Errors ................................................................................................................................. 20
Alerts ................................................................................................................................. 21
Change Log Page 4

Change Log
Date Changes Version
2018-07-25 • Added the following endpoints and related information: 1.0
o Certificate Information
o Server Configuration
o Vulnerability Checks
o Domain Validation
DigiCert SSLTools API Reference Guide Page 5

DigiCert SSLTools API Reference Guide

The software described in this book is furnished under a license agreement and
may be used only in accordance with the terms of the agreement.

Document creation date and version: July 27, 2018; v1.0

Legal Notice
Copyright © 2018 DigiCert, Inc. All rights reserved.

DigiCert and its logo are registered trademarks of DigiCert, Inc. Symantec and Norton and their
logos are trademarks used under license from Symantec Corporation. Other names may be
trademarks of their respective owners.

The product described in this document is distributed under licenses restricting its use,
copying, distribution, and decompilation/reverse engineering. No part of this document may
be reproduced in any form by any means without prior written authorization of DigiCert, Inc.
and its licensors, if any.

THE DOCUMENTATION IS PROVIDED "AS IS" AND ALL EXPRESS OR IMPLIED CONDITIONS,
REPRESENTATIONS AND WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE
DISCLAIMED, EXCEPT TO THE EXTENT THAT SUCH DISCLAIMERS ARE HELD TO BE
LEGALLY INVALID. DIGICERT, INC. SHALL NOT BE LIABLE FOR INCIDENTAL OR
CONSEQUENTIAL DAMAGES IN CONNECTION WITH THE FURNISHING, PERFORMANCE, OR
USE OF THIS DOCUMENTATION. THE INFORMATION CONTAINED IN THIS
DOCUMENTATION IS SUBJECT TO CHANGE WITHOUT NOTICE.

The licensed software and accompanying documentation are deemed to be commercial

computer software as defined in FAR 12.212 and subject to restricted rights as defined in FAR
Section 52.227-19 "Commercial Computer Software - Restricted Rights" and DFARS 227.7202,
"Rights in Commercial Computer Software or Commercial Computer Software
Documentation", as applicable, and any successor regulations. Any use, modification,
reproduction release, performance, display or disclosure of the licensed software and
accompanying documentation by the U.S. Government shall be solely in accordance with the
terms of the applicable license agreement.

DigiCert, Inc.
2801 North Thanksgiving Way Ste. 500
Lehi, Utah, 84043
https://www.digicert.com
Printed in the United States of America.
10 9 8 7 6 5 4 3 2 1
Introduction Page 6

Introduction

API Basics
All API requests are submitted via RESTful URLs using REST features including
JSON request types. The character set encoding of data in API calls and
responses is UTF-8.

Usage Guidelines
Rate limits are put in place to prevent abuse and may be changed in the future
without notice. If you exceed the rate limit or otherwise abuse the service, the
DigiCert Rest API may stop working for you temporarily.

Requests
Requests consist of two or three parts: method, endpoint, and body. The default
format of the body is application/json, which should be specified in the Content-
Type header sent, if applicable.

Base URL
Use this base URL when constructing API requests.

https://ssltools.digicert.com/chainTester/webservice

Method
All API endpoints use the standard HTTP GET method.

Endpoint
Each endpoint has a unique resource address that is added to the base URL of the
API.

Body
Generally, GET requests do not require sending formatted data. If an endpoint
supports a format other than JSON, it will be noted in the documentation. All
endpoints require passing the domain URL parameter. Additional URL parameters
are optional and can be used to filter results.
Introduction Page 7

Validation
The following endpoint URL parameters are not accepted and will return error
responses:

1. Invalid ports (i.e., out of range and non-integer ports)

2. Ports not in the supported port list
3. Empty domains, null domains, or invalid URLs (according to the Apache
Commons URL Validator)

Example cURL request

This cURL request hits the Certificate Information endpoint and passes two URL
parameters: domain and port.

curl -i
"https://ssltools.digicert.com/chainTester/webservice/cert/info?domain=w
ww.digicert.com.com&port=443"

Responses
Responses consist of two parts: headers and body. The body will always be in
JSON format with a content type of application/json.

Headers
Every response will include an appropriate HTTP response code. This header is
based on the RFC 2616 specification.

Code Description
200 OK: General success response.
201 Created: The request resulted in the creation of an entity. The resulting entity may be
obtained via a subsequent retrieval request.
202 Accepted: The request has been accepted for processing. The final status (success or
failure) must be checked at the appropriate endpoint for the created resource.
204 No Content: For successful requests that don't require a response.
400 Bad Request: The request has missing or invalid parameters.
401 Unauthorized: The request did not include an authentication header or the API key is
invalid.
404 Not Found: The processing for the resource has not yet completed.
406 Not Acceptable: The Accept header was not supplied in the request or the type is not
supported.
412 Precondition Failed: The fields in the request are not valid.
415 Unsupported Media Type: The Content-Type of the request body is not supported.
Introduction Page 8

500 Internal Server Error: Unexpected behavior from which the API couldn't recover.

Successful Response
All success responses will return an HTTP code in the 200–399 range. Clients
receiving these response codes will know that their request was successfully
handled and can expect an appropriate response.

Error Response
Error responses will return an HTTP code of 400 or above. Clients receiving these
headers know that their request failed for various reasons. The API should always
return a 500 error if there was a fatal error that wasn't caught.
Endpoints Page 9

Endpoints

Certificate Information
Use this endpoint to obtain information about a domain’s certificate. The response
body contains data about the certAlgList and serverCertAlgList fields in a JSON
response.

Info: The codes array of this endpoint contains alerts relating only to certificate
information. In the previous monolithic SSL Tools, the codes array
contained alerts corresponding to all services.

Endpoint Location
Method Resource
GET /cert/info

URL Parameters
Parameter Req/Opt Type Description
?domain={domain} required string The domain to query (e.g., www.digicert.com).
Strings starting with “[“ are not accepted.
&port={port} optional string Port number to use. Valid port numbers are 80,
443, 465, 993, 995, 8008, 8080, 8443, 8888.
Note: Uses port 443 if omitted.

Response Body
Parameter Type Description
data object Container for the certAlgList and serverCertAlgList array
of objects.
.. certAlgList array of Container for certificate details.
objects
.. .. codes array of List of alerts related only to certificate information. (See
strings Errors and Alerts.)
Note: Other alert types can be found in other endpoints.
.. .. algorithm string Encryption algorithm used to generate the certificate keys.
.. .. certList array of Container for details about each certificate in the chain.
objects (See certList.)
.. serverCertAlgList array of Container for server certificate details.
objects
.. .. algorithm string Encryption algorithm used to generate the certificate keys.
Endpoints Page 10

.. .. certList array of Container for details about each certificate in the chain.
objects (See certList.)
responseStatus object Container for status information and error messages.
.. status string Status of the domain validation request. Possible values
are SUCCESS and ERROR.
.. messages array of List of errors or alerts that occurred during the request.
strings (See Errors and Alerts.)
.. redirectURL string Blank
(Populated only when using the Domain Validation
endpoint.)

Sample Request and Response

Request
curl -i
"https://ssltools.digicert.com/chainTester/webservice/cert/info?domain=w
ww.digicert.com&port=443"

Response
Status code: 200

Content-Type: application/json

Body:
{
"data": {
"certAlgList": [
{
"algorithm": "RSA",
"certList": [
...

]
}
],
"serverCertAlgList": [
{
"algorithm": "RSA",
"certList": [
...
]
}
]
},
"responseStatus": {
"status": "SUCCESS",
"messages": [],
Endpoints Page 11

"redirectUrl": ""
}
}

Server Configuration
Use this endpoint to obtain server configuration information for the specified
domain. Alerts regarding unsafe protocol settings and enabled TLS extensions are
also included.

Info: This information was previously found in the sslConfig object of the
monolithic SSL Tools JSON response. Vulnerability data is not included
with this endpoint. Use the Vulnerability Checks endpoint instead.

Endpoint Location
Method Resource
GET /server/config

URL Parameters
Parameter Req/Opt Type Description
?domain={domain} required string The domain to query (e.g., www.digicert.com).
Strings starting with “[“ are not accepted.
&port={port} optional string Port number to use. Valid port numbers are 80,
443, 465, 993, 995, 8008, 8080, 8443, 8888.
Note: Uses port 443 if omitted.

Response Body
Parameter Type Description
data object Container for the certAlgList and serverCertAlgList
array of objects.
.. alerts array of List of alerts caused by server configuration. (See
strings Errors and Alerts.)
.. info object Container for information about the server.
.. protocols object Container for the enabled and notEnabled protocol
arrays. (See protocols.)
.. enabledCipherSuites array of List of enabled cipher suites. Values in the array contain
strings the common cipher suit name and cipher id.
.. extensions object Container for details about the server’s extension
configuration. (See extensions.)
responseStatus object Container for status information and error messages.
Endpoints Page 12

.. status string Status of the domain validation request. Possible

values are SUCCESS and ERROR.
.. messages array of List of errors or alerts that occurred during the request.
strings (See Errors and Alerts.)
.. redirectURL string Blank
(Populated only when using the Domain Validation
endpoint.)

Sample Request and Response

Request
curl -i
"https://ssltools.digicert.com/chainTester/webservice/server/config?doma
in=www.digicert.com&port=443"

Response
Status code: 200

Content-Type: application/json

Body:
{
"data": {
"alerts": [],
"info": {
...
},
"protocols": {
"enabled": [
...
],
"notEnabled": [
...
]
},
"enabledCipherSuites": [
"TLS_RSA_WITH_AES_256_CBC_SHA (0x0035)",
"TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA (0xC013)",
"TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA (0xC014)",
"TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 (0xC027)",
"TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 (0xC028)",
"TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 (0xC02F)",
"TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 (0xC030)"
],
"extensions": {
...
}
Endpoints Page 13

},
"responseStatus": {
"status": "SUCCESS",
"messages": [],
"redirectUrl": ""
}
}

Vulnerability Checks
Use this endpoint to obtain information about the vulnerability status of the most
common TLS/SSL vulnerabilities for the specified domain.

Info: This information was previously found in the sslConfig object of the
monolithic SSL Tools JSON response.

Endpoint Location
Method Resource
GET /vulnerabilities/all

URL Parameters
Parameter Req/Opt Type Description
?domain={domain} required string The domain to query (e.g., www.digicert.com).
Strings starting with “[“ are not accepted.
&port={port} optional string Port number to use. Valid port numbers are 80,
443, 465, 993, 995, 8008, 8080, 8443, 8888.
Note: Uses port 443 if omitted.

Response Body
Parameter Type Description
data object Container for vulnerability statuses.
.. codes array of List of vulnerability alert codes. (See Errors and Alerts.)
strings
.. crime Boolean Identifies if the server is susceptible to the specified
vulnerability.
.. freak Boolean Identifies if the server is susceptible to the specified
vulnerability.
.. beast Boolean Identifies if the server is susceptible to the specified
vulnerability.
Endpoints Page 14

.. poodleTLS string Identifies if the server is susceptible to the specified

vulnerability.
.. poodleSSLv3 Boolean Identifies if the server is susceptible to the specified
vulnerability.
.. heartbleed Boolean Identifies if the server is susceptible to the specified
vulnerability.
.. drown Boolean Identifies if the server is susceptible to the specified
vulnerability.
responseStatus object Container for status information and error messages.
.. status string Status of the domain validation request. Possible values
are SUCCESS and ERROR.
.. messages array of List of errors or alerts that occurred during the request.
strings (See Errors and Alerts.)
.. redirectURL string Blank
(Populated only when using the Domain Validation
endpoint.)

Sample Request and Response

Request
curl -i
"https://ssltools.digicert.com/chainTester/webservice/vulnerabilities/al
l?domain=www.digicert.com&port=443"

Response
Status code: 200

Content-Type: application/json

Body:
{
"data": {
"codes": [],
"crime": false,
"freak": false,
"beast": false,
"poodleTLS": "FALSE",
"poodleSSLv3": false,
"heartbleed": false,
"drown": false
},
"responseStatus": {
"status": "SUCCESS",
"messages": [],
"redirectUrl": ""
Endpoints Page 15

}
}

Domain Validation
Use this endpoint to validate a domain name. Domains are validated based on the
Apache Commons URL Validator.

Endpoint Location
Method Resource
GET /domain/validate

URL Parameters
Parameter Req/Opt Type Description
?domain={domain} required string The domain to query (e.g., www.digicert.com).
Strings starting with “[“ are not accepted.
&port={port} optional string Port number to use. Valid port numbers are 80,
443, 465, 993, 995, 8008, 8080, 8443, 8888.
Note: Uses port 443 if omitted.

Response Body
Parameter Type Description
status string Status of the domain validation request. Possible values
are SUCCESS and ERROR.
messages array of List of errors that occurred. (See Errors and Alerts.)
strings
redirectUrl string Displays the redirected URL of the domain.

Sample Request and Response

Request
curl -i
"https://ssltools.digicert.com/chainTester/webservice/domain/validate?do
main=www.digicert.com&port=443"

Response
Status code: 200

Content-Type: application/json
Endpoints Page 16

Body:
{
"status": "SUCCESS",
"messages": [],
"redirectUrl": "www.digicert.com"
}
Object Details Page 17

Object Details
Details about elements inside response objects.

certList
Container of certificate objects in the Certificate Information endpoint response
body. Each certificate object contains detailed information about the certificate.

Parameter Type Description

certType string The certificate type (i.e., End-Entity, Intermediate,
Root, Cross-Signed Root, etc.).
issuedByOrg array of Certificate authority that issued the certificate.
strings
issuedByCommonName array of Signing root certificate.
strings
issuedByCountry array of Certificate authority’s county of origin.
strings
serialNumberHex string Unique certificate serial number assigned by the
certificate authority.
fetchType string Method for getting the certificate (e.g., “Certificate
from server”).
revocationCheckModel object Container for info about OCSP and CRL checks.
.. ocspCheck object Container for OCSP check details.
.. crlCheck string Status of CRL check.
productType string Certificate validation type (e.g., OV).
sctPresent integer Signed Certificate Timestamp configuration.
• 2 – SCT not embedded in certificate.
• Any other # – SCT embedded in certificate.

O array of Name of the organization that was issued the

strings certificate.
OU array of Organization unit on the certificate.
strings
CN array of Common name on the certificate (e.g.,
strings www.digicert.com).
L array of Locality (i.e., city) of the organization.
strings
C array of Organization’s country of origin.
strings
Object Details Page 18

S array of State/province of the organization.

strings
validFrom string Date when the certificate is valid.
validTo string Expiration date of the certificate.
sigAlg string Signature algorithm used by the certificate.
keyLength string Size of the encryption key (i.e., number of bits).
sanList string Comma-separated list of subject alternative names.
revocationDetails object Container for details about certificate revocation.
.. method string Method used to revoke certificate.
.. status string Status of the revocation check.
.. reason string If revoked, reason for certificate revocation.

info
Object in the Server Configuration endpoint response body.

Parameter Type Description

portNumber integer Port number used in the scan.
ipAddress string IPv4 address of the server.
httpServerSignature string Web server platform used by the server (e.g., Apache).
serverName string Friendly name or IPv4 address of the server.

protocols
Object in the Server Configuration endpoint response body that contains the
enabled and notEnabled protocol arrays.

Parameter Type Description

enabled array of Enabled SSL and TLS protocol versions (e.g., TLS1.2).
strings
notEnabled array of Disabled SSL and TLS protocol versions (e.g., SSLv2).
strings

extensions
Object in the Server Configuration endpoint response body. Contains information
about whether or not the specified TLS extension or tool is enabled (true) or
disabled (false).
Object Details Page 19

Parameter Type Description

rc4CipherSupport Boolean RC4 cipher suit support status.
npn Boolean Next Protocol Negotiation status.
heartbeat Boolean Heartbeat extension status.
compression Boolean Compression extension status.
sessionCache Boolean Specifies whether or not TLS sessions are cached.
sessionTickets Boolean Specifies whether or not clients cache TLS session
tickets.
secureRenegotiation Boolean TLS renegotiation support status.
ocspStapling Boolean Specifies whether or not the server handles the OCSP
query.
downgradeAttackPrevention string Specifies whether or not the server allows TLS version
downgrading.
hsts string Specifies whether or not HTTP Strict Transport
Security (HSTS) is enabled. If enabled, the max-age is
also displayed.
Errors and Alerts Page 20

Errors and Alerts

Errors describe problems with the sent request or with information in the response
body from the specified domain. Alerts describe problems with server
configurations and issues that may affect website trust and stability.

Errors
Below are descriptions for the errors you can receive in the response body.

Error Description
error.applet_canceled Applet error.
error.applet_block_or_applet_exception
error.applet_not_loaded Java plug-in error.
error.cert_expired The certificate has expired.
error.cert_revoked Revoked certificate found.
error.revoked
error.cert_selfSigned Self-signed certificate installed.
error.cn_or_san_mismatch Wrong certificate installed.
error.default Network connection error.
error.failed Connection error.
error.g5_root Wrong root certificate on server.
error.generic_java_install URL not found.
error.heart_bleed_vulnerable Server at risk to the specified vulnerability.
error.poodle_tls_vulnerable
error.poodle_vulnerable
error.freak_vulnerable
error.Drown_vulnerable
error.hostname_mismatch Could not determine the primary certificate for the web
server.
error.incorrect_CRL_distribution Problem with the certificate chain.
error.invalid_ip Domain is using an IPv6 address. Currently, only IPv4 is
supported. If possible, configure a DNS A Record to point
it to a Fully Qualified Domain Name (FQDN) instead.
error.invalid_issuer Certificate issuer is invalid.
error.invalid_port Port value error. URL port parameter only accepts
numbers between 1 and 65525.
error.invalid_external_port Invalid server port number. Valid port numbers are 80,
443, 465, 993, 995, 8008, 8080, 8443, 8888.
error.invalid_start_date Invalid certificate validFrom date.
Errors and Alerts Page 21

error.invalid_url Invalid URL.

error.less_java_version Java update required.
error.missing_ica Intermediate certificate missing.
error.missing_ica_no_cert
error.multi_ee_certs Multiple certificates were found with the same common
name.
error.no_root Missing/invalid root certificate.
error.invalid_root
error.nonssl SSL connection could not be made.
error.peer_verify No certificates found on the web server.
error.socketIO
error.RSA_missing_ica The specified intermediate certificate type is missing.
error.DSA_missing_ica
error.ECC_missing_ica
error.socket_timeout The connection has timed out due to problems with the
web server or the way the query is constructed.
error.url_too_long Issue with the URL length.
error.url_too_short
error.wrong_hostname Domain or hostname not found.
error.wrong_domainname
error.wrong_order Certificates installed in the wrong order.

Alerts
Below are descriptions of the alerts you can receive in the response body.

Alert Description
alert.non_symc_cert Certificate not issued by DigiCert, Symantec, GeoTrust,
Thawte, or RapidSSL
alert.handshake_failure TLS handshake failure.
alert.invalid_ee_algorithm Browser compatibility at risk due to certificate using a
SHA-1 hash algorithm.
alert.crl_revocation Certificate status could be outdated.
alert.revocation_failed Certificate revocation check failed.
alert.multi_root Multiple root certificates found.
alert.remove_root_from_server Root installed on the server.
alert.update_cert_chain Certificate chain should be updated.
alert.heart_bleed_unresolved Unable to scan for Heartbleed vulnerability.
alert.poodle_tls_unresolved Unable to scan for Poodle TLS vulnerability.
alert.freak_unresolved Unable to scan for freak vulnerability.
Errors and Alerts Page 22

alert.remove_cross_cert Cross intermediate certificate installed on server.

alert.Beast_vulnerable Server vulnerable to Beast.
alert.Crime_vulnerable Server vulnerable to CRIME.
alert.RC4_failure RC4 cipher algorithm enabled. Disable the unsecure
algorithm.
alert.SSLv2_failure SSLv2 protocol enabled. Disable the unsecure protocol.
alert.SSLv3_failure SSLv3 protocol enabled. Disable the unsecure protocol.
alert.tls_1_2_failure Server vulnerable to TLS renegotiation attack.