ceph/doc/cluster-ops/auth-intro.rst

=====================================
 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 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:: 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.