← 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: John Arbash Meinel
  • Author(s): Mark Hammond
  • Date: 2008-09-09 17:02:21 UTC
  • mto: This revision was merged to the branch mainline in revision 3697.
  • Revision ID: john@arbash-meinel.com-20080909170221-svim3jw2mrz0amp3
An updated transparent icon for bzr.

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
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. Since SSH 
 
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
--------------------------
77
76
1. user and password
78
77
 
79
78
``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).
 
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
81
 
83
82
2. user, realm and password
84
83
 
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
 
  * ``user``: can be empty (``bzr`` will defaults to Python's
119
 
    ``getpass.get_user()`` for FTP, SFTP and SSH),
 
117
  * ``user``: can be empty (``bzr`` will defaults to python's
 
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 :
160
158
accidental reading (if an administrator have to look into the file, he will not
161
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
267
262
        host=home.net
268
263
        user=joe
269
 
        # Obtain the base64 encoded password by running 'echo -n "secret-pass" | base64'
270
264
        password='c2VjcmV0LXBhc3M='
271
265
        password_encoding=base64
272
266
        verify_certificates=no # Still searching a free certificate provider
273
 
 
 
267
        
274
268
        [DEFAULT]
275
269
        # Our local user is barbaz, on all remote sites we're known as foobar
276
270
        user=foobar
277
 
 
 
271
        
278
272
  * an HTTP server and a proxy::
279
273
 
280
274
        # development branches on dev server
284
278
        path=/dev
285
279
        user=user1
286
280
        password=pass1
287
 
 
 
281
        
288
282
        # toy branches
289
283
        [localhost]
290
284
        scheme=http
292
286
        path=/
293
287
        user=user2
294
288
        password=pass2
295
 
 
 
289
        
296
290
        # proxy
297
291
        [proxy]
298
292
        scheme=http
304
298
  * source hosting provider declaring sub-domains for each project::
305
299
 
306
300
        [sfnet domain]
307
 
        # we use SFTP, but SSH is the scheme used for authentication
 
301
        # we use sftp, but ssh is the scheme used for authentication
308
302
        scheme=ssh
309
303
        # The leading '.' ensures that 'sf.net' alone doesn't match
310
304
        host=.sf.net
330
324
3. No ``user`` given in the URL (and no ``password``).
331
325
 
332
326
  Get a user from ``~/.bazaar/authentication.conf`` or prompt for one if none is
333
 
  found. Continue as 2. (Not implemented yet)
 
327
  found. Continue as 2.
334
328
 
335
329
Note: A user will be queried only if the server requires it for ``HTTP`` or
336
330
``HTTPS``, other protocols always require a user.
348
342
* No assumptions should be made about the clients of this service
349
343
  (i.e. Transport is the primary target but plugins must be able to use it as
350
344
  well, the definitions used: (``scheme, host, [port,] path``) are general
351
 
  enough to described credentials for ``svn`` servers or LaunchPad XML-RPC
 
345
  enough to described credentials for ``svn`` servers or LaunchPad xmlrpc
352
346
  calls).
353
347
 
354
348
* Policies regarding default users may be taken into account by the
362
356
  a password.
363
357
 
364
358
* As this specification proposes a matching between some credentials
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.
 
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.
369
362
 
370
363
Questions and Answers
371
364
---------------------
379
372
 
380
373
  * What if a ``.netrc`` file exists ?
381
374
 
382
 
    * It is honored if the definition specifies
383
 
      ``password_encoding=netrc``.
 
375
    * It will be honored if the definition specifies
 
376
      ``password_encoding=netrc`` once the appropriate plugin have been
 
377
      written.
384
378
 
385
379
  * What mode should the authentication file use ?
386
380
 
387
381
    * 600 read/write for owner only by default, if another mode (more
388
382
      permissive) is used, a warning will be issued to inform the users of the
389
 
      potential risks.(Not implemented yet)
 
383
      potential risks.
390
384
 
391
385
  * What about using ``seahorse`` on Ubuntu or ``KeyChain Access`` on Mac OS X ?
392
386
 
393
387
    * plugins can be written and registered to handle the associated
394
388
      ``password_encoding``.
395
389
 
396
 
  * Could it be possible to encode the whole authentication file with an SSH key
 
390
  * Could it be possible to encode the whole authentication file with a ssh key
397
391
    ?
398
392
 
399
393
    * yes and if the user configure a ssh-agent it will not be queried for
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)
 
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.
403
396
 
404
397
  * Why can't bzr update the authentication file when it queried the user for a
405
398
    password ?