You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

apt-transport-https.1.xml 5.9 KiB

2 years ago
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133
  1. <?xml version="1.0" encoding="utf-8" standalone="no"?>
  2. <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
  3. "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
  4. <!ENTITY % aptent SYSTEM "apt.ent"> %aptent;
  5. <!ENTITY % aptverbatiment SYSTEM "apt-verbatim.ent"> %aptverbatiment;
  6. <!ENTITY % aptvendor SYSTEM "apt-vendor.ent"> %aptvendor;
  7. ]>
  8. <refentry>
  9. <refentryinfo>
  10. &apt-author.team;
  11. &apt-email;
  12. &apt-product;
  13. <!-- The last update date -->
  14. <date>2018-05-11T00:00:00Z</date>
  15. </refentryinfo>
  16. <refmeta>
  17. <refentrytitle>apt-transport-https</refentrytitle>
  18. <manvolnum>1</manvolnum>
  19. <refmiscinfo class="manual">APT</refmiscinfo>
  20. </refmeta>
  21. <!-- Man page title -->
  22. <refnamediv>
  23. <refname>apt-transport-https</refname>
  24. <refpurpose>APT transport for downloading via the HTTP Secure protocol (HTTPS)</refpurpose>
  25. </refnamediv>
  26. <refsect1><title>Description</title>
  27. <para>This APT transport allows the use of repositories accessed via the
  28. HTTP Secure protocol (HTTPS), also referred to as HTTP over TLS. It is available
  29. by default since apt 1.5 and was available before that in the package
  30. <package>apt-transport-https</package>. Note that a transport is never called directly by
  31. a user but used by APT tools based on user configuration.</para>
  32. <para>HTTP is by itself an unencrypted transport protocol (compare &apt-transport-http;),
  33. which, as indicated by the appended S, is wrapped in an encrypted layer known as
  34. Transport Layer Security (TLS) to provide end-to-end encryption.
  35. A sufficiently capable attacker can still observe the communication partners
  36. and deeper analysis of the encrypted communication might still reveal important details.
  37. An overview over available alternative transport methods is given in &sources-list;.</para>
  38. </refsect1>
  39. <refsect1><title>Options</title>
  40. <para>The HTTPS protocol is based on the HTTP protocol, so
  41. all options supported by &apt-transport-http; are also
  42. available via <literal>Acquire::https</literal> and will default to the same values specified
  43. for <literal>Acquire::http</literal>. This manpage will only document the options
  44. <emphasis>unique to https</emphasis>.</para>
  45. <refsect2><title>Server credentials</title>
  46. <para>By default all certificates trusted by the system (see
  47. <package>ca-certificates</package> package) are used for the verification of
  48. the server certificate. An alternative certificate authority (CA) can be
  49. configured with the <literal>Acquire::https::CAInfo</literal> option and its
  50. host-specific option <literal>Acquire::https::CAInfo::<replaceable>host</replaceable></literal>.
  51. The CAInfo option specifies a file made up of CA certificates (in PEM format)
  52. concatenated together to create the chain which APT should use to verify the
  53. path from your self-signed root certificate. If the remote server provides the
  54. whole chain during the exchange, the file need only contain the root
  55. certificate. Otherwise, the whole chain is required. If you need to support
  56. multiple authorities, the only way is to concatenate everything.</para>
  57. <para>A custom certificate revocation list (CRL) can be configured with the options
  58. <literal>Acquire::https::CRLFile</literal> and
  59. <literal>Acquire::https::CRLFile::<replaceable>host</replaceable></literal>.
  60. As with the previous option, a file in PEM format needs to be specified.</para>
  61. </refsect2>
  62. <refsect2><title>Disabling security</title>
  63. <para>During server authentication, if certificate verification fails
  64. for some reason (expired, revoked, man in the middle, etc.), the connection fails.
  65. This is obviously what you want in all cases and what the default value (true)
  66. of the option <literal>Acquire::https::Verify-Peer</literal> and its host-specific
  67. variant provides. If you know <emphasis>exactly</emphasis> what you are doing,
  68. setting this option to "<literal>false</literal>" allows you to skip peer certificate verification and
  69. make the exchange succeed. Again, this option is for debugging or testing purposes
  70. only as it removes all security provided by the use of HTTPS.</para>
  71. <para>Similarly the option <literal>Acquire::https::Verify-Host</literal> and its
  72. host-specific variant can be used to deactivate a security feature: The certificate
  73. provided by the server includes the identity of the server which should match the
  74. DNS name used to access it. By default, as requested by RFC 2818, the name of the
  75. mirror is checked against the identity found in the certificate. This default behavior
  76. is safe and should not be changed, but if you know that the server you are using has a
  77. DNS name which does not match the identity in its certificate, you can set the option to
  78. "<literal>false</literal>", which will prevent the comparison from being performed.</para>
  79. </refsect2>
  80. <refsect2><title>Client authentication</title>
  81. <para>Besides supporting password-based authentication (see &apt-authconf;) HTTPS also supports
  82. authentication based on client certificates via <literal>Acquire::https::SSLCert</literal>
  83. and <literal>Acquire::https::SSLKey</literal>. These should be set respectively to the filename of
  84. the X.509 client certificate and the associated (unencrypted) private key, both in PEM format.
  85. In practice the use of the host-specific variants of both options is highly recommended.</para>
  86. </refsect2>
  87. </refsect1>
  88. <refsect1><title>Examples</title>
  89. <literallayout>
  90. Acquire::https {
  91. Proxy::example.org "DIRECT";
  92. Proxy "socks5h://apt:pass@127.0.0.1:9050";
  93. Proxy-Auto-Detect "/usr/local/bin/apt-https-proxy-auto-detect";
  94. No-Cache "true";
  95. Max-Age "3600";
  96. No-Store "true";
  97. Timeout "10";
  98. Dl-Limit "42";
  99. Pipeline-Depth "0";
  100. AllowRedirect "false";
  101. User-Agent "My APT-HTTPS";
  102. SendAccept "false";
  103. CAInfo "/path/to/ca/certs.pem";
  104. CRLFile "/path/to/all/crl.pem";
  105. Verify-Peer "true";
  106. Verify-Host::broken.example.org "false";
  107. SSLCert::example.org "/path/to/client/cert.pem";
  108. SSLKey::example.org "/path/to/client/key.pem"
  109. };
  110. </literallayout>
  111. </refsect1>
  112. <refsect1>
  113. <title>See Also</title>
  114. <para>&apt-transport-http; &apt-conf; &apt-authconf; &sources-list;
  115. </para>
  116. </refsect1>
  117. &manbugs;
  118. </refentry>