TLS Verifier Help

Requests

Issue an url encoded POST Request to https://master.ayra.ch/TLS/API.aspx.
Fields:

• ip: Required; IP address or DNS name to connect to
• port: Required; Port to connect to
• challenge: Optional; Can be of any value. If not supplied a time stamp is used. We highly recommend that you supply this option and use a random value.
• serialize: Optional; This will encode the Result property in Base64. The value doesn't matter as long as it is supplied. We highly recommend that you use this if you perform automated requests.

Common Ports include: 443(HTTPS), 990(FTPS), 465(SMTP), 993(IMAP), 995(POP3)

Signature

The answer is signed with an RSA key. You can use this to verify, that the answer itself has not been modified. To protect from reply attacks, you can submit a value of your choice as a "challenge". If you do not supply a challenge, the server will use an increasing time stamp. The server will include this value in the signed message.

To verify the signature, take the "Challenge" value from the response and append to it the "Result" value. Verify using the "Signature" value. If the result value gets changed in transport, you can supply serialize=1 (or any other value) to have the "Result" property converted to Base64. In that case you need to decode the property before attempting to verify the signature.

The "Pubkey" value should match the one on this page. If you use the API in your application you should hardcode the Key. You can find it on the bottom of the main page.

The API tries up to two seconds to connect to the supplied destination. If you supply a DNS name that resolves to multiple addresses, each address is tried until one succeeds or all attempts have been made. The API will stop as soon as a connection can be established. It also will not verify if all addresses supply the same certificate chain.

Properly verifying

Below are the steps necessary to properly verify the signature. Abort as soon as a condition is not satisfied.

1. Check the HTTP Status code of the API Answer. It should be 200. A common other value is 400, which happens if you don't use HTTP POST or supply invalid values.
2. Verify that the "Challenge" is the value you submitted to the API.
3. Verify that the "SignatureAlgorithm" value is present and supported by your RSA library.
4. Extract the signature and Base64-decode it.
5. Convert the Result to a string. If you requested a serialized answer, do this by decoding the Base64 value, otherwise serialize the value as JSON without formatting and ensure you don't change the order of the Values.
6. Concatenate Challenge+Result.
7. Verify the signature against our Key. The key can be found on the main page but we recommend hardcoding it. If you are affected by a certificate swap, the key can be swapped too.

Format

The format of the JSON object is as outlined below. The format applies to the regular format. If you choose to serialize the answer, the Answer Property will contain its data base64 encoded.

• Challenge: String; User submitted value (or timestamp)
• SignatureAlgorithm: String; The algorithm that was used to sign the answer.
• Signature: String; Base64 encoded signature of Challenge+Result
• Result: Object; Result of the connection attempt(s)
  • DomainOrIp: String; User supplied Domain or IP Address
  • EndPoint: String; The last attempted endpoint. For established connections, this is the endpoint that delivered the certificate chain. For attempts that failed, this is the last attempted endpoint.
  • AddressList: Array(String); List of all IP addresses returned by the DNS Server. The addresses are in the order our server attempted to connect.
  • ChainOK: Bool; true or false. If true, our server would trust this chain.
  • ErrorMessages: Array(String); Array of strings that describe any errors that might have occured. Some messages might appear multiple times, if multiple IP addresses were tried to connect to and failed.
  • Chain: Array(Object); The certificate chain as supplied by the server. Ordered by the server certificate first and root certificate last.
    • ValidFrom: String; Time from which on this certificate is considered valid
    • ValidTo: String; Last time this certificate is considered valid
    • Subject: String; The combined Subject line of the certificate. For the server certificate, the value prefixed "CN=" is usually the domain/ip the certificate is valid for. Some certificates also have a SAN value that contains multiple names.
    • Issuer: String; The combined Subject Line of the issuer Certificate. This should match the Subject of the next certificate in the chain. If not, the chain might have been delivered out of order. For root certificates, this is Identical to the Suject.
    • Hash: String; Hexadecimal string of the SHA1 hash of the certificate. This supplies a simple way of comparing certificates.
    • KeyBits: Int; How many bits the public key has. For server certificates 4096 should be the minimum value, otherwise the certificate is no longer considered secure by many applications.
    • SAN: Array(String); This is a list of Subject Alternate Names, if any are present. Each entry is prefixed by what type it is (often "DNS-Name").