-
Notifications
You must be signed in to change notification settings - Fork 108
Notary Protocol
Notary servers run on 3 ports, by default this is 80, 443 and 4242.
80 is a standard HTTP proxy that will only accept CONNECT requests to destinations of port 4242, and is used for the anonymous notary proxy.
443 and 4242 implement the actual RESTful notary interface over HTTPS. The API is as follows:
- There is one supported "noun," which is 'target', specified as
/target/<host to validate>+<port> - This noun supports the POST verb for validating specific certificate fingerprints, such as
POST /target/<host to validate>+<port>with the following post data:fingerprint=<SHA1 hash fingerprint of the certificate to validate for that host> - This noun also supports the GET verb for retrieving information about seen certificate fingerprints and timestamps, such as
GET /target/<host to validate>+<port>
The type of reply a notary gives is indicated by the HTTP status code.
The notary will reply with a JSON encoded list of fingerprints both on a successful verification and a failed verification. Other errors don't include this fingerprint list in the reply. The client can cache these fingerprints to make future requests unnecessary.
The example below includes only one fingerprint, but a notary may reply
with multiple fingerprints. The signature is valid for the same JSON data,
with the signature and all excess spaces and newlines removed. Basically
the signed data is exactly "{fingerprintList:[...]}" where ... is replaced by
the actual fingerprints.
(Note: The above paragraph seems wrong for the current server implementation. The format of the signed data is whatever json.dumps generates, and it actually generates unnecessary spaces (e.g. after ':' and ','))
{
"fingerprintList":
[
{
"timestamp": {"start": "1312537562", "finish": "1315604078"},
"fingerprint": "51:1F:8E:C6:22:82:5B:ED:A2:75:CB:3E:95:AB:63:7F:69:D3:18:1C"
}
],
"signature": "MHu+jKdTJhRiNqTZleFnTYhKF/l0F4Nch8il/mG4GNoQ911VgLSAv1WICfoZ8E9+GFeNWZJMX6B7dMOVeG/mYbPdm7jH4XvJoIPFT+OoihcS0XjonUXEhYslVbmVviAiIkhESVcuuE1QZwXYHaDY21WBo4UMHBu6bVotx6Y3vgyBeA++5+yKXqVe7Tc+d/1GRcPqMCgYTpFxOTzlRSqceHUNiGx1X1HjUAGb7DqayR75cGtcIjZ9ONc0UBwJq8SYzF/j0DqB7HX4AdRyFyT8qN8ONFh9Vp04plwhuiXTmwiIM3dmDt+lD16D1RDYcPWuWBawQcReP3N82y54ZcEl3g=="
}A reply with status code 200 indicates the notary correctly verified the fingerprint you sent it. In the body of the reply the notary will respond with a JSON encoded list of fingerprints and timestamps the client can cache.
This reply code indicates the fingerprint you sent did not match the fingerprint the notary thinks is correct. As with the 200 reply the notary will include a JSON encoded list of fingerprints.
When a notary can not verify the fingerprint (for example when a notary is configured to verify some property that is not available on the requested host) it will issue this reply. The client will ignore this notaries vote entirely when it calculates the vote result.
This reply is sent when a request does not include a hostname, port or fingerprint. In the body of the reply is a human readable error description.
This reply indicates the notary had some sort of internal error when processing the request. A client should assume the verification failed. In the body of the reply is a human readable error description.