Skip to content

Latest commit

 

History

History
31 lines (22 loc) · 2.13 KB

README.md

File metadata and controls

31 lines (22 loc) · 2.13 KB

MECO API: Key Management Service (KMS)

Outline

The Key Management Service (KMS) presents a single control point to create and manage cryptographic keys and control their use across the MECO API service. KMS audits all API requests, including key management actions and usage of keys. User passwords and neither raw or hashed API keys are logged. Authorization and authentication into the KMS is token-based - specifically JSON Web Tokens (JWT). Upon signing up or signing in, a bearer token is returned. This token must be sent for each api-keys request within the Authorization header.

Core Actions

KMS provides the following services:

  • Allow users to create, view, update and delete keys.
  • Restrict key access to specific resources by providing scopes.
  • Create resource policies to whitelist certain IP addresses using IPv4 CIDR notation.
  • Allow user to specify a user-friendly key name.
  • Prefix key with a unique id so the user can identify a named key.
  • Provide audit logs of key management actions and API usage.

Key Generation

An API key is a combination of a prefix and a raw key separated by a dot: {prefix}.{raw_api_key}. A key will also have a corresponding name to let the user give a descriptive name. The raw API key is only presented to the user once on creation. From then on, if a user needs to locate a key they can do so with a combination of the prefix and name.

The generation and validation process is as follows:

  1. A UUID is generated using a cryptographically strong pseudo-random number generator.
  2. The UUID is then encoded using the Base64 encoding scheme with padding stripped to create the raw API key.
  3. A strong hash of the raw API key is generated by a BCrypt hashing function. This is stored on the database.
  4. The raw API key is prefixed with a random alphanumeric prefix separated with a dot and returned to the user.
  5. When a user sends their API key with a request:
    1. The prefix is removed leaving the raw API key.
    2. The raw API key is hashed and compared to the hash stored on the database.
    3. If the hash matched then the API key is authentic, otherwise reject the request.