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
105
103
* ``scheme``: can be empty (meaning the rest of the definition can be used
106
for any scheme), ``SFTP`` and ``bzr+ssh`` should not be used here, ``ssh``
107
should be used instead since this is the real scheme regarding
110
106
* ``host``: can be empty (to act as a default for any host),
112
108
* ``port`` can be empty (useful when an host provides several servers for the
113
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,
116
* ``path``: can be empty (FTP or SFTP will never use it),
118
* ``user``: can be empty (``bzr`` will defaults to python's
119
``getpass.get_user()`` for FTP, SFTP and ssh),
109
same scheme), only numerical values are allowed,
111
* ``path``: can be empty (FTP or SFTP will never user it),
113
* ``user``: can be empty (and will use the same default as ``bzr``, python's
114
``getpass.get_user()``),
121
116
* ``password``: can be empty (for security reasons, a user may use the
122
definitions without storing the passwords but want to be prompted ; or the
123
password will be provided by an external plugin via the
124
``password_encoding`` mechanism decribed below). Must be left empty for
117
definitions without storing the passwords but want to be prompted).
127
119
* ``password_encoding``: can be empty (default is ``plaintext``).
129
121
Also note that an optional ``verify_certificates=no`` field will allow the
130
122
connection to ``HTTPS`` hosts that provides a self certified certificate (the
131
default should be to refuse the connection and inform the user). (Not
123
default should be to refuse the connection and inform the user).
134
125
Multiple definitions can be provided and, for a given URL, bzr will select a
135
126
(``user`` [, ``password``]) based on the following rules :
141
132
3. ``scheme`` matches even if decorators are used in the requested URL,
143
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``).
134
4. ``host`` matches if included in the requested URL. ``foo.net`` will match a
135
requested ``bzr.foo.net``.
147
137
5. ``port`` matches if included in the requested URL (exact matches only)
159
149
Encoding passwords in ``base64``, while weak, provides protection against
160
150
accidental reading (if an administrator have to look into the file, he will not
161
see the passwords in clear).(Not implemented yet).
151
see the passwords in clear).
163
This specification intends to ease the authentication providing, not to secure
153
This specification intend to ease the authentication providing, not to secure
164
154
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
156
Future versions of this specification may provide additional
170
157
encodings [#password_encoding]_.
172
159
.. [#password_encoding] Additional password encoding methods may be defined
173
160
that will rely on external means to store the password which, in these
174
cases, will not appear anymore in the definition. It is assumed that
175
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.
161
cases, will not appear anymore in the definition but be provided. An
162
encoding named ``netrc`` for example will provide passwords by using the
192
178
generally servers. The same authentification definition can even be used
193
179
for several schemes for servers providing those schemes.
195
``~/.bazaar/authentication.conf`` will use the same file format as
181
``~/.bazaar/authentication.conf`` will use the same file format than
196
182
``~/.bazaar/bazaar.conf``.
198
Each section describes an authentication definition.
184
Each section will define an authentication definition.
200
186
The section name is an arbitrary string, only the ``DEFAULT`` value is reserved
201
187
and should appear as the *last* section.
211
197
* ``port``: the port the server is listening,
213
199
* ``verify_certificates``: to control certificate verification (useful
214
for self certified hosts). This applies to HTTPS only. Accepted values
200
for self certified hosts). This applies to HTTP[S] only. Accepted values
215
201
are yes and no, default to yes.
217
203
* ``path``: the branch location,
227
213
This section could define:
229
* ``user``: default user to be used (if not defined the usual
230
bzr way applies, see below).
215
* ``user``: default user to be used.
232
217
* ``password_encoding``: default password encoding.
251
236
bzr branch ftp://foo.net/bzr/branch
252
237
bzr pull ftp://bzr.foo.net/bzr/product/branch/trunk
254
* all connections are done with the same ``user`` (the remote one for which
255
the default bzr one is not appropriate) and the password is always prompted
256
with some exceptions::
239
* all connections are done with the same ``user`` (the local one) and the
240
password is always prompted with some exceptions::
258
242
# Pet projects on hobby.net
246
verify_certificates=no
262
248
password=obvious1234
269
254
password='c2VjcmV0LXBhc3M='
270
255
password_encoding=base64
271
verify_certificates=no # Still searching a free certificate provider
274
# Our local user is barbaz, on all remote sites we're known as foobar
277
* an HTTP server and a proxy::
260
* an HTTP server that also acts as a proxy (weird)::
279
262
# development branches on dev server
298
host=proxy.company.com
301
283
password=proxypass1
303
* source hosting provider declaring sub-domains for each project::
306
# we use sftp, but ssh is the scheme used for authentication
308
# The leading '.' ensures that 'sf.net' alone doesn't match
285
Note that the proxy should be specified last because it uses no path. An
286
alternative is to specify the port used by the proxy.
329
303
3. No ``user`` given in the URL (and no ``password``).
331
305
Get a user from ``~/.bazaar/authentication.conf`` or prompt for one if none is
332
found. Continue as 2. (Not implemented yet)
306
found. Continue as 2.
334
Note: A user will be queried only if the server requires it for ``HTTP`` or
335
``HTTPS``, other protocols always require a user.
308
Note: A user will be queried only if the server requires it for ``HTTP``, other
309
protocols always require a user.
337
311
In any case, if the server refuses the authentication, bzr reports to the user
341
315
--------------------------
343
317
* bzr should be able to prompt for a ``user`` for a given (``scheme``, ``host``
344
[, ``realm``]). Note that ``realm`` is available only after a first
318
[, ``realm``]). Note that ``realm`` may be available only after a first
345
319
connection attempt to the server.
347
321
* No assumptions should be made about the clients of this service
363
337
* 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.
338
definitions and real urls, the implementation should provide an optional UI
339
feedback about which credential definition is used. That will allow the user
340
to validate his definitions.
369
342
Questions and Answers
370
343
---------------------
379
352
* What if a ``.netrc`` file exists ?
381
* It is honored if the definition specifies
382
``password_encoding=netrc``.
354
* It will be honored if the definition specifies
355
``password_encoding=netrc`` once the appropriate plugin have been
384
358
* What mode should the authentication file use ?
386
360
* 600 read/write for owner only by default, if another mode (more
387
361
permissive) is used, a warning will be issued to inform the users of the
388
potential risks.(Not implemented yet)
390
364
* What about using ``seahorse`` on Ubuntu or ``KeyChain Access`` on Mac OS X ?
398
372
* 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
373
pass-phrase every time we want to query the file for a password. But that
374
seems a bit extreme for a first version.
403
376
* Why can't bzr update the authentication file when it queried the user for a
added
removed
doc/developers/authentication-ring.txt
