From: Glenn Morris Date: Thu, 5 Jun 2014 06:15:44 +0000 (-0700) Subject: Some documentation for signing of packages X-Git-Tag: emacs-24.3.92~112 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=e1b3f35f9373d71f58638e9dcaffc2ff8c4ab3b6;p=emacs.git Some documentation for signing of packages * doc/emacs/package.texi (Package Menu, Package Installation): Mention signed packages. * doc/lispref/package.texi (Package Archives): Mention signing packages. * lisp/emacs-lisp/package.el (package-check-signature) (package-unsigned-archives): Doc fixes. * etc/NEWS: Related edits. --- diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog index 27168b00021..6ca98a3f24b 100644 --- a/doc/emacs/ChangeLog +++ b/doc/emacs/ChangeLog @@ -1,3 +1,8 @@ +2014-06-05 Glenn Morris + + * package.texi (Package Menu, Package Installation): + Mention signed packages. + 2014-06-03 Glenn Morris * package.texi (Package Installation): Mention package-pinned-packages. diff --git a/doc/emacs/package.texi b/doc/emacs/package.texi index 98e3c8ac706..9b7f541ac51 100644 --- a/doc/emacs/package.texi +++ b/doc/emacs/package.texi @@ -59,8 +59,9 @@ The package's version number (e.g., @samp{11.86}). @item The package's status---normally one of @samp{available} (can be -downloaded from the package archive), @samp{installed}, or -@samp{built-in} (included in Emacs by default). +downloaded from the package archive), @samp{installed}, +@samp{unsigned} (installed, but not signed; @pxref{Package Signing}), +or @samp{built-in} (included in Emacs by default). The status can also be @samp{new}. This is equivalent to @samp{available}, except that it means the package became newly @@ -167,6 +168,41 @@ directory name of the package archive. You can alter this list if you wish to use third party package archives---but do so at your own risk, and use only third parties that you think you can trust! +@anchor{Package Signing} +@cindex package security +@cindex package signing + The maintainers of package archives can increase the trust that you +can have in their packages by @dfn{signing} them. They generate a +private/public pair of crytopgraphic keys, and use the private key to +create a @dfn{signature file} for each package. With the public key, you +can use the signature files to verify who created the package, and +that it has not been modified. A valid signature is not a cast-iron +guarantee that a package is not malicious, so you should still +exercise caution. Package archives should provide instructions +on how you can obtain their public key. One way is to download the +key from a server such as @url{http://pgp.mit.edu/}. +Use @kbd{M-x package-import-keyring} to import the key into Emacs. +Emacs stores package keys in the @file{gnupg} subdirectory +of @code{package-user-dir}. +@c Uncomment this if it becomes true. +@ignore +The public key for the GNU package archive is distributed with Emacs, +in the @file{etc/package-keyring.gpg}. Emacs uses it automatically. +@end ignore + +@vindex package-check-signature +@vindex package-unsigned-archives + If the user option @code{package-check-signature} is non-@code{nil}, +Emacs attempts to verify signatures when you install packages. If the +option has the value @code{allow-unsigned}, you can still install a +package that is not signed. If you use some archives that do not sign +their packages, you can add them to the list @code{package-unsigned-archives}. + + For more information on crytopgraphic keys and signing, +@pxref{Top,, Top, gnupg, The GNU Privacy Guard Manual}. +Emacs comes with an interface to GNU Privacy Guard, +@pxref{Top,, EasyPG, epa, Emacs EasyPG Assistant Manual}. + @vindex package-pinned-packages If you have more than one package archive enabled, and some of them offer different versions of the same package, you may find the option diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index e4f5c60c2d1..51f74f2eb12 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,7 @@ +2014-06-05 Glenn Morris + + * package.texi (Package Archives): Mention signing packages. + 2014-05-27 Glenn Morris * text.texi (Buffer Contents): diff --git a/doc/lispref/package.texi b/doc/lispref/package.texi index 4bc50b2358f..cac7519671a 100644 --- a/doc/lispref/package.texi +++ b/doc/lispref/package.texi @@ -342,3 +342,38 @@ otherwise, an error is raised. @noindent After you create an archive, remember that it is not accessible in the Package Menu interface unless it is in @code{package-archives}. + +@cindex package archive security +@cindex package signing +Maintaining a public package archive entails a degree of responsibility. +When Emacs users install packages from your archive, those packages +can cause Emacs to run arbitrary code with the permissions of the +installing user. (This is true for Emacs code in general, not just +for packages.) So you should ensure that your archive is +well-maintained and keep the hosting system secure. + + One way to increase the security of your packages is to @dfn{sign} +them using a crytopgraphic key. If you have generated a +private/public gpg key pair, you can use gpg to sign the package like +this: + +@c FIXME EasyPG / package-x way to do this. +@example +gpg -ba -o @var{file}.sig @var{file} +@end example + +@noindent +For a single-file package, @var{file} is the package Lisp file; +for a multi-file package, it is the package tar file. +You can also sign the archive's contents file in the same way. +Make the @file{.sig} files available in the same location as the packages. +You should also make your public key available for people to download; +e.g., by uploading it to a key server such as @url{http://pgp.mit.edu/}. +When people install packages from your archive, they can use +your public key to verify the signatures. + +A full explanation of these matters is outside the scope of this +manual. For more information on crytopgraphic keys and signing, +@pxref{Top,, GnuPG, gnupg, The GNU Privacy Guard Manual}. Emacs comes +with an interface to GNU Privacy Guard, @pxref{Top,, EasyPG, epa, +Emacs EasyPG Assistant Manual}. diff --git a/etc/NEWS b/etc/NEWS index bb9784718fc..fce36903c2b 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -816,13 +816,24 @@ Use `electric-indent-mode' instead. ** Package ++++ +*** The package library now supports digital signing of packages. +Maintainers of package archives should consider signing their packages +to enhance security. + ++++ +**** If the user option `package-check-signature' is non-nil, +Emacs tries to check package signatures at install time. +The value `allow-unsigned' allows installation of unsigned packages. + ++++ +**** The user option `package-unsigned-archives' lists archives where +Emacs will not try to check signatures. + +++ *** New option `package-pinned-packages'. This is useful if you have multiple archives enabled, with more than one offering a package that you want. -FIXME -*** New options `package-check-signature' and `package-unsigned-archives'. - +++ *** In the `list-packages' buffer, you can use `f' (`package-menu-filter') to filter the list of packages by a keyword. diff --git a/lisp/ChangeLog b/lisp/ChangeLog index 6bb2147595d..1280e39ec27 100644 --- a/lisp/ChangeLog +++ b/lisp/ChangeLog @@ -1,3 +1,8 @@ +2014-06-05 Glenn Morris + + * emacs-lisp/package.el (package-check-signature) + (package-unsigned-archives): Doc fixes. + 2014-06-03 Martin Rudalics * window.el (display-buffer-use-some-window): Don't make window diff --git a/lisp/emacs-lisp/package.el b/lisp/emacs-lisp/package.el index 028c57da19c..57a5429f0a1 100644 --- a/lisp/emacs-lisp/package.el +++ b/lisp/emacs-lisp/package.el @@ -292,7 +292,12 @@ contrast, `package-user-dir' contains packages for personal use." :version "24.1") (defcustom package-check-signature 'allow-unsigned - "Whether to check package signatures when installing." + "Non-nil means to check package signatures when installing. +The value `allow-unsigned' means to still install a package even if +it is unsigned. + +This also applies to the \"archive-contents\" file that lists the +contents of the archive." :type '(choice (const nil :tag "Never") (const allow-unsigned :tag "Allow unsigned") (const t :tag "Check always")) @@ -301,7 +306,7 @@ contrast, `package-user-dir' contains packages for personal use." :version "24.4") (defcustom package-unsigned-archives nil - "A list of archives which do not use package signature." + "List of archives where we do not check for package signatures." :type '(repeat (string :tag "Archive name")) :risky t :group 'package