← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/developers/authentication-ring.txt

  • Committer: Patch Queue Manager
  • Date: 2016-04-21 04:10:52 UTC
  • mfrom: (6616.1.1 fix-en-user-guide)
  • Revision ID: pqm@pqm.ubuntu.com-20160421041052-clcye7ns1qcl2n7w
(richard-wilbur) Ensure build of English use guide always uses English text
 even when user's locale specifies a different language. (Jelmer Vernooij)

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/developers/authentication-ring.txt
40
40
 
41
41
This specification also proposes a way to describe credentials so that several
42
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
 
43
for users handling a lot of passwords and who need to update them on a regular
44
44
basis.
45
45
 
46
46
Rationale
61
61
This specification describes a way to provide user and passwords to bzr while
62
62
storing them in a relatively safe way.
63
63
 
64
 
Note that ssh servers can be configured to use keys instead of (``user``,
 
64
Note that SSH servers can be configured to use keys instead of (``user``,
65
65
``password``) and, when used with appropriate agents, provide the same kind of
66
 
comfort this specification aims to provide for all other schemes. These
67
 
specification do not try to cover these configurations by providing
68
 
pass-phrases, but the mechanisms presented *can* be used to provide users.
 
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`` when used
 
69
for SSH.
69
70
 
70
71
Authentication definitions
71
72
--------------------------
76
77
1. user and password
77
78
 
78
79
``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).
 
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).
81
82
 
82
83
2. user, realm and password
83
84
 
87
88
really needed is (``user``, ``password``, ``host``, ``path``). The ``realm``
88
89
can be ignored [#ignored_realm]_ as long as it is still presented to the user
89
90
when prompting for the password (unless someone found a way to declare two
90
 
different realms for the same path). 
 
91
different realms for the same path).
91
92
 
92
 
``HTTP proxy`` can be handled as ``HTTP`` (or ``HTTPS``) by explicitely
 
93
``HTTP proxy`` can be handled as ``HTTP`` (or ``HTTPS``) by explicitly
93
94
specifying the appropriate port.
94
95
 
95
96
.. [#ignored_realm] The true purpose of realms is to allow the same credentials
112
113
    same scheme), only numerical values are allowed, this should be used only
113
114
    when the server uses a port different than the scheme standard port,
114
115
 
115
 
  * ``path``: can be empty (FTP or SFTP will never user it),
 
116
  * ``path``: can be empty (FTP or SFTP will never use it),
116
117
 
117
 
  * ``user``: can be empty (``bzr`` will defaults to python's
118
 
    ``getpass.get_user()`` and attempt another matching(see below)),
 
118
  * ``user``: can be empty (``bzr`` will defaults to Python's
 
119
    ``getpass.get_user()`` for FTP, SFTP and SSH),
119
120
 
120
121
  * ``password``: can be empty (for security reasons, a user may use the
121
122
    definitions without storing the passwords but want to be prompted ; or the
122
123
    password will be provided by an external plugin via the
123
 
    ``password_encoding`` mechanism decribed below).
 
124
    ``password_encoding`` mechanism decribed below). Must be left empty for
 
125
    ``ssh``.
124
126
 
125
127
  * ``password_encoding``: can be empty (default is ``plaintext``).
126
128
 
127
129
Also note that an optional ``verify_certificates=no`` field will allow the
128
130
connection to ``HTTPS`` hosts that provides a self certified certificate (the
129
 
default should be to refuse the connection and inform the user).
 
131
default should be to refuse the connection and inform the user). (Not
 
132
implemented yet)
130
133
 
131
134
Multiple definitions can be provided and, for a given URL, bzr will select a
132
135
(``user`` [, ``password``]) based on the following rules :
157
160
accidental reading (if an administrator have to look into the file, he will not
158
161
see the passwords in clear).
159
162
 
160
 
This specification intend to ease the authentication providing, not to secure
 
163
This specification intends to ease the authentication providing, not to secure
161
164
it in the best possible way.
162
165
 
 
166
Plugins can provide additional password encodings. The provided
 
167
``netrc_credential_store`` plugin can be used as an example implementation.
 
168
 
163
169
Future versions of this specification may provide additional
164
170
encodings [#password_encoding]_.
165
171
 
167
173
   that will rely on external means to store the password which, in these
168
174
   cases, will not appear anymore in the definition. It is assumed that
169
175
   additional password encodings will provide a storage outside of the file
170
 
   described here. An encoding named ``netrc`` for example will provide
171
 
   passwords by retrieving them in the ``.netrc`` file.
 
176
   described here. The ``netrc`` encoding, for example, provides passwords by
 
177
   retrieving them from the ``.netrc`` file.
172
178
 
173
179
File format
174
180
-----------
186
192
    generally servers. The same authentification definition can even be used
187
193
    for several schemes for servers providing those schemes.
188
194
 
189
 
``~/.bazaar/authentication.conf`` will use the same file format than
 
195
``~/.bazaar/authentication.conf`` will use the same file format as
190
196
``~/.bazaar/bazaar.conf``.
191
197
 
192
198
Each section describes an authentication definition.
205
211
  * ``port``: the port the server is listening,
206
212
 
207
213
  * ``verify_certificates``: to control certificate verification (useful
208
 
    for self certified hosts). This applies to HTTP[S] only. Accepted values
 
214
    for self certified hosts). This applies to HTTPS only. Accepted values
209
215
    are yes and no, default to yes.
210
216
 
211
217
  * ``path``: the branch location,
254
260
        host=r.hobby.net
255
261
        user=jim
256
262
        password=obvious1234
257
 
        
 
263
 
258
264
        # Home server
259
265
        [home]
260
266
        scheme=https
261
267
        host=home.net
262
268
        user=joe
 
269
        # Obtain the base64 encoded password by running 'echo -n "secret-pass" | base64'
263
270
        password='c2VjcmV0LXBhc3M='
264
271
        password_encoding=base64
265
272
        verify_certificates=no # Still searching a free certificate provider
266
 
        
 
273
 
267
274
        [DEFAULT]
268
275
        # Our local user is barbaz, on all remote sites we're known as foobar
269
276
        user=foobar
270
 
        
 
277
 
271
278
  * an HTTP server and a proxy::
272
279
 
273
280
        # development branches on dev server
277
284
        path=/dev
278
285
        user=user1
279
286
        password=pass1
280
 
        
 
287
 
281
288
        # toy branches
282
289
        [localhost]
283
290
        scheme=http
285
292
        path=/
286
293
        user=user2
287
294
        password=pass2
288
 
        
 
295
 
289
296
        # proxy
290
297
        [proxy]
291
298
        scheme=http
297
304
  * source hosting provider declaring sub-domains for each project::
298
305
 
299
306
        [sfnet domain]
300
 
        # we use sftp, but ssh is the scheme used for authentication
 
307
        # we use SFTP, but SSH is the scheme used for authentication
301
308
        scheme=ssh
302
309
        # The leading '.' ensures that 'sf.net' alone doesn't match
303
310
        host=.sf.net
323
330
3. No ``user`` given in the URL (and no ``password``).
324
331
 
325
332
  Get a user from ``~/.bazaar/authentication.conf`` or prompt for one if none is
326
 
  found. Continue as 2.
 
333
  found. Continue as 2. (Not implemented yet)
327
334
 
328
335
Note: A user will be queried only if the server requires it for ``HTTP`` or
329
336
``HTTPS``, other protocols always require a user.
341
348
* No assumptions should be made about the clients of this service
342
349
  (i.e. Transport is the primary target but plugins must be able to use it as
343
350
  well, the definitions used: (``scheme, host, [port,] path``) are general
344
 
  enough to described credentials for ``svn`` servers or LaunchPad xmlrpc
 
351
  enough to described credentials for ``svn`` servers or LaunchPad XML-RPC
345
352
  calls).
346
353
 
347
354
* Policies regarding default users may be taken into account by the
355
362
  a password.
356
363
 
357
364
* As this specification proposes a matching between some credentials
358
 
  definitions and real urls, the implementation should provide an optional UI
359
 
  feedback about which credential definition is used. That will allow the user
360
 
  to validate his definitions.
 
365
  definitions and real URLs, the implementation provides an optional UI
 
366
  feedback about which credential definition is used. Using ``-Dauth`` will
 
367
  output some traces in the ``.bzr.log`` file metionning the sections
 
368
  used. This allows the user to validate his definitions.
361
369
 
362
370
Questions and Answers
363
371
---------------------
371
379
 
372
380
  * What if a ``.netrc`` file exists ?
373
381
 
374
 
    * It will be honored if the definition specifies
375
 
      ``password_encoding=netrc`` once the appropriate plugin have been
376
 
      written.
 
382
    * It is honored if the definition specifies
 
383
      ``password_encoding=netrc``.
377
384
 
378
385
  * What mode should the authentication file use ?
379
386
 
380
387
    * 600 read/write for owner only by default, if another mode (more
381
388
      permissive) is used, a warning will be issued to inform the users of the
382
 
      potential risks.
 
389
      potential risks.(Not implemented yet)
383
390
 
384
391
  * What about using ``seahorse`` on Ubuntu or ``KeyChain Access`` on Mac OS X ?
385
392
 
386
393
    * plugins can be written and registered to handle the associated
387
394
      ``password_encoding``.
388
395
 
389
 
  * Could it be possible to encode the whole authentication file with a ssh key
 
396
  * Could it be possible to encode the whole authentication file with an SSH key
390
397
    ?
391
398
 
392
399
    * yes and if the user configure a ssh-agent it will not be queried for
393
 
      pass-phrase every time we want to query the file for a password. But that
394
 
      seems a bit extreme for a first version.
 
400
      pass-phrase every time we want to query the file for a password. But
 
401
      that seems a bit extreme for a first version.(Not implemented yet and
 
402
      may be never)
395
403
 
396
404
  * Why can't bzr update the authentication file when it queried the user for a
397
405
    password ?