diff options
Diffstat (limited to 'lang/python/docs/dita/howto/part05')
| -rw-r--r-- | lang/python/docs/dita/howto/part05/add-uid.dita | 39 | ||||
| -rw-r--r-- | lang/python/docs/dita/howto/part05/certification.dita | 36 | ||||
| -rw-r--r-- | lang/python/docs/dita/howto/part05/key-creation.dita | 34 | ||||
| -rw-r--r-- | lang/python/docs/dita/howto/part05/primary-key.dita | 97 | ||||
| -rw-r--r-- | lang/python/docs/dita/howto/part05/rev-uid.dita | 24 | ||||
| -rw-r--r-- | lang/python/docs/dita/howto/part05/subkeys.dita | 53 | ||||
| -rw-r--r-- | lang/python/docs/dita/howto/part05/user-ids.dita | 10 |
7 files changed, 293 insertions, 0 deletions
diff --git a/lang/python/docs/dita/howto/part05/add-uid.dita b/lang/python/docs/dita/howto/part05/add-uid.dita new file mode 100644 index 00000000..4265d421 --- /dev/null +++ b/lang/python/docs/dita/howto/part05/add-uid.dita @@ -0,0 +1,39 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE dita PUBLIC "-//OASIS//DTD DITA Composite//EN" "ditabase.dtd"> +<dita> + <topic id="topic_e4q_jyz_5db"> + <title>Adding a User ID</title> + <body> + <p>By comparison to creating primary keys and subkeys, adding a new user ID to an existing key + is much simpler. The method used to do this is <codeph>key_add_uid</codeph> and the only + arguments it takes are for the <codeph>key</codeph> and the new <codeph>uid</codeph>.</p> + <p> + <codeblock id="adduid-1" outputclass="language-python">import gpg + +c = gpg.Context() +c.home_dir = "~/.gnupg-dm" + +dmfpr = "177B7C25DB99745EE2EE13ED026D2F19E99E63AA" +key = c.get_key(dmfpr, secret=True) +uid = "Danger Mouse <[email protected]>" + +c.key_add_uid(key, uid) +</codeblock> + </p> + <p>Unsurprisingly the result of this is:</p> + <p> + <codeblock id="adduid-2" outputclass="language-bourne">bash-4.4$ gpg --homedir ~/.gnupg-dm -K +~/.gnupg-dm/pubring.kbx +---------------------- +sec rsa3072 2018-03-15 [SC] [expires: 2019-03-15] + 177B7C25DB99745EE2EE13ED026D2F19E99E63AA +uid [ultimate] Danger Mouse <[email protected]> +uid [ultimate] Danger Mouse <[email protected]> +ssb rsa3072 2018-03-15 [E] [expires: 2018-09-13] + +bash-4.4$ +</codeblock> + </p> + </body> + </topic> +</dita> diff --git a/lang/python/docs/dita/howto/part05/certification.dita b/lang/python/docs/dita/howto/part05/certification.dita new file mode 100644 index 00000000..072c774e --- /dev/null +++ b/lang/python/docs/dita/howto/part05/certification.dita @@ -0,0 +1,36 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE dita PUBLIC "-//OASIS//DTD DITA Composite//EN" "ditabase.dtd"> +<dita> + <topic id="topic_p15_1yz_5db"> + <title>Key Certification</title> + <body> + <p>Since key certification is more frequently referred to as key signing, the method used to + perform this function is <codeph>key_sign</codeph>.</p> + <p>The <codeph>key_sign</codeph> method takes four arguments: <codeph>key</codeph>, + <codeph>uids</codeph>, <codeph>expires_in</codeph> and <codeph>local</codeph>. The default + value of <codeph>uids</codeph> is <codeph>None</codeph> and which results in all user IDs + being selected. The default value of both <codeph>expires_in</codeph> and + <codeph>local</codeph> is <codeph>False</codeph>; which results in the signature never + expiring and being able to be exported.</p> + <p>The <codeph>key</codeph> is the key being signed rather than the key doing the signing. To + change the key doing the signing refer to the signing key selection above for signing + messages and files.</p> + <p>If the <codeph>uids</codeph> value is not <codeph>None</codeph> then it must either be a + string to match a single user ID or a list of strings to match multiple user IDs. In this + case the matching of those strings must be precise and it is case sensitive.</p> + <p>To sign Danger Mouse's key for just the initial user ID with a signature which will last a + little over a month, do this:</p> + <p> + <codeblock id="cert-1" outputclass="language-python">import gpg + +c = gpg.Context() +uid = "Danger Mouse <[email protected]>" + +dmfpr = "177B7C25DB99745EE2EE13ED026D2F19E99E63AA" +key = c.get_key(dmfpr, secret=True) +c.key_sign(key, uidsuid, expires_in=2764800) +</codeblock> + </p> + </body> + </topic> +</dita> diff --git a/lang/python/docs/dita/howto/part05/key-creation.dita b/lang/python/docs/dita/howto/part05/key-creation.dita new file mode 100644 index 00000000..6478bf95 --- /dev/null +++ b/lang/python/docs/dita/howto/part05/key-creation.dita @@ -0,0 +1,34 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE dita PUBLIC "-//OASIS//DTD DITA Composite//EN" "ditabase.dtd"> +<dita> + <topic id="topic_c4z_syd_vdb"> + <title>Creating Keys and Subkeys</title> + <body> + <p>The one thing, aside from GnuPG itself, that GPGME depends on, of course, is the keys + themselves. So it is necessary to be able to generate them and modify them by adding + subkeys, revoking or disabling them, sometimes deleting them and doing the same for user + IDs.</p> + <p>In the following examples a key will be created for the world's greatest secret agent, + Danger Mouse. Since Danger Mouse is a secret agent he needs to be able to protect + information to <tt>SECRET</tt> level clearance, so his keys will be 3072-bit keys.</p> + <p>The pre-configured <filepath>gpg.conf</filepath> file which sets cipher, digest and other + preferences contains the following configuration parameters:</p> + <p> + <codeblock id="gpg-config">expert +allow-freeform-uid +allow-secret-key-import +trust-model tofu+pgp +tofu-default-policy unknown +enable-large-rsa +enable-dsa2 +cert-digest-algo SHA512 +default-preference-list TWOFISH CAMELLIA256 AES256 CAMELLIA192 AES192 CAMELLIA128 AES BLOWFISH IDEA CAST5 3DES SHA512 SHA384 SHA256 SHA224 RIPEMD160 SHA1 ZLIB BZIP2 ZIP Uncompressed +personal-cipher-preferences TWOFISH CAMELLIA256 AES256 CAMELLIA192 AES192 CAMELLIA128 AES BLOWFISH IDEA CAST5 3DES +personal-digest-preferences SHA512 SHA384 SHA256 SHA224 RIPEMD160 SHA1 +personal-compress-preferences ZLIB BZIP2 ZIP Uncompressed +</codeblock> + </p> + <p/> + </body> + </topic> +</dita> diff --git a/lang/python/docs/dita/howto/part05/primary-key.dita b/lang/python/docs/dita/howto/part05/primary-key.dita new file mode 100644 index 00000000..5401dc9f --- /dev/null +++ b/lang/python/docs/dita/howto/part05/primary-key.dita @@ -0,0 +1,97 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE dita PUBLIC "-//OASIS//DTD DITA Composite//EN" "ditabase.dtd"> +<dita> + <topic id="topic_nfy_byz_5db"> + <title>Primary Key Creation</title> + <body> + <p>Generating a primary key uses the <codeph>create_key</codeph> method in a Context. It + contains multiple arguments and keyword arguments, including: <codeph>userid</codeph>, + <codeph>algorithm</codeph>, <codeph>expires_in</codeph>, <codeph>expires</codeph>, + <codeph>sign</codeph>, <codeph>encrypt</codeph>, <codeph>certify</codeph>, + <codeph>authenticate</codeph>, <codeph>passphrase</codeph> and <codeph>force</codeph>. The + defaults for all of those except <codeph>userid</codeph>, <codeph>algorithm</codeph>, + <codeph>expires_in</codeph>, <codeph>expires</codeph> and <codeph>passphrase</codeph> is + <codeph>False</codeph>. The defaults for <codeph>algorithm</codeph> and + <codeph>passphrase</codeph> is <codeph>None</codeph>. The default for + <codeph>expires_in</codeph> is <codeph>0</codeph>. The default for + <codeph>expires</codeph> is <codeph>True</codeph>. There is no default for + <codeph>userid</codeph>.</p> + <p>If <codeph>passphrase</codeph> is left as <codeph>None</codeph> then the key will not be + generated with a passphrase, if <codeph>passphrase</codeph> is set to a string then that + will be the passphrase and if <codeph>passphrase</codeph> is set to <codeph>True</codeph> + then gpg-agent will launch pinentry to prompt for a passphrase. For the sake of convenience, + these examples will keep passphrase set to <codeph>None</codeph>.</p> + <p> + <codeblock id="keygen-1" outputclass="language-python">import gpg + +c = gpg.Context() + +c.home_dir = "~/.gnupg-dm" +userid = "Danger Mouse <[email protected]>" + +dmkey = c.create_key(userid, algorithm="rsa3072", expires_in=31536000, + sign=True, certify=True) +</codeblock> + </p> + <p>One thing to note here is the use of setting the <codeph>c.home_dir</codeph> parameter. + This enables generating the key or keys in a different location. In this case to keep the + new key data created for this example in a separate location rather than adding it to + existing and active key store data. As with the default directory, + <filepath>~/.gnupg</filepath>, any temporary or separate directory needs the permissions + set to only permit access by the directory owner. On posix systems this means setting the + directory permissions to <codeph>700</codeph>.</p> + <p>The <cmdname>temp-homedir-config.py</cmdname> script in the HOWTO examples directory will + create an alternative homedir with these configuration options already set and the correct + directory and file permissions.</p> + <p>The successful generation of the key can be confirmed via the returned + <codeph>GenkeyResult</codeph> object, which includes the following data:</p> + <p> + <codeblock id="keygen-2" outputclass="language-python">print(""" +Fingerprint: {0} +Primary Key: {1} + Public Key: {2} + Secret Key: {3} + Sub Key: {4} + User IDs: {5} +""".format(dmkey.fpr, dmkey.primary, dmkey.pubkey, dmkey.seckey, dmkey.sub, + dmkey.uid)) +</codeblock> + </p> + <p>Alternatively the information can be confirmed using the command line program:</p> + <p> + <codeblock id="keygen-3" outputclass="language-bourne">bash-4.4$ gpg --homedir ~/.gnupg-dm -K +~/.gnupg-dm/pubring.kbx +---------------------- +sec rsa3072 2018-03-15 [SC] [expires: 2019-03-15] + 177B7C25DB99745EE2EE13ED026D2F19E99E63AA +uid [ultimate] Danger Mouse <[email protected]> + +bash-4.4$ +</codeblock> + </p> + <p>As with generating keys manually, to preconfigure expanded preferences for the cipher, + digest and compression algorithms, the <filepath>gpg.conf</filepath> file must contain those + details in the home directory in which the new key is being generated. I used a cut down + version of my own <filepath>gpg.conf</filepath> file in order to be able to generate + this:</p> + <p> + <codeblock id="keygen-4" outputclass="language-bourne">bash-4.4$ gpg --homedir ~/.gnupg-dm --edit-key 177B7C25DB99745EE2EE13ED026D2F19E99E63AA showpref quit +Secret key is available. + +sec rsa3072/026D2F19E99E63AA + created: 2018-03-15 expires: 2019-03-15 usage: SC + trust: ultimate validity: ultimate +[ultimate] (1). Danger Mouse <[email protected]> + +[ultimate] (1). Danger Mouse <[email protected]> + Cipher: TWOFISH, CAMELLIA256, AES256, CAMELLIA192, AES192, CAMELLIA128, AES, BLOWFISH, IDEA, CAST5, 3DES + Digest: SHA512, SHA384, SHA256, SHA224, RIPEMD160, SHA1 + Compression: ZLIB, BZIP2, ZIP, Uncompressed + Features: MDC, Keyserver no-modify + +bash-4.4$ +</codeblock> + </p> + </body> + </topic> +</dita> diff --git a/lang/python/docs/dita/howto/part05/rev-uid.dita b/lang/python/docs/dita/howto/part05/rev-uid.dita new file mode 100644 index 00000000..18d6efbd --- /dev/null +++ b/lang/python/docs/dita/howto/part05/rev-uid.dita @@ -0,0 +1,24 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE dita PUBLIC "-//OASIS//DTD DITA Composite//EN" "ditabase.dtd"> +<dita> + <topic id="topic_fbb_lyz_5db"> + <title>Revoking a User ID</title> + <body> + <p>Revoking a user ID is a fairly similar process, except that it uses the + <codeph>key_revoke_uid</codeph> method.</p> + <p> + <codeblock id="revuid" outputclass="language-python">import gpg + +c = gpg.Context() +c.home_dir = "~/.gnupg-dm" + +dmfpr = "177B7C25DB99745EE2EE13ED026D2F19E99E63AA" +key = c.get_key(dmfpr, secret=True) +uid = "Danger Mouse <[email protected]>" + +c.key_revoke_uid(key, uid) +</codeblock> + </p> + </body> + </topic> +</dita> diff --git a/lang/python/docs/dita/howto/part05/subkeys.dita b/lang/python/docs/dita/howto/part05/subkeys.dita new file mode 100644 index 00000000..81491979 --- /dev/null +++ b/lang/python/docs/dita/howto/part05/subkeys.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_cb4_fyz_5db"> + <title>Subkey Creation</title> + <body> + <p>Adding subkeys to a primary key is fairly similar to creating the primary key with + the <codeph>create_subkey</codeph> method. Most of the arguments are the same, but not quite + all. Instead of the <codeph>userid</codeph> argument there is now a <codeph>key</codeph> + argument for selecting which primary key to add the subkey to.</p> + <p>In the following example an encryption subkey will be added to the primary key. Since + Danger Mouse is a security conscious secret agent, this subkey will only be valid for about + six months, half the length of the primary key.</p> + <p> + <codeblock id="subkey-1" outputclass="language-python">import gpg + +c = gpg.Context() +c.home_dir = "~/.gnupg-dm" + +key = c.get_key(dmkey.fpr, secret=True) +dmsub = c.create_subkey(key, algorithm="rsa3072", expires_in=15768000, + encrypt=True) +</codeblock> + </p> + <p>As with the primary key, the results here can be checked with:</p> + <p> + <codeblock id="subkey-2" outputclass="language-python">print(""" +Fingerprint: {0} +Primary Key: {1} + Public Key: {2} + Secret Key: {3} + Sub Key: {4} + User IDs: {5} +""".format(dmsub.fpr, dmsub.primary, dmsub.pubkey, dmsub.seckey, dmsub.sub, + dmsub.uid)) +</codeblock> + </p> + <p>As well as on the command line with:</p> + <p> + <codeblock id="subkey-3" outputclass="language-bourne">bash-4.4$ gpg --homedir ~/.gnupg-dm -K +~/.gnupg-dm/pubring.kbx +---------------------- +sec rsa3072 2018-03-15 [SC] [expires: 2019-03-15] + 177B7C25DB99745EE2EE13ED026D2F19E99E63AA +uid [ultimate] Danger Mouse <[email protected]> +ssb rsa3072 2018-03-15 [E] [expires: 2018-09-13] + +bash-4.4$ +</codeblock> + </p> + </body> + </topic> +</dita> diff --git a/lang/python/docs/dita/howto/part05/user-ids.dita b/lang/python/docs/dita/howto/part05/user-ids.dita new file mode 100644 index 00000000..9308c0a6 --- /dev/null +++ b/lang/python/docs/dita/howto/part05/user-ids.dita @@ -0,0 +1,10 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE dita PUBLIC "-//OASIS//DTD DITA Composite//EN" "ditabase.dtd"> +<dita> + <topic id="topic_d1j_hyz_5db"> + <title>User IDs</title> + <body> + <p></p> + </body> + </topic> +</dita> |