X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=developers-reference.sgml;h=79a60492c16be7e96d672822c15bbfe7108037ea;hb=8e61d80da8ddea01cc9381b35c986c11aba067b4;hp=ba883c6d21fb2079c1afdafc875fa83f53ec4a2a;hpb=e4285cf6103cd328a1f5485f3e6db2a88a2605a2;p=developers-reference.git diff --git a/developers-reference.sgml b/developers-reference.sgml index ba883c6..79a6049 100644 --- a/developers-reference.sgml +++ b/developers-reference.sgml @@ -6,7 +6,7 @@ %commondata; - + + + What to do when you learn of a + security problem +

+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: + + + What versions of the package are known to be affected by the + bug. + + The nature of the exposure (root compromise, user compromise, + remote/local attack) + + The nature of the fix, if any is available (patches are + especially helpful) + + + Confidentiality +

+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. +

+There are a few ways a developer can learn of a security problem: + + + he notices it on a public forum (mailing list, website, etc.) + someone files a bug report + someone informs him via private email + + + 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: + + + 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. + + 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. + + +

+ 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). + +

+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. + +

+There are two reasons for releasing information even though secrecy is +requested: the problem has been known for too long, or the information +has become public. + + Security Advisories +

+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 . +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: + + + A description of the problem and its scope, including: + + The type of problem (privilege escalation, denial of + service, etc.) + How it can be exploited + Whether it is remotely or locally exploitable + How the problem was fixed + + Version numbers of affected packages + Version numbers of fixed packages + Information on where to obtain the updated packages + + + Preparing packages to + address security issues +

+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. +

+ When an update is made to the stable release, care must be taken to + avoid changing system behaviour 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 behaviour of a release once it is + made, so any change we make can possibly 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. +

+This means that moving to a new upstream version is not a good +solution. Instead, the relevant changes should be backported 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. +

+In some cases, it is not possible to backport a security fix, for +example when large amounts of sourcecode 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. +

+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. + +When packaging the fix, keep the following points in mind: + + + Make sure you target the right distribution in your + debian/changelog. For stable this is stable-security and for + testing this is testing-security. Do not target + distribution-proposed-updates! + + 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 dpkg + --compare-versions. For testing, this means there must be + a greater version in unstable. If there is none yet (for example, + if testing and unstable have the same version) you must upload a + new version to unstable first. + + Do not make source-only uploads if your package has any + binary-all packages. The buildd infrastructure will not build + those. This point applies to normal package uploads as well. + + Always upload with full source (use the -sa option + for dpkg-buildpackage). + + Be sure to use the exact same .orig.tar.gz as used in the + normal archive, otherwise it is not possible to move the security + fix into the main archives later. + + 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 ) + or setup a chroot (see and + ). + + + Uploading the fixed package +

+Once you have created and tested the new package, it needs to be +uploaded so it can be installed in the archives. For security uploads, +the place to upload to is +ftp://security.debian.org/pub/SecurityUploadQueue/ . + +

+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. + +

+Uploads waiting for acceptance or verification are only accessible by +the security team. This is necessary since there might be fixes for +security problems that can not be disclosed yet. + +

+If a member of the security team accepts a package it will be +installed on security.debian.org as well as the proper +distribution-proposed-updates on ftp-master or in the non-US +archive. When bugs are closed by new uploads

@@ -2615,11 +2893,11 @@ The good solution is to keep separate patches within the debian/patches directory and to apply them on the fly at build time. The package dbs provides an implementation of such a system, you just have to build-depend on dbs to -be able to use its functionnalities. The package +be able to use its functionalities. The package hello-dbs is a simple example that demonstrates how to use dbs.

-Additionnaly, dbs provides facilities to create the patches and to keep +Additionally, dbs provides facilities to create the patches and to keep track of what they are for. Multiple binary packages @@ -2628,7 +2906,7 @@ A single source package will often build several binary packages, either to provide several flavors of the same software (examples are the vim-* packages) or to make several small packages instead of a big one (it's interesting if the user doesn't need all the packages and can thus -save some diskspace). +save some disk space).

The second case can be easily managed by dh_install (from debhelper) to move files from the build directory to @@ -2643,7 +2921,35 @@ hand crafted rules file. Handling debconf translations

- &FIXME; Denis Barbier is going to write it. +Like porters, translators have a difficult task. Since they work on many +packages, they cannot keep track of every change in packages in order to +be informed when a translated string is outdated. Fortunately +debconf can automatically report outdated translations, +if package maintainers follow some basic guidelines described below. +

+Translators can use debconf-getlang (package +debconf-utils) to write a templates.xx +file containing both English and localized fields (where xx is +the language code, may be followed by a country code). This file can be +put into the debian subdirectory without any change. +

+When building a binary package, debian/templates.xx files are +merged along with debian/templates to generate the +templates file contained in the binary package. This is +automatically done by dh_installdebconf (package +debhelper). If you do not use debhelper, you can +do the same with debconf-mergetemplate +(package debconf-utils). +

+When the package maintainer needs to update the templates file, they only +change debian/templates. When English strings in this file +and in debian/templates.xx differ, translators do know that +their translation is outdated. +

+Please see the page about + +at the Debian web site, it contains more detailed instructions, including a +full example. @@ -2669,8 +2975,8 @@ Good practices for library packaging have been grouped in Other specific packages

-Several subsets of packages have special subpolicies and corresponding -packaging rules and practices : +Several subsets of packages have special sub-policies and corresponding +packaging rules and practices: Perl related packages have a , @@ -2678,7 +2984,7 @@ some examples of packages following that policy are libdbd-pg-perl (binary perl module) or libmldbm-perl (arch independent perl module). -Python related packages have their python policy : +Python related packages have their python policy: &file-python-policy; (in the python package). Emacs related packages have the . Java related packages have their . -Ocaml related packages have their ocaml policy : &file-ocaml-policy; (in -the ocaml package). A good example is the camlzip +Ocaml related packages have their ocaml policy: &file-ocaml-policy; (in +the ocaml package). A good example is the camlzip source package. @@ -2699,13 +3005,13 @@ source package.

Debconf is a configuration management system, it is used by all the various packaging scripts (postinst mainly) to request feedback from the -user in the intent to configure the package. Direct user interactions +user concerning how to configure the package. Direct user interactions must now be avoided in favor of debconf interaction. This will enable non-interactive installations in the future.

Debconf is a great tool but it is often badly used ... many common mistakes -are listed in the manpage. -It is something that you must have read if you decide to use debconf. +are listed in the man page. +It is something that you must read if you decide to use debconf. - Miscellaenous advice + Miscellaneous advice Writing useful descriptions

The description of the package (as defined by the corresponding field in the control file) is usually the first information -available to the user before he installs it. As such, it should +available to the user before they install it. As such, it should provide all the required information to let him decide whether to install the package.

For example, apart from the usual description that you adapt from the upstream README, you should include the URL of the -website if there's any. If the package is not yet considered stable +web site if there's any. If the package is not yet considered stable by the author, you may also want to warn the user that the package is not ready for production use.

+For consistency and for an aesthetic concern, you should capitalize the +first letter of the description. +

Last but not least, since the first user impression is based on -that description, you should be careful to avoid english +that description, you should be careful to avoid English mistakes. Ensure that you spell check it. -ispell has a special option (-g) for that : -ispell -d american -g debian/control +ispell has a special option (-g) for that: +ispell -d american -g debian/control. + @@ -2789,7 +3099,7 @@ out all the bugs you submitted, you just have to visit Reporting lots of bugs at once

Reporting a great number of bugs for the same problem on a great -number of different packages &mdash i.e., more than 10 &mdash is a deprecated +number of different packages — i.e., more than 10 — is a deprecated practice. Take all possible steps to avoid submitting bulk bugs at all. For instance, if checking for the problem can be automated, add a new check to lintian so that an error or warning @@ -2830,8 +3140,8 @@ If you do not get a reply after a few weeks you should collect all useful information about this maintainer. Start by logging into the and doing a full search to check whether the maintainer is on vacation -and when he was last seen. Collect any important package names -he maintains and any Release Critical bugs filled against them. +and when they were last seen. Collect any important package names +they maintain and any Release Critical bugs filed against them.

Send all this information to &email-debian-qa;, in order to let the QA people do whatever is needed. @@ -2851,7 +3161,7 @@ email the maintainer, whatever their individual email address (or addresses) may be. Replace <package> with the name of a source or a binary package.

-You may also be interested by contacting the persons who are +You may also be interested in contacting the persons who are subscribed to a given source package via . You can do so by using the <package-name>@&pts-host; email address. @@ -2879,7 +3189,7 @@ id="&url-sponsors;">. New maintainers usually have certain difficulties creating Debian packages — this is quite understandable. That is why the sponsor is there, to check the package and verify that it is good enough for inclusion in Debian. -(Note that if the sponsored package is new, the FTP admins will also have to +(Note that if the sponsored package is new, the ftpmasters will also have to inspect it before letting it in.)

Sponsoring merely by signing the upload or just recompiling is @@ -2902,9 +3212,9 @@ You can not simply upload a binary .deb from the sponsoree. In theory, you should only ask only for the diff file, and the location of the original source tarball, and then you should download the source and apply the diff yourself. In practice, you may want to use the source package -built by your sponsoree. In that case you have to check that he hasn't -altered the upstream files in the .orig.tar.gz file that he's -providing. +built by your sponsoree. In that case, you have to check that they haven't +altered the upstream files in the .orig.tar.gz file that +they're providing.

Do not be afraid to write the sponsoree back and point out changes that need to be made. It often takes several rounds of back-and-forth