docs: python bindings HOWTO - DITA XML version

* Due to the org-babel bug which breaks Python source code examples beyond the most simple snippets, ported the HOWTO to a source format which I *know* for sure won't break it. * Details of the org-mode bug is in https://dev.gnupg.org/T3977 * DITA project uses DITA-OT 2.x (2.4 or 2.5, IIRC) with support for DITA 1.3. * source files were written with oXygenXML Editor 20.0, hence the oXygenXML project file in the directory; however only the .ditamap and .dita files are required to generate any output with the DITA-OT. Signed-off-by: Ben McGinnes <[email protected]>
author: Ben McGinnes <[email protected]> 2018-05-15 03:13:16 +0000
committer: Ben McGinnes <[email protected]> 2018-05-15 03:13:16 +0000
commit: f0063afa71bc7e71f19d174acc2fde26f0c11850 (patch)
tree: a23a33ef70f13747642a8c96e7128e41b5f7ce58 /lang/python/docs/dita/howto/part03
parent: json: Improve auto-base64 encoding to not split UTF-8 chars. (diff)
download: gpgme-f0063afa71bc7e71f19d174acc2fde26f0c11850.tar.gz
gpgme-f0063afa71bc7e71f19d174acc2fde26f0c11850.zip
3 files changed, 121 insertions, 0 deletions
diff --git a/lang/python/docs/dita/howto/part03/get-key.dita b/lang/python/docs/dita/howto/part03/get-key.dita
new file mode 100644
index 00000000..1e3309c2
--- /dev/null
+++ b/lang/python/docs/dita/howto/part03/get-key.dita
@@ -0,0 +1,37 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE dita PUBLIC "-//OASIS//DTD DITA Composite//EN" "ditabase.dtd">
+<dita>
+    <topic id="topic_j3h_5my_5db">
+        <title>Get Key</title>
+        <body>
+            <p>An alternative method of getting a single key via its fingerprint is available
+        directly within a Context with Context().get_key. This is the preferred method of selecting
+        a key in order to modify it, sign or certify it and for obtaining relevant data about a
+        single key as a part of other functions; when verifying a signature made by that key, for
+        instance.</p>
+      <p>By default this method will select public keys, but it can select secret keys as well.</p>
+      <p>This first example demonstrates selecting the current key of Werner Koch, which is due to
+        expire at the end of 2018:</p>
+      <p>
+        <codeblock id="getkey-1" outputclass="language-python">import gpg
+
+fingerprint = "80615870F5BAD690333686D0F2AD85AC1E42B367"
+key = gpg.Context().get_key(fingerprint)
+        </codeblock>
+      </p>
+      <p>Whereas this example demonstrates selecting the author's current key with the secret key
+        word argument set to True:</p>
+      <p>
+        <codeblock id="getkey-2" outputclass="language-python">import gpg
+
+fingerprint = "DB4724E6FA4286C92B4E55C4321E4E2373590E5D"
+key = gpg.Context().get_key(fingerprint, secret=True)
+        </codeblock>
+      </p>
+      <p>It is, of course, quite possible to select expired, disabled and revoked keys with this
+        function, but only to effectively display information about those keys.</p>
+      <p>It is also possible to use both unicode or string literals and byte literals with the
+        fingerprint when getting a key in this way.</p>
+        </body>
+    </topic>
+</dita>
diff --git a/lang/python/docs/dita/howto/part03/key-counting.dita b/lang/python/docs/dita/howto/part03/key-counting.dita
new file mode 100644
index 00000000..b26fbd2d
--- /dev/null
+++ b/lang/python/docs/dita/howto/part03/key-counting.dita
@@ -0,0 +1,31 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE dita PUBLIC "-//OASIS//DTD DITA Composite//EN" "ditabase.dtd">
+<dita>
+  <topic id="topic_jgw_wly_5db">
+    <title>Counting Keys</title>
+    <body>
+      <p>Counting the number of keys in your public keybox (<filepath>pubring.kbx</filepath>), the
+        format which has superseded the old keyring format (<filepath>pubring.gpg</filepath> and
+          <filepath>secring.gpg</filepath>), or the number of secret keys is a very simple task.</p>
+      <p>
+        <codeblock id="kc" outputclass="language-python">import gpg
+
+c = gpg.Context()
+seckeys = c.keylist(pattern=None, secret=True)
+pubkeys = c.keylist(pattern=None, secret=False)
+
+seclist = list(seckeys)
+secnum = len(seclist)
+
+publist = list(pubkeys)
+pubnum = len(publist)
+
+print("""
+Number of secret keys:  {0}
+Number of public keys:  {1}
+""".format(secnum, pubnum))
+</codeblock>
+      </p>
+    </body>
+  </topic>
+</dita>
diff --git a/lang/python/docs/dita/howto/part03/key-selection.dita b/lang/python/docs/dita/howto/part03/key-selection.dita
new file mode 100644
index 00000000..3e51a4da
--- /dev/null
+++ b/lang/python/docs/dita/howto/part03/key-selection.dita
@@ -0,0 +1,53 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE dita PUBLIC "-//OASIS//DTD DITA Composite//EN" "ditabase.dtd">
+<dita>
+  <topic id="topic_flg_p3y_5db">
+    <title>Key Selection</title>
+    <body>
+      <p>Selecting keys to encrypt to or to sign with will be a common occurrence when working with
+        GPGMe and the means available for doing so are quite simple.</p>
+      <p>They do depend on utilising a Context; however once the data is recorded in another
+        variable, that Context does not need to be the same one which subsequent operations are
+        performed.</p>
+      <p>The easiest way to select a specific key is by searching for that key's key ID or
+        fingerprint, preferably the full fingerprint without any spaces in it. A long key ID will
+        probably be okay, but is not advised and short key IDs are already a problem with some being
+        generated to match specific patterns. It does not matter whether the pattern is upper or
+        lower case.</p>
+      <p>So this is the best method:</p>
+      <p>
+        <codeblock id="keysel-01" outputclass="language-python">import gpg
+
+k = gpg.Context().keylist(pattern="258E88DCBD3CD44D8E7AB43F6ECB6AF0DEADBEEF")
+keys = list(k)
+        </codeblock>
+      </p>
+      <p>This is passable and very likely to be common:</p>
+      <p>
+        <codeblock id="keysel-02" outputclass="language-python">import gpg
+
+k = gpg.Context().keylist(pattern="0x6ECB6AF0DEADBEEF")
+keys = list(k)
+        </codeblock>
+      </p>
+      <p>And this is a really bad idea:</p>
+      <p>
+        <codeblock id="keysel-03" outputclass="language-python">import gpg
+
+k = gpg.Context().keylist(pattern="0xDEADBEEF")
+keys = list(k)
+        </codeblock>
+      </p>
+      <p>Alternatively it may be that the intention is to create a list of keys which all match a
+        particular search string. For instance all the addresses at a particular domain, like
+        this:</p>
+      <p>
+        <codeblock id="keysel-04" outputclass="language-python">import gpg
+
+ncsc = gpg.Context().keylist(pattern="ncsc.mil")
+nsa = list(ncsc)
+        </codeblock>
+      </p>
+    </body>
+  </topic>
+</dita>
author	Ben McGinnes <[email protected]>	2018-05-15 03:13:16 +0000
committer	Ben McGinnes <[email protected]>	2018-05-15 03:13:16 +0000
commit	f0063afa71bc7e71f19d174acc2fde26f0c11850 (patch)
tree	a23a33ef70f13747642a8c96e7128e41b5f7ce58 /lang/python/docs/dita/howto/part03
parent	json: Improve auto-base64 encoding to not split UTF-8 chars. (diff)
download	gpgme-f0063afa71bc7e71f19d174acc2fde26f0c11850.tar.gz gpgme-f0063afa71bc7e71f19d174acc2fde26f0c11850.zip