branch: elpa/age
commit 148d0ade9024b204113a3464e61db1599d5e57c4
Author: Bas Alberts <[email protected]>
Commit: Bas Alberts <[email protected]>
cleanup for MELPA release
---
README.org | 141 ++++++++++++++++++++++++++-----------------------------------
1 file changed, 61 insertions(+), 80 deletions(-)
diff --git a/README.org b/README.org
index 2c2a4f7a68f..dde19b4c8e0 100644
--- a/README.org
+++ b/README.org
@@ -1,60 +1,44 @@
+[[https://melpa.org/#/age][file:https://melpa.org/packages/age-badge.svg]]
+
* age.el: age encryption support for Emacs
#+html:<p align="center"><img src="img/emacs-age.png"/></p>
-age.el is intended to provide transparent age[1] based file encryption
-and decryption in Emacs. As such age.el does not support all
-age CLI based use cases. Rather age.el assumes you have configured
-a default identity and a default recipient, e.g. based off your
-ssh private key and ssh public key in ~.ssh/id_rsa[.pub]~, which
-is the default setting.
-
-The main use case is for folks who like to e.g. encrypt their Org
-notes and things of that nature. Since age.el provides a direct
-port of EPG/EPA functionality it can support all roles that .gpg
-files can support in Emacs, e.g. ~.authinfo.age~ should work fine as well.
+age.el provides transparent [[https://github.com/FiloSottile/age][Age]] file
encryption and decryption in Emacs. It is
+based on the Emacs [[http://epg.osdn.jp/][EasyPG]] code and offers similar
Emacs file handling
+for [[https://github.com/C2SP/C2SP/blob/main/age.md][Age encrypted files]].
-[1]: https://github.com/FiloSottile/age
+Using age.el you can, for example, maintain ~.org.age~ encrypted Org files,
+provide Age encrypted authentication information out of ~.authinfo.age~, and
+open/edit/save Age encrypted files via TRAMP.
* Usage
-Put age.el somewhere in your load-path and:
-
-#+begin_src emacs-lisp
-(require 'age)
-(age-file-enable)
-#+end_src
-
-If you prefer to use ~use-package~, a quelpa configuration looks like:
+Age is available on [[https://melpa.org/#/age][melpa]] and you can install it
from there:
#+begin_src emacs-lisp
(use-package age
- :quelpa (age :fetcher github :repo "anticomputer/age.el")
:ensure t
:demand
:config
(age-file-enable))
#+end_src
-You can now open, edit, and save age encryted files from Emacs as
-long as they contain the .age extension.
-
-age.el also supports creating new .age files through find-file and
-they will be encrypted to your default recipient on first save.
+Alternatively, put ~age.el~ in your ~load-path~ and:
-Example:
-
-#+begin_src
-M-x find-file RET /tmp/test.age RET
-M-x save-buffer RET
+#+begin_src emacs-lisp
+(require 'age)
+(age-file-enable)
#+end_src
-Will create an age encrypted file named test.age in the ~/tmp~
-directory. It will be encrypted to a recipient of ~.ssh/id_rsa.pub~
-by default and decrypted with an identity of ~.ssh/id_rsa~ by default.
+You can now open, edit, and save Age encryted files from Emacs as
+long as they end with the ~.age~ file extension. You can also ~find-file~
+new Age files and they will be encrypted to the ~age-default-recipient~ on
+first save.
-You can customize the default key values via ~age-default-recipient~ and
-~age-default-identity~, respectively.
+Identities (private keys) and recipients (public keys) are maintained via the
+customizable ~age-default-identity~ and ~age-default-recipient~ variables. By
+default they are set to =~/.ssh/id_rsa= and =~/.ssh/id_rsa.pub= respectively.
age.el tries to remain composable with the core philosophy of age itself
and as such does not try to provide a kitchen sink worth of features.
@@ -201,36 +185,30 @@ interacting with my encrypted data.
* Known issues
-** Lack of pinentry support in age
+** Lack of pinentry support in age reference implementation
-The age reference client does not support pinentry by design. Users are
-encouraged to use identity (private) keys and recipient (public) keys, and
-manage those secrets outside of Emacs accordingly. As such age.el does not
-currently support passphrase based age Encryption/Decryption as we do not have
-a tty available to provide a passphrase to age (I think).
+The [[https://github.com/FiloSottile/age][age reference implementation]] does
not support pinentry by design. Users
+are encouraged to use identity (private) keys and recipient (public) keys, and
+manage those secrets accordingly.
*** Workaround: pinentry support through rage
-You can work around this by using [[https://github.com/str4d/rage][rage]]
instead of age, which is a Rust
-based implementation of the
[[https://github.com/C2SP/C2SP/blob/main/age.md][Age spec]] and which does
support pinentry by
-default and age.el will work with rage as well. An example rage config may
-look like:
+You can work around this by using [[https://github.com/str4d/rage][rage]]
instead of age, which is a Rust based
+implementation of the [[https://github.com/C2SP/C2SP/blob/main/age.md][Age
spec]] which does support pinentry by default. age.el
+will work with rage as well. An example rage config may look like:
#+begin_src emacs-lisp
(use-package age
- :quelpa (age :fetcher github :repo "anticomputer/age.el")
:ensure t
:demand
:custom
;; use rage for pinentry, note this _has_ to go through customize
(age-program "rage")
- (age-default-identity "~/.ssh/id_rsa")
- (age-default-recipient "~/.ssh/id_rsa.pub")
:config
(age-file-enable))
#+end_src
-You will now be able to use passphrase protected ssh keys as well:
+You will now be able to use passphrase protected Age identities and files.
#+html:<p align="center"><img src="img/emacs-rage.png"/></p>
@@ -264,10 +242,14 @@ prompt you for passphrases in the minibuffer.
#+html:<p align="center"><img src="img/rage-pinentry-emacs.png"/></p>
+Note: this will attempt to use Emacs as your pinentry for all commandline use
+of the rage client as well.
+
** Direct use of passphrase encrypted age files
-This requires you to use rage, or another age-spec compliant client that
-supports pinentry.
+This again requires you to use rage, or another age-spec compliant client that
+supports pinentry and follows the rage or age argument and error reporting
+conventions.
By default, age.el will be able to open and save passphrase encrypted age
files. It will detect the scrypt stanza in the age file and set the age.el
@@ -297,6 +279,24 @@ provides ~.org.age~ discoverability support for org-roam,
so if you update to
the latest release from e.g. MELPA or the main branch, org-roam will function
with .age encrypted org files.
+** pass (https://passwordstore.org) and its Emacs packages depend on gpg
+
+Please see https://github.com/anticomputer/passage.el for an age based drop-in
+replacement for pass and its associated Emacs packages.
+
+I use the following configuration that also rebinds the =pass= function to
+=passage= for convenience:
+
+#+begin_src emacs-lisp
+(use-package passage
+ :quelpa (passage :fetcher github :repo "anticomputer/passage.el")
+ :ensure t
+ :demand
+ :config
+ ;; rebind function value for pass to passage
+ (fset #'pass (lambda () (interactive) (passage))))
+#+end_src
+
* Disclaimer
This is experimental software and subject to heavy feature iterations.
@@ -304,17 +304,17 @@ This is experimental software and subject to heavy
feature iterations.
* Why age over gpg?
This is, apparently, a heated topic and folks more qualified than me have
-commented on this in great detail over many years. The following blog posts I
-think provide a good summary of the state of the debate regarding the OpenPGP
+commented on this in great detail over many years. The following blog post I
+think provides a good summary of the state of the debate regarding the OpenPGP
specification:
-- [[https://www.openbsd.org/papers/bsdcan-signify.html][signify: Securing
OpenBSD From Us To You]]
- [[https://latacora.micro.blog/2019/07/16/the-pgp-problem.html][The PGP
Problem]]
-Thanks to reddit's ~/u/a-huge-waste-of-time~ for linking those references.
+Thanks to reddit's ~/u/a-huge-waste-of-time~ for linking that reference.
In true megalomaniac fashion I'll
[[https://www.reddit.com/r/emacs/comments/zyd7bh/comment/j25ag7s/?utm_source=share&utm_medium=web2x&context=3][quote
myself]] out of the age.el ~/r/emacs~
-announcement thread when asked why I was looking to rid myself of gpg:
+announcement thread when asked why I was looking to limit my use of gpg for my
+local file encryption needs inside Emacs.
#+begin_quote
I wanted to reduce the amount of key management in my life to the bare
@@ -352,28 +352,9 @@ Having said that, age.el is not intended to encourage you
to abandon
gpg. However, if you've been looking for a lighter weight alternative for
Emacs encryption, it might be a good fit for you.
-* Copyright
-
-This code was ported from the existing EPA and EPG Emacs code and as such
-their original copyright applies:
-
-Copyright (C) 1999-2000, 2002-2022 Free Software Foundation, Inc.
-
-Author: Daiki Ueno <[email protected]>
-Keywords: emacs
-Version: 1.0.0
-
-This file is part of GNU Emacs.
-
-GNU Emacs is free software: you can redistribute it and/or modify
-it under the terms of the GNU General Public License as published by
-the Free Software Foundation, either version 3 of the License, or
-(at your option) any later version.
+* License
-GNU Emacs is distributed in the hope that it will be useful,
-but WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
-GNU General Public License for more details.
+GPLv3
-You should have received a copy of the GNU General Public License
-along with GNU Emacs. If not, see <https://www.gnu.org/licenses/>.
+This code was ported from the EasyPG Emacs code and the original author is
+Daiki Ueno <[email protected]> who has assigned their copyright to the FSF.
![https://melpa.org/#/age][file:https://melpa.org/packages/age-badge.svg](https://melpa.org/#/age][file:https://melpa.org/packages/age-badge.svg){kind=link}