← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

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

Streamline _walkdirs_utf8 for utf8 file systems, reducing time to traverse a mozilla tree from 1s to .6 seconds. (Robert Collins)

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 and who need to update them on a regular
 
43
for users handling a lot of passwords who need to update them on a regular
44
44
basis.
45
45
 
46
46
Rationale
65
65
``password``) and, when used with appropriate agents, provide the same kind of
66
66
comfort this specification aims to provide for all other schemes. Since ssh
67
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.
 
68
restricted to providing ``user`` but does not provide ``password``.
70
69
 
71
70
Authentication definitions
72
71
--------------------------
88
87
really needed is (``user``, ``password``, ``host``, ``path``). The ``realm``
89
88
can be ignored [#ignored_realm]_ as long as it is still presented to the user
90
89
when prompting for the password (unless someone found a way to declare two
91
 
different realms for the same path).
 
90
different realms for the same path). 
92
91
 
93
 
``HTTP proxy`` can be handled as ``HTTP`` (or ``HTTPS``) by explicitly
 
92
``HTTP proxy`` can be handled as ``HTTP`` (or ``HTTPS``) by explicitely
94
93
specifying the appropriate port.
95
94
 
96
95
.. [#ignored_realm] The true purpose of realms is to allow the same credentials
113
112
    same scheme), only numerical values are allowed, this should be used only
114
113
    when the server uses a port different than the scheme standard port,
115
114
 
116
 
  * ``path``: can be empty (FTP or SFTP will never use it),
 
115
  * ``path``: can be empty (FTP or SFTP will never user it),
117
116
 
118
117
  * ``user``: can be empty (``bzr`` will defaults to python's
119
 
    ``getpass.get_user()`` for FTP, SFTP and ssh),
 
118
    ``getpass.get_user()`` and attempt another matching(see below)),
120
119
 
121
120
  * ``password``: can be empty (for security reasons, a user may use the
122
121
    definitions without storing the passwords but want to be prompted ; or the
128
127
 
129
128
Also note that an optional ``verify_certificates=no`` field will allow the
130
129
connection to ``HTTPS`` hosts that provides a self certified certificate (the
131
 
default should be to refuse the connection and inform the user). (Not
132
 
implemented yet)
 
130
default should be to refuse the connection and inform the user).
133
131
 
134
132
Multiple definitions can be provided and, for a given URL, bzr will select a
135
133
(``user`` [, ``password``]) based on the following rules :
158
156
 
159
157
Encoding passwords in ``base64``, while weak, provides protection against
160
158
accidental reading (if an administrator have to look into the file, he will not
161
 
see the passwords in clear).(Not implemented yet).
 
159
see the passwords in clear).
162
160
 
163
 
This specification intends to ease the authentication providing, not to secure
 
161
This specification intend to ease the authentication providing, not to secure
164
162
it in the best possible way.
165
163
 
166
 
Plugins can provide additional password encodings. The provided
167
 
``netrc_credential_store`` plugin can be used as an example implementation.
168
 
 
169
164
Future versions of this specification may provide additional
170
165
encodings [#password_encoding]_.
171
166
 
173
168
   that will rely on external means to store the password which, in these
174
169
   cases, will not appear anymore in the definition. It is assumed that
175
170
   additional password encodings will provide a storage outside of the file
176
 
   described here. The ``netrc`` encoding, for example, provides passwords by
177
 
   retrieving them from the ``.netrc`` file.
 
171
   described here. An encoding named ``netrc`` for example will provide
 
172
   passwords by retrieving them in the ``.netrc`` file.
178
173
 
179
174
File format
180
175
-----------
192
187
    generally servers. The same authentification definition can even be used
193
188
    for several schemes for servers providing those schemes.
194
189
 
195
 
``~/.bazaar/authentication.conf`` will use the same file format as
 
190
``~/.bazaar/authentication.conf`` will use the same file format than
196
191
``~/.bazaar/bazaar.conf``.
197
192
 
198
193
Each section describes an authentication definition.
211
206
  * ``port``: the port the server is listening,
212
207
 
213
208
  * ``verify_certificates``: to control certificate verification (useful
214
 
    for self certified hosts). This applies to HTTPS only. Accepted values
 
209
    for self certified hosts). This applies to HTTP[S] only. Accepted values
215
210
    are yes and no, default to yes.
216
211
 
217
212
  * ``path``: the branch location,
260
255
        host=r.hobby.net
261
256
        user=jim
262
257
        password=obvious1234
263
 
 
 
258
        
264
259
        # Home server
265
260
        [home]
266
261
        scheme=https
269
264
        password='c2VjcmV0LXBhc3M='
270
265
        password_encoding=base64
271
266
        verify_certificates=no # Still searching a free certificate provider
272
 
 
 
267
        
273
268
        [DEFAULT]
274
269
        # Our local user is barbaz, on all remote sites we're known as foobar
275
270
        user=foobar
276
 
 
 
271
        
277
272
  * an HTTP server and a proxy::
278
273
 
279
274
        # development branches on dev server
283
278
        path=/dev
284
279
        user=user1
285
280
        password=pass1
286
 
 
 
281
        
287
282
        # toy branches
288
283
        [localhost]
289
284
        scheme=http
291
286
        path=/
292
287
        user=user2
293
288
        password=pass2
294
 
 
 
289
        
295
290
        # proxy
296
291
        [proxy]
297
292
        scheme=http
329
324
3. No ``user`` given in the URL (and no ``password``).
330
325
 
331
326
  Get a user from ``~/.bazaar/authentication.conf`` or prompt for one if none is
332
 
  found. Continue as 2. (Not implemented yet)
 
327
  found. Continue as 2.
333
328
 
334
329
Note: A user will be queried only if the server requires it for ``HTTP`` or
335
330
``HTTPS``, other protocols always require a user.
361
356
  a password.
362
357
 
363
358
* As this specification proposes a matching between some credentials
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.
 
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.
368
362
 
369
363
Questions and Answers
370
364
---------------------
378
372
 
379
373
  * What if a ``.netrc`` file exists ?
380
374
 
381
 
    * It is honored if the definition specifies
382
 
      ``password_encoding=netrc``.
 
375
    * It will be honored if the definition specifies
 
376
      ``password_encoding=netrc`` once the appropriate plugin have been
 
377
      written.
383
378
 
384
379
  * What mode should the authentication file use ?
385
380
 
386
381
    * 600 read/write for owner only by default, if another mode (more
387
382
      permissive) is used, a warning will be issued to inform the users of the
388
 
      potential risks.(Not implemented yet)
 
383
      potential risks.
389
384
 
390
385
  * What about using ``seahorse`` on Ubuntu or ``KeyChain Access`` on Mac OS X ?
391
386
 
396
391
    ?
397
392
 
398
393
    * yes and if the user configure a ssh-agent it will not be queried for
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)
 
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.
402
396
 
403
397
  * Why can't bzr update the authentication file when it queried the user for a
404
398
    password ?