doc/examples/apt-https-method-example.conf

   1 /* This file is a sample configuration for apt https method. Configuration
   2    parameters found in this example file are expected to be used in main
   3    apt.conf file, just like other configuration parameters for different
   4    methods (ftp, file, ...).
   5
   6    This example file starts with a common setup that voluntarily exhibits
   7    all available configurations knobs with simple comments. Extended
   8    comments on the behavior of the option is provided at the end for
   9    better readibility. As a matter of fact, a common configuration file
  10    will certainly contain far less elements and benefit of default values
  11    for many parameters.
  12
  13    Because some configuration parameters for apt https method in following
  14    examples apply to specific (fictional) repositories, the associated
  15    sources.list file is provided here:
  16
  17    ...
  18
  19    deb     https://secure.dom1.tld/debian unstable main contrib non-free
  20    deb-src https://secure.dom1.tld/debian unstable main contrib non-free
  21
  22    deb     https://secure.dom2.tld/debian unstable main contrib non-free
  23    deb-src https://secure.dom2.tld/debian unstable main contrib non-free
  24
  25    ...
  26
  27
  28    Some notes on the servers:
  29
  30     - secure.dom1.tld is freely accessible using https (no client
  31       authentication is required).
  32     - secure.dom1.tld certificate is part of a multi level PKI, and we
  33       want to specifically check the issuer of its certificate. We do
  34       not have the constraint for secure.dom2.tld
  35     - secure.dom2.tld requires client authentication by certificate
  36       to access its content.
  37     - The certificate presented by both server have (as expected) a CN that
  38       matches their respective DNS names.
  39     - It somtimes happens that we had other more generic https available
  40       repository to our list. We want the checks to be performed against
  41       a common list of anchors (like the one provided by ca-certificates
  42       package for instance)
  43
  44    The sample configuration below basically covers those simpe needs.
  45 */
  46
  47
  48 // Verify peer certificate and also matching between certificate name
  49 // and server name as provided in sources.list (default values)
  50 Acquire::https::Verify-Peer "true";
  51 Acquire::https::Verify-Host "true";
  52
  53 // Except otherwise specified, use that list of anchors
  54 Acquire::https::CaInfo     "/etc/ssl/certs/ca-certificates.pem";
  55
  56 // Use a specific anchor and associated CRL. Enforce issuer of
  57 // server certificate using its cert.
  58 Acquire::https::secure.dom1.tld::CaInfo     "/etc/apt/certs/ca-dom1-crt.pem";
  59
  60 // Like previous for anchor and CRL, but also provide our
  61 // certificate and keys for client authentication.
  62 Acquire::https::secure.dom2.tld::CaInfo  "/etc/apt/certs/ca-dom2-crt.pem";
  63 Acquire::https::secure.dom2.tld::SslCert "/etc/apt/certs/my-crt.pem";
  64 Acquire::https::secure.dom2.tld::SslKey  "/etc/apt/certs/my-key.pem";
  65
  66 // No need to downgrade, TLS will be proposed by default. Uncomment
  67 // to have SSLv3 proposed.
  68 // Acquire::https::mirror.ipv6.ssi.corp::SslForceVersion "SSLv3";
  69
  70 // No need for more debug if every is fine (default). Uncomment
  71 // me to get additional information.
  72 // Debug::Acquire::https "true";
  73
  74
  75 /*
  76   Options with extended comments:
  77
  78   Acquire::https[::repo.domain.tld]::CaInfo  "/path/to/ca/certs.pem";
  79
  80     A string providing the path of a file containing the list of trusted
  81     CA certificates used to verify the server certificate. The pointed
  82     file is made of the concatenation of the CA certificates (in
  83     PEM format) creating the chain used for the verification of the path
  84     from the root (self signed one). If the remote server provides the
  85     whole chain during the exchange, the file need only contain the root
  86     certificate. Otherwise, the whole chain is required.
  87
  88     If you need to support multiple authorities, the only way is to
  89     concatenate everything.
  90
  91     If None is provided, the default CA bundle used by GnuTLS (apt https
  92     method is linked against libcurl-gnutls) is used. At the time of
  93     writing, /etc/ssl/certs/ca-certificates.crt.
  94
  95     If no specific hostname is provided, the file is used by default
  96     for all https targets. If a specific mirror is provided, it is
  97     used for the https entries in the sources.list file that use that
  98     repository (with the same name).
  99
 100   Acquire::https[::repo.domain.tld]::Verify-Peer "true";
 101
 102     When authenticating the server, if the certificate verification fails
 103     for some reason (expired, revoked, man in the middle, lack of anchor,
 104     ...), the connection fails. This is obviously what you want in all
 105     cases and what the default value (true) of this option provides.
 106
 107     If you know EXACTLY what you are doing, setting this option to "false"
 108     allow you to skip peer certificate verification and make the exchange
 109     succeed. Again, this option is for debugging or testing purpose only.
 110     It removes ALL the security provided by the use of SSL.TLS to secure
 111     the HTTP exchanges.
 112
 113   Acquire::https[::repo.domain.tld]::Verify-Host "true";
 114
 115     The certificate provided by the server during the TLS/SSL exchange
 116     provides the identity of the server which should match the DNS name
 117     used to access it. By default, as requested by RFC 2818, the name
 118     of the mirror is checked against the identity found in the
 119     certificate. This default behavior is safe and should not be
 120     changed. If you know that the server you are using has a DNS name
 121     which does not match the identity in its certificate, you can
 122     [report that issue to its administrator or] set the option to
 123     "false", which will prevent the comparison to be done.
 124
 125     The options can be set globally or on a per-mirror basis. If set
 126     globally, the DNS name used is the one found in the sources.list
 127     file in the https URI.
 128
 129   Acquire::https[::repo.domain.tld]::SslCert "/path/to/client/cert.pem";
 130   Acquire::https[::repo.domain.tld]::SslKey  "/path/to/client/key.pem";
 131
 132     These two options provides support for client authentication using
 133     certificates. They respectively accept the X.509 client certificate
 134     in PEM format and the associated client key in PEM format (non
 135     encrypted form).
 136
 137     The options can be set globally (which rarely makes sense) or on a
 138     per-mirror basis.
 139
 140   Acquire::https[::repo.domain.tld]::SslForceVersion "TLSv1";
 141
 142     This option can be use to select the version which will be proposed
 143     to the server. "SSLv3" and "TLSv1" are supported. SSLv2, which is
 144     considered insecure anyway is not supported (by gnutls, which is
 145     used by libcurl against which apt https method is linked).
 146
 147     When the option is set to "SSLv3" to have apt propose SSLv3 (and
 148     associated sets of ciphersuites) instead of TLSv1 (the default)
 149     when performing the exchange. This prevents the server to select
 150     TLSv1 and use associated cipheruites. You should probably not use
 151     this option except if you know exactly what you are doing.
 152
 153     Note that the default setting does not guarantee that the server
 154     will not select SSLv3 (for ciphersuites and SSL/TLS version as
 155     selectio is always done by the server, in the end). It only means
 156     that apt will not advertise TLS support.
 157
 158   Debug::Acquire::https "true";
 159
 160     This option can be used to show debug information. Because it is
 161     quite verbose, it is mainly useful to debug problems in case of
 162     failure to connect to a server for some reason. The default value
 163     is "false".
 164
 165 */