diff --git a/library/php-ssllabs-api/Readme.md b/library/php-ssllabs-api/Readme.md new file mode 100644 index 00000000..7bceeec2 --- /dev/null +++ b/library/php-ssllabs-api/Readme.md @@ -0,0 +1,237 @@ +# PHP-SSLLabs-API +This PHP library provides basic access to the SSL Labs API. + +It's build upon the official API documentation at https://github.com/ssllabs/ssllabs-scan/blob/master/ssllabs-api-docs.md +```PHP +fetchApiInfo()); + +?> +``` +## Methods +### fetchApiInfo() +No parameters needed + +Returns an Info object (see https://github.com/ssllabs/ssllabs-scan/blob/master/ssllabs-api-docs.md#info). + +### fetchStatusCodes() +No parameters needed + +Returns a StatusCodes instance (see https://github.com/ssllabs/ssllabs-scan/blob/master/ssllabs-api-docs.md#statuscodes). + +### fetchHostInformation() +See https://github.com/ssllabs/ssllabs-scan/blob/master/ssllabs-api-docs.md#invoke-assessment-and-check-progress for parameter description. + +| Parameter | Type | Default value | | +|---------------------|---------|---------------|----------| +| **host** | string | | Required | +| **publish** | boolean | false | | +| **startNew** | boolean | false | | +| **fromCache** | boolean | false | | +| **maxAge** | int | null | | +| **all** | string | null | | +| **ignoreMismatch** | boolean | false | | + +Returns a Host object (see https://github.com/ssllabs/ssllabs-scan/blob/master/ssllabs-api-docs.md#host). + +Make sure to check the 'status' attribute inside Host object. + +### fetchHostInformationCached() +You can also use fetchHostInformation() with the proper parameters, this is just a helper function. + +| Parameter | Type | Default value | | +|---------------------|---------|---------------|----------| +| **host** | string | | Required | +| **maxAge** | int | null | | +| **publish** | boolean | false | | +| **ignoreMismatch** | boolean | false | | + +Returns a Host object (see https://github.com/ssllabs/ssllabs-scan/blob/master/ssllabs-api-docs.md#host). + +Also make sure to check the 'status' attribute inside Host object. + +### fetchEndpointData() +See https://github.com/ssllabs/ssllabs-scan/blob/master/ssllabs-api-docs.md#retrieve-detailed-endpoint-information for parameter description. + +| Parameter | Type | Default value | | +|----------------|---------|---------------|----------| +| **host** | string | | Required | +| **s** | string | | Required | +| **fromCache** | boolean | false | | + +Returns an Endpoint object (see https://github.com/ssllabs/ssllabs-scan/blob/master/ssllabs-api-docs.md#endpoint). + +### Custom API calls +Use sendApiRequest() method to create custom API calls. + +| Parameter | Type | Default value | | +|-----------------|--------|---------------|----------| +| **apiCall** | string | | Required | +| **parameters** | array | | | + +```PHP +$api->sendApiRequest('apiCallName', array('p1' => 'p1_value', 'p2' => 'p2_value')); +``` + +### getReturnJsonObjects() +Getter for returnJsonObjects + +### setReturnJsonObjects() +Setter for returnJsonObjects + +| Parameter | Type | Default value | | +|-----------------------|---------|---------------|----------| +| **returnJsonObjects** | boolean | | Required | + +## Example output (as JSON strings) +### Get API information +```PHP +$api->fetchApiInfo(); +``` +```JSON +{ + "engineVersion": "1.15.1", + "criteriaVersion": "2009i", + "clientMaxAssessments": 25, + "maxAssessments": 25, + "currentAssessments": 0, + "messages": [ + "This assessment service is provided free of charge by Qualys SSL Labs, subject to our terms and conditions: https://www.ssllabs.com/about/terms.html" + ] +} +``` + +### Get host information +```PHP +$api->fetchHostInformation('https://www.google.de'); +``` +```JSON +{ + "host": "https://www.google.de", + "port": 443, + "protocol": "HTTP", + "isPublic": false, + "status": "READY", + "startTime": 1427195976527, + "testTime": 1427196284525, + "engineVersion": "1.15.1", + "criteriaVersion": "2009i", + "endpoints": [ + { + "ipAddress": "74.125.239.119", + "serverName": "nuq05s01-in-f23.1e100.net", + "statusMessage": "Ready", + "grade": "B", + "hasWarnings": false, + "isExceptional": false, + "progress": 100, + "duration": 77376, + "eta": 1610, + "delegation": 3 + }, + { + "ipAddress": "74.125.239.120", + "serverName": "nuq05s01-in-f24.1e100.net", + "statusMessage": "Ready", + "grade": "B", + "hasWarnings": false, + "isExceptional": false, + "progress": 100, + "duration": 76386, + "eta": 1609, + "delegation": 3 + }, + { + "ipAddress": "74.125.239.127", + "serverName": "nuq05s01-in-f31.1e100.net", + "statusMessage": "Ready", + "grade": "B", + "hasWarnings": false, + "isExceptional": false, + "progress": 100, + "duration": 76937, + "eta": 1608, + "delegation": 3 + }, + { + "ipAddress": "74.125.239.111", + "serverName": "nuq05s01-in-f15.1e100.net", + "statusMessage": "Ready", + "grade": "B", + "hasWarnings": false, + "isExceptional": false, + "progress": 100, + "duration": 77171, + "eta": 1606, + "delegation": 3 + } + ] +} +``` + +### Get endpoint information +```PHP +$api->fetchEndpointData('https://www.google.de', '74.125.239.111'); +``` + +(just an except of the entire JSON output) +```JSON +{ + "ipAddress": "74.125.239.111", + "serverName": "nuq05s01-in-f15.1e100.net", + "statusMessage": "Ready", + "grade": "B", + "hasWarnings": false, + "isExceptional": false, + "progress": 100, + "duration": 77171, + "eta": 1609, + "delegation": 3, + "details": { + "hostStartTime": 1427195976527, + "key": {}, + "cert": {}, + "chain": {}, + "protocols": [], + "suites": {}, + "serverSignature": "gws", + "prefixDelegation": true, + "nonPrefixDelegation": true, + "vulnBeast": false, + "renegSupport": 2, + "sessionResumption": 1, + "compressionMethods": 0, + "supportsNpn": true, + "npnProtocols": "h2-15 h2-14 spdy/3.1 spdy/3 http/1.1", + "sessionTickets": 1, + "ocspStapling": false, + "sniRequired": false, + "httpStatusCode": 200, + "supportsRc4": true, + "forwardSecrecy": 2, + "rc4WithModern": true, + "sims": {}, + "heartbleed": false, + "heartbeat": false, + "openSslCcs": 1, + "poodleTls": 1, + "fallbackScsv": true + } +} +``` + +# Terms and Conditions +As this is just a PHP library for SSL Labs API please refer to SSL Labs terms and conditions at https://www.ssllabs.com/about/terms.html diff --git a/library/php-ssllabs-api/ssllabsApi.php b/library/php-ssllabs-api/ssllabsApi.php new file mode 100644 index 00000000..32f3d4e4 --- /dev/null +++ b/library/php-ssllabs-api/ssllabsApi.php @@ -0,0 +1,216 @@ + + * @license GNU GENERAL PUBLIC LICENSE v3 + */ + +class sslLabsApi +{ + CONST API_URL = "https://api.ssllabs.com/api/v2"; + + private $returnJsonObjects; + + /** + * sslLabsApi::__construct() + */ + public function __construct($returnJsonObjects = false) + { + $this->returnJsonObjects = (boolean) $returnJsonObjects; + } + + /** + * sslLabsApi::fetchApiInfo() + * + * API Call: info + * @see https://github.com/ssllabs/ssllabs-scan/blob/master/ssllabs-api-docs.md + */ + public function fetchApiInfo() + { + return ($this->sendApiRequest('info')); + } + + /** + * sslLabsApi::fetchHostInformation() + * + * API Call: analyze + * @see https://github.com/ssllabs/ssllabs-scan/blob/master/ssllabs-api-docs.md + * + * @param string $host Hostname to analyze + * @param boolean $publish + * @param boolean $startNew + * @param boolean $fromCache + * @param int $maxAge + * @param string $all + * @param boolean $ignoreMismatch + */ + public function fetchHostInformation($host, $publish = false, $startNew = false, $fromCache = false, $maxAge = NULL, $all = NULL, $ignoreMismatch = false) + { + $apiRequest = $this->sendApiRequest + ( + 'analyze', + array + ( + 'host' => $host, + 'publish' => $publish, + 'startNew' => $startNew, + 'fromCache' => $fromCache, + 'maxAge' => $maxAge, + 'all' => $all, + 'ignoreMismatch' => $ignoreMismatch + ) + ); + + return ($apiRequest); + } + + /** + * sslLabsApi::fetchHostInformationCached() + * + * API Call: analyze + * Same as fetchHostInformation() but prefer to receive cached information + * + * @param string $host + * @param int $maxAge + * @param string $publish + * @param string $ignoreMismatch + */ + public function fetchHostInformationCached($host, $maxAge, $publish = false, $ignoreMismatch = false) + { + return($this->fetchHostInformation($host, $publish, false, true, $maxAge, 'done', $ignoreMismatch)); + } + + /** + * sslLabsApi::fetchEndpointData() + * + * API Call: getEndpointData + * @see https://github.com/ssllabs/ssllabs-scan/blob/master/ssllabs-api-docs.md + * + * @param string $host + * @param string $s + * @param string $fromCache + * @return string + */ + public function fetchEndpointData($host, $s, $fromCache = false) + { + $apiRequest = $this->sendApiRequest + ( + 'getEndpointData', + array + ( + 'host' => $host, + 's' => $s, + 'fromCache' => $fromCache + ) + ); + + return ($apiRequest); + } + + /** + * sslLabsApi::fetchStatusCodes() + * + * API Call: getStatusCodes + */ + public function fetchStatusCodes() + { + return ($this->sendApiRequest('getStatusCodes')); + } + + /** + * sslLabsApi::sendApiRequest() + * + * Send API request + * + * @param string $apiCall + * @param array $parameters + * @return string JSON from API + */ + public function sendApiRequest($apiCall, $parameters = array()) + { + //we also want content from failed api responses + $context = stream_context_create + ( + array + ( + 'http' => array + ( + 'ignore_errors' => true + ) + ) + ); + + $apiResponse = file_get_contents(self::API_URL . '/' . $apiCall . $this->buildGetParameterString($parameters), false, $context); + + if($this->returnJsonObjects) + { + return (json_decode($apiResponse)); + } + + return ($apiResponse); + } + + /** + * sslLabsApi::setReturnJsonObjects() + * + * Setter for returnJsonObjects + * Set true to return all API responses as JSON object, false returns it as simple JSON strings (default) + * + * @param boolean $returnJsonObjects + */ + public function setReturnJsonObjects($returnJsonObjects) + { + $this->returnJsonObjects = (boolean) $returnJsonObjects; + } + + /** + * sslLabsApi::getReturnJsonObjects() + * + * Getter for returnJsonObjects + * + * @return boolean true returns all API responses as JSON object, false returns it as simple JSON string + */ + public function getReturnJsonObjects() + { + return ($this->returnJsonObjects); + } + + /** + * sslLabsApi::buildGetParameterString() + * + * Helper function to build get parameter string for URL + * + * @param array $parameters + * @return string + */ + private function buildGetParameterString($parameters) + { + $string = ''; + + $counter = 0; + foreach($parameters as $name => $value) + { + if(!is_string($name) || (!is_string($value) && !is_bool($value) && !is_int($value))) + { + continue; + } + + if(is_bool($value)) + { + $value = ($value) ? 'on' : 'off'; + } + + $string .= ($counter == 0) ? '?' : '&'; + $string .= urlencode($name) . '=' . urlencode($value); + + $counter++; + } + + return ($string); + } +} \ No newline at end of file