CINXE.COM

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> <html> <head> <meta http-equiv="X-UA-Compatible" content="IE=Edge"> <meta name="viewport" content="width=device-width, initial-scale=1"> <link rel="shortcut icon" href="/htdocs/favicon.ico"> <script type="text/javascript" src="/htdocs/bugstatus.js"></script> <meta http-equiv="Content-Type" content="text/html;charset=utf-8"> <meta name="robots" content="index,nofollow"> <title>DebianRepository/UseThirdParty - Debian Wiki</title> <script type="text/javascript" src="/htdocs/common/js/common.js"></script> <script type="text/javascript">  </script> <link rel="stylesheet" type="text/css" charset="utf-8" media="all" href="/htdocs/debwiki/css/common.css"> <link rel="stylesheet" type="text/css" charset="utf-8" media="screen" href="/htdocs/debwiki/css/screen.css"> <link rel="stylesheet" type="text/css" charset="utf-8" media="print" href="/htdocs/debwiki/css/print.css"> <link rel="stylesheet" type="text/css" charset="utf-8" media="projection" href="/htdocs/debwiki/css/projection.css"> <link rel="stylesheet" type="text/css" charset="utf-8" media="all" href="/htdocs/debian-wiki-1.0.css">   <link rel="alternate" title="Debian Wiki: DebianRepository/UseThirdParty" href="/DebianRepository/UseThirdParty?diffs=1&show_att=1&action=rss_rc&unique=0&page=DebianRepository%2FUseThirdParty&ddiffs=1" type="application/rss+xml"> <link rel="Start" href="/FrontPage"> <link rel="Alternate" title="Wiki Markup" href="/DebianRepository/UseThirdParty?action=raw"> <link rel="Alternate" media="print" title="Print View" href="/DebianRepository/UseThirdParty?action=print"> <link rel="Up" href="/DebianRepository"> <link rel="Search" href="/FindPage"> <link rel="Index" href="/TitleIndex"> <link rel="Glossary" href="/WordIndex"> <link rel="Help" href="/HelpOnFormatting"> </head> <body lang="en" dir="ltr"> <div id="logo"><a href="https://www.debian.org" title="Debian Homepage"><img src="https://www.debian.org/Pics/openlogo-50.png" alt="Debian" width="50" height="61"></a></div> <div id="header"> <div id="wikisection"> <a href="/FrontPage" title="Debian Wiki Homepage">Wiki</a> <div id="username"><a href="/DebianRepository/UseThirdParty?action=login" id="login" rel="nofollow">Login</a></div> </div> <div id="navbar"> <ul id="navibar"> <li class="wikilink"><a href="/FrontPage">FrontPage</a></li><li class="wikilink"><a href="/RecentChanges">RecentChanges</a></li><li class="wikilink"><a href="/FindPage">FindPage</a></li><li class="wikilink"><a href="/HelpContents">HelpContents</a></li><li class="current"><a href="/DebianRepository/UseThirdParty">UseThirdParty</a></li> </ul> </div> <form id="searchform" method="get" action="/DebianRepository/UseThirdParty"> <div> <input type="hidden" name="action" value="fullsearch"> <input type="hidden" name="context" value="180"> <label for="searchinput">Search:</label> <input id="searchinput" type="text" name="value" value="" size="20" onfocus="searchFocus(this)" onblur="searchBlur(this)" onkeyup="searchChange(this)" onchange="searchChange(this)" alt="Search"> <input id="titlesearch" name="titlesearch" type="submit" value="Titles" alt="Search Titles"> <input id="fullsearch" name="fullsearch" type="submit" value="Text" alt="Search Full Text"> </div> </form> <script type="text/javascript">  </script> <div id="logo"><a href="https://www.debian.org" title="Debian Homepage"><img src="https://www.debian.org/Pics/openlogo-50.png" alt="Debian" width="50" height="61"></a></div> <div id="breadcrumbs"><a href="/FrontPage" title="Debian Wiki Homepage">Wiki</a>/ </div> <ul class="editbar"><li><a href="/DebianRepository/UseThirdParty?action=login" id="login-1" rel="nofollow">Login</a></li><li class="toggleCommentsButton" style="display:none;"><a href="#" class="nbcomment" onClick="toggleComments();return false;">Comments</a></li><li><a class="nbinfo" href="/DebianRepository/UseThirdParty?action=info" rel="nofollow">Info</a></li><li><a class="nbattachments" href="/DebianRepository/UseThirdParty?action=AttachFile" rel="nofollow">Attachments</a></li><li> <form class="actionsmenu" method="GET" action="/DebianRepository/UseThirdParty"> <div> <label>More Actions:</label> <select name="action" onchange="if ((this.selectedIndex != 0) && (this.options[this.selectedIndex].disabled == false)) { this.form.submit(); } this.selectedIndex = 0;"> <option value="raw">Raw Text</option> <option value="print">Print View</option> <option value="RenderAsDocbook">Render as Docbook</option> <option value="refresh">Delete Cache</option> <option value="show" disabled class="disabled">------------------------</option> <option value="SpellCheck">Check Spelling</option> <option value="LikePages">Like Pages</option> <option value="LocalSiteMap">Local Site Map</option> <option value="show" disabled class="disabled">------------------------</option> <option value="RenamePage" disabled class="disabled">Rename Page</option> <option value="DeletePage" disabled class="disabled">Delete Page</option> <option value="show" disabled class="disabled">------------------------</option> <option value="show" disabled class="disabled">Subscribe User</option> <option value="show" disabled class="disabled">------------------------</option> <option value="show" disabled class="disabled">Remove Spam</option> <option value="show" disabled class="disabled">Revert to this revision</option> <option value="PackagePages">Package Pages</option> <option value="show" disabled class="disabled">------------------------</option> <option value="Load">Load</option> <option value="Save">Save</option> <option value="SlideShow">SlideShow</option> </select> <input type="submit" value="Do"> </div> <script type="text/javascript">  </script> </form> </li></ul> <h1 id="locationline"> <ul id="pagelocation"> <li><a href="/DebianRepository">DebianRepository</a></li><li><a href="/DebianRepository/UseThirdParty">UseThirdParty</a></li> </ul> </h1> </div> <div id="page" lang="en" dir="ltr"> <div dir="ltr" id="content" lang="en"> <h1 id="Instructions_to_connect_to_a_third-party_repository">Instructions to connect to a third-party repository</h1> There are many different ways of configuring an unofficial APT repository on a machine. This document aims to standardize the procedure to add such a third-party repository to a Debian-based system so that the new repository can only ship a set of expected packages, and so that those packages will be securely delivered to the system. Where possible, this document uses RFC-like vocabulary as defined by RFC <a class="interwiki" href="http://www.ietf.org/rfc/rfc2119.txt" title="RFC">2119</a>. Note that those instructions primarily target Debian 9 "stretch" or later. <div class="important">Note that the procedures documented here aim to prevent a repository from shipping packages that the administrator does not expect that repository to ship. For example, a repo that ships a video game emulator and its mods shouldn't be able to override <a class="interwiki" href="https://packages.debian.org/libc6" title="DebianPackage">libc6</a>. However, the installation of any single malicious package from a malicious repository can currently undo these protections, for example by running a <a href="/MaintainerScripts">MaintainerScripts</a> command to override the configured preferences or by authorizing new OpenPGP certificates. For the purposes of this page, attacks by a package that belongs to a given repository are out of scope. To restrict what an installed package can do, see the larger <a href="/UntrustedDebs">UntrustedDebs</a> problem, and particularly <a href="/Teams/Dpkg/Spec/DeclarativePackaging">Teams/Dpkg/Spec/DeclarativePackaging</a> for a potential solution. </div><div class="table-of-contents">Contents<ol><li> <a href="#Instructions_to_connect_to_a_third-party_repository">Instructions to connect to a third-party repository</a><ol><li> <a href="#OpenPGP_certificate_distribution">OpenPGP certificate distribution</a></li><li> <a href="#Sources.list_entry">Sources.list entry</a></li><li> <a href="#Standard_pinning">Standard pinning</a></li><li> <a href="#Certificate_rollover_and_updates">Certificate rollover and updates</a></li><li> <a href="#Complete_example">Complete example</a></li><li> <a href="#Troubleshooting">Troubleshooting</a></li><li> <a href="#OpenPGP_certificate_handling">OpenPGP certificate handling</a></li><li> <a href="#Credits">Credits</a></li><li> <a href="#References">References</a></li></ol></li></ol></div> <h2 id="OpenPGP_certificate_distribution">OpenPGP certificate distribution</h2> Repositories MUST be signed with an OpenPGP certificate. A binary export (<tt class="backtick">gpg --export</tt>) of the certificate SHOULD be available at the root of the repository under the filename <tt class="backtick">deriv-archive-keyring.pgp</tt>, where <tt class="backtick">deriv</tt> is the a short name for the repository. The file SHOULD NOT be ASCII-Armored (<tt class="backtick">gpg --export --armor</tt>) although a separate armored version MAY be available under <tt class="backtick">deriv-archive-keyring.asc</tt>. The certificate SHOULD be served over HTTPS if possible. A free X509 certificate MAY be obtained from <a class="https" href="https://letsencrypt.org/">Let's Encrypt</a> and automatically configured using the <a class="interwiki" href="https://packages.debian.org/certbot" title="DebianPackage">certbot</a> package. The certificate MAY also be made available on key servers. If so, operators SHOULD choose an appropriate keyserver or keyserver pool, such as <a class="https" href="https://keys.openpgp.org/">keys.openpgp.org</a> or <a class="https" href="https://keyserver.ubuntu.com/">keyserver.ubuntu.com</a>, or implement a <a class="https" href="https://datatracker.ietf.org/doc/draft-koch-openpgp-webkey-service/">OpenPGP Web Key Directory</a>. It should be noted that the previously recommended ad-hoc standard pool, <a class="https" href="https://sks-keyservers.net/">sks-keyservers.net</a> is out of service permanently. This certificate SHOULD be signed by other keys, preferably including some that are close to the strong set, in order to leverage the OpenPGP web of trust. The certificate MUST be downloaded over a secure mechanism like HTTPS to a location only writable by root. The certificate MUST NOT be placed in <tt class="backtick">/etc/apt/trusted.gpg.d</tt> or loaded by <tt class="backtick">apt-key add</tt>. If future updates to the certificate will be managed by an apt/dpkg package as recommended below, then it SHOULD be downloaded into <tt class="backtick">/usr/share/keyrings</tt> using the same filename that will be provided by the package. If it will be managed locally , it SHOULD be downloaded into <tt class="backtick">/etc/apt/keyrings</tt> instead. <div class="note">In releases older than Debian 12 and Ubuntu 22.04, <tt class="backtick">/etc/apt/keyrings</tt> does not exist by default. It SHOULD be created with permissions 0755 if it is needed and does not already exist. </div><div class="tip">For example, users MAY be told to run a command to download the certificate, but because chances are the certificate being distributed is ASCII-Armored, it is best to unconditionally dearmor them. With Sequoia-PGP: <pre>curl https://deriv.example.net/debian/deriv-archive-keyring.pgp | sq -o /usr/share/keyrings/deriv-archive-keyring.pgp dearmor</pre>or with GnuPG: <pre>curl https://deriv.example.net/debian/deriv-archive-keyring.pgp | gpg -o /usr/share/keyrings/deriv-archive-keyring.pgp --dearmor</pre></div><div class="note">The reason why we avoid ASCII-Armored files is that they can only be used by <a href="/SecureApt">SecureApt</a> in version 1.4 or later (which appeared in stretch). We also strongly recommend the use of HTTPS as it bypasses certain MITM attacks that would allow a hostile third party to inject OpenPGP certificate material in the repository setup. </div> <h2 id="Sources.list_entry">Sources.list entry</h2> A <tt class="backtick">sources.list</tt> entry SHOULD have the <tt class="backtick">signed-by</tt> option set. The <tt class="backtick">signed-by</tt> entry MUST point to a file, and not a fingerprint. The <tt class="backtick">suite</tt> entry SHOULD correspond to the target Debian release if the binaries are built for a specific suite. In other cases, the <tt class="backtick">suite</tt> SHOULD be the string "stable", or it MAY be a repository-specific string describing the suite concisely. If the suite does not correspond to a target Debian release, the <tt class="backtick">suite</tt> naming convention MUST be clearly documented. If the repository has no reason to be split into multiple components, then the <tt class="backtick">component</tt> name SHOULD be <tt class="backtick">main</tt>. If there is a reason for splitting the repo into multiple components, the reason for the split should be clearly documented (e.g. <a class="https" href="https://www.debian.org/doc/debian-policy/ch-archive#s-sections">Debian's documented split</a>) and the <tt class="backtick">component</tt> names should concisely reflect that split. Entries MUST be added in the <tt class="backtick">/etc/apt/sources.list.d</tt> directory using a shortened repository name (e.g. <tt class="backtick">deriv.list</tt>). The "Deb822" file format MAY be used instead to improve clarity for complex entries (e.g. <tt class="backtick">deriv.sources</tt>). (See <a class="interwiki" href="https://manpages.debian.org/man/buster/5/sources.list#THE_DEB_AND_DEB-SRC_TYPES:_GENERAL_FORMAT" title="DebianMan">sources.list(5)</a>) <div class="tip">For example, this would be the content of the <tt class="backtick">/etc/apt/sources.list.d/deriv.list</tt> file: <pre>deb [signed-by=/usr/share/keyrings/deriv-archive-keyring.pgp] https://deriv.example.net/debian/ stable main</pre>The above is a <tt class="backtick">sources.list</tt> line for a fictitious <tt class="backtick">Deriv</tt> Debian derivative. The <tt class="backtick">suite</tt> is <tt class="backtick">stable</tt> and the <tt class="backtick">component</tt> is the standard <tt class="backtick">main</tt> component. This is equivalent to the following Deb822 file format, under <tt class="backtick">deriv.sources</tt>: <pre>Types: deb URIs: https://deriv.example.net/debian/ Suites: stable Components: main Signed-By: /usr/share/keyrings/deriv-archive-keyring.pgp</pre></div><div class="note">The reason we point to a file instead of a fingerprint is that the latter forces the user to add the certificate to the global <a href="/SecureApt">SecureApt</a> trust anchor in <tt class="backtick">/etc/apt/trusted.gpg.d</tt>, which would cause the system to accept signatures from the third-party keyholder on all other repositories configured on the system that don't have a <tt class="backtick">signed-by</tt> option (including the official Debian repositories). </div><div class="note">Serving the repository under HTTPS is OPTIONAL, as it may make running a round-robin network of untrusted mirrors more difficult, and the trust chain provided by <a href="/SecureApt">SecureApt</a> should suffice. </div> <h2 id="Standard_pinning">Standard pinning</h2> When a repository is added to the <tt class="backtick">sources.list.d</tt>, a matching preferences file SHOULD be created to restrict the possible effects of the repository. If such a preferences file is used it MUST pin with a user-controlled label (e.g. the hostname of the URI, or some future local mark, see <a class="interwiki" href="https://bugs.debian.org/858406" title="DebianBug">858406</a>) and MUST NOT use a field provided by the upstream Release file. The <tt class="backtick">Pin-Priority</tt> field MAY be set so that packages are upgraded by default (<tt class="backtick">Pin-Priority: 100</tt>) or not (<tt class="backtick">Pin-Priority: 1</tt>) but it MUST NOT be set to any higher value that may lead to overwriting packages shipped with the default Debian distribution. If no preferences file is provided or a different <tt class="backtick">Pin-Priority</tt> is used, the user MUST be warned of the security consequences. <div class="tip">For example, this will forbid the <tt class="backtick">deriv.example.net</tt> repository from upgrading already installed packages from official repositories, while allowing upgrades to be performed for the <tt class="backtick">deriv</tt> repository: <pre>Package: * Pin: origin deriv.example.net Pin-Priority: 100</pre>Alternatively, this configuration will allow the user to install packages from the <tt class="backtick">deriv</tt> repository but forbid automated upgrades: <pre>Package: * Pin: origin deriv.example.net Pin-Priority: 1</pre></div><div class="important">The above <tt class="backtick">origin</tt> configuration has not been audited. It MAY be possible the repository could override that value. Further tests are required to confirm the above configuration is resilient to attack by the repository owner. </div><div class="important">Note that if the local system pulls multiple repositories from the same host (e.g. different paths, different suites, or different components), then the proposed <tt class="backtick">Pin: origin</tt> is incapable of distinguishing between them. Fixing this appears to require improvements in apt, see <a class="interwiki" href="https://bugs.debian.org/858406" title="DebianBug">858406</a>. </div> <h2 id="Certificate_rollover_and_updates">Certificate rollover and updates</h2> Certificate updates SHOULD be distributed by a Debian package called <tt class="backtick">deriv-archive-keyring</tt>. This package MUST distribute the certificate in binary form as <tt class="backtick">/usr/share/keyrings/deriv-archive-keyring.pgp</tt>, and MAY also include the <tt class="backtick">/etc/apt/sources.list.d/deriv.sources</tt> or <tt class="backtick">/etc/apt/sources.list.d/deriv.list</tt> files and the <tt class="backtick">/etc/apt/preferences.d/deriv.pref</tt> file. If such a mechanism is used to distribute certificate updates, the preferences file MUST allow automatic upgrades (<tt class="backtick">Pin-Priority: 100</tt>) or include a specific entry for the keyring package that adds an exception for that package: <pre>Package: deriv-archive-keyring Pin: origin deriv.example.net Pin-Priority: 100</pre> <h2 id="Complete_example">Complete example</h2> This example may serve as a template for instructions provided at the root of the archive to help users configure the APT repository. <div class="tip">This is a Debian repository. To install packages from this repository, you should first download a trust anchor into your system using this command: <pre>wget -O /usr/share/keyrings/deriv-archive-keyring.pgp https://deriv.example.net/debian/deriv-archive-keyring.pgp</pre>Then you can add the repository to your sources.list by creating a text file in <tt class="backtick">/etc/apt/sources.list.d/deriv.sources</tt> containing the following: <pre>Types: deb deb-src URIs: https://deriv.example.net/debian/ Suites: stable Architectures: i386 amd64 Components: main Signed-By: /usr/share/keyrings/deriv-archive-keyring.pgp</pre>Finally, you should also add the following preferences file to restrict what this repository can install, by creating the following file in <tt class="backtick">/etc/apt/preferences.d/deriv.pref</tt>: <pre>Package: * Pin: origin deriv.example.net Pin-Priority: 100</pre>Once this is done, you can run <tt class="backtick">apt-get update</tt> for the changes to take effect and use <tt class="backtick">apt-get install deriv-archive-keyring</tt> to make sure updates to the keyring are received in a timely manner. </div> <h2 id="Troubleshooting">Troubleshooting</h2> <pre>W: GPG error: http://deriv.example.net stable InRelease: The following signatures couldn't be verified because the public key is not available: NO_PUBKEY 744ACF4DF3319FFA</pre>This error message is commonly seen when the OpenPGP certificate you are using is ASCII-Armored instead of being in binary form. <div class="tip">Sequoia-PGP can handle ASCII-Armored data anywhere where it can handle binary data. </div> <h2 id="OpenPGP_certificate_handling">OpenPGP certificate handling</h2> APT used to be unable to handle ASCII-Armored OpenPGP certificates. And thus as indicated above, you MUST NOT use ASCII-Armored certificates. If you have such a certificate, you should convert it to binary form with something like this with Sequoia-PGP: <pre>sq dearmor -o $CERT.pgp $CERT.asc </pre>Or in a slightly more convoluted way with GnuPG: <pre>gpg --import $CERT.asc gpg --export $CERT_FINGERPRINT >$CERT.pgp</pre>Then <tt class="backtick">$CERT.pgp</tt> can be distributed everywhere with no backwards compatibility concerns. <h2 id="Credits">Credits</h2> This document was written by <a href="/TheAnarcat">TheAnarcat</a> with extensive help and review from <a href="/DanielKahnGillmor">DanielKahnGillmor</a>. <h2 id="References">References</h2> <ul><li><a href="/DebianRepository">DebianRepository</a> - more documentation on Debian repositories, see in particular <a href="/DebianRepository/Setup">setup info</a> and <a href="/DebianRepository/Format">format info</a> (more information about the different fields in the repository Release file) </li><li><a href="/SecureApt">SecureApt</a> - OpenPGP integration in APT </li><li><a href="/SecureApt/TufDerivedImprovements">SecureApt/TufDerivedImprovements</a> - possible for the above </li><li><a href="/SourcesList">SourcesList</a> - basic documentation on sources.list files </li><li><a class="interwiki" href="https://manpages.debian.org/man/sources.list" title="DebianMan">sources.list(5)</a> - manual page </li><li><a href="/UntrustedDebs">UntrustedDebs</a> - the larger effort to make third-party repositories more secure </li><li><a class="https" href="https://salsa.debian.org/apt-team/apt/-/merge_requests/176">support for embeddeding OpenPGP certificates directly in the sources.list</a> might improve on this </li></ul><hr /> <a href="/CategoryPackageManagement">CategoryPackageManagement</a> </div><div id="pagebottom"></div> </div> <div id="footer"> DebianRepository/UseThirdParty (<a class="nbinfo" href="/DebianRepository/UseThirdParty?action=info" rel="nofollow">last modified 2022-12-16 02:40:49</a>) <ul id="credits"> <li>Debian <a href="https://www.debian.org/legal/privacy">privacy policy</a>, Wiki <a href="/Teams/DebianWiki">team</a>, <a href="https://bugs.debian.org/wiki.debian.org">bugs</a> and <a href="https://salsa.debian.org/debian/wiki.debian.org">config</a>.</li><li>Powered by <a href="https://moinmo.in/" title="This site uses the MoinMoin Wiki software.">MoinMoin</a> and <a href="https://moinmo.in/Python" title="MoinMoin is written in Python.">Python</a>, with hosting provided by <a href="https://www.man-da.de/">Metropolitan Area Network Darmstadt</a>.</li> </ul> </div> </body> </html>