$Id: library-usage.txt,v 1.1.1.1 2008/09/10 09:32:57 agcrooks Exp $

Library usage examples - BSD Privacy Guard
==========================================

In this file we discuss how to use BPG libraries from external applications.
For this we analyze what should be changed in two programs: archangel and
pkg_add.

Despite this changes will allow a complete GnuPG replace in this kind of
applications, BPG is still in development phase and does not fully implement
OpenPGP, so its usage is not recommended by the moment.


archangel
---------

archangel is defined by its author Alistair Crooks as "a combination of zip,
tar, gpg on steroids". It's a backup utility that provides both compression
and security (via encrypted/signed/encrypted+signed entries).

Currently, archangel uses external calls to GnuPG for entries security. This
can be easily replaced by library calls to BPG with the next modifications:

* (aa.c) Include bpg library header file, <bpg.h>.

* (Makefile) Use dynamic library -lbpg when building the 'aatar' executable.

* (aa.c) asystem function: no more external calls are needed, so this function
  can be replaced by something like this:

/* sign/encrypt or decrypt an entry */
static int
protect(aa_t *aa, const char *file, int enc, char protection, char *name)
{
	char	desc[20];
	BPG_CTX	*opt;

	opt = BPG_CTX_new();
	get_creds(aa, protection);
	if (enc) {
		switch(protection) {
		case ARCHANGEL_SIGNED:
			opt->pass = aa->phrase;
			opt->sec_uid = aa->id;
			BPG_sign(file, NULL, opt);
			break;
		case ARCHANGEL_ENCRYPTED:
			opt->pub_uid = aa->id;
			BPG_encrypt(file, NULL, opt);
			break;
		case (ARCHANGEL_SIGNED | ARCHANGEL_ENCRYPTED):
			opt->pub_uid = aa->id;
			opt->sec_uid = aa->id;
			opt->pass = aa->phrase;
			BPG_encrypt_sign(file, NULL, opt);
			break;
		}
	} else {
		opt->pass = aa->phrase;
		BPG_decrypt(file, name, opt);
	}
	BPG_CTX_free(opt);

	return 0;
}

* Finally, replace all gpg mentions in the manual and prompts :-).


pkg_add
-------

pkg_add is a utility for installing and upgrading software package
distributions. It allows the verification of signatures of the package being
installed with the -s option.

Currently pkg_add accepts three types of verification: none, gpg and pgp5. gpg
and pgp5 signatures are verified with an external call to the program binaries.

The usage of BPG can be easily supported just adding a new verification type,
bpg, and calling the external bpg binary. But, of course, this has little sense
when we have a bpg library that could make all the work in a more elegant way.
And, as signatures and keys are compatible under the OpenPGP standard, there
will be no need for gpg and pgp5 verification types.

In terms of coding, there would be only necessary to modify the file
src/usr.sbin/pkg_install/add/verify.c. Concretely, all code would reduce to a
single verify function, that could be something like this:

/* verify the digital signature (if any) on a package */
int
verify(const char *pkg)
{
	int	ret;
	
	if (verification_type == NULL)
		return 1;
	ret = BPG_verify(pkg);
	if (ret == 0)
		(void) fprintf(stderr, "*** WARNING ***: `%s' has a bad signature\n", pkg);
	if (ret == -1)
		(void) fprintf(stderr, "Can't verify signature of `%s'", pkg);

	return ret;
}

It can be interesting to add also support for detached signatures. A new type
of verification could handle this, so having: none, integrated, detached.

