/brz/remove-bazaar

To get this branch, use:
bzr branch http://gegoxaren.bato24.eu/bzr/brz/remove-bazaar

« back to all changes in this revision

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

  • Committer: Vincent Ladeuil
  • Date: 2007-10-23 07:15:13 UTC
  • mfrom: (2926 +trunk)
  • mto: (2961.1.1 trunk)
  • mto: This revision was merged to the branch mainline in revision 2962.
  • Revision ID: v.ladeuil+lp@free.fr-20071023071513-elryt6g2at34d2ur
merge bzr.dev

Show diffs side-by-side

added added

removed removed

Lines of Context:
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
63
63
 
64
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. 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.
 
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.
70
69
 
71
70
Authentication definitions
72
71
--------------------------
73
72
 
74
 
There are two kinds of authentication used by the various schemes supported by
75
 
bzr:
 
73
There are two kinds of authentication used by the various schemes:
76
74
 
77
75
1. user and password
78
76
 
88
86
really needed is (``user``, ``password``, ``host``, ``path``). The ``realm``
89
87
can be ignored [#ignored_realm]_ as long as it is still presented to the user
90
88
when prompting for the password (unless someone found a way to declare two
91
 
different realms for the same path).
 
89
different realms for the same path). 
92
90
 
93
 
``HTTP proxy`` can be handled as ``HTTP`` (or ``HTTPS``) by explicitly
 
91
``HTTP proxy`` can be handled as ``HTTP`` (or ``HTTPS``) by explicitely
94
92
specifying the appropriate port.
95
93
 
96
94
.. [#ignored_realm] The true purpose of realms is to allow the same credentials
111
109
 
112
110
  * ``port`` can be empty (useful when an host provides several servers for the
113
111
    same scheme), only numerical values are allowed, this should be used only
114
 
    when the server uses a port different than the scheme standard port,
 
112
    when the server use a port different than the scheme standard port,
115
113
 
116
 
  * ``path``: can be empty (FTP or SFTP will never use it),
 
114
  * ``path``: can be empty (FTP or SFTP will never user it),
117
115
 
118
116
  * ``user``: can be empty (``bzr`` will defaults to python's
119
 
    ``getpass.get_user()`` for FTP, SFTP and ssh),
 
117
    ``getpass.get_user()`` and attempt another matching(see below)),
120
118
 
121
119
  * ``password``: can be empty (for security reasons, a user may use the
122
120
    definitions without storing the passwords but want to be prompted ; or the
123
121
    password will be provided by an external plugin via the
124
 
    ``password_encoding`` mechanism decribed below). Must be left empty for
125
 
    ``ssh``.
 
122
    ``password_encoding`` mechanism decribed below).
126
123
 
127
124
  * ``password_encoding``: can be empty (default is ``plaintext``).
128
125
 
129
126
Also note that an optional ``verify_certificates=no`` field will allow the
130
127
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)
 
128
default should be to refuse the connection and inform the user).
133
129
 
134
130
Multiple definitions can be provided and, for a given URL, bzr will select a
135
131
(``user`` [, ``password``]) based on the following rules :
141
137
 3. ``scheme`` matches even if decorators are used in the requested URL,
142
138
 
143
139
 4. ``host`` matches exactly or act as a domain if it starts with '.'
144
 
    (``project.bzr.sf.net`` will match ``.bzr.sf.net`` but ``projectbzr.sf.net``
145
 
    will not match ``bzr.sf.net``).
 
140
   (``project.bzr.sf.net`` will match ``.bzr.sf.net`` but ``projectbzr.sf.net``
 
141
   will not match ``bzr.sf.net``).
146
142
 
147
143
 5. ``port`` matches if included in the requested URL (exact matches only)
148
144
 
158
154
 
159
155
Encoding passwords in ``base64``, while weak, provides protection against
160
156
accidental reading (if an administrator have to look into the file, he will not
161
 
see the passwords in clear).(Not implemented yet).
 
157
see the passwords in clear).
162
158
 
163
 
This specification intends to ease the authentication providing, not to secure
 
159
This specification intend to ease the authentication providing, not to secure
164
160
it in the best possible way.
165
161
 
166
 
Plugins can provide additional password encodings. The provided
167
 
``netrc_credential_store`` plugin can be used as an example implementation.
168
 
 
169
162
Future versions of this specification may provide additional
170
163
encodings [#password_encoding]_.
171
164
 
173
166
   that will rely on external means to store the password which, in these
174
167
   cases, will not appear anymore in the definition. It is assumed that
175
168
   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.
 
169
   described here. An encoding named ``netrc`` for example will provide
 
170
   passwords by retrieving them in the ``.netrc`` file.
178
171
 
179
172
File format
180
173
-----------
192
185
    generally servers. The same authentification definition can even be used
193
186
    for several schemes for servers providing those schemes.
194
187
 
195
 
``~/.bazaar/authentication.conf`` will use the same file format as
 
188
``~/.bazaar/authentication.conf`` will use the same file format than
196
189
``~/.bazaar/bazaar.conf``.
197
190
 
198
 
Each section describes an authentication definition.
 
191
Each section will define an authentication definition.
199
192
 
200
193
The section name is an arbitrary string, only the ``DEFAULT`` value is reserved
201
194
and should appear as the *last* section.
211
204
  * ``port``: the port the server is listening,
212
205
 
213
206
  * ``verify_certificates``: to control certificate verification (useful
214
 
    for self certified hosts). This applies to HTTPS only. Accepted values
 
207
    for self certified hosts). This applies to HTTP[S] only. Accepted values
215
208
    are yes and no, default to yes.
216
209
 
217
210
  * ``path``: the branch location,
260
253
        host=r.hobby.net
261
254
        user=jim
262
255
        password=obvious1234
263
 
 
 
256
        
264
257
        # Home server
265
258
        [home]
266
259
        scheme=https
269
262
        password='c2VjcmV0LXBhc3M='
270
263
        password_encoding=base64
271
264
        verify_certificates=no # Still searching a free certificate provider
272
 
 
 
265
        
273
266
        [DEFAULT]
274
267
        # Our local user is barbaz, on all remote sites we're known as foobar
275
268
        user=foobar
276
 
 
 
269
        
277
270
  * an HTTP server and a proxy::
278
271
 
279
272
        # development branches on dev server
283
276
        path=/dev
284
277
        user=user1
285
278
        password=pass1
286
 
 
 
279
        
287
280
        # toy branches
288
281
        [localhost]
289
282
        scheme=http
291
284
        path=/
292
285
        user=user2
293
286
        password=pass2
294
 
 
 
287
        
295
288
        # proxy
296
289
        [proxy]
297
290
        scheme=http
329
322
3. No ``user`` given in the URL (and no ``password``).
330
323
 
331
324
  Get a user from ``~/.bazaar/authentication.conf`` or prompt for one if none is
332
 
  found. Continue as 2. (Not implemented yet)
 
325
  found. Continue as 2.
333
326
 
334
327
Note: A user will be queried only if the server requires it for ``HTTP`` or
335
328
``HTTPS``, other protocols always require a user.
361
354
  a password.
362
355
 
363
356
* 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.
 
357
  definitions and real urls, the implementation should provide an optional UI
 
358
  feedback about which credential definition is used. That will allow the user
 
359
  to validate his definitions.
368
360
 
369
361
Questions and Answers
370
362
---------------------
378
370
 
379
371
  * What if a ``.netrc`` file exists ?
380
372
 
381
 
    * It is honored if the definition specifies
382
 
      ``password_encoding=netrc``.
 
373
    * It will be honored if the definition specifies
 
374
      ``password_encoding=netrc`` once the appropriate plugin have been
 
375
      written.
383
376
 
384
377
  * What mode should the authentication file use ?
385
378
 
386
379
    * 600 read/write for owner only by default, if another mode (more
387
380
      permissive) is used, a warning will be issued to inform the users of the
388
 
      potential risks.(Not implemented yet)
 
381
      potential risks.
389
382
 
390
383
  * What about using ``seahorse`` on Ubuntu or ``KeyChain Access`` on Mac OS X ?
391
384
 
396
389
    ?
397
390
 
398
391
    * 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)
 
392
      pass-phrase every time we want to query the file for a password. But that
 
393
      seems a bit extreme for a first version.
402
394
 
403
395
  * Why can't bzr update the authentication file when it queried the user for a
404
396
    password ?