Load the Key or Refuse to Start

Start your server the way an operator would, for one connection and with one second of patience:

python reading_server.py --max-connections 1 --idle-timeout 1

It prints that it is listening on 127.0.0.1, on a port the system chose, waits a second for a client that never comes, and prints served its connections and stopped. Nobody asked it for a key. A server that will sign tokens must not start like that.

A key as text

An environment holds text, and a key is 32 random bytes. So the key travels as base64, the standard kind with its padding. Open README.md: it shows the test key for this course and how to start the server with it. That key is readable on purpose. It decodes to the words test-only key, never use it: 001, so nobody can mistake it for a real one.

To turn the text back into bytes, use base64.b64decode(text, validate=True), as basic_credentials does for a login. The second argument matters more here than it did there. Without it, b64decode drops every character it does not know and decodes what is left:

import base64

text = "change this text to the real signing key before the server goes live"
print(len(base64.b64decode(text)))

That prints 42. A note that somebody left in a settings file has become 42 bytes of key, and everyone who has seen the file knows them. With validate=True the same call raises binascii.Error, which is a kind of ValueError, with the message Only base64 data is allowed.

A key must also be long enough. One that is shorter than the 32 bytes of a SHA-256 digest is the weak part of the tag, which is why Chapter 2 made keys 32 bytes long. signing.py has that number as KEY_BYTES.

Fail closed

When a security requirement is not met, refuse. That rule is called fail closed, and Lesson 3’s last question was about it. Every other choice keeps the service looking healthy while it is not: a built-in key that everyone knows, a random key that ends every token at each restart, or a server that is up and refuses everybody.

Write the attack first

The attack is a server that comes up with no key in its environment. As a test: signing.load_keys({}) must raise ValueError.

A loader that raised ValueError for everything would pass that test and be useless, so test_attack_missing_key_is_refused starts with a precondition: the test key loads. steps.TEST_KEY holds the same text as README.md, and signing.load_keys({"READING_KEY": steps.TEST_KEY})["current"] must be "29c565a5". Then comes the refusal. This course does not use pytest.raises: set a flag to False, call the function inside try, set the flag to True in except ValueError, and assert the flag.

Run python -m pytest -q. The new test fails on its first line, because load_keys still raises NotImplementedError:

1 failed, 13 passed

The mapping is an argument

load_keys(environ) reads only the dict it is given. It does not import os, and it never looks at the real environment. main passes os.environ, a test passes {}, and both run the same code.

handle() never looks at the environment at all. main stores what load_keys returned in state["keys"], and from Lesson 6 on the request code finds its keys there.

Say why, on the right stream, without the secret

When load_keys raises ValueError, main catches it, prints one line to standard error, and returns 1. Catch it as except ValueError as error, and print with file=sys.stderr. main already has an environ parameter for this; when it is None, use os.environ.

Standard error and a nonzero exit code are how whatever started the server learns that it did not start. The line names the variable and never repeats its value. An error message is a log line somewhere, and Lesson 3 listed a log among the places a key must not be. That holds for a wrong value as well: a key with one character missing is still most of a key.

What load_keys returns

The work is split over two functions. key_from(environ, name) reads one variable and returns the key bytes, or raises ValueError. load_keys(environ) calls it for READING_KEY and returns a dict:

{"current": "29c565a5", "by_id": {"29c565a5": b"test-only key, never use it: 001"}}

With one key, that is more shape than you need. The next lesson adds a second key, and nothing else has to change. The short text is a key id, from the supplied key_id(key): the first 8 hex digits of the key’s SHA-256 digest. It is a public name for a secret thing. A digest cannot be turned back into a key of 32 random bytes.

Your task

Write the test and watch it fail. Then write key_from and load_keys in signing.py, and load the keys in main in reading_server.py, at the comment that marks the place. The exercise lists the steps. Then run both commands:

python reading_server.py; echo "exit code: $?"
READING_KEY=dGVzdC1vbmx5IGtleSwgbmV2ZXIgdXNlIGl0OiAwMDE= python reading_server.py --max-connections 1 --idle-timeout 1; echo "exit code: $?"

The first prints one line and the exit code. If your key_from says READING_KEY is not set, it reads:

reading_server: not starting: READING_KEY is not set
exit code: 1

The second listens, waits one second for a client that never comes, stops, and prints exit code: 0. Run python -m pytest -q again: 14 passed.

Last, fill row F7 of SECURITY.md. What is exposed is the power to sign a token for any user. Name your test in the Test cell and set the status to closed in 5.4.

Then press Check my work. Your server now has a key with a home. It has exactly one, though, and no way to replace it without ending every token at once. That is the next lesson.