← 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: Martin Pool
  • Date: 2009-03-24 05:21:02 UTC
  • mfrom: (4192 +trunk)
  • mto: This revision was merged to the branch mainline in revision 4202.
  • Revision ID: mbp@sourcefrog.net-20090324052102-8kk087b32tep3d9h
merge trunk

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
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``.
 
68
restricted to providing ``user`` but does not provide ``password`` when used
 
69
for ssh.
69
70
 
70
71
Authentication definitions
71
72
--------------------------
89
90
when prompting for the password (unless someone found a way to declare two
90
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
118
  * ``user``: can be empty (``bzr`` will defaults to python's
118
 
    ``getpass.get_user()`` and attempt another matching(see below)),
 
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
127
128
 
128
129
Also note that an optional ``verify_certificates=no`` field will allow the
129
130
connection to ``HTTPS`` hosts that provides a self certified certificate (the
130
 
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)
131
133
 
132
134
Multiple definitions can be provided and, for a given URL, bzr will select a
133
135
(``user`` [, ``password``]) based on the following rules :
156
158
 
157
159
Encoding passwords in ``base64``, while weak, provides protection against
158
160
accidental reading (if an administrator have to look into the file, he will not
159
 
see the passwords in clear).
 
161
see the passwords in clear).(Not implemented yet).
160
162
 
161
 
This specification intend to ease the authentication providing, not to secure
 
163
This specification intends to ease the authentication providing, not to secure
162
164
it in the best possible way.
163
165
 
 
166
Plugins can provide additional password encodings. The provided
 
167
``netrc_credential_store`` plugin can be used as an example implementation.
 
168
 
164
169
Future versions of this specification may provide additional
165
170
encodings [#password_encoding]_.
166
171
 
168
173
   that will rely on external means to store the password which, in these
169
174
   cases, will not appear anymore in the definition. It is assumed that
170
175
   additional password encodings will provide a storage outside of the file
171
 
   described here. An encoding named ``netrc`` for example will provide
172
 
   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.
173
178
 
174
179
File format
175
180
-----------
187
192
    generally servers. The same authentification definition can even be used
188
193
    for several schemes for servers providing those schemes.
189
194
 
190
 
``~/.bazaar/authentication.conf`` will use the same file format than
 
195
``~/.bazaar/authentication.conf`` will use the same file format as
191
196
``~/.bazaar/bazaar.conf``.
192
197
 
193
198
Each section describes an authentication definition.
206
211
  * ``port``: the port the server is listening,
207
212
 
208
213
  * ``verify_certificates``: to control certificate verification (useful
209
 
    for self certified hosts). This applies to HTTP[S] only. Accepted values
 
214
    for self certified hosts). This applies to HTTPS only. Accepted values
210
215
    are yes and no, default to yes.
211
216
 
212
217
  * ``path``: the branch location,
324
329
3. No ``user`` given in the URL (and no ``password``).
325
330
 
326
331
  Get a user from ``~/.bazaar/authentication.conf`` or prompt for one if none is
327
 
  found. Continue as 2.
 
332
  found. Continue as 2. (Not implemented yet)
328
333
 
329
334
Note: A user will be queried only if the server requires it for ``HTTP`` or
330
335
``HTTPS``, other protocols always require a user.
356
361
  a password.
357
362
 
358
363
* As this specification proposes a matching between some credentials
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.
 
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.
362
368
 
363
369
Questions and Answers
364
370
---------------------
372
378
 
373
379
  * What if a ``.netrc`` file exists ?
374
380
 
375
 
    * It will be honored if the definition specifies
376
 
      ``password_encoding=netrc`` once the appropriate plugin have been
377
 
      written.
 
381
    * It is honored if the definition specifies
 
382
      ``password_encoding=netrc``.
378
383
 
379
384
  * What mode should the authentication file use ?
380
385
 
381
386
    * 600 read/write for owner only by default, if another mode (more
382
387
      permissive) is used, a warning will be issued to inform the users of the
383
 
      potential risks.
 
388
      potential risks.(Not implemented yet)
384
389
 
385
390
  * What about using ``seahorse`` on Ubuntu or ``KeyChain Access`` on Mac OS X ?
386
391
 
391
396
    ?
392
397
 
393
398
    * yes and if the user configure a ssh-agent it will not be queried for
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.
 
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)
396
402
 
397
403
  * Why can't bzr update the authentication file when it queried the user for a
398
404
    password ?