1 files changed, 53 insertions, 0 deletions
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>