docs: python bindings howto update.
[gpgme.git] / TODO
1 Hey Emacs, this is -*- org -*- mode!
2
3 * Fix the remaining UI Server problems:
4   :PROPERTIES:
5   :CUSTOM_ID: ui-server-fix
6   :END:
7 ** VERIFY --silent support.
8    :PROPERTIES:
9    :CUSTOM_ID: verify-silent
10    :END:
11 ** ENCRYPT/DECRYPT/VERIFY/SIGN reset the engine, shouldn't be done with UISERVER?
12    :PROPERTIES:
13    :CUSTOM_ID: reset-engine-not-ui
14    :END:
15
16
17 * IMPORTANT
18   :PROPERTIES:
19   :CUSTOM_ID: important-stuff-really
20   :END:
21 ** When using descriptor passing, we need to set the fd to blocking before
22    :PROPERTIES:
23    :CUSTOM_ID: set-fd-blocking
24    :END:
25    issueing simple commands, because we are mixing synchronous
26    commands into potentially asynchronous operations.
27 ** Might want to implement nonblock for w32 native backend!
28    :PROPERTIES:
29    :CUSTOM_ID: nonblock-win32
30    :END:
31    Right now we block reading the next line with assuan.
32
33 * Before release:
34   :PROPERTIES:
35   :CUSTOM_ID: pre-release
36   :END:
37 ** Some gpg tests fail with gpg 1.3.4-cvs (gpg/t-keylist-sig)
38    :PROPERTIES:
39    :CUSTOM_ID: gpg-1-3-4-really
40    :END:
41    The test is currently disabled there and in gpg/t-import.
42 ** When gpg supports it, write binary subpackets directly,
43    :PROPERTIES:
44    :CUSTOM_ID: binary-subpackets
45    :END:
46    and parse SUBPACKET status lines.
47
48 * ABI's to break:
49   :PROPERTIES:
50   :CUSTOM_ID: abi-breakage-apparently-on-purpose
51   :END:
52 ** Old opassuan interface.
53    :PROPERTIES:
54    :CUSTOM_ID: old-opassuan
55    :END:
56 ** Implementation: Remove support for old style error codes in
57    :PROPERTIES:
58    :CUSTOM_ID: remove-old-error-codes
59    :END:
60    conversion.c::_gpgme_map_gnupg_error.
61 ** gpgme_edit_cb_t: Add "processed" return argument
62    :PROPERTIES:
63    :CUSTOM_ID: add-processed-return
64    :END:
65    (see edit.c::command_handler).
66 ** I/O and User Data could be made extensible.  But this can be done
67    :PROPERTIES:
68    :CUSTOM_ID: add-io-user-data
69    :END:
70    without breaking the ABI hopefully.
71 ** All enums should be replaced by ints and simple macros for
72    :PROPERTIES:
73    :CUSTOM_ID: enums-should-be-ints
74    :END:
75    maximum compatibility.
76 ** Compatibility interfaces that can be removed in future versions:
77    :PROPERTIES:
78    :CUSTOM_ID: compat-interfaces-to-go
79    :END:
80 *** gpgme_data_new_from_filepart
81     :PROPERTIES:
82     :CUSTOM_ID: gpgme-data-new-from-filepart
83     :END:
84 *** gpgme_data_new_from_file
85     :PROPERTIES:
86     :CUSTOM_ID: gpgme-data-new-from-file
87     :END:
88 *** gpgme_data_new_with_read_cb
89     :PROPERTIES:
90     :CUSTOM_ID: gpgme-data-new-with-read-cb
91     :END:
92 *** gpgme_data_rewind
93     :PROPERTIES:
94     :CUSTOM_ID: gpgme-data-rewind
95     :END:
96 *** gpgme_op_import_ext
97     :PROPERTIES:
98     :CUSTOM_ID: gpgme-op-import-ext
99     :END:
100 *** gpgme_get_sig_key
101     :PROPERTIES:
102     :CUSTOM_ID: gpgme-get-sig-key
103     :END:
104 *** gpgme_get_sig_ulong_attr
105     :PROPERTIES:
106     :CUSTOM_ID: gpgme-get-sig-ulong-attr
107     :END:
108 *** gpgme_get_sig_string_attr
109     :PROPERTIES:
110     :CUSTOM_ID: gpgme-get-sig-string-attr
111     :END:
112 *** GPGME_SIG_STAT_*
113     :PROPERTIES:
114     :CUSTOM_ID: gpgme-sig-stat
115     :END:
116 *** gpgme_get_sig_status
117     :PROPERTIES:
118     :CUSTOM_ID: gpgme-get-sig-status
119     :END:
120 *** gpgme_trust_item_release
121     :PROPERTIES:
122     :CUSTOM_ID: gpgme-trust-item-release
123     :END:
124 *** gpgme_trust_item_get_string_attr
125     :PROPERTIES:
126     :CUSTOM_ID: gpgme-trust-item-get-string-attr
127     :END:
128 *** gpgme_trust_item_get_ulong_attr
129     :PROPERTIES:
130     :CUSTOM_ID: gpgme-trust-item-get-ulong-attr
131     :END:
132 *** gpgme_attr_t
133     :PROPERTIES:
134     :CUSTOM_ID: gpgme-attr-t
135     :END:
136 *** All Gpgme* typedefs.
137     :PROPERTIES:
138     :CUSTOM_ID: all-gpgme-typedefs
139     :END:
140
141
142 * Thread support:
143   :PROPERTIES:
144   :CUSTOM_ID: threads
145   :END:
146 ** When GNU Pth supports sendmsg/recvmsg, wrap them properly.
147    :PROPERTIES:
148    :CUSTOM_ID: wrap-oth
149    :END:
150 ** Without timegm (3) support our ISO time parser is not thread safe.
151    :PROPERTIES:
152    :CUSTOM_ID: time-threads
153    :END:
154    There is a configure time warning, though.
155
156 * New features:
157   :PROPERTIES:
158   :CUSTOM_ID: new-features
159   :END:
160 ** Flow control for data objects.
161    :PROPERTIES:
162    :CUSTOM_ID: flow-control-is-not-a-euphemism-for-an-s-bend
163    :END:
164    Currently, gpgme_data_t objects are assumed to be blocking.  To
165    break this assumption, we need either (A) a way for an user I/O
166    callback to store the current operation in a continuation that can
167    be resumed later.  While the continuation exists, file descriptors
168    associated with this operation must be removed from their
169    respective event loop.  or (B) a way for gpgme data objects to be
170    associated with a waitable object, that can be registered with the
171    user event loop.  Neither is particularly simple.
172 ** Extended notation support.  When gpg supports arbitrary binary
173    :PROPERTIES:
174    :CUSTOM_ID: extended-notation
175    :END:
176    notation data, provide a user interface for that.
177 ** notification system
178    :PROPERTIES:
179    :CUSTOM_ID: notification-system
180    :END:
181    We need a simple notification system, probably a simple callback
182    with a string and some optional arguments.  This is for example
183    required to notify an application of a changed smartcard, The
184    application can then do whatever is required.  There are other
185    usages too.  This notfication system should be independent of any
186    contextes of course.
187
188    Not sure whether this is still required.  GPGME_PROTOCOL_ASSUAN is
189    sufficient for this.
190
191 ** --learn-code support
192    :PROPERTIES:
193    :CUSTOM_ID: learn-code
194    :END:
195    This might be integrated with import. we still need to work out how
196    to learn a card when gpg and gpgsm have support for smartcards.  In
197    GPA we currently invoke gpg directly.
198
199 ** Might need a stat() for data objects and use it for length param to gpg.
200    :PROPERTIES:
201    :CUSTOM_ID: stat-data
202    :END:
203 ** Implement support for photo ids.
204    :PROPERTIES:
205    :CUSTOM_ID: photo-id
206    :END:
207 ** Allow selection of subkeys
208    :PROPERTIES:
209    :CUSTOM_ID: subkey-selection
210    :END:
211 ** Allow to return time stamps in ISO format
212    :PROPERTIES:
213    :CUSTOM_ID: iso-format-datetime
214    :END:
215   This allows us to handle years later than 2037 properly.  With the
216   time_t interface they are all mapped to 2037-12-31
217 ** New features requested by our dear users, but rejected or left for
218    :PROPERTIES:
219    :CUSTOM_ID: feature-requests
220    :END:
221    later consideration:
222 *** Allow to export secret keys.
223     :PROPERTIES:
224     :CUSTOM_ID: export-secret-keys
225     :END:
226     Rejected because this is conceptually flawed.  Secret keys on a
227     smart card can not be exported, for example.
228     May eventually e supproted with a keywrapping system.
229 *** Selecting the key ring, setting the version or comment in output.
230     :PROPERTIES:
231     :CUSTOM_ID: select-keyring-version
232     :END:
233     Rejected because the naive implementation is engine specific, the
234     configuration is part of the engine's configuration or readily
235     worked around in a different way
236 *** Selecting the symmetric cipher.
237     :PROPERTIES:
238     :CUSTOM_ID: symmetric-cipher-selection
239     :END:
240 *** Exchanging keys with key servers.
241     :PROPERTIES:
242     :CUSTOM_ID: key-server-exchange
243     :END:
244
245
246 * Documentation
247   :PROPERTIES:
248   :CUSTOM_ID: documentation
249   :END:
250
251 ** TODO Document validity and trust issues.
252    :PROPERTIES:
253    :CUSTOM_ID: valid-trust-issues
254    :END:
255
256 ** In gpgme.texi: Register callbacks under the right letter in the index.
257    :PROPERTIES:
258    :CUSTOM_ID: gpgme-texi
259    :END:
260
261 ** Document all the new stuff.
262    :PROPERTIES:
263    :CUSTOM_ID: more-docs-is-better
264    :END:
265
266 *** TODO Fix this TODO list.
267     :PROPERTIES:
268     :CUSTOM_ID: fix-todo
269     :END:
270
271     Clean up the current TODO list.  Include properties as relevant (so
272     if someone does make a PDF or HTML version the TOC will work).
273
274     Also check ans see if some of these ancient things can be removed
275     (e.g. do we really need to fix things that were broken in GPG
276     1.3.x?  I'm thinking not so much).
277
278 **** DONE fix TODO items
279      CLOSED: [2018-03-04 Sun 08:55]
280      :PROPERTIES:
281      :CUSTOM_ID: fix-todo-items
282      :END:
283
284      Adjust todo items so each can now be referenced by custom-id and
285      checked off as necessary.
286
287 * Engines
288   :PROPERTIES:
289   :CUSTOM_ID: engines
290   :END:
291 ** Do not create/destroy engines, but create engine and then reset it.
292    :PROPERTIES:
293    :CUSTOM_ID: reset-engine-is-not-quite-just-ignition
294    :END:
295    Internally the reset operation still spawns a new engine process,
296    but this can be replaced with a reset later.  Also, be very sure to
297    release everything properly at a reset and at an error.  Think hard
298    about where to guarantee what (ie, what happens if start fails, are
299    the fds unregistered immediately - i think so?)
300    Note that we need support in gpgsm to set include-certs to default
301    as RESET does not reset it, also for no_encrypt_to and probably
302    other options.
303 ** Optimize the case where a data object has an underlying fd we can pass
304    :PROPERTIES:
305    :CUSTOM_ID: optimus-data-cousin-of-optimus-prime
306    :END:
307    directly to the engine.  This will be automatic with socket I/O and
308    descriptor passing.
309 ** Move code common to all engines up from gpg to engine.
310    :PROPERTIES:
311    :CUSTOM_ID: move-code-common-to-engines-out-of-gpg
312    :END:
313 ** engine operations can return General Error on unknown protocol
314    :PROPERTIES:
315    :CUSTOM_ID: general-error-looking-to-be-court-martialled
316    :END:
317    (it's an internal error, as select_protocol checks already).
318 ** When server mode is implemented properly, more care has to be taken to
319    :PROPERTIES:
320    :CUSTOM_ID: server-mode
321    :END:
322    release all resources on error (for example to free assuan_cmd).
323 ** op_import_keys and op_export_keys have a limit in the number of keys.
324    :PROPERTIES:
325    :CUSTOM_ID: import-export-problems
326    :END:
327    This is because we pass them in gpg via the command line and gpgsm
328    via an assuan control line.  We should pipe them instead and maybe
329    change gpg/gpgsm to not put them in memory.
330
331
332 * GPG breakage:
333   :PROPERTIES:
334   :CUSTOM_ID: gpg-breakage
335   :END:
336 ** gpg 1.4.2 lacks error reporting if sign/encrypt with revoked key.
337    :PROPERTIES:
338    :CUSTOM_ID: gpg-classic-lacks-stuff
339    :END:
340 ** gpg 1.4.2 does crappy error reporting (namely none at all) when
341    :PROPERTIES:
342    :CUSTOM_ID: gpg-classic-problems-but-do-we-care
343    :END:
344    smart card is missing for sign operation:
345     [GNUPG:] CARDCTRL 4
346     gpg: selecting openpgp failed: ec=6.110
347     gpg: signing failed: general error
348     [GNUPG:] BEGIN_ENCRYPTION 2 10
349     gpg: test: sign+encrypt failed: general error
350 ** Without agent and with wrong passphrase, gpg 1.4.2 enters into an
351    :PROPERTIES:
352    :CUSTOM_ID: recursive-gpg-classic
353    :END:
354    infinite loop.
355 ** Use correct argv[0]
356    :PROPERTIES:
357    :CUSTOM_ID: correct-argv
358    :END:
359    In rungpg.c:build_argv we use
360       argv[argc] = strdup ("gpg"); /* argv[0] */
361    This should be changed to take the real file name used in account.
362
363
364 * Operations
365   :PROPERTIES:
366   :CUSTOM_ID: operations-are-not-surgical
367   :END:
368 ** Include cert values -2, -1, 0 and 1 should be defined as macros.
369    :PROPERTIES:
370    :CUSTOM_ID: certified-macros
371    :END:
372 ** If an operation failed, make sure that the result functions don't return
373    :PROPERTIES:
374    :CUSTOM_ID: operation-failure
375    :END:
376    corrupt partial information. !!!
377    NOTE: The EOF status handler is not called in this case !!!
378 ** Verify must not fail on NODATA premature if auto-key-retrieval failed.
379    :PROPERTIES:
380    :CUSTOM_ID: autobot-key-retrieval
381    :END:
382    It should not fail silently if it knows there is an error. !!!
383 ** All operations: Better error reporting. !!
384    :PROPERTIES:
385    :CUSTOM_ID: better-reporting-not-like-fox-news
386    :END:
387 ** Export status handler need much more work. !!!
388    :PROPERTIES:
389    :CUSTOM_ID: export-status-handler
390    :END:
391 ** Import should return a useful error when one happened.
392    :PROPERTIES:
393    :CUSTOM_ID: import-useful-stuff-even-wrong-stuff
394    :END:
395 *** Import does not take notice of NODATA status report.
396     :PROPERTIES:
397     :CUSTOM_ID: import-no-data
398     :END:
399 *** When GPGSM does issue IMPORT_OK status reports, make sure to check for
400     :PROPERTIES:
401     :CUSTOM_ID: gpgsm-import-ok
402     :END:
403     them in tests/gpgs m/t-import.c.
404 ** Verify can include info about version/algo/class, but currently
405    :PROPERTIES:
406    :CUSTOM_ID: verify-class
407    :END:
408    this is only available for gpg, not gpgsm.
409 ** Return ENC_TO output in verify result.  Again, this is not available
410    :PROPERTIES:
411    :CUSTOM_ID: return-to-enc
412    :END:
413    for gpgsm.
414 ** Genkey should return something more useful than General_Error.
415    :PROPERTIES:
416    :CUSTOM_ID: general-key-assumed-command-from-general-error
417    :END:
418 ** If possible, use --file-setsize to set the file size for proper progress
419    :PROPERTIES:
420    :CUSTOM_ID: file-setsize
421    :END:
422    callback handling.  Write data interface for file size.
423 ** Optimize the file descriptor list, so the number of open fds is
424    :PROPERTIES:
425    :CUSTOM_ID: optimus-descriptus-younger-brother-of-optimus-prime
426    :END:
427    always known easily.
428 ** Encryption: It should be verified that the behaviour for partially untrusted
429    :PROPERTIES:
430    :CUSTOM_ID: only-mostly-dead-means-partially-alive
431    :END:
432    recipients is correct.
433 ** When GPG issues INV_something for invalid signers, catch them.
434    :PROPERTIES:
435    :CUSTOM_ID: invalid-sig
436    :END:
437
438
439 * Error Values
440   :PROPERTIES:
441   :CUSTOM_ID: error-value
442   :END:
443 ** Map ASSUAN/GpgSM ERR error values in a better way than is done now. !!
444    :PROPERTIES:
445    :CUSTOM_ID: map-ass-error
446    :END:
447 ** Some error values should identify the source more correctly (mostly error
448    :PROPERTIES:
449    :CUSTOM_ID: source-errors
450    :END:
451    values derived from status messages).
452 ** In rungpg.c we need to check the version of the engine
453    :PROPERTIES:
454    :CUSTOM_ID: rungpg-c-engine-ver
455    :END:
456    This requires a way to get the cached version number from the
457    engine layer.
458
459
460 * Tests
461   :PROPERTIES:
462   :CUSTOM_ID: tests
463   :END:
464 ** TODO Write a fake gpg-agent so that we can supply known passphrases to
465    :PROPERTIES:
466    :CUSTOM_ID: test-fake-gpg-agent
467    :END:
468    gpgsm and setup the configuration files to use the agent.  Without
469    this we are testing a currently running gpg-agent which is not a
470    clever idea. !
471 ** t-data
472    :PROPERTIES:
473    :CUSTOM_ID: test-data
474    :END:
475 *** Test gpgme_data_release_and_get_mem.
476     :PROPERTIES:
477     :CUSTOM_ID: test-gpgme-data-release-mem
478     :END:
479 *** Test gpgme_data_seek for invalid types.
480     :PROPERTIES:
481     :CUSTOM_ID: test-gpgme-data-seek
482     :END:
483 ** t-keylist
484    :PROPERTIES:
485    :CUSTOM_ID: test-keylist
486    :END:
487    Write a test for ext_keylist.
488 ** Test reading key signatures.
489    :PROPERTIES:
490    :CUSTOM_ID: test-key-sig
491    :END:
492
493
494 * Debug
495   :PROPERTIES:
496   :CUSTOM_ID: debug
497   :END:
498 ** Tracepoints should be added at: Every public interface enter/leave,
499    :PROPERTIES:
500    :CUSTOM_ID: tracepoint-pub-int
501    :END:
502    before and in every callback, at major decision points, at every
503    internal data point which might easily be observed by the outside
504    (system handles).  We also trace handles and I/O support threads in
505    the w32 implementation because that's fragile code.
506    Files left to do:
507    data-fd.c data-mem.c data-stream.c data-user.c debug.c rungpg.c
508    engine.c engine-gpgsm.c funopen.c w32-glib-io.c wait.c
509    wait-global.c wait-private.c wait-user.c op-support.c decrypt.c
510    decrypt-verify.c delete.c edit.c encrypt.c encrypt-sign.c export.c
511    genkey.c import.c key.c keylist.c passphrase.c progress.c signers.c
512    sig-notation.c trust-item.c trustlist.c verify.c
513 ** TODO Handle malloc and vasprintf errors.  But decide first if they should be
514    :PROPERTIES:
515    :CUSTOM_ID: malloc-vasprintf
516    :END:
517
518    ignored (and logged with 255?!), or really be assertions. !
519
520
521 * Build suite
522   :PROPERTIES:
523   :CUSTOM_ID: build-suite
524   :END:
525 ** TODO Make sure everything is cleaned correctly (esp. test area).
526    :PROPERTIES:
527    :CUSTOM_ID: clean-tests
528    :END:
529 ** TODO Enable AC_CONFIG_MACRO_DIR and bump up autoconf version requirement.
530    :PROPERTIES:
531    :CUSTOM_ID: autoconf-macros
532    :END:
533    (To fix "./autogen.sh; ./configure --enable-maintainer-mode; touch
534    configure.ac; make").  Currently worked around with ACLOCAL_AMFLAGS???
535
536
537 * Error checking 
538   :PROPERTIES:
539   :CUSTOM_ID: error-checking
540   :END:
541 ** TODO engine-gpgsm, with-validation
542    :PROPERTIES:
543    :CUSTOM_ID: gpgsm-validation
544    :END:
545    Add error checking some time after releasing a new gpgsm.
546
547
548 * Language bindings and related components
549   :PROPERTIES:
550   :CUSTOM_ID: language-bindings-and-related-stuff
551   :END:
552
553 ** TODO Emacs and elisp binding
554    :PROPERTIES:
555    :CUSTOM_ID: emacs-and-elisp
556    :END:
557
558    Currently GNU Emacs uses EPA and EPG to provide GnuPG support.  EPG
559    does this by calling the GPG executable and wrapping the commands
560    with elisp functions.  A more preferable solution would be to
561    implement an epgme.el which integrated with GPGME, then if it could
562    not to attempt calling the gpgme-tool and only if those failed to
563    fall back to the current epg.el and calling the command line
564    binaries.
565
566 ** TODO API of an API
567    :PROPERTIES:
568    :CUSTOM_ID: api-squared
569    :END:
570
571    See the more detailed notes on this in the [[lang/python/docs/TODO.org][python TODO]].
572
573 ** TODO GPGME installation and package management guide
574    :PROPERTIES:
575    :CUSTOM_ID: package-management
576    :END:
577
578    Write a guide/best practices for maintainers of GPGME packages with
579    third party package management systems.
580
581
582 * Copyright 2004, 2005, 2018 g10 Code GmbH
583   :PROPERTIES:
584   :CUSTOM_ID: copyright-and-license
585   :END:
586
587 This file is free software; as a special exception the author gives
588 unlimited permission to copy and/or distribute it, with or without
589 modifications, as long as this notice is preserved.
590
591 This file is distributed in the hope that it will be useful, but
592 WITHOUT ANY WARRANTY, to the extent permitted by law; without even the
593 implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
594 PURPOSE.