Browse Source

document https options in new apt-transport-https manpage

Same reasoning as with the previous commit for http with the added
benefit of moving the hard to discover and untranslated example config
into a manpage which could be translated.
tags/devuan/2.0.1+devuan1
David Kalnischkies 3 years ago
parent
commit
c28682430a
10 changed files with 149 additions and 219 deletions
  1. +1
    -0
      debian/apt.install
  2. +1
    -0
      doc/CMakeLists.txt
  3. +133
    -0
      doc/apt-transport-https.1.xml
  4. +6
    -0
      doc/apt-verbatim.ent
  5. +5
    -28
      doc/apt.conf.5.xml
  6. +1
    -1
      doc/examples/CMakeLists.txt
  7. +0
    -186
      doc/examples/apt-https-method-example.conf
  8. +0
    -3
      doc/examples/configure-index
  9. +1
    -0
      doc/po4a.conf
  10. +1
    -1
      doc/sources.list.5.xml

+ 1
- 0
debian/apt.install View File

@@ -36,6 +36,7 @@ usr/share/man/*/apt-key.*
usr/share/man/*/apt-mark.*
usr/share/man/*/apt-secure.*
usr/share/man/*/apt-transport-http.*
usr/share/man/*/apt-transport-https.*
usr/share/man/*/apt.*
usr/share/man/*/apt_auth.*
usr/share/man/*/apt_preferences.*


+ 1
- 0
doc/CMakeLists.txt View File

@@ -85,6 +85,7 @@ add_docbook(apt-man MANPAGE ALL
apt-secure.8.xml
apt-sortpkgs.1.xml
apt-transport-http.1.xml
apt-transport-https.1.xml
sources.list.5.xml
DEPENDS ${ENTITIES}
TRANSLATED_ENTITIES ${TRANSLATED_ENTITIES}


+ 133
- 0
doc/apt-transport-https.1.xml View File

@@ -0,0 +1,133 @@
<?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-11-22T00:00:00Z</date>
</refentryinfo>

<refmeta>
<refentrytitle>apt-transport-https</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="manual">APT</refmiscinfo>
</refmeta>

<!-- Man page title -->
<refnamediv>
<refname>apt-transport-https</refname>
<refpurpose>APT transport for downloading via the HTTP Secure protocol (HTTPS)</refpurpose>
</refnamediv>

<refsect1><title>Description</title>
<para>This APT transport allows the use of repositories accessed via the
HTTP Secure protocol (HTTPS) also referred to as HTTP over TLS. It is available
by default since apt 1.5 and was before that available in a <package>apt-transport-https</package>
package. Note that a transport is never called directly by
a user but used by APT tools based on user configuration.</para>
<para>HTTP is by itself an unencrypted transport protocol (compare &apt-transport-http;),
which, as indicated by the appended S is wrapped in an encrypted layer known as
Transport Layer Security (TLS) which provides end-to-end encryption.
A sufficiently capable attacker can still observe the communication partners
and deeper analyse of the encrypted communcation might still reveal important details.
An overview over available alternative transport methods is given in &sources-list;.</para>
</refsect1>

<refsect1><title>Options</title>
<para>The HTTPS protocol is based on the HTTP protocol and as such this implementation
has the same relation meaning that all options supported by &apt-transport-http; are also
available via <literal>Acquire::https</literal> and will default to the same values specified
for <literal>Acquire::http</literal>. This manpage will only document the options
<emphasis>unique to https</emphasis>.</para>

<refsect2><title>Server credentials</title>
<para>By default all certificates trusted by the system (see
<package>ca-certificates</package> package) are used for the verification of
the server certificate. An alternative certificate authority (CA) can be
configured with the <literal>Acquire::https::CAInfo</literal> option and its
host-specific option <literal>Acquire::https::CAInfo::<replaceable>host</replaceable></literal>.
The option specifies a file is made of the concatenation of the CA certificates
(in PEM format) creating the chain used for the verification of the path
from the root (self signed one). If the remote server provides the
whole chain during the exchange, the file need only contain the root
certificate. Otherwise, the whole chain is required. If you need to support
multiple authorities, the only way is to concatenate everything.</para>
<para>A custom certificate revocation list (CRL) can be configured with the options
<literal>Acquire::https::CRLFile</literal> and
<literal>Acquire::https::CRLFile::<replaceable>host</replaceable></literal> respectively.
Like the previous option a file in PEM format needs to be specified.</para>
</refsect2>

<refsect2><title>Disabling security</title>
<para>When authenticating the server, if the certificate verification fails
for some reason (expired, revoked, man in the middle, …), the connection fails.
This is obviously what you want in all cases and what the default value (true)
of the option <literal>Acquire::https::Verify-Peer</literal> and its host-specific
variant provides. If you know <emphasis>exactly</emphasis> what you are doing,
setting this option to "false" allows you to skip peer certificate verification and
make the exchange succeed. Again, this option is for debugging or testing purpose
only as it removes all security provided by the use of HTTPS.</para>
<para>Similarly the option <literal>Acquire::https::Verify-Host</literal> and its
host-specific variant can be used to deactivate a security feature: The certificate
provided by the server includes the identity of the server which should match the
DNS name used to access it. By default, as requested by RFC 2818, the name of the
mirror is checked against the identity found in the certificate. This default behavior
is safe and should not be changed, but if you know that the server you are using has a
DNS name which does not match the identity in its certificate, you can set the option to
"false", which will prevent the comparison to be done.</para>
</refsect2>

<refsect2><title>Client authentication</title>
<para>Beside the password based authentication available (see &apt-authconf;) HTTPS supports
authentication based on client certificates as well via <literal>Acquire::https::SSLCert</literal>
and <literal>Acquire::https::SSLKey</literal>. They respectively should be set to the filename of
the X.509 client certificate and the associated (unencrypted) private key, both in PEM format.
In practice the use of the host-specific variants of both options is highly recommended.</para>
</refsect2>

</refsect1>

<refsect1><title>Examples</title>
<literallayout>
Acquire::https {
Proxy::example.org "DIRECT";
Proxy "socks5h://apt:pass@localhost:9050";
Proxy-Auto-Detect "/usr/local/bin/apt-https-proxy-auto-detect";
No-Cache "true";
Max-Age "3600";
No-Store "true";
Timeout "10";
Dl-Limit "42";
Pipeline-Depth "0";
AllowRedirect "false";
User-Agent "My APT-HTTPS";
SendAccept "false";

CAInfo "/path/to/ca/certs.pem";
CRLFile "/path/to/all/crl.pem";
Verify-Peer "true";
Verify-Host::broken.example.org "false";
SSLCert::example.org "/path/to/client/cert.pem";
SSLKey::example.org "/path/to/client/key.pem"
};
</literallayout>
</refsect1>

<refsect1>
<title>See Also</title>
<para>&apt-transport-http; &apt-conf; &apt-authconf; &sources-list;
</para>
</refsect1>

&manbugs;

</refentry>

+ 6
- 0
doc/apt-verbatim.ent View File

@@ -87,6 +87,12 @@
</citerefentry>"
>

<!ENTITY apt-transport-https "<citerefentry>
<refentrytitle><command>apt-transport-https</command></refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>"
>

<!ENTITY sources-list "<citerefentry>
<refentrytitle><filename>sources.list</filename></refentrytitle>
<manvolnum>5</manvolnum>


+ 5
- 28
doc/apt.conf.5.xml View File

@@ -409,34 +409,11 @@ APT::Compressor::rev {
be symlinked when possible instead of copying. True is the default.</para></listitem>
</varlistentry>

<varlistentry><term><option>https</option></term>
<listitem><para>
The <literal>Cache-control</literal>, <literal>Timeout</literal>,
<literal>AllowRedirect</literal>, <literal>Dl-Limit</literal> and
<literal>proxy</literal> options work for HTTPS URIs in the same way
as for the <literal>http</literal> method, and default to the same
values if they are not explicitly set. The
<literal>Pipeline-Depth</literal> option is not yet supported.
</para>

<para><literal>CaInfo</literal> suboption specifies place of file that
holds info about trusted certificates.
<literal>&lt;host&gt;::CaInfo</literal> is the corresponding per-host option.
<literal>Verify-Peer</literal> boolean suboption determines whether or not the
server's host certificate should be verified against trusted certificates.
<literal>&lt;host&gt;::Verify-Peer</literal> is the corresponding per-host option.
<literal>Verify-Host</literal> boolean suboption determines whether or not the
server's hostname should be verified.
<literal>&lt;host&gt;::Verify-Host</literal> is the corresponding per-host option.
<literal>SslCert</literal> determines what certificate to use for client
authentication. <literal>&lt;host&gt;::SslCert</literal> is the corresponding per-host option.
<literal>SslKey</literal> determines what private key to use for client
authentication. <literal>&lt;host&gt;::SslKey</literal> is the corresponding per-host option.
<literal>SslForceVersion</literal> overrides default SSL version to use.
It can contain either of the strings '<literal>TLSv1</literal>' or
'<literal>SSLv3</literal>'.
<literal>&lt;host&gt;::SslForceVersion</literal> is the corresponding per-host option.
</para></listitem></varlistentry>
<varlistentry><term><option>http</option> <option>https</option></term>
<listitem><para>The options in these scopes configure APTs acquire transports for the protocols
HTTP and HTTPS and are documented in the &apt-transport-http; and &apt-transport-https;
manpages respectively.</para></listitem>
</varlistentry>

<varlistentry><term><option>ftp</option></term>
<listitem><para>


+ 1
- 1
doc/examples/CMakeLists.txt View File

@@ -1,4 +1,4 @@
install(FILES apt.conf apt-https-method-example.conf configure-index preferences
install(FILES apt.conf configure-index preferences
DESTINATION ${CMAKE_INSTALL_DOCDIR}/examples)
install(FILES apt-ftparchive.conf ftp-archive.conf
DESTINATION ${CMAKE_INSTALL_DOCDIR}/../apt-utils/examples)

+ 0
- 186
doc/examples/apt-https-method-example.conf View File

@@ -1,186 +0,0 @@
/* This file is a sample configuration for apt https method. Configuration
parameters found in this example file are expected to be used in main
apt.conf file, just like other configuration parameters for different
methods (ftp, file, ...).

This example file starts with a common setup that voluntarily exhibits
all available configurations knobs with simple comments. Extended
comments on the behavior of the option is provided at the end for
better readability. As a matter of fact, a common configuration file
will certainly contain far less elements and benefit of default values
for many parameters.

Because some configuration parameters for apt https method in following
examples apply to specific (fictional) repositories, the associated
sources.list file is provided here:

...

deb https://secure.dom1.tld/debian unstable main contrib non-free
deb-src https://secure.dom1.tld/debian unstable main contrib non-free

deb https://secure.dom2.tld/debian unstable main contrib non-free
deb-src https://secure.dom2.tld/debian unstable main contrib non-free

...


Some notes on the servers:

- secure.dom1.tld is freely accessible using https (no client
authentication is required).
- secure.dom1.tld certificate is part of a multi level PKI, and we
want to specifically check the issuer of its certificate. We do
not have the constraint for secure.dom2.tld
- secure.dom2.tld requires client authentication by certificate
to access its content.
- The certificate presented by both server have (as expected) a CN that
matches their respective DNS names.
- We have CRL available for both dom1.tld and dom2.tld PKI, and intend
to use them.
- It sometimes happens that we had other more generic https available
repository to our list. We want the checks to be performed against
a common list of anchors (like the one provided by ca-certificates
package for instance)

The sample configuration below basically covers those simple needs.
*/


// Verify peer certificate and also matching between certificate name
// and server name as provided in sources.list (default values)
Acquire::https::Verify-Peer "true";
Acquire::https::Verify-Host "true";

// Except otherwise specified, use that list of anchors
Acquire::https::CaInfo "/etc/ssl/certs/ca-certificates.pem";

// Use a specific anchor and associated CRL. Enforce issuer of
// server certificate using its cert.
Acquire::https::secure.dom1.tld::CaInfo "/etc/apt/certs/ca-dom1-crt.pem";
Acquire::https::secure.dom1.tld::CrlFile "/etc/apt/certs/ca-dom1-crl.pem";
Acquire::https::secure.dom1.tld::IssuerCert "/etc/apt/certs/secure.dom1-issuer-crt.pem";

// Like previous for anchor and CRL, but also provide our
// certificate and keys for client authentication.
Acquire::https::secure.dom2.tld::CaInfo "/etc/apt/certs/ca-dom2-crt.pem";
Acquire::https::secure.dom2.tld::CrlFile "/etc/apt/certs/ca-dom2-crl.pem";
Acquire::https::secure.dom2.tld::SslCert "/etc/apt/certs/my-crt.pem";
Acquire::https::secure.dom2.tld::SslKey "/etc/apt/certs/my-key.pem";

// No need to downgrade, TLS will be proposed by default. Uncomment
// to have SSLv3 proposed.
// Acquire::https::mirror.ipv6.ssi.corp::SslForceVersion "SSLv3";

// No need for more debug if every is fine (default). Uncomment
// me to get additional information.
// Debug::Acquire::https "true";


/*
Options with extended comments:

Acquire::https[::repo.domain.tld]::CaInfo "/path/to/ca/certs.pem";

A string providing the path of a file containing the list of trusted
CA certificates used to verify the server certificate. The pointed
file is made of the concatenation of the CA certificates (in
PEM format) creating the chain used for the verification of the path
from the root (self signed one). If the remote server provides the
whole chain during the exchange, the file need only contain the root
certificate. Otherwise, the whole chain is required.

If you need to support multiple authorities, the only way is to
concatenate everything.

If None is provided, the default CA bundle used by GnuTLS (apt https
method is linked against libcurl-gnutls) is used. At the time of
writing, /etc/ssl/certs/ca-certificates.crt.

If no specific hostname is provided, the file is used by default
for all https targets. If a specific mirror is provided, it is
used for the https entries in the sources.list file that use that
repository (with the same name).

Acquire::https[::repo.domain.tld]::CrlFile "/path/to/all/crl.pem";

Like previous knob but for passing the list of CRL files (in PEM
format) to be used to verify revocation status. Again, if the
option is defined with no specific mirror (probably makes little
sense), this CRL information is used for all defined https entries
in sources.list file. In a mirror specific context, it only applies
to that mirror.

Acquire::https[::repo.domain.tld]::IssuerCert "/path/to/issuer/cert.pem";

Allows one to constrain the issuer of the server certificate (for all
https mirrors or a specific one) to a specific issuer. If the
server certificate has not been issued by this certificate,
connection fails.

Acquire::https[::repo.domain.tld]::Verify-Peer "true";

When authenticating the server, if the certificate verification fails
for some reason (expired, revoked, man in the middle, lack of anchor,
...), the connection fails. This is obviously what you want in all
cases and what the default value (true) of this option provides.

If you know EXACTLY what you are doing, setting this option to "false"
allow you to skip peer certificate verification and make the exchange
succeed. Again, this option is for debugging or testing purpose only.
It removes ALL the security provided by the use of SSL.TLS to secure
the HTTP exchanges.

Acquire::https[::repo.domain.tld]::Verify-Host "true";

The certificate provided by the server during the TLS/SSL exchange
provides the identity of the server which should match the DNS name
used to access it. By default, as requested by RFC 2818, the name
of the mirror is checked against the identity found in the
certificate. This default behavior is safe and should not be
changed. If you know that the server you are using has a DNS name
which does not match the identity in its certificate, you can
[report that issue to its administrator or] set the option to
"false", which will prevent the comparison to be done.

The options can be set globally or on a per-mirror basis. If set
globally, the DNS name used is the one found in the sources.list
file in the https URI.

Acquire::https[::repo.domain.tld]::SslCert "/path/to/client/cert.pem";
Acquire::https[::repo.domain.tld]::SslKey "/path/to/client/key.pem";

These two options provides support for client authentication using
certificates. They respectively accept the X.509 client certificate
in PEM format and the associated client key in PEM format (non
encrypted form).

The options can be set globally (which rarely makes sense) or on a
per-mirror basis.

Acquire::https[::repo.domain.tld]::SslForceVersion "TLSv1";

This option can be use to select the version which will be proposed
to the server. "SSLv3" and "TLSv1" are supported. SSLv2, which is
considered insecure anyway is not supported (by gnutls, which is
used by libcurl against which apt https method is linked).

When the option is set to "SSLv3" to have apt propose SSLv3 (and
associated sets of ciphersuites) instead of TLSv1 (the default)
when performing the exchange. This prevents the server to select
TLSv1 and use associated ciphersuites. You should probably not use
this option except if you know exactly what you are doing.

Note that the default setting does not guarantee that the server
will not select SSLv3 (for ciphersuites and SSL/TLS version as
selection is always done by the server, in the end). It only means
that apt will not advertise TLS support.

Debug::Acquire::https "true";

This option can be used to show debug information. Because it is
quite verbose, it is mainly useful to debug problems in case of
failure to connect to a server for some reason. The default value
is "false".

*/

+ 0
- 3
doc/examples/configure-index View File

@@ -274,9 +274,6 @@ Acquire
// - cache-control values
// - Dl-Limit, Timeout, ... values
// if not set explicit for https
//
// see /usr/share/doc/apt/examples/apt-https-method-example.conf.gz
// for more examples
https
{
Verify-Peer "false";


+ 1
- 0
doc/po4a.conf View File

@@ -28,6 +28,7 @@
[type: manpage] apt-ftparchive.1.xml $lang:$lang/apt-ftparchive.$lang.1.xml add_$lang:xml.add
[type: manpage] apt_auth.conf.5.xml $lang:$lang/apt_auth.conf.$lang.5.xml add_$lang:xml.add
[type: manpage] apt-transport-http.1.xml $lang:$lang/apt-transport-http.$lang.1.xml add_$lang:xml.add
[type: manpage] apt-transport-https.1.xml $lang:$lang/apt-transport-https.$lang.1.xml add_$lang:xml.add

[type: docbook] guide.dbk $lang:$lang/guide.$lang.dbk
# add_$lang::$lang/addendum/docbook_$lang.add


+ 1
- 1
doc/sources.list.5.xml View File

@@ -371,7 +371,7 @@ deb-src [ option1=value1 option2=value2 ] uri suite [component1] [component2] [.
chosen transport method. See &apt-secure; for details.</para></listitem>
</varlistentry>

<varlistentry><term><command>https</command></term>
<varlistentry><term><command>https</command> (&apt-transport-https;)</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


Loading…
Cancel
Save