~bzr-pqm/bzr/bzr.dev

2625.12.1 by Vincent Ladeuil
Updated after Martin's review.
1
Authentication ring
2
===================
3
4
When accessing a remote branch (specified as an URL), it may occur that the
2625.12.2 by Vincent Ladeuil
More review feedbacks.
5
server requests an authentication.
2625.12.1 by Vincent Ladeuil
Updated after Martin's review.
6
7
This authentication can be provided in different ways:
8
2625.12.2 by Vincent Ladeuil
More review feedbacks.
9
1. Embedding the user and password
10
in the URL::
2625.12.1 by Vincent Ladeuil
Updated after Martin's review.
11
2625.12.2 by Vincent Ladeuil
More review feedbacks.
12
  bzr branch <scheme>://<user>:<password>@host:port/path
2625.12.1 by Vincent Ladeuil
Updated after Martin's review.
13
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.
20
21
2. Embedding the user in the URL and let bzr find the right password or prompt
2625.12.2 by Vincent Ladeuil
More review feedbacks.
22
for one::
2625.12.1 by Vincent Ladeuil
Updated after Martin's review.
23
2625.12.2 by Vincent Ladeuil
More review feedbacks.
24
  bzr branch <scheme>://<user>@host/path
2625.12.1 by Vincent Ladeuil
Updated after Martin's review.
25
26
3. Embedding nothing in the URL and let bzr find user and password or prompt
2625.12.2 by Vincent Ladeuil
More review feedbacks.
27
for user and/or password::
28
29
  bzr branch <scheme>://host/path
30
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.
2625.12.1 by Vincent Ladeuil
Updated after Martin's review.
35
36
When no user is specified for ``FTP``, ``SFTP`` or ``SSH``, the actual behavior
37
of ``bzr`` is to default to ``getpass.get_user()``.
38
39
Any implementation of this specification should respect that behaviour.
40
2625.12.2 by Vincent Ladeuil
More review feedbacks.
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
3757.3.8 by Vincent Ladeuil
Update doc and NEWS.
43
for users handling a lot of passwords and who need to update them on a regular
2625.12.2 by Vincent Ladeuil
More review feedbacks.
44
basis.
45
2625.12.1 by Vincent Ladeuil
Updated after Martin's review.
46
Rationale
47
---------
48
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>`_).
52
53
Storing passwords in ``~/.bazaar/bazaar.conf`` or ``~/.bazaar/locations.conf``
54
is also a security risk.
55
56
Typing user and passwords is error-prone and boring.
57
58
Yet, a safe way to store passwords, while allowing bzr to retrieve them, when
59
needed, could improve the bzr user experience.
60
61
This specification describes a way to provide user and passwords to bzr while
62
storing them in a relatively safe way.
63
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
3418.5.1 by Vincent Ladeuil
Fix #183705 by updating the authentication docs regarding ssh agents.
66
comfort this specification aims to provide for all other schemes. Since ssh
3418.5.3 by Vincent Ladeuil
Fixed as per John's review.
67
agents provide a safer way to secure the passwords, this specification is
3757.3.8 by Vincent Ladeuil
Update doc and NEWS.
68
restricted to providing ``user`` but does not provide ``password`` when used
69
for ssh.
2625.12.1 by Vincent Ladeuil
Updated after Martin's review.
70
71
Authentication definitions
72
--------------------------
73
2900.2.24 by Vincent Ladeuil
Review feedback.
74
There are two kinds of authentication used by the various schemes supported by
75
bzr:
2625.12.1 by Vincent Ladeuil
Updated after Martin's review.
76
77
1. user and password
78
79
``FTP`` and ``SFTP`` needs a (``user``, ``password``) to authenticate against a
80
``host`` (SFTP can use ssh keys too, but we don't talk about that in this
81
specification as ssh agents provide a better solution).
82
83
2. user, realm and password
84
85
``HTTP`` and ``HTTPS`` needs a (``user, realm, password``) to authenticate
86
against a host. But, by using ``.htaccess`` files, for example, it is possible
87
to define several (``user, realm, password``) for a given ``host``. So what is
88
really needed is (``user``, ``password``, ``host``, ``path``). The ``realm``
89
can be ignored [#ignored_realm]_ as long as it is still presented to the user
90
when prompting for the password (unless someone found a way to declare two
4853.1.1 by Patrick Regan
Removed trailing whitespace from files in doc directory
91
different realms for the same path).
2625.12.2 by Vincent Ladeuil
More review feedbacks.
92
3757.3.9 by Vincent Ladeuil
Fix typos as per Ian's review.
93
``HTTP proxy`` can be handled as ``HTTP`` (or ``HTTPS``) by explicitly
2625.12.2 by Vincent Ladeuil
More review feedbacks.
94
specifying the appropriate port.
2625.12.1 by Vincent Ladeuil
Updated after Martin's review.
95
96
.. [#ignored_realm] The true purpose of realms is to allow the same credentials
2625.12.2 by Vincent Ladeuil
More review feedbacks.
97
   to be reused for disjoint hierarchies. Ignoring them in this specification
98
   aims to simplify the user experience while still allowing to share the same
99
   credentials for a whole hierarchy.
2625.12.1 by Vincent Ladeuil
Updated after Martin's review.
100
101
To take all schemes into account, the password will be deduced from a set of
102
authentication definitions (``scheme``, ``host``, ``port``, ``path``, ``user``,
103
``password``).
104
105
  * ``scheme``: can be empty (meaning the rest of the definition can be used
2900.2.8 by Vincent Ladeuil
Make sftp and bzr+ssh aware of authentication config.
106
    for any scheme), ``SFTP`` and ``bzr+ssh`` should not be used here, ``ssh``
107
    should be used instead since this is the real scheme regarding
108
    authentication,
2625.12.1 by Vincent Ladeuil
Updated after Martin's review.
109
110
  * ``host``: can be empty (to act as a default for any host),
111
112
  * ``port`` can be empty (useful when an host provides several servers for the
2900.2.3 by Vincent Ladeuil
Credentials matching implementation.
113
    same scheme), only numerical values are allowed, this should be used only
2900.2.24 by Vincent Ladeuil
Review feedback.
114
    when the server uses a port different than the scheme standard port,
2625.12.1 by Vincent Ladeuil
Updated after Martin's review.
115
3757.3.8 by Vincent Ladeuil
Update doc and NEWS.
116
  * ``path``: can be empty (FTP or SFTP will never use it),
2625.12.1 by Vincent Ladeuil
Updated after Martin's review.
117
2900.2.3 by Vincent Ladeuil
Credentials matching implementation.
118
  * ``user``: can be empty (``bzr`` will defaults to python's
3757.3.8 by Vincent Ladeuil
Update doc and NEWS.
119
    ``getpass.get_user()`` for FTP, SFTP and ssh),
2625.12.1 by Vincent Ladeuil
Updated after Martin's review.
120
121
  * ``password``: can be empty (for security reasons, a user may use the
2900.2.3 by Vincent Ladeuil
Credentials matching implementation.
122
    definitions without storing the passwords but want to be prompted ; or the
123
    password will be provided by an external plugin via the
3418.5.1 by Vincent Ladeuil
Fix #183705 by updating the authentication docs regarding ssh agents.
124
    ``password_encoding`` mechanism decribed below). Must be left empty for
125
    ``ssh``.
2625.12.1 by Vincent Ladeuil
Updated after Martin's review.
126
2625.12.2 by Vincent Ladeuil
More review feedbacks.
127
  * ``password_encoding``: can be empty (default is ``plaintext``).
128
2625.12.3 by Vincent Ladeuil
Last review feedback, spec approved
129
Also note that an optional ``verify_certificates=no`` field will allow the
130
connection to ``HTTPS`` hosts that provides a self certified certificate (the
3757.3.8 by Vincent Ladeuil
Update doc and NEWS.
131
default should be to refuse the connection and inform the user). (Not
132
implemented yet)
2625.12.1 by Vincent Ladeuil
Updated after Martin's review.
133
134
Multiple definitions can be provided and, for a given URL, bzr will select a
135
(``user`` [, ``password``]) based on the following rules :
136
137
 1. the first match wins,
138
139
 2. empty fields match everything,
140
141
 3. ``scheme`` matches even if decorators are used in the requested URL,
142
2900.2.3 by Vincent Ladeuil
Credentials matching implementation.
143
 4. ``host`` matches exactly or act as a domain if it starts with '.'
2900.2.24 by Vincent Ladeuil
Review feedback.
144
    (``project.bzr.sf.net`` will match ``.bzr.sf.net`` but ``projectbzr.sf.net``
145
    will not match ``bzr.sf.net``).
2625.12.1 by Vincent Ladeuil
Updated after Martin's review.
146
147
 5. ``port`` matches if included in the requested URL (exact matches only)
148
149
 6. ``path`` matches if included in the requested URL (and by rule #2 above,
150
    empty paths will match any provided path).
151
2625.12.2 by Vincent Ladeuil
More review feedbacks.
152
An optional ``password_encoding`` field may specify how the password is encoded
153
but has no impact on the definition selection.
2625.12.1 by Vincent Ladeuil
Updated after Martin's review.
154
155
Possible values are ``plaintext`` (no encoding at all) and ``base64``. When the
156
field is absent, ``plaintext`` is assumed. Additional encodings may be added in
157
future versions.
158
159
Encoding passwords in ``base64``, while weak, provides protection against
160
accidental reading (if an administrator have to look into the file, he will not
3757.3.8 by Vincent Ladeuil
Update doc and NEWS.
161
see the passwords in clear).(Not implemented yet).
2625.12.1 by Vincent Ladeuil
Updated after Martin's review.
162
3757.3.9 by Vincent Ladeuil
Fix typos as per Ian's review.
163
This specification intends to ease the authentication providing, not to secure
2625.12.1 by Vincent Ladeuil
Updated after Martin's review.
164
it in the best possible way.
165
3757.3.9 by Vincent Ladeuil
Fix typos as per Ian's review.
166
Plugins can provide additional password encodings. The provided
3757.3.8 by Vincent Ladeuil
Update doc and NEWS.
167
``netrc_credential_store`` plugin can be used as an example implementation.
168
2625.12.2 by Vincent Ladeuil
More review feedbacks.
169
Future versions of this specification may provide additional
170
encodings [#password_encoding]_.
171
2900.2.15 by Vincent Ladeuil
AuthenticationConfig can be queried for logins too (first step).
172
.. [#password_encoding] Additional password encoding methods may be defined
173
   that will rely on external means to store the password which, in these
174
   cases, will not appear anymore in the definition. It is assumed that
175
   additional password encodings will provide a storage outside of the file
3757.3.9 by Vincent Ladeuil
Fix typos as per Ian's review.
176
   described here. The ``netrc`` encoding, for example, provides passwords by
177
   retrieving them from the ``.netrc`` file.
2625.12.1 by Vincent Ladeuil
Updated after Martin's review.
178
179
File format
180
-----------
181
182
Even if ``~/.bazaar/bazaar.conf`` and ``~/.bazaar/locations.conf`` seems to
183
provide most of the needed infrastructure, we choose to use a dedicated file
184
for the authentication info ``~/.bazaar/authentication.conf`` for the following
185
reasons:
186
187
  * allow the user to protect the content of one file only, relaxing security
188
    constraints on the others,
189
2625.12.2 by Vincent Ladeuil
More review feedbacks.
190
  * while ``locations.conf`` is organized around *local* branches,
191
    ``authentication.conf`` is organized around *remote* branches or more
192
    generally servers. The same authentification definition can even be used
193
    for several schemes for servers providing those schemes.
2625.12.1 by Vincent Ladeuil
Updated after Martin's review.
194
3757.3.9 by Vincent Ladeuil
Fix typos as per Ian's review.
195
``~/.bazaar/authentication.conf`` will use the same file format as
2625.12.1 by Vincent Ladeuil
Updated after Martin's review.
196
``~/.bazaar/bazaar.conf``.
197
2900.2.24 by Vincent Ladeuil
Review feedback.
198
Each section describes an authentication definition.
2625.12.1 by Vincent Ladeuil
Updated after Martin's review.
199
200
The section name is an arbitrary string, only the ``DEFAULT`` value is reserved
201
and should appear as the *last* section.
202
203
Each section should define:
204
205
  * ``user``: the login to be used,
206
207
Each section could define:
208
209
  * ``host``: the remote server,
210
211
  * ``port``: the port the server is listening,
212
2625.12.2 by Vincent Ladeuil
More review feedbacks.
213
  * ``verify_certificates``: to control certificate verification (useful
2929.3.19 by Vincent Ladeuil
Fix 1.1 related bugs in HTTP server, add HTTPS passing tests (by temporarily disabling pycurl certificate verification).
214
    for self certified hosts). This applies to HTTPS only. Accepted values
2625.12.2 by Vincent Ladeuil
More review feedbacks.
215
    are yes and no, default to yes.
2625.12.1 by Vincent Ladeuil
Updated after Martin's review.
216
217
  * ``path``: the branch location,
218
219
  * ``password``: the password,
220
221
  * ``password_encoding``: the method used to encode the password if any,
222
223
The default content of the file will be::
224
225
    [DEFAULT]
226
227
This section could define:
228
2900.2.2 by Vincent Ladeuil
Rephrase some sentences.
229
  * ``user``: default user to be used (if not defined the usual
230
    bzr way applies, see below).
2625.12.1 by Vincent Ladeuil
Updated after Martin's review.
231
232
  * ``password_encoding``: default password encoding.
233
234
Use Cases
235
---------
236
237
The use cases described below use the file format defined above.
238
239
  * all FTP connections to the foo.net domain are done with the same (``user``,
240
    ``password``)::
241
242
        # Identity on foo.net
243
        [foo.net]
244
        scheme=ftp
245
        host=foo.net
246
        user=joe
247
        password=secret-pass
248
249
    will provide ('joe', 'secret-pass') for::
250
251
        bzr branch ftp://foo.net/bzr/branch
252
        bzr pull ftp://bzr.foo.net/bzr/product/branch/trunk
253
2900.2.15 by Vincent Ladeuil
AuthenticationConfig can be queried for logins too (first step).
254
  * all connections are done with the same ``user`` (the remote one for which
255
    the default bzr one is not appropriate) and the password is always prompted
256
    with some exceptions::
2625.12.1 by Vincent Ladeuil
Updated after Martin's review.
257
258
        # Pet projects on hobby.net
259
        [hobby]
260
        host=r.hobby.net
261
        user=jim
262
        password=obvious1234
4853.1.1 by Patrick Regan
Removed trailing whitespace from files in doc directory
263
2625.12.1 by Vincent Ladeuil
Updated after Martin's review.
264
        # Home server
265
        [home]
2900.2.10 by Vincent Ladeuil
Add -Dauth handling.
266
        scheme=https
2625.12.1 by Vincent Ladeuil
Updated after Martin's review.
267
        host=home.net
268
        user=joe
269
        password='c2VjcmV0LXBhc3M='
270
        password_encoding=base64
2900.2.10 by Vincent Ladeuil
Add -Dauth handling.
271
        verify_certificates=no # Still searching a free certificate provider
4853.1.1 by Patrick Regan
Removed trailing whitespace from files in doc directory
272
2625.12.1 by Vincent Ladeuil
Updated after Martin's review.
273
        [DEFAULT]
2900.2.15 by Vincent Ladeuil
AuthenticationConfig can be queried for logins too (first step).
274
        # Our local user is barbaz, on all remote sites we're known as foobar
2625.12.1 by Vincent Ladeuil
Updated after Martin's review.
275
        user=foobar
4853.1.1 by Patrick Regan
Removed trailing whitespace from files in doc directory
276
2900.2.3 by Vincent Ladeuil
Credentials matching implementation.
277
  * an HTTP server and a proxy::
2625.12.1 by Vincent Ladeuil
Updated after Martin's review.
278
279
        # development branches on dev server
280
        [dev]
281
        scheme=https
282
        host=dev.company.com
283
        path=/dev
284
        user=user1
285
        password=pass1
4853.1.1 by Patrick Regan
Removed trailing whitespace from files in doc directory
286
2625.12.1 by Vincent Ladeuil
Updated after Martin's review.
287
        # toy branches
288
        [localhost]
289
        scheme=http
290
        host=dev.company.com
291
        path=/
292
        user=user2
293
        password=pass2
4853.1.1 by Patrick Regan
Removed trailing whitespace from files in doc directory
294
2900.2.3 by Vincent Ladeuil
Credentials matching implementation.
295
        # proxy
2625.12.1 by Vincent Ladeuil
Updated after Martin's review.
296
        [proxy]
297
        scheme=http
2900.2.3 by Vincent Ladeuil
Credentials matching implementation.
298
        host=proxy.company.com
299
        port=3128
2625.12.1 by Vincent Ladeuil
Updated after Martin's review.
300
        user=proxyuser1
301
        password=proxypass1
2900.2.10 by Vincent Ladeuil
Add -Dauth handling.
302
303
  * source hosting provider declaring sub-domains for each project::
304
2900.2.15 by Vincent Ladeuil
AuthenticationConfig can be queried for logins too (first step).
305
        [sfnet domain]
306
        # we use sftp, but ssh is the scheme used for authentication
307
        scheme=ssh
308
        # The leading '.' ensures that 'sf.net' alone doesn't match
309
        host=.sf.net
2900.2.10 by Vincent Ladeuil
Add -Dauth handling.
310
        user=georges
311
        password=ben...son
312
2625.12.1 by Vincent Ladeuil
Updated after Martin's review.
313
314
UI Changes
315
----------
316
317
Depending on the info provided in the URL, bzr will interact with the user in
318
different ways:
319
320
1. ``user`` and ``password`` given in the URL.
321
322
  Nothing to do.
323
324
2. ``user`` given in the URL.
325
326
  Get a password from ``~/.bazaar/authentication.conf`` or prompt
327
  for one if none is found.
328
329
3. No ``user`` given in the URL (and no ``password``).
330
331
  Get a user from ``~/.bazaar/authentication.conf`` or prompt for one if none is
3757.3.8 by Vincent Ladeuil
Update doc and NEWS.
332
  found. Continue as 2. (Not implemented yet)
2625.12.1 by Vincent Ladeuil
Updated after Martin's review.
333
2900.2.15 by Vincent Ladeuil
AuthenticationConfig can be queried for logins too (first step).
334
Note: A user will be queried only if the server requires it for ``HTTP`` or
335
``HTTPS``, other protocols always require a user.
2625.12.1 by Vincent Ladeuil
Updated after Martin's review.
336
337
In any case, if the server refuses the authentication, bzr reports to the user
338
and terminates.
339
340
Implementation constraints
341
--------------------------
342
343
* bzr should be able to prompt for a ``user`` for a given (``scheme``, ``host``
2900.2.2 by Vincent Ladeuil
Rephrase some sentences.
344
  [, ``realm``]). Note that ``realm`` is available only after a first
2625.12.1 by Vincent Ladeuil
Updated after Martin's review.
345
  connection attempt to the server.
346
347
* No assumptions should be made about the clients of this service
348
  (i.e. Transport is the primary target but plugins must be able to use it as
349
  well, the definitions used: (``scheme, host, [port,] path``) are general
350
  enough to described credentials for ``svn`` servers or LaunchPad xmlrpc
351
  calls).
352
353
* Policies regarding default users may be taken into account by the
354
  implementations, there is no good way to represent that in this specification
355
  and stays flexible enough to accommodate various needs (default user policies
356
  may differ for different schemes and that may be easier to handle in the code
357
  than in the authentication file itself).
358
359
* If no user can be found by the mechanism described above, bzr should still
360
  default to ``getpass.get_user()`` and may attempt a second matching to obtain
361
  a password.
362
2625.12.3 by Vincent Ladeuil
Last review feedback, spec approved
363
* As this specification proposes a matching between some credentials
3757.3.8 by Vincent Ladeuil
Update doc and NEWS.
364
  definitions and real urls, the implementation provides an optional UI
365
  feedback about which credential definition is used. Using ``-Dauth`` will
366
  output some traces in the ``.bzr.log`` file metionning the sections
367
  used. This allows the user to validate his definitions.
2625.12.3 by Vincent Ladeuil
Last review feedback, spec approved
368
2625.12.1 by Vincent Ladeuil
Updated after Martin's review.
369
Questions and Answers
370
---------------------
371
2625.12.2 by Vincent Ladeuil
More review feedbacks.
372
  * What if a ``.authinfo`` file exists ?
2625.12.1 by Vincent Ladeuil
Updated after Martin's review.
373
2625.12.2 by Vincent Ladeuil
More review feedbacks.
374
    * It will be ignored,
2625.12.1 by Vincent Ladeuil
Updated after Martin's review.
375
376
    * Automatic (one-time) conversions may be proposed if sufficient demand
377
      exists,
378
2625.12.2 by Vincent Ladeuil
More review feedbacks.
379
  * What if a ``.netrc`` file exists ?
380
3757.3.8 by Vincent Ladeuil
Update doc and NEWS.
381
    * It is honored if the definition specifies
382
      ``password_encoding=netrc``.
2625.12.2 by Vincent Ladeuil
More review feedbacks.
383
2625.12.1 by Vincent Ladeuil
Updated after Martin's review.
384
  * What mode should the authentication file use ?
385
386
    * 600 read/write for owner only by default, if another mode (more
387
      permissive) is used, a warning will be issued to inform the users of the
3757.3.8 by Vincent Ladeuil
Update doc and NEWS.
388
      potential risks.(Not implemented yet)
2625.12.1 by Vincent Ladeuil
Updated after Martin's review.
389
390
  * What about using ``seahorse`` on Ubuntu or ``KeyChain Access`` on Mac OS X ?
391
2625.12.2 by Vincent Ladeuil
More review feedbacks.
392
    * plugins can be written and registered to handle the associated
2625.12.1 by Vincent Ladeuil
Updated after Martin's review.
393
      ``password_encoding``.
394
395
  * Could it be possible to encode the whole authentication file with a ssh key
396
    ?
397
398
    * yes and if the user configure a ssh-agent it will not be queried for
3757.3.8 by Vincent Ladeuil
Update doc and NEWS.
399
      pass-phrase every time we want to query the file for a password. But
400
      that seems a bit extreme for a first version.(Not implemented yet and
401
      may be never)
2625.12.1 by Vincent Ladeuil
Updated after Martin's review.
402
403
  * Why can't bzr update the authentication file when it queried the user for a
404
    password ?
405
406
    * a future version may address that but:
407
408
      1. The user may want to decide which passwords are stored in the file and
2625.12.2 by Vincent Ladeuil
More review feedbacks.
409
      which aren't.
410
411
      2. The user should decide if the passwords are encoded (and how) or not
412
      (but we may default to base64).
413
414
      3. The right definition may be hard to get right, but reducing it to
415
      (``scheme, host, [port,] user, password``) may be a good start. I.e. no
416
      path so that all paths on the host will match. The user will have to
417
      modify it for more complex configurations anyway.
418