OpenPGP certificate/key management thoughts about function re-organization and cleanup

[Daniel Kahn Gillmor]

Hey folks--

This message describes some thoughts about the GnuTLS OpenPGP API (in
particular, the bits that used to be OpenCDK).  These thoughts have
come after i've played with the library for a while, but they may
still be ill-informed.  I'd be happy to have flaws in my reasoning
pointed out.  My first observation was dismay at just how many
functions were specifically available for the OpenPGP key management
functionality.  The OpenPGP function reference [0] is enormous and
difficult to wade through.  Furthermore, much functionality seems
duplicated (or quadruplicated!) across different functions, which can
make it difficult to write clean, simple code with the library.

What follows are some proposals that might simplify and streamline the
set of functions available, which would make it easier for a skimming
developer to get a sense of the main functionality offered by the
library, and would facilitate writing tighter code in scenarios where
certain aspects might be better treated as abstractions.

Primary Keys vs. Subkeys
------------------------

There are currently a lot of duplicated functions which deal with the
subkey and primary keys differently.  For example:

 gnutls_openpgp_crt_get_pk_algorithm()
 gnutls_openpgp_crt_get_subkey_pk_algorithm()

These behave exactly the same way, but the primary key is sort of
special-cased out.

When writing key management code, one often abstracts away the
differences between primary keys and subkeys, and needs to just walk
through each key separately.  Having to call different functions for
the subkey than for the primary key is awkward and makes for a lot of
code duplication, which is room for error.

We could significantly reduce the number of functions exposed by
GnuTLS if we were to collapse these pairs of functions into a single
function which takes a key index.  Key index 0 would be the primary
key, key index 1 would be the first subkey, etc.  This would allow
much simpler looping constructs over a keyset, and would make the
documentation easier to scan and understand.

Certificates vs. Private Keys
-----------------------------

Furthermore, there are many functions that have basically identical
functionality duplicated across the crt and the privkey.  I'm aware
that these functions may be created as duplicates of the functions in
the x509 space, but if the crt and the privkey shared a common base
struct, or were otherwise considered interchangable at some level, you
could reduce the function space still further.

Conclusions, and a Proposal
---------------------------

I'm aware that major changes in API (esp. removing named functions)
are strongly discouraged in a stable library, so i can understand not
wanting to deal with this.  But getting developers to adopt the
OpenPGP model is going to be difficult enough without forcing those
developers to understand and work around this kind of duplicated
interface.

Not all of these changes are necessarily desirable, of course, but i
wanted to raise the issue of how such a re-configured library might
look so we can consider the merits and disadvantages of the
arrangement.  It's also possible that a documentation overhaul could
help for the "skimming/crammming developer" scenario (though it
wouldn't help much in terms of writing code that deals with
subkeys/primary keys at a similar level of abstraction).

I'd be happy to implement a sort of shim/wrapper library around
gnutls's OpenPGP key management pieces, so people can get a sense of
what that might look like.  I believe i can do this with no loss in
functionality, and a significant reduction in the number of functions
just from merging primary key/subkey functionality alone.  I'm not
sure how to handle the crt/privkey parallels, but if other people have
suggestions, i'd welcome them.

Thanks for considering this feedback,

       --dkg

PS i'm aware that these ideas cannot be under consideration for 2.4,
   given the current timeline.  I still think it's worth bringing them
   up.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 826 bytes
Desc: not available
URL: </pipermail/attachments/20080616/4268acd7/attachment.pgp>