]> git.saurik.com Git - apt.git/blame_incremental - doc/examples/apt-https-method-example.conf
follow the recommendation of cppcheck to make some method methods (scnr)
[apt.git] / doc / examples / apt-https-method-example.conf
... / ...
CommitLineData
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)
52Acquire::https::Verify-Peer "true";
53Acquire::https::Verify-Host "true";
54
55// Except otherwise specified, use that list of anchors
56Acquire::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.
60Acquire::https::secure.dom1.tld::CaInfo "/etc/apt/certs/ca-dom1-crt.pem";
61Acquire::https::secure.dom1.tld::CrlFile "/etc/apt/certs/ca-dom1-crl.pem";
62Acquire::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.
66Acquire::https::secure.dom2.tld::CaInfo "/etc/apt/certs/ca-dom2-crt.pem";
67Acquire::https::secure.dom2.tld::CrlFile "/etc/apt/certs/ca-dom2-crl.pem";
68Acquire::https::secure.dom2.tld::SslCert "/etc/apt/certs/my-crt.pem";
69Acquire::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*/