Feature #2328


Verify and generate permission hints in Keep

Added by Tom Clegg over 10 years ago. Updated about 10 years ago.

Assigned To:
Tim Pierce
Story points:
Release relationship:


The proposed permissions model for Keep is as follows:

A Keep locator string may end with a permission hint in the form "+Asignature@timestamp". If a Keep server is configured to enforce permissions (via the --enforce-permissions flag), then GET requests for blocks must supply a block locator with a valid permission hint. If --enforce-permissions=false, then the server will accept both signed and unsigned locators, and will not attempt to verify signatures.

The signature string here is a cryptographic hash consisting of alphanumeric characters, and timestamp is a 32-bit Unix timestamp expressed as an 8-digit hexadecimal number.

A valid permission hint grants the user the ability to GET that object in Keep.

The permission hint may be generated either by Keep (after the user writes a block) or by the API server (if the user has can_read permission on the specified object). The hint is a SHA-1 hash generated from a combination of a server key (shared by Keep and the API server), the user's API token, and an expiration timestamp.

To verify a permission hint, Keep generates a new hint for the requested object (using the locator string, the timestamp, the permission secret and the user's API token, which must appear in the request headers) and compares it against the hint included in the request. If the permissions do not match, or if the API token is not present, Keep returns a 401 error.

  • Keep server expects each read request to come with an API token (in HTTP headers) and a string +Asignature@timestamp (appended to the block hash)
  • if the timestamp is in the past, 403.
  • if the signature is invalid, 401.
  • Keep server expects each write request to come with an API token (in HTTP headers)
  • Keep server generates a +Asignature@timestamp string and appends it to the hash in the response after a successful PUT
Reference: The following command line arguments are used to configure permission generation and enforcement:
  • --permission-key-file=path specifies a file which contains the permission key. If this argument is supplied, PUT requests will be required to include an OAuth token, and Keep will respond to PUT requests with a signed locator string.
  • --data-manager-token-file=path specifies a file which contains an OAuth token that identifies the Data Manager. Requests that include this OAuth token will be allowed to perform privileged operations (GET /index and DELETE).
  • --enforce-permissions= true/false to enable or disable permission enforcement.
    • If --enforce-permissions=true, the server will reject any GET requests for blocks that lack a valid signature, and will permit GET /index and DELETE requests from the data manager.
    • If --enforce-permissions=false, the server will fulfill GET requests without regard to permission signatures. It will also prohibit GET /index and DELETE requests entirely.
  • --signature-ttl=num_seconds to control expiry time of signatures

Subtasks 5 (0 open5 closed)

Task #2728: Review 2328-keep-permission-hintsResolvedTim Pierce04/30/2014Actions
Task #2653: Permissions command-line flagsResolvedTim Pierce05/05/2014Actions
Task #2652: Keep interface for generating and verifying tokensResolvedTim Pierce04/30/2014Actions
Task #2722: Review 2328-signatures-for-integration-testing branchResolvedTim Pierce04/30/2014Actions
Task #2651: Finalize spec for permissions tokensResolvedTim Pierce04/30/2014Actions

Also available in: Atom PDF