Get Key

From f0063afa71bc7e71f19d174acc2fde26f0c11850 Mon Sep 17 00:00:00 2001 From: Ben McGinnes Date: Tue, 15 May 2018 13:13:16 +1000 Subject: 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 --- lang/python/docs/dita/howto/part03/get-key.dita | 37 +++++++++++++++ .../docs/dita/howto/part03/key-counting.dita | 31 +++++++++++++ .../docs/dita/howto/part03/key-selection.dita | 53 ++++++++++++++++++++++ 3 files changed, 121 insertions(+) create mode 100644 lang/python/docs/dita/howto/part03/get-key.dita create mode 100644 lang/python/docs/dita/howto/part03/key-counting.dita create mode 100644 lang/python/docs/dita/howto/part03/key-selection.dita (limited to 'lang/python/docs/dita/howto/part03') 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 @@ + + + + + Get Key + +

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.

By default this method will select public keys, but it can select secret keys as well.

This first example demonstrates selecting the current key of Werner Koch, which is due to + expire at the end of 2018:

+ import gpg + +fingerprint = "80615870F5BAD690333686D0F2AD85AC1E42B367" +key = gpg.Context().get_key(fingerprint) + +

Whereas this example demonstrates selecting the author's current key with the secret key + word argument set to True:

+ import gpg + +fingerprint = "DB4724E6FA4286C92B4E55C4321E4E2373590E5D" +key = gpg.Context().get_key(fingerprint, secret=True) + +

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.

It is also possible to use both unicode or string literals and byte literals with the + fingerprint when getting a key in this way.

+ + + 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 @@ + + + + + Counting Keys + +

Counting the number of keys in your public keybox (pubring.kbx), the + format which has superseded the old keyring format (pubring.gpg and + secring.gpg), or the number of secret keys is a very simple task.

+ 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)) + +

+ + + 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 @@ + + + + + Key Selection + +

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.

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.

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.

So this is the best method:

+ import gpg + +k = gpg.Context().keylist(pattern="258E88DCBD3CD44D8E7AB43F6ECB6AF0DEADBEEF") +keys = list(k) + +

This is passable and very likely to be common:

+ import gpg + +k = gpg.Context().keylist(pattern="0x6ECB6AF0DEADBEEF") +keys = list(k) + +

And this is a really bad idea:

+ import gpg + +k = gpg.Context().keylist(pattern="0xDEADBEEF") +keys = list(k) + +

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:

+ import gpg + +ncsc = gpg.Context().keylist(pattern="ncsc.mil") +nsa = list(ncsc) + +

+ + + -- cgit v1.2.3