[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] Changes to emacs/man/pgg.texi [emacs-unicode-2]
From: |
Miles Bader |
Subject: |
[Emacs-diffs] Changes to emacs/man/pgg.texi [emacs-unicode-2] |
Date: |
Thu, 09 Sep 2004 08:18:53 -0400 |
Index: emacs/man/pgg.texi
diff -c /dev/null emacs/man/pgg.texi:1.2.2.1
*** /dev/null Thu Sep 9 09:39:16 2004
--- emacs/man/pgg.texi Thu Sep 9 09:36:28 2004
***************
*** 0 ****
--- 1,398 ----
+ \input texinfo @c -*-texinfo-*-
+
+ @setfilename ../info/pgg
+
+ @set VERSION 0.1
+
+
+ @copying
+ This file describes the PGG.
+
+ Copyright (C) 2003 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.1 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-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 address@hidden, 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 address@hidden, 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 address@hidden, 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 address@hidden, 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
+ address@hidden 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 address@hidden, 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-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 address@hidden, 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 address@hidden, 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 address@hidden, 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
- [Emacs-diffs] Changes to emacs/man/pgg.texi [emacs-unicode-2],
Miles Bader <=