Enabling coerced get-entries

On March 2nd, 2020 the Oak CT log will return fewer certificates to some get-entries requests in an attempt to align log monitor requests on a common set of cacheable URLs. No action on your part should be required.

The certificate-transparency-go developers state:

Calls to get-entries which are at (or above) the maximum permitted number of
entries whose start parameter does not fall on a multiple of the maximum
permitted number of entries, will have their responses truncated such that
subsequent requests will align with this boundary.

This is intended to coerce callers of get-entries into all using the same
start and end parameters and thereby increase the cachability of
these requests.

Right now, Oak and Testflume will return at most 256 leaves in response to each get-entries request. If a client requests more than the maximum batch size, their request is pruned back to the maximum batch size. If you request less than 256 leaves, you’ll receive less than 256 leaves. This is an example of the current behavior:

            255       511       767
Entries>-----|---------|---------|----...
Client A -------|---------|----------|...
Client B --|--------|---------|-------...
           ^    ^   ^     ^   ^
           `----`---`-----`---`---- Requests

# Request within the maximum batch size boundary
 $ curl -s https://oak.ct.letsencrypt.org/2020/ct/v1/get-entries?start=0\&end=255 | jq -r '.entries[].leaf_input' | wc -l
256

# Request in excess of the maximum batch size
$ curl -s https://oak.ct.letsencrypt.org/2020/ct/v1/get-entries?start=0\&end=257 | jq -r '.entries[].leaf_input' | wc -l
256

Once we enable the coercion feature, the behavior will change to the following. If a client requests leaves between boundaries, their request will be clipped to the closest boundary.

            255       511       767
Entries>-----|---------|---------|----...
Client A ----X---------|---------|...
Client B --|-X---------|---------|-------...
             ^
             `-- Requests clipped to the closest boundary

# Request within the maximum batch size boundary
 $ curl -s https://oak.ct.letsencrypt.org/2020/ct/v1/get-entries?start=0\&end=255 | jq -r '.entries[].leaf_input' | wc -l
256

# Request split between two boundaries
$ curl -s https://oak.ct.letsencrypt.org/2020/ct/v1/get-entries?start=254\&end=510 | jq -r '.entries[].leaf_input' | wc -l
2
3 Likes

This change has been deployed to our staging Testflume log.

2 Likes

This change has been deployed to our production Oak log.

2 Likes