3. 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.

(require 'pgg)

If you want to check existence of pgg.el at runtime, instead you can list autoload setting for desired functions as follows.

(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)

3.1 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 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.

Command: pgg-encrypt-region start end recipients &optional sign

Encrypt the current region between start and end for 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 sign is non-nil, the function is request to do a combined sign and encrypt. This currently only work with GnuPG.

Command: pgg-decrypt-region start end

Decrypt the current region between start and end. If decryption is successful, it replaces the current region contents (in the accessible portion) with the resulting data.

Command: pgg-sign-region start end &optional cleartext

Make the signature from text between start and end. If the optional third argument cleartext is non-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.

Command: pgg-verify-region start end &optional signature fetch

Verify the current region between start and end. If the optional third argument signature is non-nil, or the function is called interactively, it is treated as the detached signature of the current region.

If the optional 4th argument fetch is non-nil, or the function is called interactively, we attempt to fetch the signer's public key from the key server.

Command: pgg-insert-key

Retrieve the user's public key and insert it as ASCII-armored format.

Command: pgg-snarf-keys-region start end

Collect public keys in the current region between start and end, and add them into the user's keyring.

3.2 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 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 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.

Variable: pgg-scheme

Force specify the scheme of PGP implementation for decrypting and verifying. The value can be gpg, pgp, and pgp5.

Variable: pgg-default-scheme

Force specify the scheme of PGP implementation for encrypting and signing. The value can be gpg, pgp, and pgp5.

3.3 Caching passphrase

PGG uses a simple passphrase caching mechanism, which is enabled by default.

Variable: pgg-cache-passphrase

If non-nil, store passphrases. The default value of this variable is t. If you were worry about security issue, however, you could stop caching with setting it nil.

Variable: pgg-passphrase-cache-expiry

Elapsed time for expiration in seconds.

3.4 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.

Variable: pgg-default-user-id

User ID of your default identity. It defaults to the value returned by `(user-login-name)'. You can customize this variable.

Variable: pgg-gpg-user-id

User ID of the GnuPG default identity. It defaults to `nil'. This overrides `pgg-default-user-id'. You can customize this variable.

Variable: pgg-pgp-user-id

User ID of the PGP 2.x/6.x default identity. It defaults to `nil'. This overrides `pgg-default-user-id'. You can customize this variable.

Variable: pgg-pgp5-user-id

User ID of the PGP 5.x default identity. It defaults to `nil'. This overrides `pgg-default-user-id'. You can customize this variable.

This document was generated by XEmacs shared group account on December, 19 2009 using texi2html 1.65.