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 readability. 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     - We have CRL available for both dom1.tld and dom2.tld PKI, and intend
  40       to use them.
  41     - It sometimes happens that we had other more generic https available
  42       repository to our list. We want the checks to be performed against
  43       a common list of anchors (like the one provided by ca-certificates
  44       package for instance)
  45
  46    The sample configuration below basically covers those simple needs.
  47 */
  48
  49
  50 // Verify peer certificate and also matching between certificate name
  51 // and server name as provided in sources.list (default values)
  52 Acquire::https::Verify-Peer "true";
  53 Acquire::https::Verify-Host "true";
  54
  55 // Except otherwise specified, use that list of anchors
  56 Acquire::https::CaInfo     "/etc/ssl/certs/ca-certificates.pem";
  57
  58 // Use a specific anchor and associated CRL. Enforce issuer of
  59 // server certificate using its cert.
  60 Acquire::https::secure.dom1.tld::CaInfo     "/etc/apt/certs/ca-dom1-crt.pem";
  61 Acquire::https::secure.dom1.tld::CrlFile    "/etc/apt/certs/ca-dom1-crl.pem";
  62 Acquire::https::secure.dom1.tld::IssuerCert "/etc/apt/certs/secure.dom1-issuer-crt.pem";
  63
  64 // Like previous for anchor and CRL, but also provide our
  65 // certificate and keys for client authentication.
  66 Acquire::https::secure.dom2.tld::CaInfo  "/etc/apt/certs/ca-dom2-crt.pem";
  67 Acquire::https::secure.dom2.tld::CrlFile "/etc/apt/certs/ca-dom2-crl.pem";
  68 Acquire::https::secure.dom2.tld::SslCert "/etc/apt/certs/my-crt.pem";
  69 Acquire::https::secure.dom2.tld::SslKey  "/etc/apt/certs/my-key.pem";
  70
  71 // No need to downgrade, TLS will be proposed by default. Uncomment
  72 // to have SSLv3 proposed.
  73 // Acquire::https::mirror.ipv6.ssi.corp::SslForceVersion "SSLv3";
  74
  75 // No need for more debug if every is fine (default). Uncomment
  76 // me to get additional information.
  77 // Debug::Acquire::https "true";
  78
  79
  80 /*
  81   Options with extended comments:
  82
  83   Acquire::https[::repo.domain.tld]::CaInfo  "/path/to/ca/certs.pem";
  84
  85     A string providing the path of a file containing the list of trusted
  86     CA certificates used to verify the server certificate. The pointed
  87     file is made of the concatenation of the CA certificates (in
  88     PEM format) creating the chain used for the verification of the path
  89     from the root (self signed one). If the remote server provides the
  90     whole chain during the exchange, the file need only contain the root
  91     certificate. Otherwise, the whole chain is required.
  92
  93     If you need to support multiple authorities, the only way is to
  94     concatenate everything.
  95
  96     If None is provided, the default CA bundle used by GnuTLS (apt https
  97     method is linked against libcurl-gnutls) is used. At the time of
  98     writing, /etc/ssl/certs/ca-certificates.crt.
  99
 100     If no specific hostname is provided, the file is used by default
 101     for all https targets. If a specific mirror is provided, it is
 102     used for the https entries in the sources.list file that use that
 103     repository (with the same name).
 104
 105   Acquire::https[::repo.domain.tld]::CrlFile  "/path/to/all/crl.pem";
 106
 107     Like previous knob but for passing the list of CRL files (in PEM
 108     format) to be used to verify revocation status. Again, if the
 109     option is defined with no specific mirror (probably makes little
 110     sense), this CRL information is used for all defined https entries
 111     in sources.list file. In a mirror specific context, it only applies
 112     to that mirror.
 113
 114   Acquire::https[::repo.domain.tld]::IssuerCert "/path/to/issuer/cert.pem";
 115
 116     Allows to constrain the issuer of the server certificate (for all
 117     https mirrors or a specific one) to a specific issuer. If the
 118     server certificate has not been issued by this certificate,
 119     connection fails.
 120
 121   Acquire::https[::repo.domain.tld]::Verify-Peer "true";
 122
 123     When authenticating the server, if the certificate verification fails
 124     for some reason (expired, revoked, man in the middle, lack of anchor,
 125     ...), the connection fails. This is obviously what you want in all
 126     cases and what the default value (true) of this option provides.
 127
 128     If you know EXACTLY what you are doing, setting this option to "false"
 129     allow you to skip peer certificate verification and make the exchange
 130     succeed. Again, this option is for debugging or testing purpose only.
 131     It removes ALL the security provided by the use of SSL.TLS to secure
 132     the HTTP exchanges.
 133
 134   Acquire::https[::repo.domain.tld]::Verify-Host "true";
 135
 136     The certificate provided by the server during the TLS/SSL exchange
 137     provides the identity of the server which should match the DNS name
 138     used to access it. By default, as requested by RFC 2818, the name
 139     of the mirror is checked against the identity found in the
 140     certificate. This default behavior is safe and should not be
 141     changed. If you know that the server you are using has a DNS name
 142     which does not match the identity in its certificate, you can
 143     [report that issue to its administrator or] set the option to
 144     "false", which will prevent the comparison to be done.
 145
 146     The options can be set globally or on a per-mirror basis. If set
 147     globally, the DNS name used is the one found in the sources.list
 148     file in the https URI.
 149
 150   Acquire::https[::repo.domain.tld]::SslCert "/path/to/client/cert.pem";
 151   Acquire::https[::repo.domain.tld]::SslKey  "/path/to/client/key.pem";
 152
 153     These two options provides support for client authentication using
 154     certificates. They respectively accept the X.509 client certificate
 155     in PEM format and the associated client key in PEM format (non
 156     encrypted form).
 157
 158     The options can be set globally (which rarely makes sense) or on a
 159     per-mirror basis.
 160
 161   Acquire::https[::repo.domain.tld]::SslForceVersion "TLSv1";
 162
 163     This option can be use to select the version which will be proposed
 164     to the server. "SSLv3" and "TLSv1" are supported. SSLv2, which is
 165     considered insecure anyway is not supported (by gnutls, which is
 166     used by libcurl against which apt https method is linked).
 167
 168     When the option is set to "SSLv3" to have apt propose SSLv3 (and
 169     associated sets of ciphersuites) instead of TLSv1 (the default)
 170     when performing the exchange. This prevents the server to select
 171     TLSv1 and use associated ciphersuites. You should probably not use
 172     this option except if you know exactly what you are doing.
 173
 174     Note that the default setting does not guarantee that the server
 175     will not select SSLv3 (for ciphersuites and SSL/TLS version as
 176     selection is always done by the server, in the end). It only means
 177     that apt will not advertise TLS support.
 178
 179   Debug::Acquire::https "true";
 180
 181     This option can be used to show debug information. Because it is
 182     quite verbose, it is mainly useful to debug problems in case of
 183     failure to connect to a server for some reason. The default value
 184     is "false".
 185
 186 */