Rev 2834: Authentication ring specification in file:///home/pqm/archives/thelove/bzr/%2Btrunk/
Canonical.com Patch Queue Manager
pqm at pqm.ubuntu.com
Wed Sep 19 16:32:19 BST 2007
At file:///home/pqm/archives/thelove/bzr/%2Btrunk/
------------------------------------------------------------
revno: 2834
revision-id: pqm at pqm.ubuntu.com-20070919153217-w7hwnvh6v3wg6p8g
parent: pqm at pqm.ubuntu.com-20070919101753-4e8wasie12tewyjv
parent: v.ladeuil+lp at free.fr-20070919102017-0w0jcgpc3a53b57a
committer: Canonical.com Patch Queue Manager <pqm at pqm.ubuntu.com>
branch nick: +trunk
timestamp: Wed 2007-09-19 16:32:17 +0100
message:
Authentication ring specification
added:
doc/developers/authentication-ring.txt authring.txt-20070718200437-q5tdik0ne6lor86d-1
------------------------------------------------------------
revno: 2833.1.1
merged: v.ladeuil+lp at free.fr-20070919102017-0w0jcgpc3a53b57a
parent: pqm at pqm.ubuntu.com-20070919101753-4e8wasie12tewyjv
parent: v.ladeuil+lp at free.fr-20070919094745-g4daq6yb7n5irt0d
committer: Vincent Ladeuil <v.ladeuil+lp at free.fr>
branch nick: bzr.integration
timestamp: Wed 2007-09-19 12:20:17 +0200
message:
Authentication ring specification
------------------------------------------------------------
revno: 2625.12.4
merged: v.ladeuil+lp at free.fr-20070919094745-g4daq6yb7n5irt0d
parent: v.ladeuil+lp at free.fr-20070919093834-0r03bryclv0p8oit
parent: pqm at pqm.ubuntu.com-20070919080453-w4ygh8iu73fdc25i
committer: Vincent Ladeuil <v.ladeuil+lp at free.fr>
branch nick: auth.ring
timestamp: Wed 2007-09-19 11:47:45 +0200
message:
merge bzr.dev
------------------------------------------------------------
revno: 2625.12.3
merged: v.ladeuil+lp at free.fr-20070919093834-0r03bryclv0p8oit
parent: v.ladeuil+lp at free.fr-20070912170642-ictbc9bfvdj5w842
committer: Vincent Ladeuil <v.ladeuil+lp at free.fr>
branch nick: auth.ring
timestamp: Wed 2007-09-19 11:38:34 +0200
message:
Last review feedback, spec approved
------------------------------------------------------------
revno: 2625.12.2
merged: v.ladeuil+lp at free.fr-20070912170642-ictbc9bfvdj5w842
parent: v.ladeuil+lp at free.fr-20070724144907-0wjsm41i5n2bb48l
committer: Vincent Ladeuil <v.ladeuil+lp at free.fr>
branch nick: auth.ring
timestamp: Wed 2007-09-12 19:06:42 +0200
message:
More review feedbacks.
------------------------------------------------------------
revno: 2625.12.1
merged: v.ladeuil+lp at free.fr-20070724144907-0wjsm41i5n2bb48l
parent: pqm at pqm.ubuntu.com-20070717180333-5smmeduk2q3sbzvw
committer: Vincent Ladeuil <v.ladeuil+lp at free.fr>
branch nick: auth.ring
timestamp: Tue 2007-07-24 16:49:07 +0200
message:
Updated after Martin's review.
=== added file 'doc/developers/authentication-ring.txt'
--- a/doc/developers/authentication-ring.txt 1970-01-01 00:00:00 +0000
+++ b/doc/developers/authentication-ring.txt 2007-09-19 09:38:34 +0000
@@ -0,0 +1,391 @@
+Authentication ring
+===================
+
+When accessing a remote branch (specified as an URL), it may occur that the
+server requests an authentication.
+
+This authentication can be provided in different ways:
+
+1. Embedding the user and password
+in the URL::
+
+ bzr branch <scheme>://<user>:<password>@host:port/path
+
+* ``scheme``: Any transport protocol requiring authentication.
+* ``user``: The login used to authenticate.
+* ``password``: The associated password.
+* ``host``: The address of the server.
+* ``port``: The port the server is listening to.
+* ``path``: The path on the server.
+
+2. Embedding the user in the URL and let bzr find the right password or prompt
+for one::
+
+ bzr branch <scheme>://<user>@host/path
+
+3. Embedding nothing in the URL and let bzr find user and password or prompt
+for user and/or password::
+
+ bzr branch <scheme>://host/path
+
+This specification proposes a mechanism that will allow users to
+just use ``bzr branch <scheme>://host/path`` or ``bzr branch
+<scheme>://<user>@host/path`` and leaves bzr find the ``user``
+and ``password`` in its configuration files.
+
+When no user is specified for ``FTP``, ``SFTP`` or ``SSH``, the actual behavior
+of ``bzr`` is to default to ``getpass.get_user()``.
+
+Any implementation of this specification should respect that behaviour.
+
+This specification also proposes a way to describe credentials so that several
+remote branches can use the same definition. This is particularily important
+for users handling a lot of passwords who need to update them on a regular
+basis.
+
+Rationale
+---------
+
+Embedding user and passwords in the command line is a security
+hazard (see `bug #34685
+<https://launchpad.net/products/bzr/+bug/34685>`_).
+
+Storing passwords in ``~/.bazaar/bazaar.conf`` or ``~/.bazaar/locations.conf``
+is also a security risk.
+
+Typing user and passwords is error-prone and boring.
+
+Yet, a safe way to store passwords, while allowing bzr to retrieve them, when
+needed, could improve the bzr user experience.
+
+This specification describes a way to provide user and passwords to bzr while
+storing them in a relatively safe way.
+
+Note that ssh servers can be configured to use keys instead of (``user``,
+``password``) and, when used with appropriate agents, provide the same kind of
+comfort this specification aims to provide for all other schemes. These
+specification do not try to cover these configurations by providing
+pass-phrases, but the mechanisms presented *can* be used to provide users.
+
+Authentication definitions
+--------------------------
+
+There are two kinds of authentication used by the various schemes:
+
+1. user and password
+
+``FTP`` and ``SFTP`` needs a (``user``, ``password``) to authenticate against a
+``host`` (SFTP can use ssh keys too, but we don't talk about that in this
+specification as ssh agents provide a better solution).
+
+2. user, realm and password
+
+``HTTP`` and ``HTTPS`` needs a (``user, realm, password``) to authenticate
+against a host. But, by using ``.htaccess`` files, for example, it is possible
+to define several (``user, realm, password``) for a given ``host``. So what is
+really needed is (``user``, ``password``, ``host``, ``path``). The ``realm``
+can be ignored [#ignored_realm]_ as long as it is still presented to the user
+when prompting for the password (unless someone found a way to declare two
+different realms for the same path).
+
+``HTTP proxy`` can be handled as ``HTTP`` (or ``HTTPS``) by explicitely
+specifying the appropriate port.
+
+.. [#ignored_realm] The true purpose of realms is to allow the same credentials
+ to be reused for disjoint hierarchies. Ignoring them in this specification
+ aims to simplify the user experience while still allowing to share the same
+ credentials for a whole hierarchy.
+
+To take all schemes into account, the password will be deduced from a set of
+authentication definitions (``scheme``, ``host``, ``port``, ``path``, ``user``,
+``password``).
+
+ * ``scheme``: can be empty (meaning the rest of the definition can be used
+ for any scheme),
+
+ * ``host``: can be empty (to act as a default for any host),
+
+ * ``port`` can be empty (useful when an host provides several servers for the
+ same scheme), only numerical values are allowed,
+
+ * ``path``: can be empty (FTP or SFTP will never user it),
+
+ * ``user``: can be empty (and will use the same default as ``bzr``, python's
+ ``getpass.get_user()``),
+
+ * ``password``: can be empty (for security reasons, a user may use the
+ definitions without storing the passwords but want to be prompted).
+
+ * ``password_encoding``: can be empty (default is ``plaintext``).
+
+Also note that an optional ``verify_certificates=no`` field will allow the
+connection to ``HTTPS`` hosts that provides a self certified certificate (the
+default should be to refuse the connection and inform the user).
+
+Multiple definitions can be provided and, for a given URL, bzr will select a
+(``user`` [, ``password``]) based on the following rules :
+
+ 1. the first match wins,
+
+ 2. empty fields match everything,
+
+ 3. ``scheme`` matches even if decorators are used in the requested URL,
+
+ 4. ``host`` matches if included in the requested URL. ``foo.net`` will match a
+ requested ``bzr.foo.net``.
+
+ 5. ``port`` matches if included in the requested URL (exact matches only)
+
+ 6. ``path`` matches if included in the requested URL (and by rule #2 above,
+ empty paths will match any provided path).
+
+An optional ``password_encoding`` field may specify how the password is encoded
+but has no impact on the definition selection.
+
+Possible values are ``plaintext`` (no encoding at all) and ``base64``. When the
+field is absent, ``plaintext`` is assumed. Additional encodings may be added in
+future versions.
+
+Encoding passwords in ``base64``, while weak, provides protection against
+accidental reading (if an administrator have to look into the file, he will not
+see the passwords in clear).
+
+This specification intend to ease the authentication providing, not to secure
+it in the best possible way.
+
+Future versions of this specification may provide additional
+encodings [#password_encoding]_.
+
+.. [#password_encoding] Additional password encoding methods may be defined
+ that will rely on external means to store the password which, in these
+ cases, will not appear anymore in the definition but be provided. An
+ encoding named ``netrc`` for example will provide passwords by using the
+ ``.netrc`` file.
+
+File format
+-----------
+
+Even if ``~/.bazaar/bazaar.conf`` and ``~/.bazaar/locations.conf`` seems to
+provide most of the needed infrastructure, we choose to use a dedicated file
+for the authentication info ``~/.bazaar/authentication.conf`` for the following
+reasons:
+
+ * allow the user to protect the content of one file only, relaxing security
+ constraints on the others,
+
+ * while ``locations.conf`` is organized around *local* branches,
+ ``authentication.conf`` is organized around *remote* branches or more
+ generally servers. The same authentification definition can even be used
+ for several schemes for servers providing those schemes.
+
+``~/.bazaar/authentication.conf`` will use the same file format than
+``~/.bazaar/bazaar.conf``.
+
+Each section will define an authentication definition.
+
+The section name is an arbitrary string, only the ``DEFAULT`` value is reserved
+and should appear as the *last* section.
+
+Each section should define:
+
+ * ``user``: the login to be used,
+
+Each section could define:
+
+ * ``host``: the remote server,
+
+ * ``port``: the port the server is listening,
+
+ * ``verify_certificates``: to control certificate verification (useful
+ for self certified hosts). This applies to HTTP[S] only. Accepted values
+ are yes and no, default to yes.
+
+ * ``path``: the branch location,
+
+ * ``password``: the password,
+
+ * ``password_encoding``: the method used to encode the password if any,
+
+The default content of the file will be::
+
+ [DEFAULT]
+
+This section could define:
+
+ * ``user``: default user to be used.
+
+ * ``password_encoding``: default password encoding.
+
+Use Cases
+---------
+
+The use cases described below use the file format defined above.
+
+ * all FTP connections to the foo.net domain are done with the same (``user``,
+ ``password``)::
+
+ # Identity on foo.net
+ [foo.net]
+ scheme=ftp
+ host=foo.net
+ user=joe
+ password=secret-pass
+
+ will provide ('joe', 'secret-pass') for::
+
+ bzr branch ftp://foo.net/bzr/branch
+ bzr pull ftp://bzr.foo.net/bzr/product/branch/trunk
+
+ * all connections are done with the same ``user`` (the local one) and the
+ password is always prompted with some exceptions::
+
+ # Pet projects on hobby.net
+ [hobby]
+ scheme=https
+ host=r.hobby.net
+ verify_certificates=no
+ user=jim
+ password=obvious1234
+
+ # Home server
+ [home]
+ host=home.net
+ user=joe
+ password='c2VjcmV0LXBhc3M='
+ password_encoding=base64
+
+ [DEFAULT]
+ user=foobar
+
+ * an HTTP server that also acts as a proxy (weird)::
+
+ # development branches on dev server
+ [dev]
+ scheme=https
+ host=dev.company.com
+ path=/dev
+ user=user1
+ password=pass1
+
+ # toy branches
+ [localhost]
+ scheme=http
+ host=dev.company.com
+ path=/
+ user=user2
+ password=pass2
+
+ # Pesky proxy
+ [proxy]
+ scheme=http
+ host=dev.company.com
+ user=proxyuser1
+ password=proxypass1
+
+Note that the proxy should be specified last because it uses no path. An
+alternative is to specify the port used by the proxy.
+
+UI Changes
+----------
+
+Depending on the info provided in the URL, bzr will interact with the user in
+different ways:
+
+1. ``user`` and ``password`` given in the URL.
+
+ Nothing to do.
+
+2. ``user`` given in the URL.
+
+ Get a password from ``~/.bazaar/authentication.conf`` or prompt
+ for one if none is found.
+
+3. No ``user`` given in the URL (and no ``password``).
+
+ Get a user from ``~/.bazaar/authentication.conf`` or prompt for one if none is
+ found. Continue as 2.
+
+Note: A user will be queried only if the server requires it for ``HTTP``, other
+protocols always require a user.
+
+In any case, if the server refuses the authentication, bzr reports to the user
+and terminates.
+
+Implementation constraints
+--------------------------
+
+* bzr should be able to prompt for a ``user`` for a given (``scheme``, ``host``
+ [, ``realm``]). Note that ``realm`` may be available only after a first
+ connection attempt to the server.
+
+* No assumptions should be made about the clients of this service
+ (i.e. Transport is the primary target but plugins must be able to use it as
+ well, the definitions used: (``scheme, host, [port,] path``) are general
+ enough to described credentials for ``svn`` servers or LaunchPad xmlrpc
+ calls).
+
+* Policies regarding default users may be taken into account by the
+ implementations, there is no good way to represent that in this specification
+ and stays flexible enough to accommodate various needs (default user policies
+ may differ for different schemes and that may be easier to handle in the code
+ than in the authentication file itself).
+
+* If no user can be found by the mechanism described above, bzr should still
+ default to ``getpass.get_user()`` and may attempt a second matching to obtain
+ a password.
+
+* As this specification proposes a matching between some credentials
+ definitions and real urls, the implementation should provide an optional UI
+ feedback about which credential definition is used. That will allow the user
+ to validate his definitions.
+
+Questions and Answers
+---------------------
+
+ * What if a ``.authinfo`` file exists ?
+
+ * It will be ignored,
+
+ * Automatic (one-time) conversions may be proposed if sufficient demand
+ exists,
+
+ * What if a ``.netrc`` file exists ?
+
+ * It will be honored if the definition specifies
+ ``password_encoding=netrc`` once the appropriate plugin have been
+ written.
+
+ * What mode should the authentication file use ?
+
+ * 600 read/write for owner only by default, if another mode (more
+ permissive) is used, a warning will be issued to inform the users of the
+ potential risks.
+
+ * What about using ``seahorse`` on Ubuntu or ``KeyChain Access`` on Mac OS X ?
+
+ * plugins can be written and registered to handle the associated
+ ``password_encoding``.
+
+ * Could it be possible to encode the whole authentication file with a ssh key
+ ?
+
+ * yes and if the user configure a ssh-agent it will not be queried for
+ pass-phrase every time we want to query the file for a password. But that
+ seems a bit extreme for a first version.
+
+ * Why can't bzr update the authentication file when it queried the user for a
+ password ?
+
+ * a future version may address that but:
+
+ 1. The user may want to decide which passwords are stored in the file and
+ which aren't.
+
+ 2. The user should decide if the passwords are encoded (and how) or not
+ (but we may default to base64).
+
+ 3. The right definition may be hard to get right, but reducing it to
+ (``scheme, host, [port,] user, password``) may be a good start. I.e. no
+ path so that all paths on the host will match. The user will have to
+ modify it for more complex configurations anyway.
+
More information about the bazaar-commits
mailing list