openstack
/
keystone
Code Issues Proposed changes

Improve keystone.conf [fernet_tokens] documentation 

Change-Id: Ie9af8a20a23dec4592944e36bb5df9788bcc013b
This commit is contained in:
Dolph Mathews 2016-07-01 16:03:35 +00:00
parent a59aa8b5c6
commit d122e9b86c
1 changed files with 25 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

31
keystone/conf/fernet_tokens.py
View File

@ -19,7 +19,26 @@ key_repository = cfg.StrOpt(
'key_repository',
default='/etc/keystone/fernet-keys/',
help=utils.fmt("""
Directory containing Fernet token keys.
Directory containing Fernet token keys. This directory must exist before using
`keystone-manage fernet_setup` for the first time, must be writable by the user
running `keystone-manage fernet_setup` or `keystone-manage fernet_rotate`, and
of course must be readable by keystone's server process. The repository may
contain keys in one of three states: a single staged key (always index 0) used
for token validation, a single primary key (always the highest index) used for
token creation and validation, and any number of secondary keys (all other
index values) used for token validation. With multiple keystone nodes, each
node must share the same key repository contents, with the exception of the
staged key (index 0). It is safe to run `keystone-manage fernet_rotate` once on
any one node to promote a staged key (index 0) to be the new primary
(incremented from the previous highest index), and produce a new staged key (a
new key with index 0); the resulting repository can then be atomically
replicated to other nodes without any risk of race conditions (for example, it
is safe to run `keystone-manage fernet_rotate` on host A, wait any amount of
time, create a tarball of the directory on host A, unpack it on host B to a
temporary location, and atomically move (`mv`) the directory into place on host
B). Running `keystone-manage fernet_rotate` *twice* on a key repository without
syncing other nodes will result in tokens that can not be validated by all
nodes.
"""))
max_active_keys = cfg.IntOpt(
@ -27,11 +46,11 @@ max_active_keys = cfg.IntOpt(
default=3,
min=1,
help=utils.fmt("""
This controls how many keys are held in rotation by keystone-manage
fernet_rotate before they are discarded. The default value of 3 means that
keystone will maintain one staged key, one primary key, and one secondary key.
Increasing this value means that additional secondary keys will be kept in the
rotation.
This controls how many keys are held in rotation by `keystone-manage
fernet_rotate` before they are discarded. The default value of 3 means that
keystone will maintain one staged key (always index 0), one primary key (the
highest numerical index), and one secondary key (every other index). Increasing
this value means that additional secondary keys will be kept in the rotation.
"""))