Merge branch 'feature/authconf'

5 files changed, 187 insertions, 19 deletions

diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt
index a1491428f..d7241eb5e 100644
--- a/doc/CMakeLists.txt
+++ b/doc/CMakeLists.txt
@@ -66,6 +66,7 @@ endif()
 add_docbook(apt-man MANPAGE ALL
     DOCUMENTS
         apt.8.xml
+        apt_auth.conf.5.xml
         apt-cache.8.xml
         apt-cdrom.8.xml
         apt.conf.5.xml
diff --git a/doc/apt-verbatim.ent b/doc/apt-verbatim.ent
index b555c5de5..be599d393 100644
--- a/doc/apt-verbatim.ent
+++ b/doc/apt-verbatim.ent
@@ -15,6 +15,12 @@
   </citerefentry>"
 >
 
+<!ENTITY apt-authconf "<citerefentry>
+    <refentrytitle><filename>apt_auth.conf</filename></refentrytitle>
+    <manvolnum>5</manvolnum>
+  </citerefentry>"
+>
+
 <!ENTITY apt-get "<citerefentry>
     <refentrytitle><command>apt-get</command></refentrytitle>
     <manvolnum>8</manvolnum>
diff --git a/doc/apt_auth.conf.5.xml b/doc/apt_auth.conf.5.xml
new file mode 100644
index 000000000..8a1882604
--- /dev/null
+++ b/doc/apt_auth.conf.5.xml
@@ -0,0 +1,132 @@
+<?xml version="1.0" encoding="utf-8" standalone="no"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+  "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % aptent SYSTEM "apt.ent"> %aptent;
+<!ENTITY % aptverbatiment SYSTEM "apt-verbatim.ent"> %aptverbatiment;
+<!ENTITY % aptvendor SYSTEM "apt-vendor.ent"> %aptvendor;
+]>
+
+<refentry>
+
+ <refentryinfo>
+   &apt-author.team;
+   &apt-email;
+   &apt-product;
+   <!-- The last update date -->
+   <date>2017-07-07T00:00:00Z</date>
+ </refentryinfo>
+
+ <refmeta>
+   <refentrytitle>apt_auth.conf</refentrytitle>
+   <manvolnum>5</manvolnum>
+   <refmiscinfo class="manual">APT</refmiscinfo>
+ </refmeta>
+
+ <!-- Man page title -->
+ <refnamediv>
+    <refname>apt_auth.conf</refname>
+    <refpurpose>Login configuration file for APT sources and proxies</refpurpose>
+ </refnamediv>
+
+<refsect1><title>Description</title>
+<para>APT configuration files like &sources-list; or &apt-conf; need to be accessible
+for everyone using apt tools on the system to have access to all package-related
+information like the available packages in a repository. Login information
+needed to connect to a proxy or to download data from a repository on the other
+hand shouldn't always be accessible by everyone and can hence not be placed in a
+file with world-readable file permissions.</para>
+
+<para>The APT auth.conf file <filename>/etc/apt/auth.conf</filename> can be used to store
+login information in a netrc-like format with restrictive file permissions.</para>
+</refsect1>
+
+<refsect1><title>netrc-like format</title>
+<para>The format defined here is similar to the format of the <filename>~/.netrc</filename>
+file used by <citerefentry><refentrytitle><command>ftp</command></refentrytitle><manvolnum>1</manvolnum></citerefentry>
+and similar programs interacting with servers.
+It is a simple token-based format with the following tokens being recognized;
+Unknown tokens will be ignored. Tokens may be separated by spaces, tabs or newlines.</para>
+
+<variablelist>
+<varlistentry>
+<term><literal>machine</literal> <replaceable>hostname</replaceable>[:<replaceable>port</replaceable>][/<replaceable>path</replaceable>]</term>
+<listitem><para>Entries are looked up by searching for the
+<emphasis><literal>machine</literal></emphasis> token matching the
+hostname of the URI apt needs login information for. Extending the netrc-format
+a portnumber can be specified. If no port is given the token matches for all ports.
+Similar the path is optional and only needed and useful if multiple repositories with
+different login information reside on the same server. A machine token with a path
+matches if the path in the URI starts with the path given in the token.
+Once a match is made, the subsequent tokens are processed, stopping when the
+end of file is reached or another <emphasis><literal>machine</literal></emphasis>
+token is encountered.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><literal>login</literal> <replaceable>name</replaceable></term>
+<listitem><para>The username to be used.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><literal>password</literal> <replaceable>string</replaceable></term>
+<listitem><para>The password to be used.</para></listitem>
+</varlistentry>
+
+</variablelist>
+
+</refsect1>
+
+<refsect1><title>Example</title>
+<para>Supplying login information for a user named <literal>apt</literal>
+with the password <literal>debian</literal> for the &sources-list; entry
+<literallayout>deb http://example.org/debian &debian-stable-codename; main</literallayout>
+could be done in the entry directly:
+<literallayout>deb http://apt:debian@example.org/debian &debian-stable-codename; main</literallayout>
+Alternatively an entry like the following in the auth.conf file could be used:
+<literallayout>machine example.org
+login apt
+password debian</literallayout>
+Or alternatively within a single line:
+<literallayout>machine example.org login apt password debian</literallayout>
+If you need to be more specific all of these lines will also apply to the example entry:</para>
+<literallayout>machine example.org/deb login apt password debian
+machine example.org/debian login apt password debian
+machine example.org/debian/ login apt password debian
+</literallayout>
+On the other hand neither of the following lines apply:
+<literallayout>machine example.org:80 login apt password debian
+machine example.org/deb/ login apt password debian
+machine example.org/ubuntu login apt password debian
+machine example.orga login apt password debian
+machine example.net login apt password debian
+</literallayout>
+</refsect1>
+
+<refsect1><title>Notes</title>
+<para>Basic support for this feature is present since version 0.7.25, but was
+undocumented for years. The documentation was added in version 1.5 changing
+also the implementation slightly. For maximum backward compatibility you should
+avoid multiple <literal>machine</literal> tokens with the same hostname, but if
+you need multiple they should all have a path specified in the
+<literal>machine</literal> token.</para>
+</refsect1>
+
+<refsect1>
+<title>Files</title>
+  <variablelist>
+     <varlistentry><term><filename>/etc/apt/auth.conf</filename></term>
+	<listitem><para>Login information for APT sources and proxies in a netrc-like format.
+	Configuration Item: <literal>Dir::Etc::netrc</literal>.</para></listitem>
+     </varlistentry>
+  </variablelist>
+</refsect1>
+
+<refsect1>
+<title>See Also</title>
+<para>&apt-conf; &sources-list;
+</para>
+</refsect1>
+
+ &manbugs;
+
+</refentry>
diff --git a/doc/examples/configure-index b/doc/examples/configure-index
index 244d7c1c3..61a749495 100644
--- a/doc/examples/configure-index
+++ b/doc/examples/configure-index
@@ -107,7 +107,11 @@ APT
      IndexTargets::ReleaseInfo "<BOOL>";
      IndexTargets::format "<STRING>";
 
-     Update::InteractiveReleaseInfoChanges "<BOOL>";
+     Update
+     {
+        InteractiveReleaseInfoChanges "<BOOL>";
+        SourceListWarnings "<BOOL>";
+     };
   };
 
   Cache
diff --git a/doc/sources.list.5.xml b/doc/sources.list.5.xml
index dd057eb32..c4df9aa58 100644
--- a/doc/sources.list.5.xml
+++ b/doc/sources.list.5.xml
@@ -350,6 +350,40 @@ deb-src [ option1=value1 option2=value2 ] uri suite [component1] [component2] [.
 
     <para>The currently recognized URI types are:
    <variablelist>
+    <varlistentry><term><command>http</command></term>
+    <listitem><para>
+    The http scheme specifies an HTTP server for an archive and is the most
+    commonly used method, with many options in the
+    <literal>Acquire::http</literal> scope detailed in &apt-conf;. The URI can
+    directly include login information if the archive requires it, but the use
+    of &apt-authconf; should be preferred. The method also supports SOCKS5 and
+    HTTP(S) proxies either configured via apt-specific configuration or
+    specified by the environment variable <envar>http_proxy</envar> in the
+    format (assuming an HTTP proxy requiring authentication)
+    <replaceable>http://user:pass@server:port/</replaceable>.
+    The authentication details for proxies can also be supplied via
+    &apt-authconf;.</para>
+    <para>Note that these forms of authentication are insecure as the whole
+    communication with the remote server (or proxy) is not encrypted so a
+    sufficiently capable attacker can observe and record login as well as all
+    other interactions. The attacker can <emphasis>not</emphasis> modify the
+    communication through as APTs data security model is independent of the
+    chosen transport method. See &apt-secure; for details.</para></listitem>
+    </varlistentry>
+
+    <varlistentry><term><command>https</command></term>
+    <listitem><para>
+    The https scheme specifies an HTTPS server for an archive and is very
+    similar in use and available options to the http scheme. The main
+    difference is that the communication between apt and server (or proxy) is
+    encrypted. Note that the encryption does not prevent an attacker from
+    knowing which server (or proxy) apt is communicating with and deeper
+    analyses can potentially still reveal which data was downloaded. If this is
+    a concern the Tor-based schemes mentioned further below might be a suitable
+    alternative.</para></listitem>
+    </varlistentry>
+
+
     <varlistentry><term><command>file</command></term>
     <listitem><para>
     The file scheme allows an arbitrary directory in the file system to be
@@ -359,27 +393,19 @@ deb-src [ option1=value1 option2=value2 ] uri suite [component1] [component2] [.
     
     <varlistentry><term><command>cdrom</command></term>
     <listitem><para>
-    The cdrom scheme allows APT to use a local CD-ROM drive with media
+    The cdrom scheme allows APT to use a local CD-ROM, DVD or USB drive with media
     swapping. Use the &apt-cdrom; program to create cdrom entries in the
     source list.</para></listitem>
     </varlistentry>
 
-    <varlistentry><term><command>http</command></term>
-    <listitem><para>
-    The http scheme specifies an HTTP server for the archive. If an environment
-    variable <envar>http_proxy</envar> is set with the format 
-    http://server:port/, the proxy server specified in
-    <envar>http_proxy</envar> will be used. Users of authenticated
-    HTTP/1.1 proxies may use a string of the format
-    http://user:pass@server:port/.
-    Note that this is an insecure method of authentication.</para></listitem>
-    </varlistentry>
-
     <varlistentry><term><command>ftp</command></term>
     <listitem><para>
-    The ftp scheme specifies an FTP server for the archive. APT's FTP behavior
-    is highly configurable; for more information see the
-    &apt-conf; manual page. Please note that an FTP proxy can be specified
+    The ftp scheme specifies an FTP server for an archive. Use of FTP is on the
+    decline in favour of <literal>http</literal> and <literal>https</literal>
+    and many archives either never offered or are retiring FTP access. If you
+    still need this method many configuration options for it are available in
+    the <literal>Acquire::ftp</literal> scope and detailed in &apt-conf;.</para>
+    <para>Please note that an FTP proxy can be specified
     by using the <envar>ftp_proxy</envar> environment variable. It is possible
     to specify an HTTP proxy (HTTP proxy servers often understand FTP URLs)
     using this environment variable and <emphasis>only</emphasis> this
@@ -407,9 +433,8 @@ deb-src [ option1=value1 option2=value2 ] uri suite [component1] [component2] [.
     <listitem><para>
     APT can be extended with more methods shipped in other optional packages, which should
     follow the naming scheme <package>apt-transport-<replaceable>method</replaceable></package>.
-    For instance, the APT team also maintains the package <package>apt-transport-https</package>,
-    which provides access methods for HTTPS URIs with features similar to the http method.
-    Methods for using e.g. debtorrent are also available - see &apt-transport-debtorrent;.
+    For instance, the APT team also maintains the package <package>apt-transport-tor</package>,
+    which provides access methods for HTTP and HTTPS URIs routed via the Tor network.
     </para></listitem>
     </varlistentry>
   </variablelist>