X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;ds=sidebyside;f=developers-reference.sgml;h=a86386ec698e921b12591d62fe783296e22639e7;hb=f6b74f287273767115c98b492382544bcf16776f;hp=f108203e2bda90fe3cf4867efc6018620551e27e;hpb=3655759aa4aa898ab5761e83be37aef2ca29a3d0;p=developers-reference.git diff --git a/developers-reference.sgml b/developers-reference.sgml index f108203..a86386e 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: +about the problem, and promptly contact the security team at +&email-security-team; as soon as possible. Useful information +includes, for example: What versions of the package are known to be affected by the @@ -2016,7 +2157,11 @@ Useful information includes, for example: especially helpful) Any fixed packages that you have prepared yourself (send only - the .diff.gz and .dsc files) + the .diff.gz and .dsc files and read first) + + Any assistance you can provide to help with testing (exploits, + regression testing, etc.) Any information needed for the advisory (see ) @@ -2026,9 +2171,12 @@ Useful information includes, for example: Confidentiality

Unlike most other activities within Debian, information about security -issues must sometimes be kept private for a time. Whether this is the +issues must sometimes be kept private for a time. +This allows software distributors to coordinate their disclosure in +order to minimize their users' exposure. 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: @@ -2044,27 +2192,28 @@ There are a few ways a developer can learn of a security problem: 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 security exposure is minor, there is sometimes 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 + If the problem is severe, 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). + In all cases if the person who reports the problem asks that it not + be disclosed, such requests should be honored, with the obvious + exception of informing the security team in order that a fix may be + produced for a stable release of Debian. When sending confidential + information to the security team, be sure to mention this fact.

-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. +Please note that if secrecy is needed you may not upload a fix to +unstable (or anywhere else, such as a public CVS repository). It is +not sufficient to obfuscate the details of the change, as the code +itself is public, and can (and will) be examined by the general public.

There are two reasons for releasing information even though secrecy is @@ -2074,27 +2223,34 @@ or exploit has become public. Security Advisories

Security advisories are only issued for the current, released stable -distribution, not for testing or unstable. When released, advisories +distribution, and 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: +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.) + What privileges may be gained, and by whom (if any) How it can be exploited Whether it is remotely or locally exploitable How the problem was fixed + + This information allows users to assess the threat to their systems. + Version numbers of affected packages Version numbers of fixed packages Information on where to obtain the updated packages + (usually from the Debian security archive) References to upstream advisories, identifiers, and any other information useful in cross-referencing the vulnerability @@ -2104,16 +2260,17 @@ text. Information that should be in an advisory includes: 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 +provide them with 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 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. + 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.

This means that moving to a new upstream version is not a good solution. Instead, the relevant changes should be back-ported to the @@ -2124,8 +2281,8 @@ Debian security team may be able to help. 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. +upstream version. However, this is only done in extreme situations, +and 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 @@ -2136,9 +2293,9 @@ fix can break seemingly unrelated features in subtle ways. Review and test your changes as much as possible. Check the differences from the previous version repeatedly (interdiff from the patchutils package -and debdiff from devscripts are useful tools for -this). - +and debdiff from devscripts are useful +tools for this, see ). +

When packaging the fix, keep the following points in mind: @@ -2148,6 +2305,11 @@ When packaging the fix, keep the following points in mind: stable release, this is oldstable-security. Do not target distribution-proposed-updates! + Make descriptive, meaningful changelog entries. Others will + rely on them to determine whether a particular bug was fixed. + Whenever possible, include an external reference, preferably a CVE + identifier, so that it can be cross-referenced. + 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 @@ -2172,7 +2334,7 @@ When packaging the fix, keep the following points in mind: 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 + Be sure to build the package 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 ) @@ -2182,7 +2344,8 @@ When packaging the fix, keep the following points in mind: Uploading the fixed package

-DO NOT upload a package to the security upload queue without +DO NOT upload a package to the security upload queue +(oldstable-security, stable-security, etc.) 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. @@ -2217,7 +2380,6 @@ installed on security.debian.org as well as the proper distribution-proposed-updates on ftp-master or in the non-US archive. - Moving, removing, renaming, adopting, and orphaning packages @@ -2417,13 +2579,17 @@ Make sure that your Build-Depends and Build-Depends-Indep settings in debian/control are set properly. The best way to validate this is to use the debootstrap package to create an unstable chroot -environment. Within that chrooted environment, install the +environment (see ). +Within that chrooted environment, install the build-essential package and any package dependencies mentioned in Build-Depends and/or Build-Depends-Indep. Finally, try building your package within that chrooted environment. These steps can be automated by the use of the pbuilder program which is provided by -the package of the same name. +the package of the same name (see ). +

+If you can't set up a proper chroot, dpkg-depcheck may be +of assistance (see ).

See the for instructions on setting build dependencies. @@ -2461,7 +2627,7 @@ Make sure your debian/rules contains separate ``binary-arch'' and ``binary-indep'' targets, as the Debian Policy Manual requires. Make sure that both targets work independently, that is, that you can call the target without having called the other before. To test this, -try to run dpkg-buildpackage -b. +try to run dpkg-buildpackage -B. @@ -2721,7 +2887,7 @@ the bug. Don't forget to tag the bug with the "patch" keyword. Wait a few more days. If you still haven't got an answer from the maintainer, send him a mail announcing your intent to NMU the package. Prepare an NMU as described in , test it -carefully on your machine (cf. ). +carefully on your machine (cf. ). Double check that your patch doesn't have any unexpected side effects. Make sure your patch is as small and as non-disruptive as it can be. @@ -2852,9 +3018,8 @@ entry in the changelog file documenting the non-maintainer upload. Building source NMUs

Source NMU packages are built normally. Pick a distribution using the -same rules as found in . Just as described in -, a normal changes file, etc., will be built. In -fact, all the prescriptions from apply. +same rules as found in , follow the other +prescriptions in .

Make sure you do not change the value of the maintainer in the debian/control file. Your name as given in the NMU entry of @@ -3031,22 +3196,22 @@ documentation and examples (in /usr/share/doc/dpatch). Multiple binary packages

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 +either to provide several flavors of the same software (e.g., +the vim source package) or to make several small packages instead of a big one (e.g., if the user can install only the subset she needs, and thus save some disk space).

The second case can be easily managed in debian/rules. You just need to move the appropriate files from the build directory into the package's temporary trees. You can do this using -install (vanilla approach) or dh_install -(from debhelper). Be sure to check the different +install or dh_install +from debhelper. Be sure to check the different permutations of the various packages, ensuring that you have the inter-package dependencies set right in debian/control.

The first case is a bit more difficult since it involves multiple -recompiles of the same software but with different configure -options. The vim is an example of how to manage +recompiles of the same software but with different configuration +options. The vim source package is an example of how to manage this using an hand-crafted debian/rules file. + + + Best practices for maintainer scripts

Maintainer scripts include the files debian/postinst, @@ -3111,76 +3568,11 @@ not on the root partition. That is, it's in /usr/bin rather than /bin, so one can't use it in scripts which are run before the /usr partition is mounted. Most scripts won't have this problem, though. - - - - Best practices for debian/control -

-The following practices supplement the .

- - - Writing useful descriptions -

-The description of the package (as defined by the corresponding field -in the control file) is the primary information available -to the user about a package before they install it. It should provide -all the required information to let the user decide whether to install -the package. -

-For consistency and aesthetics, you should capitalize the first letter -of the Synopsis. Don't put a full stop (period) at the end. The -description itself should consist of full sentences. -

-Since the first user impression is based on the description, be -careful to avoid spelling and grammar mistakes. Ensure that you -spell-check it. ispell has a special -g option -for debian/control files: - -ispell -d american -g debian/control - -If you want someone to proofread the description that you -intend to use you may ask on &email-debian-l10n-english;. - - - - Upstream home page -

-We recommend that you add the URL for the package's home page to the -package description in debian/control. This information -should be added at the -end of description, using the following format: - - . - Homepage: http://some-project.some-place.org/ - -Note the spaces prepending the line, which serves to break the lines -correctly. To see an example of how this displays, see . -

-If there is no home page for the software, this should naturally be -left empty. -

-Note that we expect this field will eventually be replaced by a proper -debian/control field understood by dpkg and -&packages-host;. If you don't want to bother migrating the -home page from the description to this field, you should probably wait -until that is available.

- - - Configuration management with debconf -

Debconf is a configuration management system which can be used by all the various packaging scripts @@ -3191,7 +3583,7 @@ interaction. This will enable non-interactive installations in the future.

Debconf is a great tool but it is often poorly used. Many common mistakes -are listed in the man page. +are listed in the man page. It is something that you must read if you decide to use debconf. @@ -3364,26 +3756,29 @@ Lisp packages should register themselves with sympa may be an example package --> - Architecture-independent data -

- It is not uncommon to have a large amount of architecture-independent - data packaged with a program. For example, collection of icons, - wallpapers or other graphic files, or audio files. If the size of - this data is negligible compared to the size of the remainder of the - package, you can keep it all in the same package. - -

- However, if the size of the data is considerable, consider splitting - it out into a separate, architecture-independent package - ("_all.deb"). By doing this, you avoid needless duplication of the - same data into eleven or more .debs per each architecture. While - this adds some extra overhead into the Packages files, it can save a - lot of disk space on Debian mirrors, and it also reduces processing - time of Lintian or Linda when run over the entire Debian archive. - - + + Architecture-independent data +

+It is not uncommon to have a large amount of architecture-independent +data packaged with a program. For example, audio files, a collection +of icons, wallpaper patterns, or other graphic files. If the size of +this data is negligible compared to the size of the rest of the +package, it's probably best to keep it all in a single package. +

+However, if the size of the data is considerable, consider splitting +it out into a separate, architecture-independent package ("_all.deb"). +By doing this, you avoid needless duplication of the same data into +eleven or more .debs, one per each architecture. While this +adds some extra overhead into the Packages files, it +saves a lot of disk space on Debian mirrors. Separating out +architecture-independent data also reduces processing time of +lintian or linda (see ) +when run over the entire Debian archive. + + + Beyond Packaging @@ -3398,21 +3793,39 @@ members in choosing what they want to work on and in choosing the most critical thing to spend their time on. - Bug reporting + Bug reporting

We encourage you to file bugs as you find them in Debian packages. In fact, Debian developers are often the first line testers. Finding and -reporting bugs in other developer's packages improves the quality of +reporting bugs in other developers' packages improves the quality of Debian.

+Read the in the Debian . +

Try to submit the bug from a normal user account at which you are -likely to receive mail. Do not submit bugs as root. +likely to receive mail, so that people can reach you if they need +further information about the bug. Do not submit bugs as root. +

+You can use a tool like to +submit bugs. It can automate and generally ease the process. +

+Make sure the bug is not already filed against a package. +Each package has a bug list easily reachable at +http://&bugs-host;/packagename +Utilities like can also +provide you with this information (and reportbug +will usually invoke querybts before sending, too). +

+Try to direct your bugs to the proper location. When for example +your bug is about a package that overwrites files from another package, +check the bug lists for both of those packages in order to +avoid filing duplicate bug reports.

-Make sure the bug is not already filed against a package. Try to do a -good job reporting a bug and redirecting it to the proper location. For extra credit, you can go through other packages, merging bugs -which are reported more than once, or setting bug severities to -`fixed' when they have already been fixed. Note that when you are +which are reported more than once, or tagging bugs `fixed' +when they have already been fixed. Note that when you are neither the bug submitter nor the package maintainer, you should not actually close the bug (unless you secure permission from the maintainer). @@ -3421,7 +3834,7 @@ From time to time you may want to check what has been going on with the bug reports that you submitted. Take this opportunity to close those that you can't reproduce anymore. To find out all the bugs you submitted, you just have to visit -http://&bugs-host;/from:<your-email-addr>. +http://&bugs-host;/from:<your-email-addr>. Reporting lots of bugs at once

@@ -3440,7 +3853,7 @@ will help prevent a situation in which several maintainers start filing the same bug report simultaneously.

Note that when sending lots of bugs on the same subject, you should -send the bug report to maintonly@bugs.debian.org so +send the bug report to maintonly@&bugs-host; so that the bug report is not forwarded to the bug distribution mailing list. @@ -3633,13 +4046,12 @@ that need to be made. It often takes several rounds of back-and-forth email before the package is in acceptable shape. Being a sponsor means being a mentor.

-Once the package meets Debian standards, build the package with -dpkg-buildpackage -us -uc and sign it -with debsign -m"FULLNAME email-addr" changes-file +Once the package meets Debian standards, build and sign it with +dpkg-buildpackage -kKEY-ID before uploading it to the incoming directory.

The Maintainer field of the control file and the -changelog should list the person who did the packaging, i.e. the +changelog should list the person who did the packaging, i.e., the sponsoree. The sponsoree will therefore get all the BTS mail about the package.

@@ -3748,7 +4160,7 @@ You should periodically get the newest lintian from option provides detailed explanations of what each error or warning means, what is its basis in Policy, and commonly how you can fix the problem.

-Refer to for more information on how and when +Refer to for more information on how and when to use Lintian.

You can also see a summary of all problems reported by Lintian on your @@ -3764,8 +4176,33 @@ packages at . Those reports contain the latest lintian but has a different set of checks. Its written in Python rather than Perl.

+ + + debdiff +

+debdiff (from the devscripts package, ) +compares file lists and control files of two packages. It is a simple +regression test, as it will help you notice if the number of binary +packages has changed since the last upload, or if something's changed +in the control file. Of course, some of the changes it reports will be +all right, but it can help you prevent various accidents. +

+You can run it over a pair of binary packages: + +debdiff package_1-1_arch.deb package_2-1_arch.deb + +

+Or even a pair of changes files: + +debdiff package_1-1_arch.changes package_2-1_arch.changes + +

+For more information please see . + + + Helpers for debian/rules

@@ -4014,6 +4451,30 @@ directory of your package. For instance, when editing debian/changelog, there are handy functions for finalizing a version and listing the package's current bugs.

 + + + dpkg-depcheck +

+dpkg-depcheck (from the devscripts +package, ) +runs a command under strace to determine all the packages that +were used by the said command. +

+For Debian packages, this is useful when you have to compose a +Build-Depends line for your new package: running the build +process through dpkg-depcheck will provide you with a +good first approximation of the build-dependencies. For example: + +dpkg-depcheck -b debian/rules build + +

+dpkg-depcheck can also be used to check for run-time +dependencies, especially if your package uses exec(2) to run other +programs. +

+For more information please see . + + @@ -4080,6 +4541,9 @@ it.