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/CMakeLists.txt | 1 + doc/apt-transport-https.1.xml | 133 +++++++++++++++++++++ doc/apt-verbatim.ent | 6 + doc/apt.conf.5.xml | 33 +---- doc/examples/CMakeLists.txt | 2 +- doc/examples/apt-https-method-example.conf | 186 ----------------------------- doc/examples/configure-index | 3 - doc/po4a.conf | 1 + doc/sources.list.5.xml | 2 +- 9 files changed, 148 insertions(+), 219 deletions(-) create mode 100644 doc/apt-transport-https.1.xml delete mode 100644 doc/examples/apt-https-method-example.conf (limited to 'doc') diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt index df88eb809..cb2fe892c 100644 --- a/doc/CMakeLists.txt +++ b/doc/CMakeLists.txt @@ -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} 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; + + diff --git a/doc/apt-verbatim.ent b/doc/apt-verbatim.ent index 1af7b174d..8d0a56b6c 100644 --- a/doc/apt-verbatim.ent +++ b/doc/apt-verbatim.ent @@ -87,6 +87,12 @@ " > + + apt-transport-https + 1 + " +> + sources.list 5 diff --git a/doc/apt.conf.5.xml b/doc/apt.conf.5.xml index 30714e66b..e0be6a37d 100644 --- a/doc/apt.conf.5.xml +++ b/doc/apt.conf.5.xml @@ -409,34 +409,11 @@ APT::Compressor::rev { be symlinked when possible instead of copying. True is the default. - - - The Cache-control, Timeout, - AllowRedirect, Dl-Limit and - proxy options work for HTTPS URIs in the same way - as for the http method, and default to the same - values if they are not explicitly set. The - Pipeline-Depth option is not yet supported. - - - CaInfo suboption specifies place of file that - holds info about trusted certificates. - <host>::CaInfo is the corresponding per-host option. - Verify-Peer boolean suboption determines whether or not the - server's host certificate should be verified against trusted certificates. - <host>::Verify-Peer is the corresponding per-host option. - Verify-Host boolean suboption determines whether or not the - server's hostname should be verified. - <host>::Verify-Host is the corresponding per-host option. - SslCert determines what certificate to use for client - authentication. <host>::SslCert is the corresponding per-host option. - SslKey determines what private key to use for client - authentication. <host>::SslKey is the corresponding per-host option. - SslForceVersion overrides default SSL version to use. - It can contain either of the strings 'TLSv1' or - 'SSLv3'. - <host>::SslForceVersion is the corresponding per-host option. - + + 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. + diff --git a/doc/examples/CMakeLists.txt b/doc/examples/CMakeLists.txt index 1998867db..8d9ea068f 100644 --- a/doc/examples/CMakeLists.txt +++ b/doc/examples/CMakeLists.txt @@ -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) diff --git a/doc/examples/apt-https-method-example.conf b/doc/examples/apt-https-method-example.conf deleted file mode 100644 index 3152ef1e2..000000000 --- a/doc/examples/apt-https-method-example.conf +++ /dev/null @@ -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". - -*/ diff --git a/doc/examples/configure-index b/doc/examples/configure-index index 153637ebc..9088bd844 100644 --- a/doc/examples/configure-index +++ b/doc/examples/configure-index @@ -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"; diff --git a/doc/po4a.conf b/doc/po4a.conf index 4b8d33f52..f1fe4cb0c 100644 --- a/doc/po4a.conf +++ b/doc/po4a.conf @@ -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 diff --git a/doc/sources.list.5.xml b/doc/sources.list.5.xml index 3f81dd515..5572b8da3 100644 --- a/doc/sources.list.5.xml +++ b/doc/sources.list.5.xml @@ -371,7 +371,7 @@ deb-src [ option1=value1 option2=value2 ] uri suite [component1] [component2] [. chosen transport method. See &apt-secure; for details. - https + https (&apt-transport-https;) 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 -- cgit v1.2.3