Rev 2924: Review feedback. in http://code.launchpad.net/%7Ev-ladeuil/bzr/auth.ring
Vincent Ladeuil
v.ladeuil+lp at free.fr
Sun Nov 4 15:24:45 GMT 2007
At http://code.launchpad.net/%7Ev-ladeuil/bzr/auth.ring
------------------------------------------------------------
revno: 2924
revision-id:v.ladeuil+lp at free.fr-20071104152427-p9k7e4toywa87wfc
parent: v.ladeuil+lp at free.fr-20071023144744-33llcbc104e98ej5
committer: Vincent Ladeuil <v.ladeuil+lp at free.fr>
branch nick: auth.ring
timestamp: Sun 2007-11-04 16:24:27 +0100
message:
Review feedback.
* doc/en/user-guide/authentication_conf.txt:
New file. Authentication configuration file documentation.
* doc/en/user-guide/configuration.txt:
Slight modifications, add authentication.conf reference.
* doc/en/mini-tutorial/index.txt:
Fix make docs warning.
* doc/developers/authentication-ring.txt:
Small cleanups noticed during
doc/en/user-guide/authentication_conf.txt redaction.
* bzrlib/transport/http/_urllib.py:
(HttpTransport_urllib._perform): Use a dict() instead of {} syntax.
* bzrlib/tests/blackbox/test_whoami.py:
(TestWhoami.test_whoami_branch): Delete BZREMAIL related tests.
* bzrlib/config.py:
(Config.username): BZREMAIL deleted, has been obsolete for more
than a year.
(AuthenticationConfig.__init__): Review feedback, since keeping a
callback as an attribute is useless, call it now and keep the
filename itself as an attribute.
(AuthenticationConfig.get_credentials): Use a dict() instead of {}
syntax.
* NEWS:
Updated as per Martin's suggestion.
added:
doc/en/user-guide/authentication_conf.txt authentication_conf.-20071104135035-glfv0ri355tyg1nf-1
modified:
NEWS NEWS-20050323055033-4e00b5db738777ff
bzrlib/config.py config.py-20051011043216-070c74f4e9e338e8
bzrlib/tests/blackbox/test_whoami.py test_whoami.py-20060629025641-8h3m2ch7kutqx7ug-1
bzrlib/transport/http/_urllib.py _urlgrabber.py-20060113083826-0bbf7d992fbf090c
doc/developers/authentication-ring.txt authring.txt-20070718200437-q5tdik0ne6lor86d-1
doc/en/mini-tutorial/index.txt index.txt-20070813141352-2u64ooqzo0or4hss-2
doc/en/user-guide/configuration.txt configuration.txt-20060314161707-868350809502af01
-------------- next part --------------
=== added file 'doc/en/user-guide/authentication_conf.txt'
--- a/doc/en/user-guide/authentication_conf.txt 1970-01-01 00:00:00 +0000
+++ b/doc/en/user-guide/authentication_conf.txt 2007-11-04 15:24:27 +0000
@@ -0,0 +1,227 @@
+=================================
+Authentication configuration file
+=================================
+
+
+Intent
+======
+
+Many different authentication policies can be described in the
+``$HOME/.bazaar/authentication.conf`` file but a particular user should need
+only a few definitions to cover his needs without having to specify a user and
+a password for every branch he uses.
+
+The definitions found in this file are used to find the credentials to use for
+a given url. The same credentials can generally be used for as many branches as
+possible by grouping their declaration around the remote servers that need
+them. It's even possible to declare credentials that will be used by different
+servers.
+
+The intent is to make this file as small as possible to minimize maintenance.
+
+Once the relevant credentials are declared in this file you may use branch urls
+without embedding passwords (security hazard) or even users (enabling sharing
+of your urls with others).
+
+Instead of using::
+
+ bzr branch ftp://joe:secret@host.com/path/to/my/branch
+
+you simply use::
+
+ bzr branch ftp://host.com/path/to/my/branch
+
+provided you have created the following ``authentication.conf`` file::
+
+ [myprojects]
+ scheme=ftp
+ host=host.com
+ user=joe
+ password=secret
+
+
+Authentication definitions
+==========================
+
+There are two kinds of authentication used by the various schemes supported by
+bzr:
+
+1. user and password
+
+``FTP`` and ``SFTP`` needs a (``user``, ``password``) to authenticate against a
+``host`` (SFTP can use ssh keys too, but we don't talk about that here as ssh
+agents provide a better solution).
+
+2. user, realm and password
+
+``HTTP`` and ``HTTPS`` needs a (``user, realm, password``) to authenticate
+against a host. But, by using ``.htaccess`` files, for example, it is possible
+to define several (``user, realm, password``) for a given ``host``. So what is
+really needed is (``user``, ``password``, ``host``, ``path``). The ``realm`` is
+not taken into account in the defitions, but will displayed if bzr prompts you
+for a password.
+
+``HTTP proxy`` can be handled as ``HTTP`` (or ``HTTPS``) by explicitely
+specifying the appropriate port.
+
+To take all schemes into account, the password will be deduced from a set of
+authentication definitions (``scheme``, ``host``, ``port``, ``path``, ``user``,
+``password``).
+
+ * ``scheme``: can be empty (meaning the rest of the definition can be used
+ for any scheme), ``SFTP`` and ``bzr+ssh`` should not be used here, ``ssh``
+ should be used instead since this is the real scheme regarding
+ authentication,
+
+ * ``host``: can be empty (to act as a default for any host),
+
+ * ``port`` can be empty (useful when an host provides several servers for the
+ same scheme), only numerical values are allowed, this should be used only
+ when the server uses a port different than the scheme standard port,
+
+ * ``path``: can be empty (FTP or SFTP will never user it),
+
+ * ``user``: can be empty (``bzr`` will defaults to python's
+ ``getpass.get_user()``),
+
+ * ``password``: can be empty if you prefer to always be prompted for your
+ password.
+
+Multiple definitions can be provided and, for a given URL, bzr will select a
+(``user`` [, ``password``]) based on the following rules :
+
+ 1. the first match wins,
+
+ 2. empty fields match everything,
+
+ 3. ``scheme`` matches even if decorators are used in the requested URL,
+
+ 4. ``host`` matches exactly or act as a domain if it starts with '.'
+ (``project.bzr.sf.net`` will match ``.bzr.sf.net`` but ``projectbzr.sf.net``
+ will not match ``bzr.sf.net``).
+
+ 5. ``port`` matches if included in the requested URL (exact matches only)
+
+ 6. ``path`` matches if included in the requested URL (and by rule #2 above,
+ empty paths will match any provided path).
+
+
+
+File format
+===========
+
+The general rules for `configuration files`_ apply except for the variable
+policies.
+
+.. _configuration files: configuration.html
+
+Each section describes an authentication definition.
+
+The section name is an arbitrary string, only the ``DEFAULT`` value is reserved
+and should appear as the *last* section.
+
+Each section should define:
+
+* ``user``: the login to be used,
+
+Each section could define:
+
+* ``host``: the remote server,
+
+* ``port``: the port the server is listening,
+
+* ``path``: the branch location,
+
+* ``password``: the password.
+
+
+Examples
+========
+
+
+Personal projects hosted outside
+--------------------------------
+
+All connections are done with the same ``user`` (the remote one for which the
+default bzr one is not appropriate) and the password is always prompted with
+some exceptions::
+
+ # Pet projects on hobby.net
+ [hobby]
+ host=r.hobby.net
+ user=jim
+ password=obvious1234
+
+ # Home server
+ [home]
+ scheme=https
+ host=home.net
+ user=joe
+ password=1essobV10us
+
+ [DEFAULT]
+ # Our local user is barbaz, on all remote sites we're known as foobar
+ user=foobar
+
+
+Source hosting provider
+-----------------------
+
+In the shp.net (fictious) domain, each project has its own site::
+
+ [shpnet domain]
+ # we use sftp, but ssh is the scheme used for authentication
+ scheme=ssh
+ # The leading '.' ensures that 'shp.net' alone doesn't match
+ host=.shp.net
+ user=joe
+ password=precious
+
+HTTPS, SFTP servers and their proxy
+-----------------------------------
+
+At company.com, the server hosting released and integration code is behind a
+proxy, the two servers use different authentication policies::
+
+ [reference code]
+ scheme=https
+ host=dev.company.com
+ path=/dev
+ user=user1
+ password=pass1
+
+ # development branches on dev server
+ [dev]
+ scheme=ssh # bzr+ssh and sftp are available here
+ host=dev.company.com
+ path=/dev/integration
+ user=user2
+ password=pass2
+
+ # proxy
+ [proxy]
+ scheme=http
+ host=proxy.company.com
+ port=3128
+ user=proxyuser1
+ password=proxypass1
+
+
+Planned enhancements
+====================
+
+The following are not yet implemented but planned as parts of a work in
+progress:
+
+* add a ``password_encoding`` field allowing:
+
+ - storing the passwords in various obfuscating encodings (base64 for one),
+
+ - delegate password storage to plugins (.netrc for example).
+
+* update the credentials when the user is prompted for user or password,
+
+* add a ``verify_certificates`` field for ``HTTPS``.
+
+The ``password_encoding`` and ``verify_certificates`` fields are recognized but
+ignored in the actual implementation.
\ No newline at end of file
=== modified file 'NEWS'
--- a/NEWS 2007-10-23 14:47:44 +0000
+++ b/NEWS 2007-11-04 15:24:27 +0000
@@ -30,7 +30,9 @@
FEATURES:
- * New ``authentication.conf`` file to define remote servers credentials.
+ * New ``authentication.conf`` file holding the password or other credentials
+ for remote servers. This can be used for ssh, sftp, smtp and other
+ supported transports.
(Vincent Ladeuil)
* New ``reconfigure`` command. (Aaron Bentley)
=== modified file 'bzrlib/config.py'
--- a/bzrlib/config.py 2007-10-23 14:31:10 +0000
+++ b/bzrlib/config.py 2007-11-04 15:24:27 +0000
@@ -236,13 +236,6 @@
v = os.environ.get('BZR_EMAIL')
if v:
return v.decode(bzrlib.user_encoding)
- v = os.environ.get('BZREMAIL')
- if v:
- # FIXME: Seems to have been deprecated since more than a year now,
- # time to delete ? -- vila 20071019
- trace.warning('BZREMAIL is deprecated in favor of BZR_EMAIL.'
- ' Please update your configuration.')
- return v.decode(bzrlib.user_encoding)
v = self._get_user_id()
if v:
@@ -947,13 +940,13 @@
"""
def __init__(self, _file=None):
- super(AuthenticationConfig, self).__init__()
self._config = None # The ConfigObj
if _file is None:
- self._get_filename = authentication_config_filename
- self._input = self._get_filename()
+ self._filename = authentication_config_filename()
+ self._input = self._filename = authentication_config_filename()
else:
- self._get_filename = None
+ # Tests can provide a string as _file
+ self._filename = None
self._input = _file
def _get_config(self):
@@ -1049,10 +1042,9 @@
if a_user is None:
# Can't find a user
continue
- credentials = {'name': auth_def_name,
- 'user': a_user, 'password': auth_def['password'],
- 'verify_certificates': a_verify_certificates,
- }
+ credentials = dict(name=auth_def_name,
+ user=a_user, password=auth_def['password'],
+ verify_certificates=a_verify_certificates)
self.decode_password(credentials,
auth_def.get('password_encoding', None))
if 'auth' in debug.debug_flags:
=== modified file 'bzrlib/tests/blackbox/test_whoami.py'
--- a/bzrlib/tests/blackbox/test_whoami.py 2007-06-26 20:32:49 +0000
+++ b/bzrlib/tests/blackbox/test_whoami.py 2007-11-04 15:24:27 +0000
@@ -45,9 +45,6 @@
bzr_email = os.environ.get('BZR_EMAIL')
if bzr_email is not None:
del os.environ['BZR_EMAIL']
- bzremail = os.environ.get('BZREMAIL')
- if bzremail is not None:
- del os.environ['BZREMAIL']
try:
whoami = self.run_bzr("whoami")[0]
self.assertEquals('Branch Identity <branch at identi.ty>\n', whoami)
@@ -62,16 +59,9 @@
whoami_email = self.run_bzr("whoami --email")[0]
self.assertEquals('other at environ.ment\n', whoami_email)
del os.environ['BZR_EMAIL']
- os.environ['BZREMAIL'] = 'Yet Another ID <yetother at environ.ment>'
- whoami, warn = self.run_bzr("whoami")
- self.assertEquals('Yet Another ID <yetother at environ.ment>\n', whoami)
- self.assertTrue(len(warn) > 0)
- del os.environ['BZREMAIL']
finally:
if bzr_email is not None:
os.environ['BZR_EMAIL'] = bzr_email
- if bzremail is not None:
- os.environ['BZREMAIL'] = bzremail
def test_whoami_utf8(self):
"""verify that an identity can be in utf-8."""
=== modified file 'bzrlib/transport/http/_urllib.py'
--- a/bzrlib/transport/http/_urllib.py 2007-10-22 21:19:13 +0000
+++ b/bzrlib/transport/http/_urllib.py 2007-11-04 15:24:27 +0000
@@ -79,11 +79,16 @@
# scheme and realm will be set by the _urllib2_wrappers.AuthHandler
user = self._user
password = self._password
+ auth = dict(host=self._host, port=self._port,
+ user=user, password=password,
+ protocol=self._unqualified_scheme,
+ path=self._path)
auth = {'host': self._host, 'port': self._port,
'user': user, 'password': password,
'protocol': self._unqualified_scheme,
'path': self._path}
# Proxy initialization will be done by first proxied request
+ proxy_auth = dict()
proxy_auth = {}
# Ensure authentication info is provided
request.auth = auth
=== modified file 'doc/developers/authentication-ring.txt'
--- a/doc/developers/authentication-ring.txt 2007-10-22 15:18:24 +0000
+++ b/doc/developers/authentication-ring.txt 2007-11-04 15:24:27 +0000
@@ -70,7 +70,8 @@
Authentication definitions
--------------------------
-There are two kinds of authentication used by the various schemes:
+There are two kinds of authentication used by the various schemes supported by
+bzr:
1. user and password
@@ -109,7 +110,7 @@
* ``port`` can be empty (useful when an host provides several servers for the
same scheme), only numerical values are allowed, this should be used only
- when the server use a port different than the scheme standard port,
+ when the server uses a port different than the scheme standard port,
* ``path``: can be empty (FTP or SFTP will never user it),
@@ -137,8 +138,8 @@
3. ``scheme`` matches even if decorators are used in the requested URL,
4. ``host`` matches exactly or act as a domain if it starts with '.'
- (``project.bzr.sf.net`` will match ``.bzr.sf.net`` but ``projectbzr.sf.net``
- will not match ``bzr.sf.net``).
+ (``project.bzr.sf.net`` will match ``.bzr.sf.net`` but ``projectbzr.sf.net``
+ will not match ``bzr.sf.net``).
5. ``port`` matches if included in the requested URL (exact matches only)
@@ -188,7 +189,7 @@
``~/.bazaar/authentication.conf`` will use the same file format than
``~/.bazaar/bazaar.conf``.
-Each section will define an authentication definition.
+Each section describes an authentication definition.
The section name is an arbitrary string, only the ``DEFAULT`` value is reserved
and should appear as the *last* section.
=== modified file 'doc/en/mini-tutorial/index.txt'
--- a/doc/en/mini-tutorial/index.txt 2007-10-16 14:05:09 +0000
+++ b/doc/en/mini-tutorial/index.txt 2007-11-04 15:24:27 +0000
@@ -1,6 +1,6 @@
-===================
+======================
Bazaar in five minutes
-===================
+======================
.. contents::
=== modified file 'doc/en/user-guide/configuration.txt'
--- a/doc/en/user-guide/configuration.txt 2007-10-19 13:51:48 +0000
+++ b/doc/en/user-guide/configuration.txt 2007-11-04 15:24:27 +0000
@@ -64,12 +64,22 @@
The path where Bazaar should look for shell plugin external commands.
-Location of configuration files
-===============================
-Each user gets a pair of configurations files in ``$HOME/.bazaar``. The first
-one, named ``bazaar.conf``, includes default configuration options. The other
-file, ``locations.conf``, contains configuration information for specific
-branch locations. These files are sometimes referred to as ``ini files``.
+Configuration files
+===================
+
+Location
+--------
+
+Configuration files are located in ``$HOME/.bazaar`` and are
+sometimes referred to as ``ini files``:
+
+* ``bazaar.conf`` describes default configuration options,
+
+* ``locations.conf`` describes configuration information for
+ specific branch locations,
+
+* ``authentication.conf`` describes credential information for
+ remote servers.
Each branch can also contain a configuration file that sets values specific
to that branch. This file is found at ``.bzr/branch/branch.conf`` within the
@@ -78,18 +88,19 @@
can do so in ``locations.conf``.
General Format
-==============
+--------------
+
An ini file has three types of contructs: section headers, section
variables and comments.
Comments
---------
+~~~~~~~~
A comment is any line that starts with a "#" (sometimes called a "hash
mark", "pound sign" or "number sign"). Comment lines are ignored by
Bazaar when parsing ini files.
Section Headers
----------------
+~~~~~~~~~~~~~~~
A section header is a word enclosed in brackets that starts at the begining
of a line. A typical section header looks like this::
@@ -109,7 +120,7 @@
Section Variables
------------------
+~~~~~~~~~~~~~~~~~
A section variable resides within a section. A section variable contains a
variable name, an equals sign and a value. For example::
@@ -119,7 +130,7 @@
Variable Policies
------------------
+~~~~~~~~~~~~~~~~~
Variables defined in a section affect the named directory or URL plus
any locations they contain. Policies can be used to change how a
@@ -164,11 +175,15 @@
check_signatures = check-available
create_signatures = when-required
-``$HOME/.bazaar/locations.conf`` allows one to specify overriding settings for a
-specific branch. The format is almost identical to the default section in
-bazaar.conf with one significant change: The section header, instead of
-saying default, will be the path to a branch that you wish to override a
-value for. The '?' and '*' wildcards are supported::
+
+The branch location configuration file, locations.conf
+------------------------------------------------------
+
+``$HOME/.bazaar/locations.conf`` allows one to specify overriding settings for
+a specific branch. The format is almost identical to the default section in
+bazaar.conf with one significant change: The section header, instead of saying
+default, will be the path to a branch that you wish to override a value
+for. The '?' and '*' wildcards are supported::
[/home/jdoe/branches/nethack]
email = Nethack Admin <nethack at nethack.com>
@@ -180,6 +195,21 @@
[http://bazaar-vcs.org/bzr/*]
check_signatures = require
+The authentication configuration file, authentication.conf
+----------------------------------------------------------
+
+``$HOME/.bazaar/authentication.conf`` allows one to specify credentials for
+remote servers. This can be used for all the supported transports and any part
+of bzr that requires authentication (smtp for example).
+
+The syntax of the file obeys the same rules as the others except for the
+variable policies which don't apply.
+
+For more information on the possible uses of the authentication configuration
+file see the `authentication configuration file documentation`_.
+
+.. _authentication configuration file documentation: authentication_conf.html
+
Common Variable Options
=======================
More information about the bazaar-commits
mailing list