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
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
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.
71
70
Authentication definitions
72
71
--------------------------
74
There are two kinds of authentication used by the various schemes supported by
73
There are two kinds of authentication used by the various schemes:
77
75
1. user and password
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).
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.
96
94
.. [#ignored_realm] The true purpose of realms is to allow the same credentials
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,
116
* ``path``: can be empty (FTP or SFTP will never use it),
114
* ``path``: can be empty (FTP or SFTP will never user it),
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)),
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
122
``password_encoding`` mechanism decribed below).
127
124
* ``password_encoding``: can be empty (default is ``plaintext``).
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
128
default should be to refuse the connection and inform the user).
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,
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``).
147
143
5. ``port`` matches if included in the requested URL (exact matches only)
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).
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.
166
Plugins can provide additional password encodings. The provided
167
``netrc_credential_store`` plugin can be used as an example implementation.
169
162
Future versions of this specification may provide additional
170
163
encodings [#password_encoding]_.
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.
192
185
generally servers. The same authentification definition can even be used
193
186
for several schemes for servers providing those schemes.
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``.
198
Each section describes an authentication definition.
191
Each section will define an authentication definition.
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,
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.
217
210
* ``path``: the branch location,
269
262
password='c2VjcmV0LXBhc3M='
270
263
password_encoding=base64
271
264
verify_certificates=no # Still searching a free certificate provider
274
267
# Our local user is barbaz, on all remote sites we're known as foobar
277
270
* an HTTP server and a proxy::
279
272
# development branches on dev server
329
322
3. No ``user`` given in the URL (and no ``password``).
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.
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.
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.
369
361
Questions and Answers
370
362
---------------------
379
371
* What if a ``.netrc`` file exists ?
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
384
377
* What mode should the authentication file use ?
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)
390
383
* What about using ``seahorse`` on Ubuntu or ``KeyChain Access`` on Mac OS X ?
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
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.
403
395
* Why can't bzr update the authentication file when it queried the user for a
added
removed
doc/developers/authentication-ring.txt
