Skip to content

Commit

Permalink
Add docs on key rotation
Browse files Browse the repository at this point in the history
Signed-off-by: Luís Cobucci <[email protected]>
  • Loading branch information
lcobucci committed Nov 4, 2023
1 parent 15d5b75 commit a6afecf
Show file tree
Hide file tree
Showing 3 changed files with 221 additions and 0 deletions.
9 changes: 9 additions & 0 deletions .readthedocs.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
version: 2

build:
os: ubuntu-22.04
tools:
python: 3

mkdocs:
configuration: mkdocs.yml
211 changes: 211 additions & 0 deletions docs/rotating-keys.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,211 @@
# Rotating Keys

Key rotation consists in retiring and replacing cryptographic keys with new ones.
Performing that operation on a regular basis is an industry standard.

## Why should I rotate my keys?

Rotating keys allows us to:

1. Limit the number of tokens signed with the same key, helping the prevention of attacks enabled by cryptanalysis
2. Adopt other algorithms or stronger keys
3. Limit the impact of eventual compromised keys

## The challenges

After rotating keys, apps will likely receive requests with tokens issues with the previous key.
If the key rotation of an app is done with a "hard cut", requests with non-expired tokens issued with the old key **will fail**!

Imagine if you were the user who logged in just before a key rotation on that kind of app, you'd probably have to log in again!

That's rather frustrating, right!?

## Preventing issues

It's possible to handle key rotation in a smoother way by leveraging the `SignedWithOneInSet` validation constraint!

Say your application uses the symmetric algorithm `HS256` with a not so secure key to issue tokens:

```php
<?php
declare(strict_types=1);

namespace MyApp;

require 'vendor/autoload.php';

use DateTimeImmutable;
use Lcobucci\Clock\FrozenClock;
use Lcobucci\JWT\Builder;
use Lcobucci\JWT\JwtFacade;
use Lcobucci\JWT\Signer;
use Lcobucci\JWT\Signer\Key\InMemory;

// `FrozenClock` is used here to fix to a point in time that allows our validation to pass
$clock = new FrozenClock(new DateTimeImmutable('2023-11-04 21:06:01+00:00'));
$token = (new JwtFacade(clock: $clock))->issue(
new Signer\Hmac\Sha256(),
InMemory::plainText(
'a-very-long-and-secure-key-that-should-actually-be-something-else'
),
static fn (Builder $builder): Builder => $builder
->issuedBy('https://api.my-awesome-app.io')
->permittedFor('https://client-app.io')
);
```

!!! Sample
Here's a token issued with the code above, if you want to test the script locally:

<details>
<summary>Sample token</summary>
// line breaks added for readability
eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9
.eyJpYXQiOjE2OTkxMzE5NjEsIm5iZiI6MTY5OTEzMTk2MSwiZXhwIjoxNjk5MTMyMjYxLCJpc3MiOiJ
odHRwczovL2FwaS5teS1hd2Vzb21lLWFwcC5pbyIsImF1ZCI6Imh0dHBzOi8vY2xpZW50LWFwcC5pbyJ9
.IA9S0n8Q2O97lyR8KczVE8g-hxbbH6_TfJS-JWTQR4c
</details>

Your parsing logic (with validations) look like:

```php
<?php
declare(strict_types=1);

namespace MyApp;

require 'vendor/autoload.php';

use DateTimeImmutable;
use Lcobucci\Clock\FrozenClock;
use Lcobucci\JWT\JwtFacade;
use Lcobucci\JWT\Signer;
use Lcobucci\JWT\Signer\Key\InMemory;
use Lcobucci\JWT\Validation\Constraint;

$validationConstraints = [
new Constraint\SignedWith(
new Signer\Hmac\Sha256(),
InMemory::plainText(
'a-very-long-and-secure-key-that-should-actually-be-something-else'
),
),
new Constraint\StrictValidAt(
// `FrozenClock` is used here to fix to a point in time that allows our
// validation to pass
new FrozenClock(new DateTimeImmutable('2023-11-04 21:06:35+00:00'))
)
];

$jwt = ''; // Fetched from, for example, a request header

$token = (new JwtFacade())->parse($jwt, ...$validationConstraints);
```

### Performing a backwards compatible rotation

Now Imagine that you want to adopt the new `BLAKE2B` symmetric algorithm.

These are the changes to your issuing logic:

```diff
<?php
declare(strict_types=1);

namespace MyApp;

require 'vendor/autoload.php';

use DateTimeImmutable;
use Lcobucci\Clock\FrozenClock;
use Lcobucci\JWT\Builder;
use Lcobucci\JWT\JwtFacade;
use Lcobucci\JWT\Signer;
use Lcobucci\JWT\Signer\Key\InMemory;

// `FrozenClock` is used here to fix to a point in time that allows our validation to pass
$clock = new FrozenClock(new DateTimeImmutable('2023-11-04 21:06:01+00:00'));
$token = (new JwtFacade(clock: $clock))->issue(
- new Signer\Hmac\Sha256(),
+ new Signer\Blake2b(),
- InMemory::plainText(
- 'a-very-long-and-secure-key-that-should-actually-be-something-else'
+ InMemory::base64Encoded(
+ 'GOu4rLyVCBxmxP+sbniU68ojAja5PkRdvv7vNvBCqDQ='
),
static fn (Builder $builder): Builder => $builder
->issuedBy('https://api.my-awesome-app.io')
->permittedFor('https://client-app.io')
);
```

!!! Sample
Here's a token issued with the code above, if you want to test the script locally:

<details>
<summary>Sample token</summary>
// line breaks added for readability
eyJ0eXAiOiJKV1QiLCJhbGciOiJCTEFLRTJCIn0
.eyJpYXQiOjE2OTkxMzE5NjEsIm5iZiI6MTY5OTEzMTk2MSwiZXhwIjoxNjk5MTMyMjYxLCJpc3Mi
OiJodHRwczovL2FwaS5teS1hd2Vzb21lLWFwcC5pbyIsImF1ZCI6Imh0dHBzOi8vY2xpZW50LWFwc
C5pbyJ9.bD67s8IXpAJiBTIZn1et_M5WSS7kfmuNiacNRz5lArQ
</details>

So far, nothing different that a normal rotation.

Now check the changes on the parsing and validation logic:

```diff
<?php
declare(strict_types=1);

namespace MyApp;

require 'vendor/autoload.php';

use DateTimeImmutable;
use Lcobucci\Clock\FrozenClock;
use Lcobucci\JWT\JwtFacade;
use Lcobucci\JWT\Signer;
use Lcobucci\JWT\Signer\Key\InMemory;
use Lcobucci\JWT\Validation\Constraint;

$validationConstraints = [
- new Constraint\SignedWith(
- new Signer\Hmac\Sha256(),
- InMemory::plainText(
- 'a-very-long-and-secure-key-that-should-actually-be-something-else'
- ),
- ),
+ new Constraint\SignedWithOneInSet(
+ new Constraint\SignedWith(
+ new Signer\Blake2b(),
+ InMemory::base64Encoded(
+ 'GOu4rLyVCBxmxP+sbniU68ojAja5PkRdvv7vNvBCqDQ='
+ ),
+ ),
+ new Constraint\SignedWith(
+ new Signer\Hmac\Sha256(),
+ InMemory::plainText(
+ 'a-very-long-and-secure-key-that-should-actually-be-something-else'
+ ),
+ ),
+ ),
new Constraint\StrictValidAt(
// `FrozenClock` is used here to fix to a point in time that allows our
// validation to pass
new FrozenClock(new DateTimeImmutable('2023-11-04 21:06:35+00:00'))
)
];

$jwt = ''; // Fetched from, for example, a request header

$token = (new JwtFacade())->parse($jwt, ...$validationConstraints);
```

Now the application is able to accept non-expired tokens issued with either old and new keys!

!!! Important
The order of `SignedWith` constraints given to `SignedWithOneInSet` does matter, and it's recommended to leave older keys at the end of the list.
1 change: 1 addition & 0 deletions mkdocs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ nav:
- 'configuration.md'
- Guides:
- 'extending-the-library.md'
- 'rotating-keys.md'
- 'upgrading.md'

markdown_extensions:
Expand Down

0 comments on commit a6afecf

Please sign in to comment.