From fddb14845c4276bb42707adb26d4106c219c9469 Mon Sep 17 00:00:00 2001 From: ueno Date: Sat, 2 Jun 2001 09:05:43 +0000 Subject: [PATCH] * pgg.texi: New file. --- pgg.texi | 365 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 365 insertions(+) create mode 100644 pgg.texi diff --git a/pgg.texi b/pgg.texi new file mode 100644 index 0000000..0f07f15 --- /dev/null +++ b/pgg.texi @@ -0,0 +1,365 @@ +\input texinfo @c -*-texinfo-*- + +@setfilename pgg.info + +@set VERSION 0.1 + +@direntry +* PGG: (pgg). Emacs interface to various PGP implementations. +@end direntry + +@settitle PGG @value{VERSION} + +@ifinfo +This file describes the PGG. + +Copyright (C) 2000 Daiki Ueno. + +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 ifinfo + +@tex + +@titlepage +@title PGG + +@author by Daiki Ueno +@page + +@vskip 0pt plus 1filll +Copyright @copyright{} 2000 Daiki Ueno. + +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 titlepage +@page + +@end tex + +@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:: +* How to use:: Calling PGP from your applications. +* 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 assumes to use GnuPG, but Pretty Good Privacy version 2 +or version 5 are also supported. If you are new to such a system, I +recomend 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 still simple, and only +intended to use with public-key cryptographic operation. + +To use PGG, please 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 settings for functions you want 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:: +@end menu + +@node User Commands +@section User Commands + +At this time you can use various cryptographic commands. The behavior +of these commands relies on the fashion of invocation because these +commands are also intended to be used as library functions. For +example, in case you don't have the signer's public key, the function +`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 +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. +@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 @var{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 +@var{pgg-default-scheme}. In other words, there are two options to +controll 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 @var{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. +@end defvar + +@defvar pgg-passphrase-cache-expiry +The elapsed time for expiration in seconds. +@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 interoperablity 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 @var{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 +Encrypt the current region between @var{start} and @var{end} for +@var{recipients}. 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 +successflly 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: -- 1.7.10.4