API Key Rotation

API Key Rotation is a security mechanism designed to enhance the safety of your API by periodically changing the cryptographic keys used to encrypt and decrypt API keys. This process involves a seamless transition from an old key to a new one, ensuring minimal disruption to your API consumers while increasing security.

This document explains how to activate and configure API Key Rotation in your Django project using the package, detailing the inner workings of the rotation process.

Key Rotation Overview

API Key Rotation in the rest_framework_simple_api_key package involves periodically changing the encryption keys used to secure API keys. During rotation, a new key is introduced, and both the old and new keys are used for a transition period. This ensures that existing API keys remain valid while new keys are encrypted with the fresh key.

Activation

Before activating a rotation, ensure to set the rotating Fernet key ROTATION_FERNET_SECRET in the settings of the package.

You will need to add the rotation app rest_framework_simple_api_key.rotation in the INSTALLED_APPS Django setting of your project.

INSTALLED_APPS=(
     ...
     "rest_framework",
     "rest_framework_simple_api_key",
     "rest_framework_simple_api_key.rotation", # added app
 )

And you will need to run the migrate command:

python manage.py migrate rest_framework_simple_api_key_rotation

To activate API Key Rotation, you can choose one of the following methods:

Using Django Management Command

Open your terminal.
Run the following Django management command to start the key rotation:
```
python manage.py rotation
```
This command initializes the rotation process, creating a rotation object, setting the is_rotation_enabled flag to True in the database.
To stop the rotation, execute the following command:
```
python manage.py rotation --stop
```
This command disables the rotation process by setting the is_rotation_enabled flag to False of the latest rotation object with
is_rotation_enabled to False.

Using Django Admin Interface

Access your Django Admin Interface.
Navigate to the “API Key Rotation” section.
To activate rotation, create a new rotation entry by clicking the “Add” button to create a new rotation object.
To deactivate rotation, edit the rotation entry and set the is_rotation_enabled flag to False.

How Rotation Works

API Key Rotation operates through several key phases to ensure a smooth transition while maintaining the security of your API keys.

Key Rotation Phases

Initialization Phase: Rotation begins when you activate it using the methods mentioned above.
Transition Phase: During this phase, both the old and new keys are active. Existing API keys continue to work, and new keys are encrypted using the new key.
Completion Phase: After a defined period (ROTATION_PERIOD), the old key is no longer used. New API keys are encrypted exclusively with the new key. For this purpose, you will need to manually interchange values of ROTATION_FERNET_SECRET and FERNET_SECRET.

Key Usage During Rotation

Decryption: API keys can be decrypted using either the old or new key during the transition phase, ensuring that existing keys remain valid.
Encryption: During rotation, new API keys are encrypted using the new key to ensure enhanced security.