[issue210] A note on the backend interface design (process)

[Marc Mutz]

New submission from Marc Mutz <marc at klaralvdalens-datakonsult.se>:

Hi Werner, Marcus.

Reading #183 and #199 again makes me wonder how much of that suff will 
actually survive the next {gpgme,gnupg} version. One one hand, you fight 
against adding new interfaces (read: functions) to gpgme, and keep adding 
command line hacks that make Kleopatra a more and more unmaintainable mixture 
of gpgconf/gpgme/gpgsm calls, OTOH, you keep overloading the keylist 
operation with more and more semantics that don't have anything to do with 
key listing. Setting root certs trust through a keylisting? Hello?

The operations that you overloaded on gpgme_op_keylist naturally share a 
common code path in Kleopatra, different operations differentiating 
themselves through minor usage of the occasional ternary operator. This is 
fine, apart from the overloaded keylist semantics.

But now I am asked (#183) to break up all these common code paths, duplicating 
a lot of code, writing a lot of new code, so that gpgme can keep adding even 
more semantics to it's existing interfaces, keeping _it's_ code paths shared, 
to a point (trust setting) that's getting ridiculous fast.

Also, imposing arbitrary restrictions on a long-established interface just as 
bugs show up is not a sign of good interface design. There is nothing 
stopping me from presenting the user with a listbox and [Add...] and [Remove] 
buttons to build up a list of patterns to send to gpgme for listing. Qt won't 
impose any restrictions other than stuff like MAXINT and the available 
memory. And I would have _no way_ of imposing a limit on the number of 
patterns in the GUI, since I do not know where that limit is. This limit is 
an implementation detail of the gpgme<->gpg/gpgsm protocol, and only these 
two components know about that limit. One of them enforces the limit, but the 
other one doesn't understand the error, and returns the not very helpful 
error message "invalid engine".

If there's a limit, enforce it and return a meaningful error message/code. And 
provide an interface for the common task of validating a list of keys, 
something _useful_ like:
 gpgme_error_t gpgme_op_validate_start( gpgme_key_t * keys, ... );
that doesn't have this limit. Its passed gpgme_key_t's so that I don't need to 
guess that it's probably fingerprints that you want passed in that case, and 
an equivalent function for this root trust setting, although a decent command 
line interface would be more fitting there.

Whether or not you internally map that to a keylist is up to you, but at least 
this is what I would call a clear, to-the-point interface, instead of the 
mish-mash that keylist is now.

There are some other areas in gpgme where the semantics are not well-defined 
(I've written the occasional mail about them, but didn't have the time or 
right spirit to argue over such small things) and stuff has been added 
ad-hoc. The identification of root certs, e.g., is one of them that 
immediately comes to mind, since it caused shotgun surgery on our side. I've 
since added a method GpgME::Key::isRoot() since I coudn't for the live of me 
remember whether chain_id == subkeys->fpr or !chain_id was meant to mean 
"isRoot". A simple flag in gpgme_key_t or an inline function 
gpgme_key_is_rootcert( gpgme_key_t ) would've made dealing with this sort of 
thing so much easier.

I've also added GpgME::Key::fingerprint(), which associates a fingerprint with 
a _key_, which is what you use it for when doing a validating keylisting, as 
well as GpgME::Key::keyID() and ::shortKeyID(), which are probably very wrong 
for RSA and/or X.509 keys, but without which a decent UI isn't possible.

All in all, your arguments at the beginning of the project for not adding 
requested functions/features were that they would expose implementation 
details of gpgme/gpg/gpgsm/whatever in the interface. However, what has come 
out of this project is a gpgme that requires the user (of the API) to rely on 
undocumented behaviour of the API, accept implementation-defined and 
non-queriable limits, interspersing of gpgme calls with direct calls to the 
gpg/gpgsm/gpgconf commandline, and so on.

Actually, I think I should stop here. I just wanted to point out that I think 
the handling of the gpgme API was too strict and that the addition of a 
keymanager API on top of the gpgme one (and splitting keyring handling 
operations such as delete_key out of gpgme into that keymanager-interface) 
would have made much more sense than the current patchwork of ad-hoc hacks. 
Somehow I get the idea that you hope that (S/MIME) key managers for GnuPG 
will go away again after this project. Which is kind of funny, since I 
remember Werner violently agreeing that the trend for OpenPGP and .S/MIME 
over the next years will be to more and more integrate them with each other 
(OpenPGP keys for TLS, OpenPGP sigs with X.509 keys, etc), so I can't really 
understand the reluctance on your side, but there you go...

Thanks for listening,
Marc

----------
messages: 1034
nosy: marc
status: unread
title: A note on the backend interface design (process)
______________________________________________________
Aegypten issue tracker <aegypten-issues at intevation.de>
<https://intevation.de/roundup/aegypten/issue210>
______________________________________________________