summaryrefslogtreecommitdiff
path: root/doc/examples
diff options
context:
space:
mode:
authorDavid Kalnischkies <david@kalnischkies.de>2017-11-23 00:58:00 +0100
committerDavid Kalnischkies <david@kalnischkies.de>2018-01-03 18:55:41 +0100
commitc28682430a27f75ceb8cc8dff78b3a560fd68399 (patch)
tree1f35ce875db0622bb71bff7060cb49d8dfb9a053 /doc/examples
parent956145444e1a3b7f5e660f71904711f4ea5bd262 (diff)
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.
Diffstat (limited to 'doc/examples')
-rw-r--r--doc/examples/CMakeLists.txt2
-rw-r--r--doc/examples/apt-https-method-example.conf186
-rw-r--r--doc/examples/configure-index3
3 files changed, 1 insertions, 190 deletions
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";