[Emacs-diffs] emacs-24 r117206: Some documentation for signing of packages

[Glenn Morris]

------------------------------------------------------------
revno: 117206
revision-id: address@hidden
parent: address@hidden
committer: Glenn Morris <address@hidden>
branch nick: emacs-24
timestamp: Wed 2014-06-04 23:15:44 -0700
message:
  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.
modified:
  doc/emacs/ChangeLog            changelog-20091113204419-o5vbwnq5f7feedwu-6227
  doc/emacs/package.texi         package.texi-20110825190024-lpvyu1zke977csqu-1
  doc/lispref/ChangeLog          changelog-20091113204419-o5vbwnq5f7feedwu-6155
  doc/lispref/package.texi       package.texi-20100825202226-iq7hwjiir2jpyd4g-1
  etc/NEWS                       news-20100311060928-aoit31wvzf25yr1z-1
  lisp/ChangeLog                 changelog-20091113204419-o5vbwnq5f7feedwu-1432
  lisp/emacs-lisp/package.el     package.el-20100617020707-ybavz666awsxwin6-2

=== modified file 'doc/emacs/ChangeLog'
--- a/doc/emacs/ChangeLog       2014-06-03 04:45:56 +0000
+++ b/doc/emacs/ChangeLog       2014-06-05 06:15:44 +0000
@@ -1,3 +1,8 @@
+2014-06-05  Glenn Morris  <address@hidden>
+
+       * package.texi (Package Menu, Package Installation):
+       Mention signed packages.
+
 2014-06-03  Glenn Morris  <address@hidden>
 
        * package.texi (Package Installation): Mention package-pinned-packages.

=== modified file 'doc/emacs/package.texi'
--- a/doc/emacs/package.texi    2014-06-03 04:45:56 +0000
+++ b/doc/emacs/package.texi    2014-06-05 06:15:44 +0000
@@ -59,8 +59,9 @@
 
 @item
 The package's status---normally one of @samp{available} (can be
-downloaded from the package archive), @samp{installed}, or
address@hidden (included in Emacs by default).
+downloaded from the package archive), @samp{installed},
address@hidden (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 @@
 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!
 
address@hidden Signing}
address@hidden package security
address@hidden 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}.
address@hidden Uncomment this if it becomes true.
address@hidden
+The public key for the GNU package archive is distributed with Emacs,
+in the @file{etc/package-keyring.gpg}.  Emacs uses it automatically.
address@hidden ignore
+
address@hidden package-check-signature
address@hidden package-unsigned-archives
+  If the user option @code{package-check-signature} is address@hidden,
+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,
address@hidden,, Top, gnupg, The GNU Privacy Guard Manual}.
+Emacs comes with an interface to GNU Privacy Guard,
address@hidden,, 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

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2014-05-27 01:53:45 +0000
+++ b/doc/lispref/ChangeLog     2014-06-05 06:15:44 +0000
@@ -1,3 +1,7 @@
+2014-06-05  Glenn Morris  <address@hidden>
+
+       * package.texi (Package Archives): Mention signing packages.
+
 2014-05-27  Glenn Morris  <address@hidden>
 
        * text.texi (Buffer Contents):

=== modified file 'doc/lispref/package.texi'
--- a/doc/lispref/package.texi  2014-02-12 01:43:35 +0000
+++ b/doc/lispref/package.texi  2014-06-05 06:15:44 +0000
@@ -342,3 +342,38 @@
 @noindent
 After you create an archive, remember that it is not accessible in the
 Package Menu interface unless it is in @code{package-archives}.
+
address@hidden package archive security
address@hidden 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:
+
address@hidden FIXME EasyPG / package-x way to do this.
address@hidden
+gpg -ba -o @var{file}.sig @var{file}
address@hidden example
+
address@hidden
+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,
address@hidden,, GnuPG, gnupg, The GNU Privacy Guard Manual}.  Emacs comes
+with an interface to GNU Privacy Guard, @pxref{Top,, EasyPG, epa,
+Emacs EasyPG Assistant Manual}.

=== modified file 'etc/NEWS'
--- a/etc/NEWS  2014-06-03 04:45:56 +0000
+++ b/etc/NEWS  2014-06-05 06:15:44 +0000
@@ -817,12 +817,23 @@
 ** 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.

=== modified file 'lisp/ChangeLog'
--- a/lisp/ChangeLog    2014-06-03 12:38:17 +0000
+++ b/lisp/ChangeLog    2014-06-05 06:15:44 +0000
@@ -1,3 +1,8 @@
+2014-06-05  Glenn Morris  <address@hidden>
+
+       * emacs-lisp/package.el (package-check-signature)
+       (package-unsigned-archives): Doc fixes.
+
 2014-06-03  Martin Rudalics  <address@hidden>
 
        * window.el (display-buffer-use-some-window): Don't make window

=== modified file 'lisp/emacs-lisp/package.el'
--- a/lisp/emacs-lisp/package.el        2014-06-03 04:41:20 +0000
+++ b/lisp/emacs-lisp/package.el        2014-06-05 06:15:44 +0000
@@ -292,7 +292,12 @@
   :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 @@
   :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