From c28682430a27f75ceb8cc8dff78b3a560fd68399 Mon Sep 17 00:00:00 2001 From: David Kalnischkies Date: Thu, 23 Nov 2017 00:58:00 +0100 Subject: 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. --- doc/apt-transport-https.1.xml | 133 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 133 insertions(+) create mode 100644 doc/apt-transport-https.1.xml (limited to 'doc/apt-transport-https.1.xml') diff --git a/doc/apt-transport-https.1.xml b/doc/apt-transport-https.1.xml new file mode 100644 index 000000000..97137fc2c --- /dev/null +++ b/doc/apt-transport-https.1.xml @@ -0,0 +1,133 @@ + + %aptent; + %aptverbatiment; + %aptvendor; +]> + + + + + &apt-author.team; + &apt-email; + &apt-product; + + 2017-11-22T00:00:00Z + + + + apt-transport-https + 1 + APT + + + + + apt-transport-https + APT transport for downloading via the HTTP Secure protocol (HTTPS) + + +Description +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 apt-transport-https +package. Note that a transport is never called directly by +a user but used by APT tools based on user configuration. +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;. + + +Options +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 Acquire::https and will default to the same values specified +for Acquire::http. This manpage will only document the options +unique to https. + +Server credentials +By default all certificates trusted by the system (see +ca-certificates package) are used for the verification of +the server certificate. An alternative certificate authority (CA) can be +configured with the Acquire::https::CAInfo option and its +host-specific option Acquire::https::CAInfo::host. +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. +A custom certificate revocation list (CRL) can be configured with the options +Acquire::https::CRLFile and +Acquire::https::CRLFile::host respectively. +Like the previous option a file in PEM format needs to be specified. + + +Disabling security +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 Acquire::https::Verify-Peer and its host-specific +variant provides. If you know exactly 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. +Similarly the option Acquire::https::Verify-Host 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. + + +Client authentication +Beside the password based authentication available (see &apt-authconf;) HTTPS supports +authentication based on client certificates as well via Acquire::https::SSLCert +and Acquire::https::SSLKey. 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. + + + + +Examples + +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" +}; + + + + +See Also +&apt-transport-http; &apt-conf; &apt-authconf; &sources-list; + + + + &manbugs; + + -- cgit v1.2.3-18-g5258