4
When accessing a remote branch (specified as an URL), it may occur that the
5
server requests an authentication.
7
This authentication can be provided in different ways:
9
1. Embedding the user and password
12
bzr branch <scheme>://<user>:<password>@host:port/path
14
* ``scheme``: Any transport protocol requiring authentication.
15
* ``user``: The login used to authenticate.
16
* ``password``: The associated password.
17
* ``host``: The address of the server.
18
* ``port``: The port the server is listening to.
19
* ``path``: The path on the server.
21
2. Embedding the user in the URL and let bzr find the right password or prompt
24
bzr branch <scheme>://<user>@host/path
26
3. Embedding nothing in the URL and let bzr find user and password or prompt
27
for user and/or password::
29
bzr branch <scheme>://host/path
31
This specification proposes a mechanism that will allow users to
32
just use ``bzr branch <scheme>://host/path`` or ``bzr branch
33
<scheme>://<user>@host/path`` and leaves bzr find the ``user``
34
and ``password`` in its configuration files.
36
When no user is specified for ``FTP``, ``SFTP`` or ``SSH``, the actual behavior
37
of ``bzr`` is to default to ``getpass.get_user()``.
39
Any implementation of this specification should respect that behaviour.
41
This specification also proposes a way to describe credentials so that several
42
remote branches can use the same definition. This is particularily important
43
for users handling a lot of passwords who need to update them on a regular
49
Embedding user and passwords in the command line is a security
50
hazard (see `bug #34685
51
<https://launchpad.net/products/bzr/+bug/34685>`_).
53
Storing passwords in ``~/.bazaar/bazaar.conf`` or ``~/.bazaar/locations.conf``
54
is also a security risk.
56
Typing user and passwords is error-prone and boring.
58
Yet, a safe way to store passwords, while allowing bzr to retrieve them, when
59
needed, could improve the bzr user experience.
61
This specification describes a way to provide user and passwords to bzr while
62
storing them in a relatively safe way.
64
Note that ssh servers can be configured to use keys instead of (``user``,
65
``password``) and, when used with appropriate agents, provide the same kind of
66
comfort this specification aims to provide for all other schemes. Since ssh
67
agents provide a safer way to secure the passwords, this specification is
68
restricted to providing ``user`` but does not provide ``password``.
70
Authentication definitions
71
--------------------------
73
There are two kinds of authentication used by the various schemes supported by
78
``FTP`` and ``SFTP`` needs a (``user``, ``password``) to authenticate against a
79
``host`` (SFTP can use ssh keys too, but we don't talk about that in this
80
specification as ssh agents provide a better solution).
82
2. user, realm and password
84
``HTTP`` and ``HTTPS`` needs a (``user, realm, password``) to authenticate
85
against a host. But, by using ``.htaccess`` files, for example, it is possible
86
to define several (``user, realm, password``) for a given ``host``. So what is
87
really needed is (``user``, ``password``, ``host``, ``path``). The ``realm``
88
can be ignored [#ignored_realm]_ as long as it is still presented to the user
89
when prompting for the password (unless someone found a way to declare two
90
different realms for the same path).
92
``HTTP proxy`` can be handled as ``HTTP`` (or ``HTTPS``) by explicitely
93
specifying the appropriate port.
95
.. [#ignored_realm] The true purpose of realms is to allow the same credentials
96
to be reused for disjoint hierarchies. Ignoring them in this specification
97
aims to simplify the user experience while still allowing to share the same
98
credentials for a whole hierarchy.
100
To take all schemes into account, the password will be deduced from a set of
101
authentication definitions (``scheme``, ``host``, ``port``, ``path``, ``user``,
104
* ``scheme``: can be empty (meaning the rest of the definition can be used
105
for any scheme), ``SFTP`` and ``bzr+ssh`` should not be used here, ``ssh``
106
should be used instead since this is the real scheme regarding
109
* ``host``: can be empty (to act as a default for any host),
111
* ``port`` can be empty (useful when an host provides several servers for the
112
same scheme), only numerical values are allowed, this should be used only
113
when the server uses a port different than the scheme standard port,
115
* ``path``: can be empty (FTP or SFTP will never user it),
117
* ``user``: can be empty (``bzr`` will defaults to python's
118
``getpass.get_user()`` and attempt another matching(see below)),
120
* ``password``: can be empty (for security reasons, a user may use the
121
definitions without storing the passwords but want to be prompted ; or the
122
password will be provided by an external plugin via the
123
``password_encoding`` mechanism decribed below). Must be left empty for
126
* ``password_encoding``: can be empty (default is ``plaintext``).
128
Also note that an optional ``verify_certificates=no`` field will allow the
129
connection to ``HTTPS`` hosts that provides a self certified certificate (the
130
default should be to refuse the connection and inform the user).
132
Multiple definitions can be provided and, for a given URL, bzr will select a
133
(``user`` [, ``password``]) based on the following rules :
135
1. the first match wins,
137
2. empty fields match everything,
139
3. ``scheme`` matches even if decorators are used in the requested URL,
141
4. ``host`` matches exactly or act as a domain if it starts with '.'
142
(``project.bzr.sf.net`` will match ``.bzr.sf.net`` but ``projectbzr.sf.net``
143
will not match ``bzr.sf.net``).
145
5. ``port`` matches if included in the requested URL (exact matches only)
147
6. ``path`` matches if included in the requested URL (and by rule #2 above,
148
empty paths will match any provided path).
150
An optional ``password_encoding`` field may specify how the password is encoded
151
but has no impact on the definition selection.
153
Possible values are ``plaintext`` (no encoding at all) and ``base64``. When the
154
field is absent, ``plaintext`` is assumed. Additional encodings may be added in
157
Encoding passwords in ``base64``, while weak, provides protection against
158
accidental reading (if an administrator have to look into the file, he will not
159
see the passwords in clear).
161
This specification intend to ease the authentication providing, not to secure
162
it in the best possible way.
164
Future versions of this specification may provide additional
165
encodings [#password_encoding]_.
167
.. [#password_encoding] Additional password encoding methods may be defined
168
that will rely on external means to store the password which, in these
169
cases, will not appear anymore in the definition. It is assumed that
170
additional password encodings will provide a storage outside of the file
171
described here. An encoding named ``netrc`` for example will provide
172
passwords by retrieving them in the ``.netrc`` file.
177
Even if ``~/.bazaar/bazaar.conf`` and ``~/.bazaar/locations.conf`` seems to
178
provide most of the needed infrastructure, we choose to use a dedicated file
179
for the authentication info ``~/.bazaar/authentication.conf`` for the following
182
* allow the user to protect the content of one file only, relaxing security
183
constraints on the others,
185
* while ``locations.conf`` is organized around *local* branches,
186
``authentication.conf`` is organized around *remote* branches or more
187
generally servers. The same authentification definition can even be used
188
for several schemes for servers providing those schemes.
190
``~/.bazaar/authentication.conf`` will use the same file format than
191
``~/.bazaar/bazaar.conf``.
193
Each section describes an authentication definition.
195
The section name is an arbitrary string, only the ``DEFAULT`` value is reserved
196
and should appear as the *last* section.
198
Each section should define:
200
* ``user``: the login to be used,
202
Each section could define:
204
* ``host``: the remote server,
206
* ``port``: the port the server is listening,
208
* ``verify_certificates``: to control certificate verification (useful
209
for self certified hosts). This applies to HTTP[S] only. Accepted values
210
are yes and no, default to yes.
212
* ``path``: the branch location,
214
* ``password``: the password,
216
* ``password_encoding``: the method used to encode the password if any,
218
The default content of the file will be::
222
This section could define:
224
* ``user``: default user to be used (if not defined the usual
225
bzr way applies, see below).
227
* ``password_encoding``: default password encoding.
232
The use cases described below use the file format defined above.
234
* all FTP connections to the foo.net domain are done with the same (``user``,
237
# Identity on foo.net
244
will provide ('joe', 'secret-pass') for::
246
bzr branch ftp://foo.net/bzr/branch
247
bzr pull ftp://bzr.foo.net/bzr/product/branch/trunk
249
* all connections are done with the same ``user`` (the remote one for which
250
the default bzr one is not appropriate) and the password is always prompted
251
with some exceptions::
253
# Pet projects on hobby.net
264
password='c2VjcmV0LXBhc3M='
265
password_encoding=base64
266
verify_certificates=no # Still searching a free certificate provider
269
# Our local user is barbaz, on all remote sites we're known as foobar
272
* an HTTP server and a proxy::
274
# development branches on dev server
293
host=proxy.company.com
298
* source hosting provider declaring sub-domains for each project::
301
# we use sftp, but ssh is the scheme used for authentication
303
# The leading '.' ensures that 'sf.net' alone doesn't match
312
Depending on the info provided in the URL, bzr will interact with the user in
315
1. ``user`` and ``password`` given in the URL.
319
2. ``user`` given in the URL.
321
Get a password from ``~/.bazaar/authentication.conf`` or prompt
322
for one if none is found.
324
3. No ``user`` given in the URL (and no ``password``).
326
Get a user from ``~/.bazaar/authentication.conf`` or prompt for one if none is
327
found. Continue as 2.
329
Note: A user will be queried only if the server requires it for ``HTTP`` or
330
``HTTPS``, other protocols always require a user.
332
In any case, if the server refuses the authentication, bzr reports to the user
335
Implementation constraints
336
--------------------------
338
* bzr should be able to prompt for a ``user`` for a given (``scheme``, ``host``
339
[, ``realm``]). Note that ``realm`` is available only after a first
340
connection attempt to the server.
342
* No assumptions should be made about the clients of this service
343
(i.e. Transport is the primary target but plugins must be able to use it as
344
well, the definitions used: (``scheme, host, [port,] path``) are general
345
enough to described credentials for ``svn`` servers or LaunchPad xmlrpc
348
* Policies regarding default users may be taken into account by the
349
implementations, there is no good way to represent that in this specification
350
and stays flexible enough to accommodate various needs (default user policies
351
may differ for different schemes and that may be easier to handle in the code
352
than in the authentication file itself).
354
* If no user can be found by the mechanism described above, bzr should still
355
default to ``getpass.get_user()`` and may attempt a second matching to obtain
358
* As this specification proposes a matching between some credentials
359
definitions and real urls, the implementation should provide an optional UI
360
feedback about which credential definition is used. That will allow the user
361
to validate his definitions.
363
Questions and Answers
364
---------------------
366
* What if a ``.authinfo`` file exists ?
368
* It will be ignored,
370
* Automatic (one-time) conversions may be proposed if sufficient demand
373
* What if a ``.netrc`` file exists ?
375
* It will be honored if the definition specifies
376
``password_encoding=netrc`` once the appropriate plugin have been
379
* What mode should the authentication file use ?
381
* 600 read/write for owner only by default, if another mode (more
382
permissive) is used, a warning will be issued to inform the users of the
385
* What about using ``seahorse`` on Ubuntu or ``KeyChain Access`` on Mac OS X ?
387
* plugins can be written and registered to handle the associated
388
``password_encoding``.
390
* Could it be possible to encode the whole authentication file with a ssh key
393
* yes and if the user configure a ssh-agent it will not be queried for
394
pass-phrase every time we want to query the file for a password. But that
395
seems a bit extreme for a first version.
397
* Why can't bzr update the authentication file when it queried the user for a
400
* a future version may address that but:
402
1. The user may want to decide which passwords are stored in the file and
405
2. The user should decide if the passwords are encoded (and how) or not
406
(but we may default to base64).
408
3. The right definition may be hard to get right, but reducing it to
409
(``scheme, host, [port,] user, password``) may be a good start. I.e. no
410
path so that all paths on the host will match. The user will have to
411
modify it for more complex configurations anyway.
added
removed
doc/developers/authentication-ring.txt
