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

[Simon Josefsson]

Daniel Kahn Gillmor <dkg-debian.org at fifthhorseman.net> writes:

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

Hi!  Thanks for discussing this.

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

Agreed.

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

I think this suggestion makes sense, although I'm not an OpenPGP expert.
I have also found the number of APIs related to keys+subkeys rather
overwhelming.

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

I agree that duplicated functionality is quite bad, but having a
separate type for private keys can be useful if you want to perform a
code review of all code dealing with the private keys only.  There could
be ideas that harmonize these two priorities though.

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

I think the size of the installed base for the OpenPGP stuff is rather
limited, so I'm quite open to improving the API in this area.  We should
make an effort to maintain ABI compatibility though.

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

Better documentation is always good.

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

Hm.  Maybe we can add a libgnutls-openpgp which contains a simplified
OpenPGP related API?  Eventually, the old OpenPGP API in libgnutls could
be deprecated.

In general, I would prefer if libgnutls is a minimal TLS library
implementation, and there would be libgnutls-openpgp and libgnutls-x509
with the OpenPGP/X.509 functionality.  Not everyone needs X.509/OpenPGP.
Your ideas to have a OpenPGP wrapper library would tie well into my
wishes here.

One problem is the internal crypto abstraction interface: but if we make
that API publicly available, the libgnutls-foo libraries can access them
as well.  Applications can too.

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

Definitely, and thanks for doing that.

/Simon