)]}'
{"doc/source/admin/identity-fernet-token-faq.rst":[{"author":{"_account_id":17860,"name":"Samuel de Medeiros Queiroz","email":"samueldmq@gmail.com","username":"samueldmq"},"change_message_id":"ab429903b602a96f72aab4856c1daee01c853185","unresolved":false,"context_lines":[{"line_number":8,"context_line":"What is a fernet token?"},{"line_number":9,"context_line":"~~~~~~~~~~~~~~~~~~~~~~~"},{"line_number":10,"context_line":""},{"line_number":11,"context_line":"A fernet token is a bearer token the represents user authentication. Fernet"},{"line_number":12,"context_line":"tokens contain a limited amount of identity and authorization data in a"},{"line_number":13,"context_line":"`MessagePacked \u003chttp://msgpack.org/\u003e`_ payload. The payload is then wrapped as"},{"line_number":14,"context_line":"a `Fernet \u003chttps://github.com/fernet/spec\u003e`_ message for transport, where"}],"source_content_type":"text/x-rst","patch_set":1,"id":"5f201791_06d2bf00","line":11,"range":{"start_line":11,"start_character":33,"end_line":11,"end_character":36},"updated":"2017-06-26 22:36:12.000000000","message":"that","commit_id":"2c89dee8c8dd07a278b6e3ec2c8850dc36237395"},{"author":{"_account_id":5046,"name":"Lance Bragstad","email":"lbragstad@redhat.com","username":"ldbragst"},"change_message_id":"d3c03b83b894148959c68b59458b214bd37af068","unresolved":false,"context_lines":[{"line_number":8,"context_line":"What is a fernet token?"},{"line_number":9,"context_line":"~~~~~~~~~~~~~~~~~~~~~~~"},{"line_number":10,"context_line":""},{"line_number":11,"context_line":"A fernet token is a bearer token the represents user authentication. Fernet"},{"line_number":12,"context_line":"tokens contain a limited amount of identity and authorization data in a"},{"line_number":13,"context_line":"`MessagePacked \u003chttp://msgpack.org/\u003e`_ payload. The payload is then wrapped as"},{"line_number":14,"context_line":"a `Fernet \u003chttps://github.com/fernet/spec\u003e`_ message for transport, where"}],"source_content_type":"text/x-rst","patch_set":1,"id":"3f1d235d_da6137ab","line":11,"in_reply_to":"5f201791_06d2bf00","updated":"2017-07-05 15:55:56.000000000","message":"Done","commit_id":"2c89dee8c8dd07a278b6e3ec2c8850dc36237395"},{"author":{"_account_id":6482,"name":"Steve Martinelli","email":"s.martinelli@gmail.com","username":"stevemar"},"change_message_id":"95d27526810242d7ec0e151e7c3b77c090898032","unresolved":false,"context_lines":[{"line_number":33,"context_line":"The state of the key determines how keystone uses a key with fernet tokens. The"},{"line_number":34,"context_line":"different types are as follows:"},{"line_number":35,"context_line":""},{"line_number":36,"context_line":"Primary key:"},{"line_number":37,"context_line":"  There is only ever one primary key in a key repository. The primary key is"},{"line_number":38,"context_line":"  allowed to encrypt and decrypt tokens. This key is always named as the"},{"line_number":39,"context_line":"  highest index in the repository."},{"line_number":40,"context_line":"Secondary key:"},{"line_number":41,"context_line":"  A secondary key was at one point a primary key, but has been demoted in place"},{"line_number":42,"context_line":"  of another primary key. It is only allowed to decrypt tokens. Since it was"},{"line_number":43,"context_line":"  the primary at some point in time, its existence in the key repository is"},{"line_number":44,"context_line":"  justified. Keystone needs to be able to decrypt tokens that were created with"},{"line_number":45,"context_line":"  old primary keys."},{"line_number":46,"context_line":"Staged key:"},{"line_number":47,"context_line":"  The staged key is a special key that shares some similarities with secondary"},{"line_number":48,"context_line":"  keys. There can only ever be one staged key in a repository and it must"},{"line_number":49,"context_line":"  exist. Just like secondary keys, staged keys have the ability to decrypt"},{"line_number":50,"context_line":"  tokens. Unlike secondary keys, staged keys have never been a primary key. In"},{"line_number":51,"context_line":"  fact, they are opposites since the staged key will always be the next primary"},{"line_number":52,"context_line":"  key. This helps clarify the name because they are the next key staged to be"},{"line_number":53,"context_line":"  the primary key. This key is always named as ``0`` in the key repository."},{"line_number":54,"context_line":""},{"line_number":55,"context_line":"So, how does a staged key help me and why do I care about it?"},{"line_number":56,"context_line":"~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~"}],"source_content_type":"text/x-rst","patch_set":1,"id":"5f201791_97eddbb8","line":53,"range":{"start_line":36,"start_character":0,"end_line":53,"end_character":75},"updated":"2017-06-27 01:31:46.000000000","message":"part of it is here","commit_id":"2c89dee8c8dd07a278b6e3ec2c8850dc36237395"}],"doc/source/admin/identity-tokens.rst":[{"author":{"_account_id":6482,"name":"Steve Martinelli","email":"s.martinelli@gmail.com","username":"stevemar"},"change_message_id":"95d27526810242d7ec0e151e7c3b77c090898032","unresolved":false,"context_lines":[{"line_number":69,"context_line":"The token type issued by keystone is configurable through the"},{"line_number":70,"context_line":"``/etc/keystone/keystone.conf`` file. Currently, there are two supported"},{"line_number":71,"context_line":"token types, ``UUID`` and ``fernet``."},{"line_number":72,"context_line":""},{"line_number":73,"context_line":"UUID tokens"},{"line_number":74,"context_line":"~~~~~~~~~~~"},{"line_number":75,"context_line":""},{"line_number":76,"context_line":"UUID was the first token type supported and is currently the default token"},{"line_number":77,"context_line":"provider. UUID tokens are 32 bytes in length and must be persisted in a back"},{"line_number":78,"context_line":"end. Clients must pass their UUID token to the Identity service in order to"},{"line_number":79,"context_line":"validate it."},{"line_number":80,"context_line":""},{"line_number":81,"context_line":"Fernet tokens"},{"line_number":82,"context_line":"~~~~~~~~~~~~~"},{"line_number":83,"context_line":""},{"line_number":84,"context_line":"The fernet token format was introduced in the OpenStack Kilo release. Unlike"},{"line_number":85,"context_line":"the other token types mentioned in this document, fernet tokens do not need to"},{"line_number":86,"context_line":"be persisted in a back end. ``AES256`` encryption is used to protect the"},{"line_number":87,"context_line":"information stored in the token and integrity is verified with a ``SHA256"},{"line_number":88,"context_line":"HMAC`` signature. Only the Identity service should have access to the keys used"},{"line_number":89,"context_line":"to encrypt and decrypt fernet tokens. Like UUID tokens, fernet tokens must be"},{"line_number":90,"context_line":"passed back to the Identity service in order to validate them. For more"},{"line_number":91,"context_line":"information on the fernet token type, see the :doc:`identity-fernet-token-faq`."},{"line_number":92,"context_line":""},{"line_number":93,"context_line":".. support_matrix:: token-support-matrix.ini"}],"source_content_type":"text/x-rst","patch_set":1,"id":"5f201791_f73f6f22","line":91,"range":{"start_line":72,"start_character":0,"end_line":91,"end_character":79},"updated":"2017-06-27 01:31:46.000000000","message":"part of it is also here","commit_id":"2c89dee8c8dd07a278b6e3ec2c8850dc36237395"}],"doc/source/configuration.rst":[{"author":{"_account_id":17860,"name":"Samuel de Medeiros Queiroz","email":"samueldmq@gmail.com","username":"samueldmq"},"change_message_id":"ab429903b602a96f72aab4856c1daee01c853185","unresolved":false,"context_lines":[{"line_number":615,"context_line":"  :class:`keystone.token.providers.uuid.Provider`"},{"line_number":616,"context_line":""},{"line_number":617,"context_line":""},{"line_number":618,"context_line":"UUID or Fernet?"},{"line_number":619,"context_line":"^^^^^^^^^^^^^^^"},{"line_number":620,"context_line":"Each token format uses different technologies to achieve various performance,"},{"line_number":621,"context_line":"scaling and architectural requirements."},{"line_number":622,"context_line":""},{"line_number":623,"context_line":"UUID tokens contain randomly generated UUID4 IDs that are issued and"},{"line_number":624,"context_line":"validated by the identity service. They are encoded using their hex digest for"},{"line_number":625,"context_line":"transport and are thus URL-friendly. They must be persisted by the identity"},{"line_number":626,"context_line":"service in order to be later validated. Revoking them is simply a matter of"},{"line_number":627,"context_line":"deleting them from the token persistence backend."},{"line_number":628,"context_line":""},{"line_number":629,"context_line":"Fernet tokens contain a limited amount of identity and authorization data in a"},{"line_number":630,"context_line":"`MessagePacked \u003chttp://msgpack.org/\u003e`_ payload. The payload is then wrapped as"},{"line_number":631,"context_line":"a `Fernet \u003chttps://github.com/fernet/spec\u003e`_ message for transport, where"},{"line_number":632,"context_line":"Fernet provides the required web safe characteristics for use in URLs and"},{"line_number":633,"context_line":"headers. Fernet tokens require symmetric encryption keys which can be"},{"line_number":634,"context_line":"established using ``keystone-manage fernet_setup`` and periodically rotated"},{"line_number":635,"context_line":"using ``keystone-manage fernet_rotate``."},{"line_number":636,"context_line":""},{"line_number":637,"context_line":".. WARNING::"},{"line_number":638,"context_line":"    UUID and Fernet tokens are both bearer tokens, meaning that they"},{"line_number":639,"context_line":"    must be protected from unnecessary disclosure to prevent unauthorized"},{"line_number":640,"context_line":"    access."},{"line_number":641,"context_line":""},{"line_number":642,"context_line":".. support_matrix:: token-support-matrix.ini"},{"line_number":643,"context_line":""},{"line_number":644,"context_line":"Encryption Keys for Fernet Tokens"},{"line_number":645,"context_line":"\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d"},{"line_number":646,"context_line":""},{"line_number":647,"context_line":"``keystone-manage fernet_setup`` will attempt to create a key repository as"},{"line_number":648,"context_line":"configured in the ``[fernet_tokens]`` section of ``keystone.conf`` and"},{"line_number":649,"context_line":"bootstrap it with encryption keys."},{"line_number":650,"context_line":""},{"line_number":651,"context_line":"A single 256-bit key is actually composed of two smaller keys: a 128-bit key"},{"line_number":652,"context_line":"used for SHA256 HMAC signing and a 128-bit key used for AES encryption. See the"},{"line_number":653,"context_line":"`Fernet token \u003chttps://github.com/fernet/spec\u003e`_ specification for more detail."},{"line_number":654,"context_line":""},{"line_number":655,"context_line":"``keystone-manage fernet_rotate`` will rotate encryption keys through the"},{"line_number":656,"context_line":"following states:"},{"line_number":657,"context_line":""},{"line_number":658,"context_line":"* **Staged key**: In a key rotation, a new key is introduced into the rotation"},{"line_number":659,"context_line":"  in this state. Only one key is considered to be the *staged* key at any given"},{"line_number":660,"context_line":"  time. This key will become the *primary* during the *next* key rotation. This"},{"line_number":661,"context_line":"  key is only used to validate tokens and serves to avoid race conditions in"},{"line_number":662,"context_line":"  multi-node deployments (all nodes should recognize all *primary* keys in the"},{"line_number":663,"context_line":"  deployment at all times). In a multi-node keystone deployment this would"},{"line_number":664,"context_line":"  allow for the *staged* key to be replicated to all keystone nodes before"},{"line_number":665,"context_line":"  being promoted to *primary* on a single node. This prevents the case where a"},{"line_number":666,"context_line":"  *primary* key is created on one keystone node and tokens encrypted/signed with"},{"line_number":667,"context_line":"  that new *primary* are rejected on another keystone node because the new"},{"line_number":668,"context_line":"  *primary* doesn\u0027t exist there yet."},{"line_number":669,"context_line":""},{"line_number":670,"context_line":"* **Primary key**: In a key rotation, the old *staged* key is promoted to be"},{"line_number":671,"context_line":"  the *primary*. Only one key is considered to be the *primary* key at any"},{"line_number":672,"context_line":"  given time. This is the key used to generate new tokens. This key is also"},{"line_number":673,"context_line":"  used to validate previously generated tokens."},{"line_number":674,"context_line":""},{"line_number":675,"context_line":"* **Secondary keys**: In a key rotation, the old *primary* key is demoted to be"},{"line_number":676,"context_line":"  a *secondary* key. *Secondary* keys are only used to validate previously"},{"line_number":677,"context_line":"  generated tokens. You can maintain any number of *secondary* keys, up to"},{"line_number":678,"context_line":"  ``[fernet_tokens] max_active_keys`` (where \"active\" refers to the sum of all"},{"line_number":679,"context_line":"  recognized keys in any state: *staged*, *primary* or *secondary*). When"},{"line_number":680,"context_line":"  ``max_active_keys`` is exceeded during a key rotation, the oldest keys are"},{"line_number":681,"context_line":"  discarded."},{"line_number":682,"context_line":""},{"line_number":683,"context_line":"When a new primary key is created, all new tokens will be encrypted using the"},{"line_number":684,"context_line":"new primary key. The old primary key is demoted to a secondary key, which can"},{"line_number":685,"context_line":"still be used for validating tokens. Excess secondary keys (beyond"},{"line_number":686,"context_line":"``[fernet_tokens] max_active_keys``) are revoked. Revoked keys are permanently"},{"line_number":687,"context_line":"deleted."},{"line_number":688,"context_line":""},{"line_number":689,"context_line":"Rotating keys too frequently, or with ``[fernet_tokens] max_active_keys`` set"},{"line_number":690,"context_line":"too low, will cause tokens to become invalid prior to their expiration. As"},{"line_number":691,"context_line":"tokens may be fetched beyond there initial expiration period keys should not be"},{"line_number":692,"context_line":"fully rotated within the period of ``[token] expiration`` + ``[token]"},{"line_number":693,"context_line":"allow_expired_window`` seconds to prevent the tokens becoming unavailable."},{"line_number":694,"context_line":""},{"line_number":695,"context_line":"Caching Layer"},{"line_number":696,"context_line":"\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d"}],"source_content_type":"text/x-rst","patch_set":1,"id":"5f201791_86c80f22","side":"PARENT","line":693,"range":{"start_line":618,"start_character":0,"end_line":693,"end_character":74},"updated":"2017-06-26 22:36:12.000000000","message":"isnt all this useful info?","commit_id":"9070172084fe31c9564de38886662fb198de68cb"},{"author":{"_account_id":5046,"name":"Lance Bragstad","email":"lbragstad@redhat.com","username":"ldbragst"},"change_message_id":"d3c03b83b894148959c68b59458b214bd37af068","unresolved":false,"context_lines":[{"line_number":690,"context_line":"too low, will cause tokens to become invalid prior to their expiration. As"},{"line_number":691,"context_line":"tokens may be fetched beyond there initial expiration period keys should not be"},{"line_number":692,"context_line":"fully rotated within the period of ``[token] expiration`` + ``[token]"},{"line_number":693,"context_line":"allow_expired_window`` seconds to prevent the tokens becoming unavailable."},{"line_number":694,"context_line":""},{"line_number":695,"context_line":"Caching Layer"},{"line_number":696,"context_line":"\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d"}],"source_content_type":"text/x-rst","patch_set":1,"id":"3f1d235d_9a0cdfec","side":"PARENT","line":693,"in_reply_to":"5f201791_86c80f22","updated":"2017-07-05 15:55:56.000000000","message":"It is - most of this lives within the fernet FAQ section.","commit_id":"9070172084fe31c9564de38886662fb198de68cb"}]}