[Patch] For the Manual: using org-crypt

[Patch] For the Manual: using org-crypt

[Ian Barton]

Apologies in advance this isn't a "real" patch:) This is the entry for 
the manual describing org-crypt.el. I was going to put it in 
http://orgmode.org/manual/Miscellaneous.html#Miscellaneous However, 
since I am not a Tex user, I rapidly came to the conclusion that if I 
tried to patch org.texi, I would probably do more harm than good.

I have also pushed a short Tutorial to Worg about using encryption with 
org files.

Ian.


* org-crypt.el
org-crypt will encrypt the text of an entry, but not the
headline, or properties. Org-crypt uses the Emacs EasyPG library to
ecnrypt and decrypt files. EasyPG is part of recent Emacs releases (at
least Emacs 23). It is available as a separate package for earlier
versions of Emacs. If your version of Emacs already has EasyPG do not
install the package manager's version. Doing so will lead to
unpredictable results.

To use org-crypt you will need to have something like the following
in your .emacs:

#+BEGIN_SRC emacs-lisp
(require 'org-crypt)
(org-crypt-use-before-save-magic)
(setq org-tags-exclude-from-inheritance (quote ("crypt")))
;; GPG key to use for encryption
;; Either the Key ID or set to nil to use symmetric encryption.
(setq org-crypt-key nil)
#+END_SRC

If you want to use Public Key Encryption, you will need to generate a
suitable pubic/private key pair using gnupg.

Now any text below a headline that has a :crypt: tag will be
automatically be encrypted when the file is saved. If you want to use
a different tag just customize the "org-crypt-tag-matcher" setting.

Preventing tag inheritance stops you having encrypted text inside
encrypted text.

To decrypt the text just call "M-x org-decrypt-entry" and the
encrypted text where the point is will be replaced with the plain
text. If you use this feature a lot, you will probably want to bind
"M-x org-decrypt-entry" to a key.

Re: [Patch] For the Manual: using org-crypt

[Julien Danjou]

[-- Attachment #1: Type: text/plain, Size: 733 bytes --]

On Fri, Mar 18 2011, Ian Barton wrote:

> Apologies in advance this isn't a "real" patch:) This is the entry for the
> manual describing org-crypt.el. I was going to put it in
> http://orgmode.org/manual/Miscellaneous.html#Miscellaneous However, since I
> am not a Tex user, I rapidly came to the conclusion that if I tried to patch
> org.texi, I would probably do more harm than good.
>
> I have also pushed a short Tutorial to Worg about using encryption with org
> files.

It seems nobody answered you: I think that if you do not try to provide
this in form of a patch it will be forgotten.
Or could somebody help integrating this into a patch to org.texi maybe?

-- 
Julien Danjou
❱ http://julien.danjou.info

[-- Attachment #2: Type: application/pgp-signature, Size: 835 bytes --]

Re: [Patch] For the Manual: using org-crypt

[Christian Egli]

Julien Danjou <julien@danjou.info> writes:

> On Fri, Mar 18 2011, Ian Barton wrote:
>
>> Apologies in advance this isn't a "real" patch:) This is the entry for the
>> manual describing org-crypt.el. I was going to put it in
>> http://orgmode.org/manual/Miscellaneous.html#Miscellaneous However, since I
>> am not a Tex user, I rapidly came to the conclusion that if I tried to patch
>> org.texi, I would probably do more harm than good.
>>
>> I have also pushed a short Tutorial to Worg about using encryption with org
>> files.
>
> It seems nobody answered you: I think that if you do not try to provide
> this in form of a patch it will be forgotten.
> Or could somebody help integrating this into a patch to org.texi maybe?

The attached patch should get you started. It is just a simple org ->
texi translation, I don't know if the text conforms to the guidelines
put forth in the Documentation_Standards[1]. Please make sure it
conforms to these and then resubmit the patch. If you need any more help
please let me know.

Thanks
Christian

Footnotes: 
[1]  http://orgmode.org/w/?p=org-mode.git;a=blob;f=doc/Documentation_Standards.org;hb=HEAD

diff --git a/doc/org.texi b/doc/org.texi
index 6fc848b..fa0676f 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -675,8 +675,6 @@ Specific header arguments
                                 files during tangling
 * comments::                    Toggle insertion of comments in tangled
                                 code files
-* padline::                     Control insertion of padding lines in tangled
-                                code files
 * no-expand::                   Turn off variable assignment and noweb
                                 expansion during tangling
 * session::                     Preserve the state of code evaluation
@@ -701,6 +699,7 @@ Miscellaneous
 * Clean view::                  Getting rid of leading stars in the outline
 * TTY keys::                    Using Org on a tty
 * Interaction::                 Other Emacs packages
+* org-crypt.el::                
 
 Interaction with other packages
 
@@ -11823,8 +11822,6 @@ The following header arguments are defined:
                                 files during tangling
 * comments::                    Toggle insertion of comments in tangled
                                 code files
-* padline::                     Control insertion of padding lines in tangled
-                                code files
 * no-expand::                   Turn off variable assignment and noweb
                                 expansion during tangling
 * session::                     Preserve the state of code evaluation
@@ -12284,7 +12281,7 @@ The @code{:mkdirp} header argument can be used to create parent directories
 of tangled files when missing.  This can be set to @code{yes} to enable
 directory creation or to @code{no} to inhibit directory creation.
 
-@node comments, padline, mkdirp, Specific header arguments
+@node comments, no-expand, mkdirp, Specific header arguments
 @subsubsection @code{:comments}
 By default code blocks are tangled to source-code files without any insertion
 of comments beyond those which may already exist in the body of the code
@@ -12324,7 +12321,7 @@ Insert newlines before and after each code block body in tangled code files.
 Do not insert any newline padding in tangled output.
 @end itemize
 
-@node no-expand, session, padline, Specific header arguments
+@node no-expand, session, comments, Specific header arguments
 @subsubsection @code{:no-expand}
 
 By default, code blocks are expanded with @code{org-babel-expand-src-block}
@@ -12830,6 +12827,7 @@ emacs -Q --batch -l $ORGINSTALL \
 * Clean view::                  Getting rid of leading stars in the outline
 * TTY keys::                    Using Org on a tty
 * Interaction::                 Other Emacs packages
+* org-crypt.el::                
 @end menu
 
 
@@ -13506,7 +13504,7 @@ tty you would rather use @kbd{C-c .} to re-insert the timestamp.
 @end multitable
 
 
-@node Interaction,  , TTY keys, Miscellaneous
+@node Interaction, org-crypt.el, TTY keys, Miscellaneous
 @section Interaction with other packages
 @cindex packages, interaction with other
 Org lives in the world of GNU Emacs and interacts in various ways
@@ -13715,6 +13713,46 @@ another key for this command, or override the key in
 
 @end table
 
+@node org-crypt.el,  , Interaction, Miscellaneous
+@section org-crypt.el
+@cindex @file{org-crypt.el}
+@cindex @code{org-decrypt-entry}
+@cindex Encryption
+@cindex EasyPG
+
+org-crypt will encrypt the text of an entry, but not the headline, or
+properties. Org-crypt uses the Emacs EasyPG library to encrypt and decrypt
+files. EasyPG is part of recent Emacs releases (at least Emacs 23). It is
+available as a separate package for earlier versions of Emacs. If your
+version of Emacs already has EasyPG do not install the package manager's
+version. Doing so will lead to unpredictable results.
+
+To use org-crypt you will need to have something like the following in your
+@file{.emacs}:
+
+@example
+(require 'org-crypt)
+(org-crypt-use-before-save-magic)
+(setq org-tags-exclude-from-inheritance (quote ("crypt")))
+;; GPG key to use for encryption
+;; Either the Key ID or set to nil to use symmetric encryption.
+(setq org-crypt-key nil)
+@end example
+
+If you want to use Public Key Encryption, you will need to generate a
+suitable pubic/private key pair using @command{gnupg}.
+
+Now any text below a headline that has a @samp{:crypt:} tag will be
+automatically be encrypted when the file is saved. If you want to use a
+different tag just customize the @code{org-crypt-tag-matcher} setting.
+
+Preventing tag inheritance stops you having encrypted text inside encrypted
+text.
+
+To decrypt the text just call @kbd{M-x org-decrypt-entry} and the encrypted
+text where the point is will be replaced with the plain text. If you use this
+feature a lot, you will probably want to bind @kbd{M-x org-decrypt-entry} to
+a key.
 
 @node Hacking, MobileOrg, Miscellaneous, Top
 @appendix Hacking


-- 
Christian Egli
Swiss Library for the Blind, Visually Impaired and Print Disabled
Grubenstrasse 12, CH-8045 Zürich, Switzerland

Re: [Patch] For the Manual: using org-crypt

[Jambunathan K]

Thanks Christian. Some minor improvements. The intention is not to
nitpick but to build on top of what you have provided and help the
reviewer.

> +org-crypt will encrypt the text of an entry, but not the headline, or
> +properties. Org-crypt uses the Emacs EasyPG library to encrypt and decrypt
> +files. 

--8<---------------cut here---------------start------------->8---
> EasyPG is part of recent Emacs releases (at least Emacs 23). It is
> +available as a separate package for earlier versions of Emacs. If your
> +version of Emacs already has EasyPG do not install the package manager's
> +version. Doing so will lead to unpredictable results.
--8<---------------cut here---------------end--------------->8---

This information could be captured elsewhere and be left out of the
manual. (This parts reads like a tutorial entry)

> +
> +To use org-crypt you will need to have something like the following in your
> +@file{.emacs}:

`Recommendation', `suggestion' would be a better word. Word `something'
is ambiguous.

--8<---------------cut here---------------start------------->8---
> +If you want to use Public Key Encryption, you will need to generate a
> +suitable pubic/private key pair using @command{gnupg}.
--8<---------------cut here---------------end--------------->8---

This portion better be left out of the Org manual.

--8<---------------cut here---------------start------------->8---
> +Now any text below a headline that has a @samp{:crypt:} tag will be
> +automatically be encrypted when the file is saved. 
--8<---------------cut here---------------end--------------->8---

Above portion qualifies to be part of introductory text.


--8<---------------cut here---------------start------------->8---
> +Preventing tag inheritance stops you having encrypted text inside encrypted
> +text.
--8<---------------cut here---------------end--------------->8---

Above segment seems a bit out of context ... May be some supplementary
information has to go with it or is it just an implementation artefact
that the user need not bother about. Or is this part of the user
configuration?

> +To decrypt the text just call @kbd{M-x org-decrypt-entry} and the encrypted
> +text where the point is will be replaced with the plain text. 

The first part is complete in itself. The latter can be removed.

--8<---------------cut here---------------start------------->8---
> If you use this +feature a lot, you will probably want to bind
> @kbd{M-x org-decrypt-entry} to +a key.
--8<---------------cut here---------------end--------------->8---

Shouldn't part of the manual?

Jambunathan K.


-- 

Re: [Patch] For the Manual: using org-crypt

[Carsten Dominik]

Hi,

Is anyone working on making this a complete patch?

Thanks

- Carsten

On Mar 23, 2011, at 5:03 PM, Jambunathan K wrote:

> 
> Thanks Christian. Some minor improvements. The intention is not to
> nitpick but to build on top of what you have provided and help the
> reviewer.
> 
>> +org-crypt will encrypt the text of an entry, but not the headline, or
>> +properties. Org-crypt uses the Emacs EasyPG library to encrypt and decrypt
>> +files. 
> 
> --8<---------------cut here---------------start------------->8---
>> EasyPG is part of recent Emacs releases (at least Emacs 23). It is
>> +available as a separate package for earlier versions of Emacs. If your
>> +version of Emacs already has EasyPG do not install the package manager's
>> +version. Doing so will lead to unpredictable results.
> --8<---------------cut here---------------end--------------->8---
> 
> This information could be captured elsewhere and be left out of the
> manual. (This parts reads like a tutorial entry)
> 
>> +
>> +To use org-crypt you will need to have something like the following in your
>> +@file{.emacs}:
> 
> `Recommendation', `suggestion' would be a better word. Word `something'
> is ambiguous.
> 
> --8<---------------cut here---------------start------------->8---
>> +If you want to use Public Key Encryption, you will need to generate a
>> +suitable pubic/private key pair using @command{gnupg}.
> --8<---------------cut here---------------end--------------->8---
> 
> This portion better be left out of the Org manual.
> 
> --8<---------------cut here---------------start------------->8---
>> +Now any text below a headline that has a @samp{:crypt:} tag will be
>> +automatically be encrypted when the file is saved. 
> --8<---------------cut here---------------end--------------->8---
> 
> Above portion qualifies to be part of introductory text.
> 
> 
> --8<---------------cut here---------------start------------->8---
>> +Preventing tag inheritance stops you having encrypted text inside encrypted
>> +text.
> --8<---------------cut here---------------end--------------->8---
> 
> Above segment seems a bit out of context ... May be some supplementary
> information has to go with it or is it just an implementation artefact
> that the user need not bother about. Or is this part of the user
> configuration?
> 
>> +To decrypt the text just call @kbd{M-x org-decrypt-entry} and the encrypted
>> +text where the point is will be replaced with the plain text. 
> 
> The first part is complete in itself. The latter can be removed.
> 
> --8<---------------cut here---------------start------------->8---
>> If you use this +feature a lot, you will probably want to bind
>> @kbd{M-x org-decrypt-entry} to +a key.
> --8<---------------cut here---------------end--------------->8---
> 
> Shouldn't part of the manual?
> 
> Jambunathan K.
> 
> 
> -- 
> 

- Carsten

Re: [Patch] For the Manual: using org-crypt

[Christian Egli]

Carsten Dominik <carsten.dominik@gmail.com> writes:

> Is anyone working on making this a complete patch?

Sorry, no.

-- 
Christian Egli
Swiss Library for the Blind, Visually Impaired and Print Disabled
Grubenstrasse 12, CH-8045 Zürich, Switzerland

Re: [Patch] For the Manual: using org-crypt

[Ian Barton]

On 27/05/11 10:15, Christian Egli wrote:
> Carsten Dominik<carsten.dominik@gmail.com>  writes:
>
>> Is anyone working on making this a complete patch?
>
> Sorry, no.
>
I'll have a go and try to make a proper patch against the current 
manual. Don't blame me if the manual breaks:)

Ian.

Re: [Patch] For the Manual: using org-crypt

[Ian Barton]

[-- Attachment #1: Type: text/plain, Size: 784 bytes --]

Here is the patch. Thanks to Christian for his help. I have edited the 
text to take into account Jambunathans comments.

Ian.

On 27/05/11 11:47, Carsten Dominik wrote:
> Actually, please just make the section in texi formatting, I or someone else will link it in into the manual structure.  This is difficult to get right with a patch.  Please take Jambunathans comments int account.
>
> Thanks
>
> - Carsten
>
> On May 27, 2011, at 12:38 PM, Ian Barton wrote:
>
>> On 27/05/11 10:15, Christian Egli wrote:
>>> Carsten Dominik<carsten.dominik@gmail.com>   writes:
>>>
>>>> Is anyone working on making this a complete patch?
>>> Sorry, no.
>>>
>> I'll have a go and try to make a proper patch against the current manual. Don't blame me if the manual breaks:)
>>
>> Ian.
>>
>>
>
>
>


[-- Attachment #2: org-crypt.patch --]
[-- Type: text/x-diff, Size: 2229 bytes --]

From 1861079c6db46c9be36dbbc30ef5d738d5d14193 Mon Sep 17 00:00:00 2001
From: Ian Barton <ian@wilkesley.net>
Date: Mon, 30 May 2011 18:48:33 +0100
Subject: [PATCH] Add section about org-crypt.el.

---
 doc/org.texi |   30 +++++++++++++++++++++++++++++-
 1 files changed, 29 insertions(+), 1 deletions(-)

diff --git a/doc/org.texi b/doc/org.texi
index e13af4b..91cd199 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -12773,6 +12773,7 @@ emacs -Q --batch -l $ORGINSTALL \
 * Clean view::                  Getting rid of leading stars in the outline
 * TTY keys::                    Using Org on a tty
 * Interaction::                 Other Emacs packages
+* org-crypt.el::                Encrypting Org files
 @end menu
 
 
@@ -13449,7 +13450,7 @@ tty you would rather use @kbd{C-c .} to re-insert the timestamp.
 @end multitable
 
 
-@node Interaction,  , TTY keys, Miscellaneous
+@node Interaction, org-crypt.el, TTY keys, Miscellaneous
 @section Interaction with other packages
 @cindex packages, interaction with other
 Org lives in the world of GNU Emacs and interacts in various ways
@@ -13658,6 +13659,33 @@ another key for this command, or override the key in
 
 @end table
 
++@node org-crypt.el,  , Interaction, Miscellaneous
++@section org-crypt.el
++@cindex @file{org-crypt.el}
++@cindex @code{org-decrypt-entry}
+
+Org-crypt will encrypt the text of an entry, but not the headline, or
+properties. Org-crypt uses the Emacs EasyPG library to encrypt and decrypt
+files.
+
+Any text below a headline that has a @samp{:crypt:} tag will be
+automatically be encrypted when the file is saved. If you want to use a
+different tag just customize the @code{org-crypt-tag-matcher} setting.
+
+To use org-crypt it is suggested that you have the following in your
+@file{.emacs}:
+
+@example
+(require 'org-crypt)
+(org-crypt-use-before-save-magic)
+(setq org-tags-exclude-from-inheritance (quote ("crypt")))
+;; GPG key to use for encryption
+;; Either the Key ID or set to nil to use symmetric encryption.
+(setq org-crypt-key nil)
+@end example
+
+Excluding the crypt tag from inheritance prevents already encrypted text
+being encrypted again.
 
 @node Hacking, MobileOrg, Miscellaneous, Top
 @appendix Hacking
-- 
1.7.4.1

Re: [Patch] For the Manual: using org-crypt

[Carsten Dominik]

Applied, thanks.

- Carsten

On May 30, 2011, at 8:23 PM, Ian Barton wrote:

> Here is the patch. Thanks to Christian for his help. I have edited the text to take into account Jambunathans comments.
> 
> Ian.
> 
> On 27/05/11 11:47, Carsten Dominik wrote:
>> Actually, please just make the section in texi formatting, I or someone else will link it in into the manual structure.  This is difficult to get right with a patch.  Please take Jambunathans comments int account.
>> 
>> Thanks
>> 
>> - Carsten
>> 
>> On May 27, 2011, at 12:38 PM, Ian Barton wrote:
>> 
>>> On 27/05/11 10:15, Christian Egli wrote:
>>>> Carsten Dominik<carsten.dominik@gmail.com>   writes:
>>>> 
>>>>> Is anyone working on making this a complete patch?
>>>> Sorry, no.
>>>> 
>>> I'll have a go and try to make a proper patch against the current manual. Don't blame me if the manual breaks:)
>>> 
>>> Ian.
>>> 
>>> 
>> 
>> 
>> 
> 
> <org-crypt.patch>

- Carsten