|
- <?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>2018-05-11T00: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 available before that in the package
- <package>apt-transport-https</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) to provide end-to-end encryption.
- A sufficiently capable attacker can still observe the communication partners
- and deeper analysis of the encrypted communication 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, so
- 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 CAInfo option specifies a file made up of CA certificates (in PEM format)
- concatenated together to create the chain which APT should use to verify the
- path from your self-signed root certificate. 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>.
- As with the previous option, a file in PEM format needs to be specified.</para>
- </refsect2>
-
- <refsect2><title>Disabling security</title>
- <para>During server authentication, if certificate verification fails
- for some reason (expired, revoked, man in the middle, etc.), 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 "<literal>false</literal>" allows you to skip peer certificate verification and
- make the exchange succeed. Again, this option is for debugging or testing purposes
- 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
- "<literal>false</literal>", which will prevent the comparison from being performed.</para>
- </refsect2>
-
- <refsect2><title>Client authentication</title>
- <para>Besides supporting password-based authentication (see &apt-authconf;) HTTPS also supports
- authentication based on client certificates via <literal>Acquire::https::SSLCert</literal>
- and <literal>Acquire::https::SSLKey</literal>. These should be set respectively 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@127.0.0.1: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>
|