From 0818e1e95a76c5523a3da4d33583af120d86a4e4 Mon Sep 17 00:00:00 2001 From: John Wilkins Date: Tue, 16 Oct 2012 15:22:25 -0700 Subject: [PATCH] doc: Added a new intro for cephx authentication. Signed-off-by: John Wilkins --- doc/cluster-ops/auth-intro.rst | 291 +++++++++++++++++++++++++++++++++ 1 file changed, 291 insertions(+) create mode 100644 doc/cluster-ops/auth-intro.rst diff --git a/doc/cluster-ops/auth-intro.rst b/doc/cluster-ops/auth-intro.rst new file mode 100644 index 0000000000000..d7c2ea32224fe --- /dev/null +++ b/doc/cluster-ops/auth-intro.rst @@ -0,0 +1,291 @@ +===================================== + Ceph Authentication & Authorization +===================================== + +Ceph is a distributed storage system where a typical deployment involves a +relatively small quorum of *monitors*, scores of *metadata servers* (MDSs) and +many thousands of OSD daemons operating across many hosts/nodes--representing +the server portion of the Ceph object store. Ceph clients such as CephFS, Ceph +block device and Ceph Gateway interact with the Ceph object store. All Ceph +object store clients use the ``librados`` library to interact with the Ceph +object store. The following diagram illustrates an abstract client/server +technology stack. + +.. ditaa:: +---------------------------------------------------+ + | client | + +---------------------------------------------------+ + | librados | + +---------------------------------------------------+ + +---------------+ +---------------+ +---------------+ + | OSDs | | MDSs | | Monitors | + +---------------+ +---------------+ +---------------+ + +Users are either individuals or system actors such as applications, which +use Ceph clients to interact with Ceph server daemons. + +.. ditaa:: +-----+ + | {o} | + | | + +--+--+ /---------\ /---------\ + | | Ceph | | Ceph | + ---+---*----->| |<------------->| | + | uses | Clients | | Servers | + | \---------/ \---------/ + /--+--\ + | | + | | + actor + +For additional information, see our `Cephx Guide`_ and `ceph-authtool manpage`_. + +.. _Cephx Guide: ../authentication +.. _ceph-authtool manpage: ../../man/8/ceph-authtool/ + +Ceph Authentication (cephx) +=========================== + +Cryptographic authentication has some computational costs, though they should +generally be quite low. If the network environment connecting your client and +server hosts is very safe and you cannot afford authentication, you can use a +Ceph option to turn it off. **This is not generally recommended**, but should you +need to do so, details can be found in the `Disable Cephx`_ section. + +.. important:: Remember, if you disable authentication, you are at risk of a + man-in-the-middle attack altering your client/server messages, which could + lead to disastrous security effects. + +A key scalability feature of Ceph is to avoid a centralized interface to the +Ceph object store, which means that Ceph clients must be able to interact with +OSDs directly. To protect data, Ceph provides its ``cephx`` authentication +system, which authenticates users operating Ceph clients. The ``cephx`` protocol +operates in a manner with behavior similar to `Kerberos`_. + +.. _Disable Cephx: ../authentication#disable-cephx +.. _Kerberos: http://en.wikipedia.org/wiki/Kerberos_(protocol) + +A user/actor invokes a Ceph client to contact a monitor. Unlike Kerberos, each +monitor can authenticate users and distribute keys, so there is no single point +of failure or bottleneck when using ``cephx``. The monitor returns an +authentication data structure similar to a Kerberos ticket that contains a +session key for use in obtaining Ceph services. This session key is itself +encrypted with the user's permanent secret key, so that only the user can +request services from the Ceph monitor(s). The client then uses the session key +to request its desired services from the monitor, and the monitor provides the +client with a ticket that will authenticate the client to the OSDs that actually +handle data. Ceph monitors and OSDs share a secret, so the client can use the +ticket provided by the monitor with any OSD or metadata server in the cluster. +Like Kerberos, ``cephx`` tickets expire, so an attacker cannot use an expired +ticket or session key obtained surreptitiously. This form of authentication will +prevent attackers with access to the communications medium from either creating +bogus messages under another user's identity or altering another user's +legitimate messages, as long as the user's secret key is not divulged before it +expires. + +To use ``cephx``, an administrator must set up users first. In the following +diagram, the ``client.admin`` user invokes ``ceph auth get-or-create-key`` from +the command line to generate a username and secret key. Ceph's ``auth`` +subsystem generates the username and key, stores a copy with the monitor(s) and +transmits the user's secret back to the ``client.admin`` user. This means that +the client and the monitor share a secret key. + +.. important:: The ``client.admin`` user must provide the user ID and + secret key to the user in a secure manner. + +.. ditaa:: +---------+ +---------+ + | Client | | Monitor | + +---------+ +---------+ + | request to | + | create a user | + |-------------->|----------+ create user + | | | and + |<--------------|<---------+ store key + | transmit key | + | | + + +To authenticate with the monitor, the client passes in the user name to the +monitor, and the monitor generates a session key and encrypts it with the secret +key associated to the user name. Then, the monitor transmits the encrypted +ticket back to the client. The client then decrypts the payload with the shared +secret key to retrieve the session key. The session key identifies the user for +the current session. The client then requests a ticket on behalf of the user +signed by the session key. The monitor generates a ticket, encrypts it with the +user's secret key and transmits it back to the client. The client decrypts the +ticket and uses it to sign requests to OSDs and metadata servers throughout the +cluster. + +.. ditaa:: +---------+ +---------+ + | Client | | Monitor | + +---------+ +---------+ + | authenticate | + |-------------->|----------+ generate and + | | | encrypt + |<--------------|<---------+ session key + | transmit | + | encrypted | + | session key | + | | + |-----+ decrypt | + | | session | + |<----+ key | + | | + | req. ticket | + |-------------->|----------+ generate and + | | | encrypt + |<--------------|<---------+ ticket + | recv. ticket | + | | + |-----+ decrypt | + | | ticket | + |<----+ | + + +The ``cephx`` protocol authenticates ongoing communications between the client +machine and the Ceph servers. Each message sent between a client and server, +subsequent to the initial authentication, is signed using a ticket that the +monitors, OSDs and metadata servers can verify with their shared secret. + +.. ditaa:: +---------+ +---------+ +-------+ +-------+ + | Client | | Monitor | | MDS | | OSD | + +---------+ +---------+ +-------+ +-------+ + | request to | | | + | create a user | | | + |-------------->| mon and | | + |<--------------| client share | | + | receive | a secret. | | + | shared secret | | | + | |<------------>| | + | |<-------------+------------>| + | | mon, mds, | | + | authenticate | and osd | | + |-------------->| share | | + |<--------------| a secret | | + | session key | | | + | | | | + | req. ticket | | | + |-------------->| | | + |<--------------| | | + | recv. ticket | | | + | | | | + | make request (CephFS only) | | + |----------------------------->| | + |<-----------------------------| | + | receive response (CephFS only) | + | | + | make request | + |------------------------------------------->| + |<-------------------------------------------| + receive response + +The protection offered by this authentication is between the Ceph client and the +Ceph server hosts. The authentication is not extended beyond the Ceph client. If +the user accesses the Ceph client from a remote host, Ceph authentication is not +applied to the connection between the user's host and the client host. + + +Ceph Authorization (caps) +========================= + +Ceph uses the term "capabilities" (caps) to describe authorizing an +authenticated user to exercise the functionality of the monitors, OSDs and +metadata servers. Capabilities can also restrict access to data within one or +more pools. + +.. important:: Ceph capabilities are **NOT** the same as CephFS + filesystem authorization permission using the POSIX file system + interface (e.g., ``chmod``). + +A Ceph ``client.admin`` user sets a user's capabilities when creating +the user. + + +``allow`` + +:Description: Precedes access settings for a daemon. Implies ``rw`` for MDS only. +:Example: ``ceph-authtool -n client.foo --cap mds 'allow'`` + + +``r`` + +:Description: Gives the user read access. Required with monitors to retrieve the CRUSH map. +:Example: ``ceph-authtool -n client.foo --cap mon 'allow r'`` + + +``w`` + +:Description: Gives the user write access to objects. +:Example: ``ceph-authtool -n client.foo --cap osd 'allow w'`` + + +``x`` + +:Description: Gives the user the capability to call class methods (i.e., both read and write). +:Example: ``ceph-authtool -n client.foo --cap osd 'allow x'`` + + +``class-read`` + +:Descriptions: Gives the user the capability to call class read methods. Subset of ``x``. +:Example: ``ceph-authtool -n client.foo --cap osd 'allow class-read'`` + + +``class-write`` + +:Description: Gives the user the capability to call class write methods. Subset of ``x``. +:Example: ``ceph-authtool -n client.foo --cap osd 'allow class-write'`` + + +``*`` + +:Description: Gives the user read, write and execute permissions for a particular daemon/pool, and the ability to execute admin commands. +:Example: ``ceph-authtool -n client.foo --cap osd 'allow *'`` + + +When setting capabilities for a user, Ceph also supports restricting the +capabilities to a particular pool. This means you can have full access to some +pools, and restricted (or no) access to other pools for the same user. +For example:: + + ceph-authtool -n client.foo --cap osd 'allow rwx' pool=customer-pool + + + +Cephx Limitations +================= + +The ``cephx`` protocol authenticates Ceph clients and servers to each other. It +is not intended to handle authentication of human users or application programs +run on their behalf. If that effect is required to handle your access control +needs, you must have another mechanism, which is likely to be specific to the +front end used to access the Ceph object store. This other mechanism has the +role of ensuring that only acceptable users and programs are able to run on the +machine that Ceph will permit to access its object store. + +The keys used to authenticate Ceph clients and servers are typically stored in +a plain text file with appropriate permissions in a trusted host. + +.. important:: This method has security shortcomings, but they are difficult to avoid, + given the basic authentication methods Ceph uses in the background. Those setting up + Ceph systems should be aware of these shortcomings. + +In particular, arbitrary user machines, especially portable machines, should not +be configured to interact directly with Ceph, since that mode of use would +require the storage of a plaintext authentication key on an insecure machine. +Anyone who stole that machine or obtained surreptitious access to it could +obtain the key that will allow them to authenticate their own machines to Ceph. + +Rather than permitting potentially insecure machines to access a Ceph object +store directly, users should be required to sign in to a trusted machine in +your environment using a method that provides sufficient security for your +purposes. That trusted machine will store the plaintext Ceph keys for the +human users. A future version of Ceph may address these particular +authentication issues more fully. + +At the moment, none of the Ceph authentication protocols provide secrecy for +messages in transit. Thus, an eavesdropper on the wire can hear and understand +all data sent between clients and servers in Ceph, even if he cannot create or +alter them. Further, Ceph does not include options to encrypt user data in the +object store. Users can hand-encrypt and store their own data in the Ceph +object store, of course, but Ceph provides no features to perform object +encryption itself. Those storing sensitive data in Ceph should consider +encrypting their data before providing it to the Ceph system. -- 2.39.5