From: John Wilkins Date: Thu, 14 Aug 2014 03:30:04 +0000 (-0700) Subject: doc: Removed cephx intro. Moved details to user management, config, and architecture. X-Git-Tag: v0.86~154^2~6 X-Git-Url: http://git-server-git.apps.pok.os.sepia.ceph.com/?a=commitdiff_plain;h=5e8eae725f64718bf30bf2dfd4496dd5ba54e9ea;p=ceph.git doc: Removed cephx intro. Moved details to user management, config, and architecture. Signed-off-by: John Wilkins --- diff --git a/doc/rados/operations/auth-intro.rst b/doc/rados/operations/auth-intro.rst deleted file mode 100644 index 4d8e8c3aa503..000000000000 --- a/doc/rados/operations/auth-intro.rst +++ /dev/null @@ -1,295 +0,0 @@ -===================================== - 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. - -.. note:: 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. - -.. note:: Ceph uses the capabilities discussed here for setting up and - controlling access between various Ceph client and server instances, and - are relevant regardless of what type of client accesses the Ceph object - store. CephFS uses a different type of capability for files and directories - internal to the CephFS filesystem. CephFS filesystem access controls are - relevant to CephFS, but not block devices or the RESTful gateway. - -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:: Storing keys in plaintext files 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.