Merge branch 'master' of ssh+git://playfair.gnupg.org/git/gpgme into ben/docs/2018-03
authorBen McGinnes <ben@adversary.org>
Thu, 8 Mar 2018 22:31:44 +0000 (09:31 +1100)
committerBen McGinnes <ben@adversary.org>
Thu, 8 Mar 2018 22:31:44 +0000 (09:31 +1100)
* Fixed conflicts with TODO.

.gitignore
TODO
lang/python/docs/GPGMEpythonHOWTOen.org [new file with mode: 0644]
lang/python/docs/TODO.org
src/gpgme-tool.c

index de173b8..e5bf69d 100644 (file)
@@ -52,4 +52,3 @@ nosetests.xml
 default.profraw
 .DS_Store
 ._.DS_Store
-default.profraw
\ No newline at end of file
diff --git a/TODO b/TODO
index 5f03fb6..a915ed7 100644 (file)
--- a/TODO
+++ b/TODO
@@ -14,23 +14,46 @@ Hey Emacs, this is -*- org -*- mode!
   tracked through the [[https://dev.gnupg.org/][dev.gnupg.org]] site.
 
 
-* TODO Document all the new stuff.
+* Documentation
   :PROPERTIES:
-  :CUSTOM_ID: more-docs-is-better
+  :CUSTOM_ID: documentation
   :END:
 
-** STARTED Fix this TODO list.
+** Document all the new stuff.
    :PROPERTIES:
-   :CUSTOM_ID: fix-todo
+   :CUSTOM_ID: more-docs-is-better
    :END:
-   - State "STARTED"    from "TODO"       [2018-03-09 Fri 08:31]
-   Clean up the current TODO list.  Include properties as relevant (so
-   if someone does make a PDF or HTML version the TOC will work).
 
-   Also check ans see if some of these ancient things can be removed
-   (e.g. do we really need to fix things that were broken in GPG
-   1.3.x?  I'm thinking not so much).
+*** TODO Fix this TODO list.
+    :PROPERTIES:
+    :CUSTOM_ID: fix-todo
+    :END:
+
+    Clean up the current TODO list.  Include properties as relevant (so
+    if someone does make a PDF or HTML version the TOC will work).
+
+    Also check ans see if some of these ancient things can be removed
+    (e.g. do we really need to fix things that were broken in GPG
+    1.3.x?  I'm thinking not so much).
+
+**** DONE fix TODO items
+     CLOSED: [2018-03-04 Sun 08:55]
+     :PROPERTIES:
+     :CUSTOM_ID: fix-todo-items
+     :END:
+
+     Adjust todo items so each can now be referenced by custom-id and
+     checked off as necessary.
 
+** TODO Document validity and trust issues.
+   :PROPERTIES:
+   :CUSTOM_ID: valid-trust-issues
+   :END:
+
+** In gpgme.texi: Register callbacks under the right letter in the index.
+   :PROPERTIES:
+   :CUSTOM_ID: gpgme-texi
+   :END:
 
 
 * Fix the remaining UI Server problems:
@@ -63,10 +86,12 @@ Hey Emacs, this is -*- org -*- mode!
    :END:
    Right now we block reading the next line with assuan.
 
+
 * Before release:
   :PROPERTIES:
   :CUSTOM_ID: pre-release
   :END:
+
 ** CANCELLED Some gpg tests fail with gpg 1.3.4-cvs (gpg/t-keylist-sig)
    CLOSED: [2018-03-09 Fri 08:16]
    :PROPERTIES:
@@ -75,100 +100,123 @@ Hey Emacs, this is -*- org -*- mode!
    - State "CANCELLED"  from "TODO"       [2018-03-09 Fri 08:16] \\
      WON'T FIX — too old or no longer applies.
    The test is currently disabled there and in gpg/t-import.
+
 ** When gpg supports it, write binary subpackets directly,
    :PROPERTIES:
    :CUSTOM_ID: binary-subpackets
    :END:
    and parse SUBPACKET status lines.
 
+
 * ABI's to break:
   :PROPERTIES:
   :CUSTOM_ID: abi-breakage-apparently-on-purpose
   :END:
+
 ** Old opassuan interface.
    :PROPERTIES:
    :CUSTOM_ID: old-opassuan
    :END:
+
 ** Implementation: Remove support for old style error codes in
    :PROPERTIES:
    :CUSTOM_ID: remove-old-error-codes
    :END:
    conversion.c::_gpgme_map_gnupg_error.
+
 ** gpgme_edit_cb_t: Add "processed" return argument
    :PROPERTIES:
    :CUSTOM_ID: add-processed-return
    :END:
    (see edit.c::command_handler).
+
 ** I/O and User Data could be made extensible.  But this can be done
    :PROPERTIES:
    :CUSTOM_ID: add-io-user-data
    :END:
    without breaking the ABI hopefully.
+
 ** All enums should be replaced by ints and simple macros for
    :PROPERTIES:
    :CUSTOM_ID: enums-should-be-ints
    :END:
    maximum compatibility.
+
 ** Compatibility interfaces that can be removed in future versions:
    :PROPERTIES:
    :CUSTOM_ID: compat-interfaces-to-go
    :END:
+
 *** gpgme_data_new_from_filepart
     :PROPERTIES:
     :CUSTOM_ID: gpgme-data-new-from-filepart
     :END:
+
 *** gpgme_data_new_from_file
     :PROPERTIES:
     :CUSTOM_ID: gpgme-data-new-from-file
     :END:
+
 *** gpgme_data_new_with_read_cb
     :PROPERTIES:
     :CUSTOM_ID: gpgme-data-new-with-read-cb
     :END:
+
 *** gpgme_data_rewind
     :PROPERTIES:
     :CUSTOM_ID: gpgme-data-rewind
     :END:
+
 *** gpgme_op_import_ext
     :PROPERTIES:
     :CUSTOM_ID: gpgme-op-import-ext
     :END:
+
 *** gpgme_get_sig_key
     :PROPERTIES:
     :CUSTOM_ID: gpgme-get-sig-key
     :END:
+
 *** gpgme_get_sig_ulong_attr
     :PROPERTIES:
     :CUSTOM_ID: gpgme-get-sig-ulong-attr
     :END:
+
 *** gpgme_get_sig_string_attr
     :PROPERTIES:
     :CUSTOM_ID: gpgme-get-sig-string-attr
     :END:
+
 *** GPGME_SIG_STAT_*
     :PROPERTIES:
     :CUSTOM_ID: gpgme-sig-stat
     :END:
+
 *** gpgme_get_sig_status
     :PROPERTIES:
     :CUSTOM_ID: gpgme-get-sig-status
     :END:
+
 *** gpgme_trust_item_release
     :PROPERTIES:
     :CUSTOM_ID: gpgme-trust-item-release
     :END:
+
 *** gpgme_trust_item_get_string_attr
     :PROPERTIES:
     :CUSTOM_ID: gpgme-trust-item-get-string-attr
     :END:
+
 *** gpgme_trust_item_get_ulong_attr
     :PROPERTIES:
     :CUSTOM_ID: gpgme-trust-item-get-ulong-attr
     :END:
+
 *** gpgme_attr_t
     :PROPERTIES:
     :CUSTOM_ID: gpgme-attr-t
     :END:
+
 *** All Gpgme* typedefs.
     :PROPERTIES:
     :CUSTOM_ID: all-gpgme-typedefs
@@ -179,20 +227,24 @@ Hey Emacs, this is -*- org -*- mode!
   :PROPERTIES:
   :CUSTOM_ID: threads
   :END:
+
 ** When GNU Pth supports sendmsg/recvmsg, wrap them properly.
    :PROPERTIES:
    :CUSTOM_ID: wrap-oth
    :END:
+
 ** Without timegm (3) support our ISO time parser is not thread safe.
    :PROPERTIES:
    :CUSTOM_ID: time-threads
    :END:
    There is a configure time warning, though.
 
+
 * New features:
   :PROPERTIES:
   :CUSTOM_ID: new-features
   :END:
+
 ** Flow control for data objects.
    :PROPERTIES:
    :CUSTOM_ID: flow-control-is-not-a-euphemism-for-an-s-bend
@@ -205,11 +257,13 @@ Hey Emacs, this is -*- org -*- mode!
    respective event loop.  or (B) a way for gpgme data objects to be
    associated with a waitable object, that can be registered with the
    user event loop.  Neither is particularly simple.
+
 ** Extended notation support.  When gpg supports arbitrary binary
    :PROPERTIES:
    :CUSTOM_ID: extended-notation
    :END:
    notation data, provide a user interface for that.
+
 ** notification system
    :PROPERTIES:
    :CUSTOM_ID: notification-system
@@ -236,25 +290,30 @@ Hey Emacs, this is -*- org -*- mode!
    :PROPERTIES:
    :CUSTOM_ID: stat-data
    :END:
+
 ** Implement support for photo ids.
    :PROPERTIES:
    :CUSTOM_ID: photo-id
    :END:
+
 ** Allow selection of subkeys
    :PROPERTIES:
    :CUSTOM_ID: subkey-selection
    :END:
+
 ** Allow to return time stamps in ISO format
    :PROPERTIES:
    :CUSTOM_ID: iso-format-datetime
    :END:
-  This allows us to handle years later than 2037 properly.  With the
-  time_t interface they are all mapped to 2037-12-31
+   This allows us to handle years later than 2037 properly.  With the
+   time_t interface they are all mapped to 2037-12-31
+
 ** New features requested by our dear users, but rejected or left for
    :PROPERTIES:
    :CUSTOM_ID: feature-requests
    :END:
    later consideration:
+
 *** Allow to export secret keys.
     :PROPERTIES:
     :CUSTOM_ID: export-secret-keys
@@ -262,6 +321,7 @@ Hey Emacs, this is -*- org -*- mode!
     Rejected because this is conceptually flawed.  Secret keys on a
     smart card can not be exported, for example.
     May eventually e supproted with a keywrapping system.
+
 *** Selecting the key ring, setting the version or comment in output.
     :PROPERTIES:
     :CUSTOM_ID: select-keyring-version
@@ -269,46 +329,23 @@ Hey Emacs, this is -*- org -*- mode!
     Rejected because the naive implementation is engine specific, the
     configuration is part of the engine's configuration or readily
     worked around in a different way
+
 *** Selecting the symmetric cipher.
     :PROPERTIES:
     :CUSTOM_ID: symmetric-cipher-selection
     :END:
+
 *** Exchanging keys with key servers.
     :PROPERTIES:
     :CUSTOM_ID: key-server-exchange
     :END:
 
 
-* Documentation
-  :PROPERTIES:
-  :CUSTOM_ID: documentation
-  :END:
-** TODO Document validity and trust issues.
-   :PROPERTIES:
-   :CUSTOM_ID: valid-trust-issues
-   :END:
-** In gpgme.texi: Register callbacks under the right letter in the index.
-   :PROPERTIES:
-   :CUSTOM_ID: gpgme-texi
-   :END:
-** TODO Update TODO file
-   :PROPERTIES:
-   :CUSTOM_ID: todo-update
-   :END:
-
-*** DONE fix TODO items
-    CLOSED: [2018-03-04 Sun 08:55]
-    :PROPERTIES:
-    :CUSTOM_ID: fix-todo-items
-    :END:
-
-    Adjust todo items so each can now be referenced by custom-id and
-    checked off as necessary.
-
 * Engines
   :PROPERTIES:
   :CUSTOM_ID: engines
   :END:
+
 ** Do not create/destroy engines, but create engine and then reset it.
    :PROPERTIES:
    :CUSTOM_ID: reset-engine-is-not-quite-just-ignition
@@ -321,26 +358,31 @@ Hey Emacs, this is -*- org -*- mode!
    Note that we need support in gpgsm to set include-certs to default
    as RESET does not reset it, also for no_encrypt_to and probably
    other options.
+
 ** Optimize the case where a data object has an underlying fd we can pass
    :PROPERTIES:
    :CUSTOM_ID: optimus-data-cousin-of-optimus-prime
    :END:
    directly to the engine.  This will be automatic with socket I/O and
    descriptor passing.
+
 ** Move code common to all engines up from gpg to engine.
    :PROPERTIES:
    :CUSTOM_ID: move-code-common-to-engines-out-of-gpg
    :END:
+
 ** engine operations can return General Error on unknown protocol
    :PROPERTIES:
    :CUSTOM_ID: general-error-looking-to-be-court-martialled
    :END:
    (it's an internal error, as select_protocol checks already).
+
 ** When server mode is implemented properly, more care has to be taken to
    :PROPERTIES:
    :CUSTOM_ID: server-mode
    :END:
    release all resources on error (for example to free assuan_cmd).
+
 ** op_import_keys and op_export_keys have a limit in the number of keys.
    :PROPERTIES:
    :CUSTOM_ID: import-export-problems
@@ -354,6 +396,7 @@ Hey Emacs, this is -*- org -*- mode!
   :PROPERTIES:
   :CUSTOM_ID: gpg-breakage
   :END:
+
 ** CANCELLED gpg 1.4.2 lacks error reporting if sign/encrypt with revoked key.
    CLOSED: [2018-03-09 Fri 08:19]
    :PROPERTIES:
@@ -361,6 +404,7 @@ Hey Emacs, this is -*- org -*- mode!
    :END:
    - State "CANCELLED"  from "TODO"       [2018-03-09 Fri 08:19] \\
      WON'T FIX.
+
 ** CANCELLED gpg 1.4.2 does crappy error reporting (namely none at all) when
    CLOSED: [2018-03-09 Fri 08:20]
    :PROPERTIES:
@@ -374,6 +418,7 @@ Hey Emacs, this is -*- org -*- mode!
     gpg: signing failed: general error
     [GNUPG:] BEGIN_ENCRYPTION 2 10
     gpg: test: sign+encrypt failed: general error
+
 ** DONE Without agent and with wrong passphrase, gpg 1.4.2 enters into an
    CLOSED: [2018-03-09 Fri 08:20]
    :PROPERTIES:
@@ -382,6 +427,7 @@ Hey Emacs, this is -*- org -*- mode!
    - State "DONE"       from "TODO"       [2018-03-09 Fri 08:20] \\
      Must have been fixed in a subsequent release.
    infinite loop.
+
 ** CANCELLED Use correct argv[0]
    CLOSED: [2018-03-09 Fri 08:24]
    :PROPERTIES:
@@ -402,71 +448,86 @@ Hey Emacs, this is -*- org -*- mode!
   :PROPERTIES:
   :CUSTOM_ID: operations-are-not-surgical
   :END:
+
 ** Include cert values -2, -1, 0 and 1 should be defined as macros.
    :PROPERTIES:
    :CUSTOM_ID: certified-macros
    :END:
+
 ** If an operation failed, make sure that the result functions don't return
    :PROPERTIES:
    :CUSTOM_ID: operation-failure
    :END:
    corrupt partial information. !!!
    NOTE: The EOF status handler is not called in this case !!!
+
 ** Verify must not fail on NODATA premature if auto-key-retrieval failed.
    :PROPERTIES:
    :CUSTOM_ID: autobot-key-retrieval
    :END:
    It should not fail silently if it knows there is an error. !!!
+
 ** All operations: Better error reporting. !!
    :PROPERTIES:
    :CUSTOM_ID: better-reporting-not-like-fox-news
    :END:
+
 ** Export status handler need much more work. !!!
    :PROPERTIES:
    :CUSTOM_ID: export-status-handler
    :END:
+
 ** Import should return a useful error when one happened.
    :PROPERTIES:
    :CUSTOM_ID: import-useful-stuff-even-wrong-stuff
    :END:
+
 *** Import does not take notice of NODATA status report.
     :PROPERTIES:
     :CUSTOM_ID: import-no-data
     :END:
+
 *** When GPGSM does issue IMPORT_OK status reports, make sure to check for
     :PROPERTIES:
     :CUSTOM_ID: gpgsm-import-ok
     :END:
     them in tests/gpgs m/t-import.c.
+
 ** Verify can include info about version/algo/class, but currently
    :PROPERTIES:
    :CUSTOM_ID: verify-class
    :END:
    this is only available for gpg, not gpgsm.
+
 ** Return ENC_TO output in verify result.  Again, this is not available
    :PROPERTIES:
    :CUSTOM_ID: return-to-enc
    :END:
    for gpgsm.
+
 ** Genkey should return something more useful than General_Error.
    :PROPERTIES:
    :CUSTOM_ID: general-key-assumed-command-from-general-error
    :END:
+
 ** If possible, use --file-setsize to set the file size for proper progress
    :PROPERTIES:
    :CUSTOM_ID: file-setsize
    :END:
    callback handling.  Write data interface for file size.
+
 ** Optimize the file descriptor list, so the number of open fds is
    :PROPERTIES:
    :CUSTOM_ID: optimus-descriptus-younger-brother-of-optimus-prime
    :END:
    always known easily.
+
 ** Encryption: It should be verified that the behaviour for partially untrusted
    :PROPERTIES:
    :CUSTOM_ID: only-mostly-dead-means-partially-alive
    :END:
    recipients is correct.
+
 ** When GPG issues INV_something for invalid signers, catch them.
    :PROPERTIES:
    :CUSTOM_ID: invalid-sig
@@ -477,15 +538,18 @@ Hey Emacs, this is -*- org -*- mode!
   :PROPERTIES:
   :CUSTOM_ID: error-value
   :END:
+
 ** Map ASSUAN/GpgSM ERR error values in a better way than is done now. !!
    :PROPERTIES:
    :CUSTOM_ID: map-ass-error
    :END:
+
 ** Some error values should identify the source more correctly (mostly error
    :PROPERTIES:
    :CUSTOM_ID: source-errors
    :END:
    values derived from status messages).
+
 ** In rungpg.c we need to check the version of the engine
    :PROPERTIES:
    :CUSTOM_ID: rungpg-c-engine-ver
@@ -498,6 +562,7 @@ Hey Emacs, this is -*- org -*- mode!
   :PROPERTIES:
   :CUSTOM_ID: tests
   :END:
+
 ** TODO Write a fake gpg-agent so that we can supply known passphrases to
    :PROPERTIES:
    :CUSTOM_ID: test-fake-gpg-agent
@@ -505,23 +570,28 @@ Hey Emacs, this is -*- org -*- mode!
    gpgsm and setup the configuration files to use the agent.  Without
    this we are testing a currently running gpg-agent which is not a
    clever idea. !
+
 ** t-data
    :PROPERTIES:
    :CUSTOM_ID: test-data
    :END:
+
 *** Test gpgme_data_release_and_get_mem.
     :PROPERTIES:
     :CUSTOM_ID: test-gpgme-data-release-mem
     :END:
+
 *** Test gpgme_data_seek for invalid types.
     :PROPERTIES:
     :CUSTOM_ID: test-gpgme-data-seek
     :END:
+
 ** t-keylist
    :PROPERTIES:
    :CUSTOM_ID: test-keylist
    :END:
    Write a test for ext_keylist.
+
 ** Test reading key signatures.
    :PROPERTIES:
    :CUSTOM_ID: test-key-sig
@@ -532,6 +602,7 @@ Hey Emacs, this is -*- org -*- mode!
   :PROPERTIES:
   :CUSTOM_ID: debug
   :END:
+
 ** Tracepoints should be added at: Every public interface enter/leave,
    :PROPERTIES:
    :CUSTOM_ID: tracepoint-pub-int
@@ -547,6 +618,7 @@ Hey Emacs, this is -*- org -*- mode!
    decrypt-verify.c delete.c edit.c encrypt.c encrypt-sign.c export.c
    genkey.c import.c key.c keylist.c passphrase.c progress.c signers.c
    sig-notation.c trust-item.c trustlist.c verify.c
+
 ** TODO Handle malloc and vasprintf errors.  But decide first if they should be
    :PROPERTIES:
    :CUSTOM_ID: malloc-vasprintf
@@ -559,10 +631,12 @@ Hey Emacs, this is -*- org -*- mode!
   :PROPERTIES:
   :CUSTOM_ID: build-suite
   :END:
+
 ** TODO Make sure everything is cleaned correctly (esp. test area).
    :PROPERTIES:
    :CUSTOM_ID: clean-tests
    :END:
+
 ** TODO Enable AC_CONFIG_MACRO_DIR and bump up autoconf version requirement.
    :PROPERTIES:
    :CUSTOM_ID: autoconf-macros
@@ -575,6 +649,7 @@ Hey Emacs, this is -*- org -*- mode!
   :PROPERTIES:
   :CUSTOM_ID: error-checking
   :END:
+
 ** TODO engine-gpgsm, with-validation
    :PROPERTIES:
    :CUSTOM_ID: gpgsm-validation
@@ -615,7 +690,11 @@ Hey Emacs, this is -*- org -*- mode!
    Write a guide/best practices for maintainers of GPGME packages with
    third party package management systems.
 
-Copyright 2004, 2005, 2018 g10 Code GmbH
+
+* Copyright 2004, 2005, 2018 g10 Code GmbH
+  :PROPERTIES:
+  :CUSTOM_ID: copyright-and-license
+  :END:
 
 This file is free software; as a special exception the author gives
 unlimited permission to copy and/or distribute it, with or without
diff --git a/lang/python/docs/GPGMEpythonHOWTOen.org b/lang/python/docs/GPGMEpythonHOWTOen.org
new file mode 100644 (file)
index 0000000..17ec428
--- /dev/null
@@ -0,0 +1,456 @@
+#+TITLE: GNU Privacy Guard (GnuPG)  Made Easy Python Bindings HOWTO (English)
+#+LATEX_COMPILER: xelatex
+#+LATEX_CLASS: article
+#+LATEX_CLASS_OPTIONS: [12pt]
+#+LATEX_HEADER: \usepackage{xltxtra}
+#+LATEX_HEADER: \usepackage[margin=1in]{geometry}
+#+LATEX_HEADER: \setmainfont[Ligatures={Common}]{Times New Roman}
+#+LATEX_HEADER: \author{Ben McGinnes <ben@gnupg.org>}
+
+
+* Introduction
+  :PROPERTIES:
+  :CUSTOM_ID: intro
+  :END:
+
+Version: 0.0.1-alpha [2018-03-07 Wed]
+Author: Ben McGinnes <ben@gnupg.org>
+Author GPG Key: DB4724E6FA4286C92B4E55C4321E4E2373590E5D
+
+This document provides basic instruction in how to use the GPGME
+Python bindings to programmatically leverage the GPGME library.
+
+
+* GPGME Concepts
+  :PROPERTIES:
+  :CUSTOM_ID: gpgme-concepts
+  :END:
+
+** A C API
+   :PROPERTIES:
+   :CUSTOM_ID: gpgme-c-api
+   :END:
+
+   Unlike many modern APIs with which programmers will be more
+   familiar with these days, the GPGME API is a C API.  The API is
+   intended for use by C coders who would be able to access its
+   features by including the =gpgme.h= header file eith their own C
+   source code and then access its functions just as they would any
+   other C headers.
+
+   This is a very effective method of gaining complete access to the
+   API and in the most efficient manner possible.  It does, however,
+   have the drawback that it cannot be directly used by other
+   languages without some means of providing an interface to those
+   languages.  This is where the need for bindings in various
+   languages stems.
+
+** Python bindings
+   :PROPERTIES:
+   :CUSTOM_ID: gpgme-python-bindings
+   :END:
+
+   The Python bindings for GPGME provide a higher level means of
+   accessing the complete feature set of GPGME itself.  It also
+   provides a more pythonic means of calling these API functions.
+
+   The bindings are generated dynamically with SWIG and the copy of
+   =gpgme.h= generated when GPGME is compiled.
+
+   This means that a version of the Python bindings is fundamentally
+   tied to the exact same version of GPGME used to gemerate that copy
+   of =gpgme.h=.
+
+** Difference between the Python bindings and other GnuPG Python packages
+   :PROPERTIES:
+   :CUSTOM_ID: gpgme-python-bindings-diffs
+   :END:
+
+   There have been numerous attempts to add GnuPG support to Python
+   over the years.  Some of the most well known are listed here, along
+   with what differentiates them.
+
+*** The python-gnupg package maintained by Vinay Sajip
+    :PROPERTIES:
+    :CUSTOM_ID: diffs-python-gnupg
+    :END:
+
+    This is arguably the most popular means of integrating GPG with
+    Python.  The package utilises the =subprocess= module to implement
+    wrappers for the =gpg= and =gpg2= executables normally invoked on
+    the command line (=gpg.exe= and =gpg2.exe= on Windows).
+
+    The popularity of this package stemmed from its ease of use and
+    capability in providing the most commonly required features.
+
+    Unfortunately it has been beset by a number of security issues,
+    most of which stemmed from using unsafe methods of accessing the
+    command line via the =subprocess= calls.
+
+    The python-gnupg package is available under the MIT license.
+
+*** The gnupg package created and maintained by Isis Lovecruft
+    :PROPERTIES:
+    :CUSTOM_ID: diffs-isis-gnupg
+    :END:
+
+    In 2015 Isis Lovecruft from the Tor Project forked and then
+    re-implemented the python-gnupg package as just gnupg.  This new
+    package also relied on subprocess to call the =gpg= or =gpg2=
+    binaries, but did so somewhat more securely.
+
+    However the naming and version numbering selected for this package
+    resulted in conflicts with the original python-gnupg and since its
+    functions were called in a different manner, the release of this
+    package also resulted in a great deal of consternation when people
+    installed what they thought was an upgrade that subsequently broke
+    the code relying on it.
+
+    The gnupg package is available under the GNU General Public
+    License version 3.0 (or later).
+
+*** The PyME package maintained by Martin Albrecht
+    :PROPERTIES:
+    :CUSTOM_ID: diffs-pyme
+    :END:
+
+    This package is the origin of these bindings, though they are
+    somewhat different now.  For details of when and how the PyME
+    package was folded back into GPGME itself see the [[Short_History.org][Short History]]
+    document in this Python bindings =docs= directory.
+
+    The PyME package was first released in 2002 and was also the first
+    attempt to implement a low level binding to GPGME.  In doing so it
+    provided access to considerably more functionality than either the
+    =python-gnupg= or =gnupg= packages.
+
+    The PyME package is only available for Python 2.6 and 2.7.
+
+    Porting the PyME package to Python 3.4 in 2015 is what resulted in
+    it being folded into the GPGME project and the current bindings
+    are the end result of that effort.
+
+    The PyME package is available under the same dual licensing as
+    GPGME itself: the GNU General Public License version 2.0 (or any
+    later version) and the GNU Lesser Public License version 2.1 (or
+    any later version).
+
+
+* GPGME Python bindings installation
+  :PROPERTIES:
+  :CUSTOM_ID: gpgme-python-install
+  :END:
+
+** No PyPI
+   :PROPERTIES:
+   :CUSTOM_ID: do-not-use-pypi
+   :END:
+
+   Most third-party Python packages and modules are available and
+   distributed through the Python Package Installer, known as PyPI.
+
+   Due to the nature of what these bindings are and how they work, it
+   is infeasible to install the GPGME Python bindings in the same way.
+
+** Requirements
+   :PROPERTIES:
+   :CUSTOM_ID: gpgme-python-requirements
+   :END:
+
+   The GPGME Python bindings only have three requirements:
+
+   1. A suitable version of Python 2 or Python 3.  With Python 2 that
+      means Python 2.7 and with Python 3 that means Python 3.4 or
+      higher.
+   2. SWIG.
+   3. GPGME itself.  Which also means that all of GPGME's dependencies
+      must be installed too.
+
+** Installation
+   :PROPERTIES:
+   :CUSTOM_ID: installation
+   :END:
+
+   Installing the Python bindings is effectively achieved by compiling
+   and installing GPGME itself.
+
+   Once SWIG is installed with Python and all the dependencies for
+   GPGME are installed you only need to confirm that the version(s) of
+   Python you want the bindings installed for are in your =$PATH=.
+
+   By default GPGME will attempt to install the bindings for the most
+   recent or highest version number of Python 2 and Python 3 it
+   detects in =$PATH=.  It specifically checks for the =python= and
+   =python3= executabled first and then checks for specific version
+   numbers.
+
+   For Python 2 it checks for these executables in this order:
+   =python=, =python2= and =python2.7=.
+
+   For Python 3 it checks for these executables in this order:
+   =python3=, =python3.6=, =python3.5= and =python3.4=.
+
+*** Installing GPGME
+    :PROPERTIES:
+    :CUSTOM_ID: install-gpgme
+    :END:
+
+    See the [[../../../README][GPGME README file]] for details of how to install GPGME from
+    source.
+
+
+* Fundamentals
+  :PROPERTIES:
+  :CUSTOM_ID: howto-fund-a-mental
+  :END:
+
+  Before we can get to the fun stuff, there are a few matters
+  regarding GPGME's design which hold true whether you're dealing with
+  the C code directly or these Python bindings.
+
+** No REST
+   :PROPERTIES:
+   :CUSTOM_ID: no-rest-for-the-wicked
+   :END:
+
+   The first part of which is or will be fairly blatantly obvious upon
+   viewing the first example, but it's worth reiterating anyway.  That
+   being that this API is /*not*/ a REST API.  Nor indeed could it
+   ever be one.
+
+   Most, if not all, Python programmers (and not just Python
+   programmers) know how easy it is to work with a RESTful API.  In
+   fact they've become so popular that many other APIs attempt to
+   emulate REST-like behaviour as much as they are able.  Right down
+   to the use of JSON formatted output to facilitate the use of their
+   API without having to retrain developers.
+
+   This API does not do that.  It would not be able to do that and
+   also provide access to the entire C API on which it's built.  It
+   does, however, provide a very pythonic interface on top of the
+   direct bindings and it's this pythonic layer with which this HOWTO
+   deals with.
+
+** Context
+   :PROPERTIES:
+   :CUSTOM_ID: howto-get-context
+   :END:
+
+   One of the reasons which prevents this API from being RESTful is
+   that most operations require more than one instruction to the API
+   to perform the task.  Sure, there are certain functions which can
+   be performed simultaneously, particularly if the result known or
+   strongly anticipated (e.g selecting and encrypting to a key known
+   to be in the public keybox).
+
+   There are many more, however, which cannot be manipulated so
+   readily: they must be performed in a specific sequence and the
+   result of one operation has a direct bearing on the outcome of
+   subsequent operations.  Not merely by generating an error either.
+
+   When dealing with this type of persistant state on the web, full of
+   both the RESTful and REST-like, it's most commonly referred to as a
+   session.  In GPGME, however, it is called a context and every
+   operation type has one.
+
+
+* Basic Functions
+  :PROPERTIES:
+  :CUSTOM_ID: howto-the-basics
+  :END:
+
+** Encryption
+   :PROPERTIES:
+   :CUSTOM_ID: howto-basic-encryption
+   :END:
+
+   Encrypting to one key:
+
+   #+begin_src python
+     import gpg
+     import os
+
+     rkey = "0x12345678DEADBEEF"
+     text = """
+     Some plain text to test with.  Obtained from any input source Python can read.
+
+     It makes no difference whether it is string or bytes, but the bindings always
+     produce byte output data.  Which is useful to know when writing out either the
+     encrypted or decrypted results.
+
+     """
+
+     plain = gpg.core.Data(text)
+     cipher = gpg.core.Data()
+     c = gpg.core.Context()
+     c.set_armor(1)
+
+     c.op_keylist_start(rkey, 0)
+     r = c.op_keylist_next()
+
+     if r == None:
+        print("""The key for user "{0}" was not found""".format(rkey))
+     else:
+        try:
+            c.op_encrypt([r], 1, plain, cipher)
+            cipher.seek(0, os.SEEK_SET)
+            del(text)
+            del(plain)
+            afile = open("secret_plans.org.asc", "wb")
+            afile.write(cipher.read())
+            afile.close()
+        except gpg.errors.GPGMEError as ex:
+            print(ex.getstring())
+   #+end_src
+
+** Decryption
+   :PROPERTIES:
+   :CUSTOM_ID: howto-basic-encryption
+   :END:
+
+   Decrypting something encrypted to a key in one's secret keyring
+   (will display some extra data you normally wouldn't show, but which
+   may be of use):
+
+   #+begin_src python
+     import os.path
+     import gpg
+
+     if os.path.exists("/path/to/secret_plans.org.asc") is True:
+        ciphertext = "/path/to/secret_plans.org.asc"
+     elif os.path.exists("/path/to/secret_plans.org.gpg") is True:
+        ciphertext = "/path/to/secret_plans.org.gpg"
+     else:
+        ciphertext = None
+
+     if ciphertext is not None:
+        afile = open(ciphertext, "rb")
+        plaintext = gpg.Context().decrypt(afile)
+        afile.close()
+        newfile = open("/path/to/secret_plans.org", "wb")
+        newfile.write(plaintext[0])
+        newfile.close()
+        print(plaintext[0])
+        plaintext[1]
+        plaintext[2]
+        del(plaintext)
+     else:
+        pass
+   #+end_src
+
+** Signing text
+   :PROPERTIES:
+   :CUSTOM_ID: howto-basic-signing
+   :END:
+
+   Need to determine whether or not to include clearsigning and
+   detached signing here or give them separate sections.
+
+   #+begin_src python
+     import gpg
+
+     text = """Declaration of ... something.
+
+     """
+
+     c = gpg.Context()
+     c.armor = True
+     signed = c.sign(text, mode=mode.NORMAL)
+
+     afile = open("/path/to/statement.txt.asc", "w")
+     for i in range(len(signed[0].splitlines())):
+        afile.write("{0}\n".format(signed[0].splitlines()[i].decode('utf-8')))
+     afile.close()
+   #+end_src
+
+   Clearsigning:
+
+   #+begin_src python
+     import gpg
+
+     text = """Declaration of ... something.
+
+     """
+
+     c = gpg.Context()
+     c.armor = True
+     signed = c.sign(text, mode=mode.CLEAR)
+
+     afile = open("/path/to/statement.txt.asc", "w")
+     for i in range(len(signed[0].splitlines())):
+        afile.write("{0}\n".format(signed[0].splitlines()[i].decode('utf-8')))
+     afile.close()
+   #+end_src
+
+   Detached ASCII Armoured signing:
+
+   #+begin_src python
+     import gpg
+
+     text = """Declaration of ... something.
+
+     """
+
+     c = gpg.Context()
+     c.armor = True
+     signed = c.sign(text, mode=mode.DETACH)
+
+     afile = open("/path/to/statement.txt.asc", "w")
+     for i in range(len(signed[0].splitlines())):
+        afile.write("{0}\n".format(signed[0].splitlines()[i].decode('utf-8')))
+     afile.close()
+   #+end_src
+
+   Detached binary signing (maybe change text to be reading a file's
+   content):
+
+   #+begin_src python
+import gpg
+
+text = """Declaration of ... something.
+
+"""
+
+c = gpg.Context()
+c.armor = True
+signed = c.sign(text, mode=mode.DETACH)
+
+afile = open("/path/to/statement.txt.sig", "wb")
+afile.write(signed[0])
+afile.close()
+   #+end_src
+
+
+** Signature verification
+   :PROPERTIES:
+   :CUSTOM_ID: howto-basic-verification
+   :END:
+
+x
+
+
+* Copyright and Licensing
+  :PROPERTIES:
+  :CUSTOM_ID: copyright-and-license
+  :END:
+
+** Copyright (C) The GnuPG Project, 2018
+   :PROPERTIES:
+   :CUSTOM_ID: copyright
+   :END:
+
+   Copyright © The GnuPG Project, 2018.
+
+** License GPL compatible
+   :PROPERTIES:
+   :CUSTOM_ID: license
+   :END:
+
+   This file is free software; as a special exception the author gives
+   unlimited permission to copy and/or distribute it, with or without
+   modifications, as long as this notice is preserved.
+
+   This file is distributed in the hope that it will be useful, but
+   WITHOUT ANY WARRANTY, to the extent permitted by law; without even
+   the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+   PURPOSE.
index 9f039d8..897c617 100644 (file)
    to produce reST versions via Pandoc and DITA XML can be reached
    through converting to either Markdown or XHTML first.
 
-** TODO Documentation HOWTO
+** STARTED Documentation HOWTO
    :PROPERTIES:
    :CUSTOM_ID: todo-docs-howto
    :END:
 
+   - State "STARTED"    from "TODO"       [2018-03-08 Thu 13:59] \\
+     Started yesterday.
    Write a HOWTO style guide for the current Python bindings.
 
+*** DONE Start python bindings HOWTO
+    CLOSED: [2018-03-07 Wed 18:14]
+    :PROPERTIES:
+    :CUSTOM_ID: howto-start
+    :END:
+
+*** TODO Include certain specific instructions in the HOWTO
+    :PROPERTIES:
+    :CUSTOM_ID: howto-requests
+    :END:
+
+    Some functions can be worked out from the handful of examples
+    available, but many more can't and I've already begun receiving
+    requests for certain functions to be explained.
+
+**** TODO Standard scenarios
+     :PROPERTIES:
+     :CUSTOM_ID: howto-the-basics
+     :END:
+
+     What everyone expects: encryption, decryption, signing and verifying.
+
+**** TODO Key control
+     :PROPERTIES:
+     :CUSTOM_ID: howto-key-control
+     :END:
+
+     Generating keys, adding subkeys, revoking subkeys (and keeping
+     the cert key), adding and revoking UIDs, signing/certifying keys.
+
+**** TODO Key control
+     :PROPERTIES:
+     :CUSTOM_ID: howto-key-selection
+     :END:
+
+     Selecting keys to encrypt to or manipulate in other ways (e.g. as
+     with key control or the basics).
+
+**** TODO S/MIME
+     :PROPERTIES:
+     :CUSTOM_ID: howto-s-mime
+     :END:
+
+     Eventually add some of this, but it the OpenPGP details are far
+     more important at the moment.
+
 ** TODO Documentation SWIG
    :PROPERTIES:
    :CUSTOM_ID: todo-docs-swig
    available or for which it is too difficult to create proper
    bindings.
 
+
 * Project Task Details
   :PROPERTIES:
   :CUSTOM_ID: detailed-tasks
index 3e2dc78..e7a7a6f 100644 (file)
@@ -3101,7 +3101,7 @@ cmd_hash_algo_name (assuan_context_t ctx, char *line)
 
 
 static const char hlp_identify[] =
-  "IDENTIY\n"
+  "IDENTIFY\n"
   "\n"
   "Identify the type of data set with the INPUT command.";
 static gpg_error_t