From 5e4df2a509d7d8f23a6bd48972b78dd2a0aef968 Mon Sep 17 00:00:00 2001 From: Sage Weil Date: Wed, 30 Jan 2019 10:40:47 -0600 Subject: [PATCH] doc/dev/cephx: re-wordwrap Signed-off-by: Sage Weil --- doc/dev/cephx.rst | 90 +++++++++++++++++++++++++++-------------------- 1 file changed, 51 insertions(+), 39 deletions(-) diff --git a/doc/dev/cephx.rst b/doc/dev/cephx.rst index b46d9de4f08..1703e3eb4cf 100644 --- a/doc/dev/cephx.rst +++ b/doc/dev/cephx.rst @@ -27,21 +27,25 @@ Terms ----- - *monitor(s)*: central authorization authority -- *service*: the set of all daemons of a particular type (e.g., all OSDs, all MDSs) +- *service*: the set of all daemons of a particular type (e.g., all + OSDs, all MDSs) - *client*: an entity or principal that is accessing the service -- *entity name*: the string identifier for a principal (e.g. client.admin, osd.123) -- *ticket*: a bit of data that cryptographically asserts identify and authorization +- *entity name*: the string identifier for a principal + (e.g. client.admin, osd.123) +- *ticket*: a bit of data that cryptographically asserts identify and + authorization - *principal*: a client or daemon, identified by a unique entity_name, that shares a secret with the monitor. -- *principal_secret*: principal secret, a shared secret (16 bytes) known by the - principal and the monitor +- *principal_secret*: principal secret, a shared secret (16 bytes) + known by the principal and the monitor - *mon_secret*: monitor secret, a shared secret known by all monitors - *service_secret*: a rotating secret known by all members of a service class (e.g., all OSDs) - *auth ticket*: a ticket proving identity to the monitors -- *service ticket*: a ticket proving identify and authorization to a service +- *service ticket*: a ticket proving identify and authorization to a + service Terminology @@ -58,9 +62,9 @@ auth implementation. The messages are transferred by the Messenger protocol or by MAuth messages, depending on the version of the messenger protocol. See also :ref:`msgr2`. -An initial (messenger) handshake negotiates an authentication method to be used -(cephx vs none or krb or whatever) and an assertion of what entity the client or -daemon is attempting to authenticate as. +An initial (messenger) handshake negotiates an authentication method +to be used (cephx vs none or krb or whatever) and an assertion of what +entity the client or daemon is attempting to authenticate as. Phase I: obtaining auth ticket ------------------------------ @@ -74,8 +78,9 @@ client/principal.:: u64 server_challenge # random (by server) } -The client responds by adding its own challenge, and calculating a value derived -from both challenges and its shared key principal_secret.:: +The client responds by adding its own challenge, and calculating a +value derived from both challenges and its shared key +principal_secret.:: p->a : CephxRequestHeader { @@ -98,9 +103,10 @@ Prior to nautilus,:: blob old_ticket # old ticket, if we are reconnecting or renewing } -The monitor looks up principal_secret in database, and verifies the key is correct. -If old_ticket is present, verify it is valid, and we can reuse the same global_id. -(Otherwise, a new global_id is assigned by the monitor.):: +The monitor looks up principal_secret in database, and verifies the +key is correct. If old_ticket is present, verify it is valid, and we +can reuse the same global_id. (Otherwise, a new global_id is assigned +by the monitor.):: a->p : CephxReplyHeader { @@ -165,18 +171,21 @@ where:: So: for each ticket, principal gets a part that it decrypts with its secret to get the session_key (CephxServiceTicket). And the CephxTicketBlob is opaque (secured by the mon secret) but can be used -later to prove who we are and what we can do (see CephxAuthorizer below). +later to prove who we are and what we can do (see CephxAuthorizer +below). For Nautilus+, we also include the service tickets. -The client can infer that the monitor is authentic because it can decrypt the -service_ticket with its secret (i.e., the server has its secret key). +The client can infer that the monitor is authentic because it can +decrypt the service_ticket with its secret (i.e., the server has its +secret key). Phase II: Obtaining service tickets (pre-nautilus) -------------------------------------------------- -Now the client needs the keys used to talk to non-monitors (osd, mds, mgr).:: +Now the client needs the keys used to talk to non-monitors (osd, mds, +mgr).:: p->a : CephxRequestHeader { @@ -205,9 +214,9 @@ where:: } The monitor validates the authorizer by decrypting the auth_ticket -with ``mon_secret`` and confirming that it says this principal is who they -say they are in the CephxAuthorizer fields. Note that the nonce random bytes -aren't used here (the field exists for Phase III below). +with ``mon_secret`` and confirming that it says this principal is who +they say they are in the CephxAuthorizer fields. Note that the nonce +random bytes aren't used here (the field exists for Phase III below). Assuming all is well, the authorizer can generate service tickets based on the CEPH_ENTITY_TYPE_* bits in the ``keys`` bitmask. @@ -254,8 +263,9 @@ Where, as above,:: u32 flags = 0 # unused } -This concludes the authentication exchange with the monitor. The client or daemon -now has tickets to talk to the mon and all other daemons of interest. +This concludes the authentication exchange with the monitor. The +client or daemon now has tickets to talk to the mon and all other +daemons of interest. Phase III: Opening a connection to a service @@ -289,8 +299,8 @@ of:: } The server will inspect the auth_ticket CephxTicketBlob (by decrypting -it with its current rotating service key). If it is a pre-v12.2.6 or pre-v13.2.2 -client, the server immediately replies with:: +it with its current rotating service key). If it is a pre-v12.2.6 or +pre-v13.2.2 client, the server immediately replies with:: s->p : {CephxAuthorizeReply reply}^session_key @@ -313,8 +323,8 @@ where:: u64 server_challenge # random from server } -The client decrypts and updates its CephxAuthorize msg accordingly, resending most -of the same information as before:: +The client decrypts and updates its CephxAuthorize msg accordingly, +resending most of the same information as before:: p->s : CephxAuthorizer { @@ -334,8 +344,9 @@ where:: u64 server_challenge_plus_one # server_challenge + 1 } -The server validates the ticket as before, and then also verifies the msg nonce -has it's challenge + 1, confirming this is a live authentication attempt (not a replay). +The server validates the ticket as before, and then also verifies the +msg nonce has it's challenge + 1, confirming this is a live +authentication attempt (not a replay). Finally, the server responds with a reply that proves its authenticity to the client. It also includes some entropy to use for encryption of @@ -368,12 +379,12 @@ Rotating service secrets Daemons make use of a rotating secret for their tickets instead of a fixed secret in order to limit the severity of a compromised daemon. -If a daemon's secret key is compromised by an attacker, that -daemon and its key can be removed from the monitor's -database, but the attacker may also have obtained a copy of the -service secret shared by all daemons. To mitigate this, service keys rotate -periodically so that after a period of time (auth_service_ticket_ttl) -the key the attacker obtained will no longer be valid.:: +If a daemon's secret key is compromised by an attacker, that daemon +and its key can be removed from the monitor's database, but the +attacker may also have obtained a copy of the service secret shared by +all daemons. To mitigate this, service keys rotate periodically so +that after a period of time (auth_service_ticket_ttl) the key the +attacker obtained will no longer be valid.:: p->a : CephxRequestHeader { @@ -387,8 +398,9 @@ the key the attacker obtained will no longer be valid.:: } {CryptoKey service_key}^principal_secret -That is, the new rotating key is simply protected by the daemon's rotating secret. +That is, the new rotating key is simply protected by the daemon's +rotating secret. -Note that, as an implementation detail, the services keep the current key and the -prior key on hand so that the can continue to validate requests while the key is -being rotated. +Note that, as an implementation detail, the services keep the current +key and the prior key on hand so that the can continue to validate +requests while the key is being rotated. -- 2.39.5