-
Notifications
You must be signed in to change notification settings - Fork 104
Knox API Server
The Knox API server is the interface for communicating with Knox. The API server runs over HTTPS and exposes several operations regarding the management and use of keys. This section will go over the API exposed by the Knox server using HTTP routes, authentication, authorization, and talk about customizability using HTTP decorators.
These routes are defined in code in server/routes.go. That should be deemed the source of truth, but I’ll go over the routes here as well.
This route is a GET request to /v0/keys/. If the query string is empty, it returns all key IDs stored in Knox. Otherwise it expects the query string to be a list of Key IDs and their current version hash. In this case, it will return a list of key IDs where the version hash is different from the given version hash. This route requires user or machine authentication and provides information about all keys.
This route is a POST request to /v0/keys/. This will create a new key with the given values. It expects form encoded post stat containing an ID for the key ID of the create key, data for the initial primary version of the key (this field is expected to be base64 encoded), and an optional ACL parameter that is a JSON encoded ACL of the key. By default the ACL will be modified to include the creator as an admin for the key and to add any configured default accesses to the key. This route requires user authentication, but has no additional restrictions.
This route is a GET request to /v0/keys/<key_id>/. This will get the key and all associated data in JSON format. This requires that the authenticated principal has read, write, or admin access to the key.
This route is a DELETE request to /v0/keys/<key_id>/. This will delete the key and all version data from knox. This requires that the authenticated principal has admin access to the key.
This route is a PUT request to /v0/keys/<key_id>/access/. This will update the key’s acl by adding access information. This will overwrite any existing access information if the type and id is already present in the ACL for the key.This requires that the authenticated principal has admin access to the key.
This route is a POST request to "/v0/keys/{keyID}/versions/". This is used for adding a new key version to the key id in question. This version will be set to active when added. Data is base64 encoded key data. This requires that the authenticated principal has write or admin access to the key.
This route is a PUT request to "/v0/keys/{keyID}/versions/{versionID}/". This is used for updating the status of a key version. This version status can be Primary, Active, or Inactive. There must be exactly one primary key version at any point in time (the old primary version will become active if primary is selected). This requires that the authenticated principal has write or admin access to the key.
Principals in Knox are classified as user or machines. Authentication of users or machines is accomplished server side via the Authentication decorator which parses the Authorization header and then uses the appropriate handler as defined by the user. I strongly recommend using TLS based authentication for machines and a form of single sign on for user authentication. These will likely need to be tweaked for your organization.
Authorization is done through per-key access control whitelists. These lists contain a principal type, an ID, and the type of access granted.
There are four types of access: Read, Write, Admin, and None. None gives no permissions (used for revoking access; not actually stored in the acl) and the other 3 types of access are described in the routes that use them. They is a hierarchy and Write includes all permissions of Read and Admin includes all permissions of Read and Write.
In terms of principal type, there are four valid values: User, Machine, UserGroup, and MachinePrefix. User and machine means the ID must exactly match the user or machine that authenticates. The authentication provider can set groups for users which allows for role based access. Pinterest uses these groups to correspond to teams through our SSO provider. MachinePrefix has the assumption that hostnames relate to purpose and if the prefix matches the authenticated host it will be succeed. For example if the machine was named “infra-secure-service-a7ef80” and the rule was for Read for MachinePrefix on “infra-secure-service-” that machine would have read access.
When initializing the knox server in code. It requires a list of decorators to be passed in. We use these for visibility, metrics, and adding security headers, but you can use it to override the authentication handlers or customize knox to your liking. These are passed into server.GetRouter and take the form of func(f http.HandlerFunc) http.HandlerFunc. See server/decorators.go for examples.