+ <sect1 id="bug-security">Handling security-related bugs
+ <p>
+Due to their sensitive nature, security-related bugs must be handled
+carefully. The Debian Security Team exists to coordinate this
+activity, keeping track of outstanding security problems, helping
+maintainers with security problems or fix them themselves, sending
+security advisories, and maintaining security.debian.org.
+
+<!-- information about the security database goes here once it's ready -->
+<!-- (mdz) -->
+
+ <sect2 id="bug-security-you">What to do when you learn of a
+ security problem
+ <p>
+When you become aware of a security-related bug in a Debian package,
+whether or not you are the maintainer, collect pertinent information
+about the problem, and promptly contact the security team at
+&email-security-team;.
+Useful information includes, for example:
+
+<list compact>
+ <item>What versions of the package are known to be affected by the
+ bug. Check each version that is present in a supported Debian
+ release, as well as testing and unstable.
+
+ <item>The nature of the fix, if any is available (patches are
+ especially helpful)
+
+ <item>Any fixed packages that you have prepared yourself (send only
+ the <tt>.diff.gz</tt> and <tt>.dsc</tt> files)
+
+ <item>Any information needed for the advisory (see <ref
+ id="bug-security-advisories">)
+
+</list>
+
+ <sect2 id="bug-security-confidentiality">Confidentiality
+ <p>
+Unlike most other activities within Debian, information about security
+issues must sometimes be kept private for a time. Whether this is the
+case depends on the nature of the problem and corresponding fix, and
+whether it is already a matter of public knowledge.
+<p>
+There are a few ways a developer can learn of a security problem:
+
+<list compact>
+ <item>he notices it on a public forum (mailing list, web site, etc.)
+ <item>someone files a bug report
+ <item>someone informs him via private email
+</list>
+
+ In the first two cases, the information is public and it is important
+ to have a fix as soon as possible. In the last case, however, it
+ might not be public information. In that case there are a few
+ possible options for dealing with the problem:
+
+<list>
+ <item>if it is a trivial problem (like insecure temporary files)
+ there is no need to keep the problem a secret and a fix should be
+ made and released.
+
+ <item>if the problem is severe (remotely exploitable, possibility to
+ gain root privileges) it is preferable to share the information with
+ other vendors and coordinate a release. The security team keeps
+ contacts with the various organizations and individuals and can take
+ care of that.
+</list>
+
+<p>
+ In all cases if the person who reports the problem asks to not
+ disclose the information that should be respected, with the obvious
+ exception of informing the security team (make sure you tell the
+ security team that the information can not be disclosed).
+
+<p>
+Please note that if secrecy is needed you can also not upload a fix to
+unstable (or anywhere else), since the changelog and diff information
+for unstable is public.
+
+<p>
+There are two reasons for releasing information even though secrecy is
+requested: the problem has been known for a while, or that the problem
+or exploit has become public.
+
+ <sect2 id="bug-security-advisories">Security Advisories
+ <p>
+Security advisories are only issued for the current, released stable
+distribution, not for testing or unstable. When released, advisories
+are sent to the &email-debian-security-announce;
+mailing list and posted on <url
+id="&url-debian-security-advisories;" name="the security web page">.
+Security advisories are written and posted by the security
+team. However they certainly do not mind if a maintainer can supply
+some of the information for them, or write part of the
+text. Information that should be in an advisory includes:
+
+<list compact>
+ <item>A description of the problem and its scope, including:
+ <list>
+ <item>The type of problem (privilege escalation, denial of
+ service, etc.)
+ <item>How it can be exploited
+ <item>Whether it is remotely or locally exploitable
+ <item>How the problem was fixed
+ </list>
+ <item>Version numbers of affected packages
+ <item>Version numbers of fixed packages
+ <item>Information on where to obtain the updated packages
+ <item>References to upstream advisories, <url
+ id="http://cve.mitre.org" name="CVE"> identifiers, and any other
+ information useful in cross-referencing the vulnerability
+</list>
+
+ <sect2 id="bug-security-building">
+ <heading>Preparing packages to address security issues</heading>
+ <p>
+One way that you can assist the security team in their duties is to
+provide fixed packages suitable for a security advisory for the stable
+Debian release.
+ <p>
+ When an update is made to the stable release, care must be taken to
+ avoid changing system behavior or introducing new bugs. In order to
+ do this, make as few changes as possible to fix the bug. Users and
+ administrators rely on the exact behavior of a release once it is
+ made, so any change that is made might break someone's system.
+ This is especially true of libraries: make sure you never change the
+ API or ABI, no matter how small the change.
+<p>
+This means that moving to a new upstream version is not a good
+solution. Instead, the relevant changes should be back-ported to the
+version present in the current stable Debian release. Generally,
+upstream maintainers are willing to help if needed. If not, the
+Debian security team may be able to help.
+<p>
+In some cases, it is not possible to back-port a security fix, for
+example when large amounts of source code need to be modified or
+rewritten. If this happens, it may be necessary to move to a new
+upstream version. However, you must always coordinate that with the
+security team beforehand.
+<p>
+Related to this is another important guideline: always test your
+changes. If you have an exploit available, try it and see if it
+indeed succeeds on the unpatched package and fails on the fixed
+package. Test other, normal actions as well, as sometimes a security
+fix can break seemingly unrelated features in subtle ways.
+<p>
+Review and test your changes as much as possible. Check the
+differences from the previous version repeatedly
+(<prgn>interdiff</prgn> and <prgn>debdiff</prgn> are useful tools for
+this).
+
+When packaging the fix, keep the following points in mind:
+
+<list>
+ <item>Make sure you target the right distribution in your
+ <file>debian/changelog</file>. For stable this is <tt>stable-security</tt> and for
+ testing this is <tt>testing-security</tt>, and for the previous
+ stable release, this is <tt>oldstable-security</tt>. Do not target
+ <var>distribution</var>-proposed-updates!
+
+ <item>Make sure the version number is proper. It must be greater
+ than the current package, but less than package versions in later
+ distributions. If in doubt, test it with <tt>dpkg
+ --compare-versions</tt>. For <em>testing</em>, there must be
+ a higher version in <em>unstable</em>. If there is none yet (for example,
+ if <em>testing</em> and <em>unstable</em> have the same version) you must upload a
+ new version to unstable first.
+
+ <item>Do not make source-only uploads if your package has any
+ binary-all packages (do not use the <tt>-S</tt> option to
+ <prgn>dpkg-buildpackage</prgn>). The <prgn>buildd</prgn> infrastructure will
+ not build those. This point applies to normal package uploads as
+ well.
+
+ <item>If the upstream source has been uploaded to
+ security.debian.org before (by a previous security update), build
+ the upload without the upstream source (<tt>dpkg-buildpackage
+ -sd</tt>). Otherwise, build with full source
+ (<tt>dpkg-buildpackage -sa</tt>).
+
+ <item>Be sure to use the exact same <file>*.orig.tar.gz</file> as used in the
+ normal archive, otherwise it is not possible to move the security
+ fix into the main archives later.
+
+ <item>Be sure, when compiling a package, to compile on a clean
+ system which only has packages installed from the distribution you
+ are building for. If you do not have such a system yourself, you
+ can use a debian.org machine (see <ref id="server-machines">)
+ or setup a chroot (see <ref id="pbuilder"> and
+ <ref id="debootstrap">).
+</list>
+
+ <sect2 id="bug-security-upload">Uploading the fixed package
+<p>
+<em>DO NOT</em> upload a package to the security upload queue without
+prior authorization from the security team. If the package does not
+exactly meet the team's requirements, it will cause many problems and
+delays in dealing with the unwanted upload.
+<p>
+<em>DO NOT</em> upload your fix to proposed-updates without
+coordinating with the security team. Packages from
+security.debian.org will be copied into the proposed-updates directory
+automatically. If a package with the same or a higher version number
+is already installed into the archive, the security update will be
+rejected by the archive system. That way, the stable distribution
+will end up without a security update for this package instead.
+<p>
+Once you have created and tested the new package and it has been
+approved by the security team, it needs to be uploaded so that it can
+be installed in the archives. For security uploads, the place to
+upload to is
+<tt>ftp://security.debian.org/pub/SecurityUploadQueue/</tt> .
+
+<p>
+Once an upload to the security queue has been accepted, the package
+will automatically be rebuilt for all architectures and stored for
+verification by the security team.
+
+<p>
+Uploads which are waiting for acceptance or verification are only
+accessible by the security team. This is necessary since there might
+be fixes for security problems that cannot be disclosed yet.
+
+<p>
+If a member of the security team accepts a package, it will be
+installed on security.debian.org as well as the proper
+<var>distribution</var>-proposed-updates on ftp-master or in the non-US
+archive.