mirror of
https://git.savannah.gnu.org/git/emacs.git
synced 2024-12-02 08:22:22 +00:00
400 lines
13 KiB
Plaintext
400 lines
13 KiB
Plaintext
\input texinfo @c -*-texinfo-*-
|
|
|
|
@setfilename ../info/pgg
|
|
|
|
@set VERSION 0.1
|
|
|
|
|
|
@copying
|
|
This file describes the PGG.
|
|
|
|
Copyright (C) 2003, 2004, 2005 Free Software Foundation, Inc.
|
|
Copyright (C) 2001 Daiki Ueno.
|
|
|
|
@quotation
|
|
Permission is granted to copy, distribute and/or modify this document
|
|
under the terms of the GNU Free Documentation License, Version 1.2 or
|
|
any later version published by the Free Software Foundation; with no
|
|
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
|
|
Texts. A copy of the license is included in the section entitled ``GNU
|
|
Free Documentation License''.
|
|
@end quotation
|
|
@end copying
|
|
|
|
@dircategory Emacs
|
|
@direntry
|
|
* PGG: (pgg). Emacs interface to various PGP implementations.
|
|
@end direntry
|
|
|
|
@settitle PGG @value{VERSION}
|
|
|
|
|
|
@titlepage
|
|
@title PGG
|
|
|
|
@author by Daiki Ueno
|
|
@page
|
|
|
|
@vskip 0pt plus 1filll
|
|
@insertcopying
|
|
@end titlepage
|
|
@page
|
|
|
|
@node Top
|
|
@top PGG
|
|
This manual describes PGG. PGG is an interface library between Emacs
|
|
and various tools for secure communication. PGG also provides a simple
|
|
user interface to encrypt, decrypt, sign, and verify MIME messages.
|
|
|
|
@menu
|
|
* Overview:: What PGG is.
|
|
* Prerequisites:: Complicated stuff you may have to do.
|
|
* How to use:: Getting started quickly.
|
|
* Architecture::
|
|
* Parsing OpenPGP packets::
|
|
* Function Index::
|
|
* Variable Index::
|
|
@end menu
|
|
|
|
@node Overview
|
|
@chapter Overview
|
|
|
|
PGG is an interface library between Emacs and various tools for secure
|
|
communication. Even though Mailcrypt has similar feature, it does not
|
|
deal with detached PGP messages, normally used in PGP/MIME
|
|
infrastructure. This was the main reason why I wrote the new library.
|
|
|
|
PGP/MIME is an application of MIME Object Security Services (RFC1848).
|
|
The standard is documented in RFC2015.
|
|
|
|
@node Prerequisites
|
|
@chapter Prerequisites
|
|
|
|
PGG requires at least one implementation of privacy guard system.
|
|
This document assumes that you have already obtained and installed them
|
|
and that you are familiar with its basic functions.
|
|
|
|
By default, PGG uses GnuPG, but Pretty Good Privacy version 2 or version
|
|
5 are also supported. If you are new to such a system, I recommend that
|
|
you should look over the GNU Privacy Handbook (GPH) which is available
|
|
at @uref{http://www.gnupg.org/gph/}.
|
|
|
|
@node How to use
|
|
@chapter How to use
|
|
|
|
The toplevel interface of this library is quite simple, and only
|
|
intended to use with public-key cryptographic operation.
|
|
|
|
To use PGG, evaluate following expression at the beginning of your
|
|
application program.
|
|
|
|
@lisp
|
|
(require 'pgg)
|
|
@end lisp
|
|
|
|
If you want to check existence of pgg.el at runtime, instead you can
|
|
list autoload setting for desired functions as follows.
|
|
|
|
@lisp
|
|
(autoload 'pgg-encrypt-region "pgg"
|
|
"Encrypt the current region." t)
|
|
(autoload 'pgg-decrypt-region "pgg"
|
|
"Decrypt the current region." t)
|
|
(autoload 'pgg-sign-region "pgg"
|
|
"Sign the current region." t)
|
|
(autoload 'pgg-verify-region "pgg"
|
|
"Verify the current region." t)
|
|
(autoload 'pgg-insert-key "pgg"
|
|
"Insert the ASCII armored public key." t)
|
|
(autoload 'pgg-snarf-keys-region "pgg"
|
|
"Import public keys in the current region." t)
|
|
@end lisp
|
|
|
|
@menu
|
|
* User Commands::
|
|
* Selecting an implementation::
|
|
* Caching passphrase::
|
|
* Default user identity::
|
|
@end menu
|
|
|
|
@node User Commands
|
|
@section User Commands
|
|
|
|
At this time you can use some cryptographic commands. The behavior of
|
|
these commands relies on a fashion of invocation because they are also
|
|
intended to be used as library functions. In case you don't have the
|
|
signer's public key, for example, the function @code{pgg-verify-region}
|
|
fails immediately, but if the function had been called interactively, it
|
|
would ask you to retrieve the signer's public key from the server.
|
|
|
|
@deffn Command pgg-encrypt-region start end recipients &optional sign
|
|
Encrypt the current region between @var{start} and @var{end} for
|
|
@var{recipients}. When the function were called interactively, you
|
|
would be asked about the recipients.
|
|
|
|
If encryption is successful, it replaces the current region contents (in
|
|
the accessible portion) with the resulting data.
|
|
|
|
If optional argument @var{sign} is non-@code{nil}, the function is
|
|
request to do a combined sign and encrypt. This currently only work
|
|
with GnuPG.
|
|
@end deffn
|
|
|
|
@deffn Command pgg-decrypt-region start end
|
|
Decrypt the current region between @var{start} and @var{end}. If
|
|
decryption is successful, it replaces the current region contents (in
|
|
the accessible portion) with the resulting data.
|
|
@end deffn
|
|
|
|
@deffn Command pgg-sign-region start end &optional cleartext
|
|
Make the signature from text between @var{start} and @var{end}. If the
|
|
optional third argument @var{cleartext} is non-@code{nil}, or the
|
|
function is called interactively, it does not create a detached
|
|
signature. In such a case, it replaces the current region contents (in
|
|
the accessible portion) with the resulting data.
|
|
@end deffn
|
|
|
|
@deffn Command pgg-verify-region start end &optional signature fetch
|
|
Verify the current region between @var{start} and @var{end}. If the
|
|
optional third argument @var{signature} is non-@code{nil}, or the function
|
|
is called interactively, it is treated as the detached signature of the
|
|
current region.
|
|
|
|
If the optional 4th argument @var{fetch} is non-@code{nil}, or the
|
|
function is called interactively, we attempt to fetch the signer's
|
|
public key from the key server.
|
|
@end deffn
|
|
|
|
@deffn Command pgg-insert-key
|
|
Retrieve the user's public key and insert it as ASCII-armored format.
|
|
@end deffn
|
|
|
|
@deffn Command pgg-snarf-keys-region start end
|
|
Collect public keys in the current region between @var{start} and
|
|
@var{end}, and add them into the user's keyring.
|
|
@end deffn
|
|
|
|
@node Selecting an implementation
|
|
@section Selecting an implementation
|
|
|
|
Since PGP has a long history and there are a number of PGP
|
|
implementations available today, the function which each one has differs
|
|
considerably. For example, if you are using GnuPG, you know you can
|
|
select cipher algorithm from 3DES, CAST5, BLOWFISH, and so on, but on
|
|
the other hand the version 2 of PGP only supports IDEA.
|
|
|
|
By default, if the variable @code{pgg-scheme} is not set, PGG searches the
|
|
registered scheme for an implementation of the requested service
|
|
associated with the named algorithm. If there are no match, PGG uses
|
|
@code{pgg-default-scheme}. In other words, there are two options to
|
|
control which command is used to process the incoming PGP armors. One
|
|
is for encrypting and signing, the other is for decrypting and
|
|
verifying.
|
|
|
|
@defvar pgg-scheme
|
|
Force specify the scheme of PGP implementation for decrypting and verifying.
|
|
The value can be @code{gpg}, @code{pgp}, and @code{pgp5}.
|
|
@end defvar
|
|
|
|
@defvar pgg-default-scheme
|
|
Force specify the scheme of PGP implementation for encrypting and signing.
|
|
The value can be @code{gpg}, @code{pgp}, and @code{pgp5}.
|
|
@end defvar
|
|
|
|
@node Caching passphrase
|
|
@section Caching passphrase
|
|
|
|
PGG provides a simple passphrase caching mechanism. If you want to
|
|
arrange the interaction, set the variable @code{pgg-read-passphrase}.
|
|
|
|
@defvar pgg-cache-passphrase
|
|
If non-@code{nil}, store passphrases. The default value of this
|
|
variable is @code{t}. If you were worry about security issue, however,
|
|
you could stop caching with setting it @code{nil}.
|
|
@end defvar
|
|
|
|
@defvar pgg-passphrase-cache-expiry
|
|
Elapsed time for expiration in seconds.
|
|
@end defvar
|
|
|
|
@node Default user identity
|
|
@section Default user identity
|
|
|
|
The PGP implementation is usually able to select the proper key to use
|
|
for signing and decryption, but if you have more than one key, you may
|
|
need to specify the key id to use.
|
|
|
|
@defvar pgg-default-user-id
|
|
User ID of your default identity. It defaults to the value returned
|
|
by @samp{(user-login-name)}. You can customize this variable.
|
|
@end defvar
|
|
|
|
@defvar pgg-gpg-user-id
|
|
User ID of the GnuPG default identity. It defaults to @samp{nil}.
|
|
This overrides @samp{pgg-default-user-id}. You can customize this
|
|
variable.
|
|
@end defvar
|
|
|
|
@defvar pgg-pgp-user-id
|
|
User ID of the PGP 2.x/6.x default identity. It defaults to
|
|
@samp{nil}. This overrides @samp{pgg-default-user-id}. You can
|
|
customize this variable.
|
|
@end defvar
|
|
|
|
@defvar pgg-pgp5-user-id
|
|
User ID of the PGP 5.x default identity. It defaults to @samp{nil}.
|
|
This overrides @samp{pgg-default-user-id}. You can customize this
|
|
variable.
|
|
@end defvar
|
|
|
|
@node Architecture
|
|
@chapter Architecture
|
|
|
|
PGG introduces the notion of a "scheme of PGP implementation" (used
|
|
interchangeably with "scheme" in this document). This term refers to a
|
|
singleton object wrapped with the luna object system.
|
|
|
|
Since PGG was designed for accessing and developing PGP functionality,
|
|
the architecture had to be designed not just for interoperability but
|
|
also for extensiblity. In this chapter we explore the architecture
|
|
while finding out how to write the PGG backend.
|
|
|
|
@menu
|
|
* Initializing::
|
|
* Backend methods::
|
|
* Getting output::
|
|
@end menu
|
|
|
|
@node Initializing
|
|
@section Initializing
|
|
|
|
A scheme must be initialized before it is used.
|
|
It had better guarantee to keep only one instance of a scheme.
|
|
|
|
The following code is snipped out of @file{pgg-gpg.el}. Once an
|
|
instance of @code{pgg-gpg} scheme is initialized, it's stored to the
|
|
variable @code{pgg-scheme-gpg-instance} and will be reused from now on.
|
|
|
|
@lisp
|
|
(defvar pgg-scheme-gpg-instance nil)
|
|
|
|
(defun pgg-make-scheme-gpg ()
|
|
(or pgg-scheme-gpg-instance
|
|
(setq pgg-scheme-gpg-instance
|
|
(luna-make-entity 'pgg-scheme-gpg))))
|
|
@end lisp
|
|
|
|
The name of the function must follow the
|
|
regulation---@code{pgg-make-scheme-} follows the backend name.
|
|
|
|
@node Backend methods
|
|
@section Backend methods
|
|
|
|
In each backend, these methods must be present. The output of these
|
|
methods is stored in special buffers (@ref{Getting output}), so that
|
|
these methods must tell the status of the execution.
|
|
|
|
@deffn Method pgg-scheme-lookup-key scheme string &optional type
|
|
Return keys associated with @var{string}. If the optional third
|
|
argument @var{type} is non-@code{nil}, it searches from the secret
|
|
keyrings.
|
|
@end deffn
|
|
|
|
@deffn Method pgg-scheme-encrypt-region scheme start end recipients &optional sign
|
|
Encrypt the current region between @var{start} and @var{end} for
|
|
@var{recipients}. If @var{sign} is non-@code{nil}, do a combined sign
|
|
and encrypt. If encryption is successful, it returns @code{t},
|
|
otherwise @code{nil}.
|
|
@end deffn
|
|
|
|
@deffn Method pgg-scheme-decrypt-region scheme start end
|
|
Decrypt the current region between @var{start} and @var{end}. If
|
|
decryption is successful, it returns @code{t}, otherwise @code{nil}.
|
|
@end deffn
|
|
|
|
@deffn Method pgg-scheme-sign-region scheme start end &optional cleartext
|
|
Make the signature from text between @var{start} and @var{end}. If the
|
|
optional third argument @var{cleartext} is non-@code{nil}, it does not
|
|
create a detached signature. If signing is successful, it returns
|
|
@code{t}, otherwise @code{nil}.
|
|
@end deffn
|
|
|
|
@deffn Method pgg-scheme-verify-region scheme start end &optional signature
|
|
Verify the current region between @var{start} and @var{end}. If the
|
|
optional third argument @var{signature} is non-@code{nil}, it is treated
|
|
as the detached signature of the current region. If the signature is
|
|
successfully verified, it returns @code{t}, otherwise @code{nil}.
|
|
@end deffn
|
|
|
|
@deffn Method pgg-scheme-insert-key scheme
|
|
Retrieve the user's public key and insert it as ASCII-armored format.
|
|
On success, it returns @code{t}, otherwise @code{nil}.
|
|
@end deffn
|
|
|
|
@deffn Method pgg-scheme-snarf-keys-region scheme start end
|
|
Collect public keys in the current region between @var{start} and
|
|
@var{end}, and add them into the user's keyring.
|
|
On success, it returns @code{t}, otherwise @code{nil}.
|
|
@end deffn
|
|
|
|
@node Getting output
|
|
@section Getting output
|
|
|
|
The output of the backend methods (@ref{Backend methods}) is stored in
|
|
special buffers, so that these methods must tell the status of the
|
|
execution.
|
|
|
|
@defvar pgg-errors-buffer
|
|
The standard error output of the execution of the PGP command is stored
|
|
here.
|
|
@end defvar
|
|
|
|
@defvar pgg-output-buffer
|
|
The standard output of the execution of the PGP command is stored here.
|
|
@end defvar
|
|
|
|
@defvar pgg-status-buffer
|
|
The rest of status information of the execution of the PGP command is
|
|
stored here.
|
|
@end defvar
|
|
|
|
@node Parsing OpenPGP packets
|
|
@chapter Parsing OpenPGP packets
|
|
|
|
The format of OpenPGP messages is maintained in order to publish all
|
|
necessary information needed to develop interoperable applications.
|
|
The standard is documented in RFC 2440.
|
|
|
|
PGG has its own parser for the OpenPGP packets.
|
|
|
|
@defun pgg-parse-armor string
|
|
List the sequence of packets in @var{string}.
|
|
@end defun
|
|
|
|
@defun pgg-parse-armor-region start end
|
|
List the sequence of packets in the current region between @var{start}
|
|
and @var{end}.
|
|
@end defun
|
|
|
|
@defvar pgg-ignore-packet-checksum
|
|
If non-@code{nil}, don't check the checksum of the packets.
|
|
@end defvar
|
|
|
|
@node Function Index
|
|
@chapter Function Index
|
|
@printindex fn
|
|
|
|
@node Variable Index
|
|
@chapter Variable Index
|
|
@printindex vr
|
|
|
|
@summarycontents
|
|
@contents
|
|
@bye
|
|
|
|
@c End:
|
|
|
|
@ignore
|
|
arch-tag: 0c205838-34b9-41a5-b9d7-49ae57ccac85
|
|
@end ignore
|