Cert Spotter Whitelisting API

Whitelist Public Key

When you whitelist a public key, Cert Spotter won't notify you about certificates that certify the key. Any certificates for the key that have already been discovered will be removed from your unknown certificates list.

When you whitelist a public key, you must specify which DNS names are authorized to use the key. Cert Spotter will still notify you about certificates that use the key if they are valid for other DNS names.

To whitelist a public key, send a POST request to https://sslmate.com/api/v3/monitoring/known_keys. The posted body can be one of the following:

  • PEM-encoded CSR. If you upload a PEM-encoded CSR with a Content-Type of application/x-pem-file, SSLMate will whitelist the CSR's public key for every DNS name in the CSR's subjectAltName extension.

  • DER-encoded CSR. If you upload a DER-encoded CSR with a Content-Type of application/pkcs10, SSLMate will whitelist the CSR's public key for every DNS name in the CSR's subjectAltName extension.

  • JSON object. You can upload a JSON object with a Content-Type of application/json that contains the following fields:

    • pubkey_sha256 (string): The lowercase hex-encoded SHA-256 hash of the public key to whitelist. The hash is computed over the DER-encoded subject public key info.
    • dns_names (array of strings): The DNS names for which the public key will be whitelisted.

Whitelist Certificate

When you whitelist a certificate, Cert Spotter won't notify you if the certificate is later discovered in a Certificate Transparency log. If Cert Spotter has already discovered the certificate, the certificate will be removed from your unknown certificates list.

There is an inherent race condition when whitelisting certificates - if Cert Spotter has already discovered the certificate by the time you whitelist it, you will have already received a notification. For this reason, we recommend that you whitelist public keys instead, by uploading CSRs to Cert Spotter before you submit them to your certificate authority. If you have to whitelist by certificate, we recommend you do so immediately after receiving the certificate from your certificate authority, to maximize the probability that Cert Spotter has not yet discovered it.

To whitelist a certificate, send a POST request to https://sslmate.com/api/v3/monitoring/known_certs. The posted body can be one of the following:

  • PEM-encoded certificate. If you upload a PEM-encoded certificate with a Content-Type of application/x-pem-file or application/pem-certificate-chain, SSLMate will whitelist the certificate.

  • DER-encoded certificate. If you upload a DER-encoded certificate with a Content-Type of application/pkix-cert, SSLMate will whitelist the certificate.

  • JSON object (for advanced users only). You can upload a JSON object with a Content-Type of application/json that contains the following field:

    • tbs_sha256 (string): The lowercase hex-encoded SHA-256 hash of the TBSCertificate to whitelist. The hash is computed over the "DER-encoded TBSCertificate component of the Precertificate," per RFC6962, Section 3.2.

    Since constructing the TBSCertificate is complex, we recommend uploading a certificate instead of a JSON object.

Authentication

Your API key can be found on your account page.

Authentication examples:

curl -H "Authorization: Bearer 123_sampleapikey" https://sslmate.com/api/v3/monitoring/known_keys

curl -u 123_sampleapikey: https://sslmate.com/api/v3/monitoring/known_keys

Worry Less About Outages and Security Problems

Monitor your certificates with Cert Spotter, so that you, not your boss, will be the one to hear about security and uptime problems.

Click to sign up for Cert Spotter