Adding upstream version 1.8.2.3.upstream/1.8.2.3upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 133 insertions, 0 deletions

diff --git a/doc/apt-transport-https.1.xml b/doc/apt-transport-https.1.xml
new file mode 100644
index 0000000..64d473c
--- /dev/null
+++ b/doc/apt-transport-https.1.xml
@@ -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>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>