Protocol Details
Calling the API
Current API calls are made through GET requests to 'http://signaturecheck.org/apiV1.php'.
The API expects an IP address(or hostname) and a random client variable.
The IP/hostname is set with the 'url' variable. (e.g. http://signaturecheck.org/apiV1.php?url=66.102.7.99)
Note: Using IP addresses is suggested to prevent DNS load balancing from directing SignatureCheck.org's request to a different server.
While different SSL certificates for the same site is unusual, it's not impossible.
The client random variable is optional, but it's heavily recommended to detect replay attacks,
as it is included in the protected hash value. This random string is set with the 'cnonce' variable.
(e.g. http://signaturecheck.org/apiV1.php?url=google.com&cnonce=9asd0ufa0sudf43398jot09d)
The API has an additional optional GET variable that named 'flushcache'.
This is because the service caches thumbprints for several hours to handle subsequent requests for the same site.
If a website does change its certificate in this time frame, it would cause a thumbprint mismatch on the client.
This flushcache value can be set to clear the cache for a requested site.
In implementation, only request that a cache be cleared upon a second request after a thumbprint mismatch is detected.
The API call will return data in an XML format detailed in the next section.
Data Format
A properly formatted call will return XML in the following format.
A root element of "Result" with one child element of "Status".
Even though they may be empty, all of the attributes are always included, even on a site connection failure.
<?xml version="1.0" encoding="utf-8"?>
<Result status="ok|failsiteconnection">
<CertificateInfo site="Requested Website. Set by 'url' in API call."
currentModulus="Modulus value needed to decrypt 'enchash'"
encModulusHash="Encrypted Hash Value of 'currentModulus'. Decrypted with long term Modulus. "
sNonce="Randomly Generated Variable by Server"
cNonce="Random Variable Set with 'cnonce' in API call ('none' if one isn't provided)"
caID="Requested Certificate's Signing Authority's ID"
cID="Requested Certificate ID"
cachehit="yes|no"
sha1thumbprint="Requested Certificate SHA1 Thumbprint"
md5thumbprint="Requested Certificate MD5 Thumbprint"
encHash="encrypted hash data" />
</Result>
The status field of the root element indicates whether or not
SignatureCheck.org could retrieve the certificate from the requested server.
Possible values are ok or failsiteconnection.
This field is protected by encHash.
The site field indicates what the value of url was in the API call.
This field can be used to ensure that the API call wasn't changed in transit.
This field is protected by encHash.
The currentModulus field is a 2048-bit modulus in hexadecimal that can
be used in conjunction with the public key of 010001 to decrypt encHash.
This field is protected by encModulusHash.
The encModulus field is an encrypted SHA1 hash of currentModulus. Output is hexadecimal.
This can be decrypted with the long term modulus available on the status page along with the public key
of 010001.
The sNonce field is a random string generated by the server to help protect against cryptographic attacks
on the keys used to encrypt the hash data.
This field is protected by encHash.
The cNonce field is set by the cnonce field in the API request that can be used to verify
that a response is for a given API call.
This field is protected by encHash.
The caID field is the certificate authority identifier for the retrieved certificate. May be null.
This field is protected by encHash.
The cID field is the certificate identifier for the retrieved certificate. May be null.
This field is protected by encHash.
The cachehit field indicates whether or not the retrieved value was from the cache. The flushcache API
call may be made after a first request fails due to a thumbprint mismatch. Possible values are yes or no.
This field is protected by encHash.
The sha1thumbprint field is the SHA1 thumbprint of the retrieved certificate.
This field is protected by encHash.
The md5thumbprint field is the MD5 thumbprint of the retrieved certificate.
This field is protected by encHash.
The encHash is the hexadecimcal output from encrypting the following hash value:
SHA1(md5thumbprint+sha1thumbprint+caID+sNonce+cNonce+MD5(status+site+cID))
The +'s indicate concatenation. This can be decrypted with currentModulus along with the public key 010001.