diff --git a/lang/python/docs/GPGMEpythonHOWTOen.org b/lang/python/docs/GPGMEpythonHOWTOen.org index 219f602d..cb85b61b 100644 --- a/lang/python/docs/GPGMEpythonHOWTOen.org +++ b/lang/python/docs/GPGMEpythonHOWTOen.org @@ -1,1370 +1,1406 @@ #+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 } +#+HTML_HEAD_EXTRA: * Introduction :PROPERTIES: :CUSTOM_ID: intro :END: | Version: | 0.1.0 | | Author: | Ben McGinnes | | Author GPG Key: | DB4724E6FA4286C92B4E55C4321E4E2373590E5D | | Language: | Australian English, British English | | xml:lang: | en-AU, en-GB, en | This document provides basic instruction in how to use the GPGME Python bindings to programmatically leverage the GPGME library. ** Python 2 versus Python 3 :PROPERTIES: :CUSTOM_ID: py2-vs-py3 :END: Though the GPGME Python bindings themselves provide support for both Python 2 and 3, the focus is unequivocally on Python 3 and specifically from Python 3.4 and above. As a consequence all the examples and instructions in this guide use Python 3 code. Much of it will work with Python 2, but much of it also deals with Python 3 byte literals, particularly when reading and writing data. Developers concentrating on Python 2.7, and possibly even 2.6, will need to make the appropriate modifications to support the older string and unicode types as opposed to bytes. There are multiple reasons for concentrating on Python 3; some of which relate to the immediate integration of these bindings, some of which relate to longer term plans for both GPGME and the python bindings and some of which relate to the impending EOL period for Python 2.7. Essentially, though, there is little value in tying the bindings to a version of the language which is a dead end and the advantages offered by Python 3 over Python 2 make handling the data types with which GPGME deals considerably easier. ** Examples :PROPERTIES: :CUSTOM_ID: howto-python3-examples :END: All of the examples found in this document can be found as Python 3 scripts in the =lang/python/examples/howto= directory. * 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 with 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 generate 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 in the past; most of which stemmed from using unsafe methods of accessing the command line via the =subprocess= calls. While some effort has been made over the last two to three years (as of 2018) to mitigate this, particularly by no longer providing shell access through those subprocess calls, the wrapper is still somewhat limited in the scope of its GnuPG features coverage. 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. The naming and version numbering selected for this package, however, resulted in conflicts with the original python-gnupg and since its functions were called in a different manner to python-gnupg, 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 any later version). *** 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/ - document[fn:1] in this Python bindings =docs= directory.[fn:2] + document[fn:1] in the Python bindings =docs= directory.[fn:2] 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 General 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. This is because the bindings use SWIG to dynamically generate C bindings against =gpgme.h= and =gpgme.h= is generated from =gpgme.h.in= at compile time when GPGME is built from source. Thus to include a package in PyPI which actually built correctly would require either statically built libraries for every architecture bundled with it or a full implementation of C for each architecture. ** 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= executables 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 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 persistent 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. * Working with keys :PROPERTIES: :CUSTOM_ID: howto-keys :END: ** Key selection :PROPERTIES: :CUSTOM_ID: howto-keys-selection :END: 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: #+begin_src python import gpg k = gpg.Context().keylist(pattern="258E88DCBD3CD44D8E7AB43F6ECB6AF0DEADBEEF") keys = list(k) #+end_src This is passable and very likely to be common: #+begin_src python import gpg k = gpg.Context().keylist(pattern="0x6ECB6AF0DEADBEEF") keys = list(k) #+end_src And this is a really bad idea: #+begin_src python import gpg k = gpg.Context().keylist(pattern="0xDEADBEEF") keys = list(k) #+end_src 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: #+begin_src python import gpg ncsc = gpg.Context().keylist(pattern="ncsc.mil") nsa = list(ncsc) #+end_src *** Counting keys :PROPERTIES: :CUSTOM_ID: howto-keys-counting :END: 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. #+begin_src 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)) #+end_src ** Get key :PROPERTIES: :CUSTOM_ID: howto-get-key :END: 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: #+begin_src python import gpg fingerprint = "80615870F5BAD690333686D0F2AD85AC1E42B367" key = gpg.Context().get_key(fingerprint) #+end_src Whereas this example demonstrates selecting the author's current key with the =secret= key word argument set to =True=: #+begin_src python import gpg fingerprint = "DB4724E6FA4286C92B4E55C4321E4E2373590E5D" key = gpg.Context().get_key(fingerprint, secret=True) #+end_src 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. * Basic Functions :PROPERTIES: :CUSTOM_ID: howto-the-basics :END: The most frequently called features of any cryptographic library will be the most fundamental tasks for encryption software. In this section we will look at how to programmatically encrypt data, decrypt it, sign it and verify signatures. ** Encryption :PROPERTIES: :CUSTOM_ID: howto-basic-encryption :END: Encrypting is very straight forward. In the first example below the message, =text=, is encrypted to a single recipient's key. In the second example the message will be encrypted to multiple recipients. *** Encrypting to one key :PROPERTIES: :CUSTOM_ID: howto-basic-encryption-single :END: Once the the Context is set the main issues with encrypting data is essentially reduced to key selection and the keyword arguments specified in the =gpg.Context().encrypt()= method. Those keyword arguments are: =recipients=, a list of keys encrypted to (covered in greater detail in the following section); =sign=, whether or not to sign the plaintext data, see subsequent sections on signing and verifying signatures below (defaults to =True=); =sink=, to write results or partial results to a secure sink instead of returning it (defaults to =None=); =passphrase=, only used when utilising symmetric encryption (defaults to =None=); =always_trust=, used to override the trust model settings for recipient keys (defaults to =False=); =add_encrypt_to=, utilises any preconfigured =encrypt-to= or =default-key= settings in the user's =gpg.conf= file (defaults to =False=); =prepare=, prepare for encryption (defaults to =False=); =expect_sign=, prepare for signing (defaults to =False=); =compress=, compresses the plaintext prior to encryption (defaults to =True=). #+begin_src python import gpg a_key = "0x12345678DEADBEEF" text = b"""Some text to test with. Since the text in this case must be bytes, it is most likely that the input form will be a separate file which is opened with "rb" as this is the simplest method of obtaining the correct data format. """ c = gpg.Context(armor=True) rkey = list(c.keylist(pattern=a_key, secret=False)) ciphertext, result, sign_result = c.encrypt(text, recipients=rkey, sign=False) with open("secret_plans.txt.asc", "wb") as afile: afile.write(ciphertext) #+end_src Though this is even more likely to be used like this; with the plaintext input read from a file, the recipient keys used for encryption regardless of key trust status and the encrypted output also encrypted to any preconfigured keys set in the =gpg.conf= file: #+begin_src python import gpg a_key = "0x12345678DEADBEEF" with open("secret_plans.txt", "rb") as afile: text = afile.read() c = gpg.Context(armor=True) rkey = list(c.keylist(pattern=a_key, secret=False)) ciphertext, result, sign_result = c.encrypt(text, recipients=rkey, - sign=True, always_trust=True, - add_encrypt_to=True) + sign=True, always_trust=True, add_encrypt_to=True) with open("secret_plans.txt.asc", "wb") as afile: afile.write(ciphertext) #+end_src If the =recipients= paramater is empty then the plaintext is encrypted symmetrically. If no =passphrase= is supplied as a parameter or via a callback registered with the =Context()= then an out-of-band prompt for the passphrase via pinentry will be invoked. *** Encrypting to multiple keys :PROPERTIES: :CUSTOM_ID: howto-basic-encryption-multiple :END: Encrypting to multiple keys essentially just expands upon the key selection process and the recipients from the previous examples. The following example encrypts a message (=text=) to everyone with an email address on the =gnupg.org= domain,[fn:3] but does /not/ encrypt to a default key or other key which is configured to normally encrypt to. #+begin_src python import gpg text = b"""Oh look, another test message. The same rules apply as with the previous example and more likely than not, the message will actually be drawn from reading the contents of a file or, maybe, from entering data at an input() prompt. Since the text in this case must be bytes, it is most likely that the input form will be a separate file which is opened with "rb" as this is the simplest method of obtaining the correct data format. """ c = gpg.Context(armor=True) rpattern = list(c.keylist(pattern="@gnupg.org", secret=False)) logrus = [] for i in range(len(rpattern)): if rpattern[i].can_encrypt == 1: logrus.append(rpattern[i]) ciphertext, result, sign_result = c.encrypt(text, recipients=logrus, sign=False, - always_trust=True) + always_trust=True) with open("secret_plans.txt.asc", "wb") as afile: - afile.write(ciphertext) + afile.write(ciphertext) #+end_src All it would take to change the above example to sign the message and also encrypt the message to any configured default keys would be to change the =c.encrypt= line to this: #+begin_src python ciphertext, result, sign_result = c.encrypt(text, recipients=logrus, - always_trust=True, + always_trust=True, add_encrypt_to=True) #+end_src The only keyword arguments requiring modification are those for which the default values are changing. The default value of =sign= is =True=, the default of =always_trust= is =False=, the default of =add_encrypt_to= is =False=. If =always_trust= is not set to =True= and any of the recipient keys are not trusted (e.g. not signed or locally signed) then the encryption will raise an error. It is possible to mitigate this somewhat with something more like this: #+begin_src python import gpg with open("secret_plans.txt.asc", "rb") as afile: - text = afile.read() + text = afile.read() c = gpg.Context(armor=True) rpattern = list(c.keylist(pattern="@gnupg.org", secret=False)) logrus = [] for i in range(len(rpattern)): if rpattern[i].can_encrypt == 1: logrus.append(rpattern[i]) try: - ciphertext, result, sign_result = c.encrypt(text, recipients=logrus, add_encrypt_to=True) + ciphertext, result, sign_result = c.encrypt(text, recipients=logrus, + add_encrypt_to=True) except gpg.errors.InvalidRecipients as e: for i in range(len(e.recipients)): for n in range(len(logrus)): if logrus[n].fpr == e.recipients[i].fpr: logrus.remove(logrus[n]) - else: - pass + else: + pass try: - ciphertext, result, sign_result = c.encrypt(text, recipients=logrus, add_encrypt_to=True) + ciphertext, result, sign_result = c.encrypt(text, recipients=logrus, + add_encrypt_to=True) except: pass with open("secret_plans.txt.asc", "wb") as afile: - afile.write(ciphertext) + afile.write(ciphertext) #+end_src This will attempt to encrypt to all the keys searched for, then remove invalid recipients if it fails and try again. ** Decryption :PROPERTIES: :CUSTOM_ID: howto-basic-decryption :END: Decrypting something encrypted to a key in one's secret keyring is fairly straight forward. In this example code, however, preconfiguring either =gpg.Context()= or =gpg.core.Context()= as =c= is unnecessary because there is no need to modify the Context prior to conducting the decryption and since the Context is only used once, setting it to =c= simply adds lines for no gain. #+begin_src python import gpg ciphertext = input("Enter path and filename of encrypted file: ") newfile = input("Enter path and filename of file to save decrypted data to: ") + with open(ciphertext, "rb") as cfile: - plaintext, result, verify_result = gpg.Context().decrypt(cfile) + plaintext, result, verify_result = gpg.Context().decrypt(cfile) + with open(newfile, "wb") as nfile: - nfile.write(plaintext) + nfile.write(plaintext) #+end_src - The data available in plaintext in this example is the decrypted - content as a byte object in =plaintext[0]=, the recipient key IDs - and algorithms in =plaintext[1]= and the results of verifying any - signatures of the data in =plaintext[0]=. + The data available in =plaintext= in this example is the decrypted + content as a byte object, the recipient key IDs and algorithms in + =result= and the results of verifying any signatures of the data in + =verify_result=. ** Signing text and files :PROPERTIES: :CUSTOM_ID: howto-basic-signing :END: The following sections demonstrate how to specify keys to sign with. *** Signing key selection :PROPERTIES: :CUSTOM_ID: howto-basic-signing-signers :END: By default GPGME and the Python bindings will use the default key configured for the user invoking the GPGME API. If there is no default key specified and there is more than one secret key available it may be necessary to specify the key or keys with which to sign messages and files. #+begin_src python import gpg logrus = input("Enter the email address or string to match signing keys to: ") hancock = gpg.Context().keylist(pattern=logrus, secret=True) sig_src = list(hancock) #+end_src The signing examples in the following sections include the explicitly designated =signers= parameter in two of the five examples; once where the resulting signature would be ASCII armoured and once where it would not be armoured. While it would be possible to enter a key ID or fingerprint here to match a specific key, it is not possible to enter two fingerprints and match two keys since the patten expects a string, bytes or None and not a list. A string with two fingerprints won't match any single key. *** Normal or default signing messages or files :PROPERTIES: :CUSTOM_ID: howto-basic-signing-normal :END: The normal or default signing process is essentially the same as is most often invoked when also encrypting a message or file. So when the encryption component is not utilised, the result is to produce an encoded and signed output which may or may not be ASCII armoured and which may or may not also be compressed. By default compression will be used unless GnuPG detects that the plaintext is already compressed. ASCII armouring will be determined according to the value of =gpg.Context().armor=. The compression algorithm is selected in much the same way as the symmetric encryption algorithm or the hash digest algorithm is when multiple keys are involved; from the preferences saved into the key itself or by comparison with the preferences with all other keys involved. #+begin_src python import gpg text0 = """Declaration of ... something. """ text = text0.encode() c = gpg.Context(armor=True, signers=sig_src) signed_data, result = c.sign(text, mode=gpg.constants.sig.mode.NORMAL) with open("/path/to/statement.txt.asc", "w") as afile: afile.write(signed_data.decode()) #+end_src Though everything in this example is accurate, it is more likely that reading the input data from another file and writing the result to a new file will be performed more like the way it is done in the next example. Even if the output format is ASCII armoured. #+begin_src python import gpg with open("/path/to/statement.txt", "rb") as tfile: text = tfile.read() c = gpg.Context() signed_data, result = c.sign(text, mode=gpg.constants.sig.mode.NORMAL) with open("/path/to/statement.txt.sig", "wb") as afile: afile.write(signed_data) #+end_src *** Detached signing messages and files :PROPERTIES: :CUSTOM_ID: howto-basic-signing-detached :END: Detached signatures will often be needed in programmatic uses of GPGME, either for signing files (e.g. tarballs of code releases) or as a component of message signing (e.g. PGP/MIME encoded email). #+begin_src python import gpg text0 = """Declaration of ... something. """ text = text0.encode() c = gpg.Context(armor=True) signed_data, result = c.sign(text, mode=gpg.constants.sig.mode.DETACH) with open("/path/to/statement.txt.asc", "w") as afile: afile.write(signed_data.decode()) #+end_src As with normal signatures, detached signatures are best handled as byte literals, even when the output is ASCII armoured. #+begin_src python import gpg with open("/path/to/statement.txt", "rb") as tfile: text = tfile.read() c = gpg.Context(signers=sig_src) signed_data, result = c.sign(text, mode=gpg.constants.sig.mode.DETACH) with open("/path/to/statement.txt.sig", "wb") as afile: afile.write(signed_data) #+end_src *** Clearsigning messages or text :PROPERTIES: :CUSTOM_ID: howto-basic-signing-clear :END: Though PGP/in-line messages are no longer encouraged in favour of PGP/MIME, there is still sometimes value in utilising in-line signatures. This is where clear-signed messages or text is of value. #+begin_src python import gpg text0 = """Declaration of ... something. """ text = text0.encode() c = gpg.Context() signed_data, result = c.sign(text, mode=gpg.constants.sig.mode.CLEAR) with open("/path/to/statement.txt.asc", "w") as afile: afile.write(signed_data.decode()) #+end_src In spite of the appearance of a clear-signed message, the data handled by GPGME in signing it must still be byte literals. #+begin_src python import gpg with open("/path/to/statement.txt", "rb") as tfile: text = tfile.read() c = gpg.Context() signed_data, result = c.sign(text, mode=gpg.constants.sig.mode.CLEAR) with open("/path/to/statement.txt.asc", "wb") as afile: afile.write(signed_data) #+end_src ** Signature verification :PROPERTIES: :CUSTOM_ID: howto-basic-verification :END: Essentially there are two principal methods of verification of a signature. The first of these is for use with the normal or default signing method and for clear-signed messages. The second is for use with files and data with detached signatures. The following example is intended for use with the default signing method where the file was not ASCII armoured: #+begin_src python import gpg import time filename = "statement.txt" gpg_file = "statement.txt.gpg" c = gpg.Context() try: data, result = c.verify(open(gpg_file)) verified = True except gpg.errors.BadSignatures as e: verified = False print(e) if verified is True: for i in range(len(result.signatures)): sign = result.signatures[i] print("""Good signature from: {0} with key {1} made at {2} """.format(c.get_key(sign.fpr).uids[0].uid, sign.fpr, time.ctime(sign.timestamp))) else: pass #+end_src Whereas this next example, which is almost identical would work with normal ASCII armoured files and with clear-signed files: #+begin_src python import gpg import time filename = "statement.txt" asc_file = "statement.txt.asc" c = gpg.Context() try: data, result = c.verify(open(asc_file)) verified = True except gpg.errors.BadSignatures as e: verified = False print(e) if verified is True: for i in range(len(result.signatures)): sign = result.signatures[i] print("""Good signature from: {0} with key {1} made at {2} """.format(c.get_key(sign.fpr).uids[0].uid, sign.fpr, time.ctime(sign.timestamp))) else: pass #+end_src In both of the previous examples it is also possible to compare the original data that was signed against the signed data in =data= to see if it matches with something like this: #+begin_src python with open(filename, "rb") as afile: text = afile.read() if text == data: print("Good signature.") else: pass #+end_src The following two examples, however, deal with detached signatures. With his method of verification the data that was signed does not get returned since it is already being explicitly referenced in the first argument of =c.verify=. So =data= is =None= and only the information in =result= is available. #+begin_src python import gpg import time filename = "statement.txt" sig_file = "statement.txt.sig" c = gpg.Context() try: data, result = c.verify(open(filename), open(sig_file)) verified = True except gpg.errors.BadSignatures as e: verified = False print(e) if verified is True: for i in range(len(result.signatures)): sign = result.signatures[i] print("""Good signature from: {0} with key {1} made at {2} """.format(c.get_key(sign.fpr).uids[0].uid, sign.fpr, time.ctime(sign.timestamp))) else: pass #+end_src #+begin_src python import gpg import time filename = "statement.txt" asc_file = "statement.txt.asc" c = gpg.Context() try: data, result = c.verify(open(filename), open(asc_file)) verified = True except gpg.errors.BadSignatures as e: verified = False print(e) if verified is not None: for i in range(len(result.signatures)): sign = result.signatures[i] print("""Good signature from: {0} with key {1} made at {2} """.format(c.get_key(sign.fpr).uids[0].uid, sign.fpr, time.ctime(sign.timestamp))) else: pass #+end_src * Creating keys and subkeys :PROPERTIES: :CUSTOM_ID: key-generation :END: 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. 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 =SECRET= level clearance, so his keys will be 3072-bit keys. The pre-configured =gpg.conf= file which sets cipher, digest and other preferences contains the following configuration parameters: #+begin_src conf expert allow-freeform-uid allow-secret-key-import trust-model tofu+pgp tofu-default-policy unknown enable-large-rsa enable-dsa2 # cert-digest-algo SHA256 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 #+end_src ** Primary key :PROPERTIES: :CUSTOM_ID: keygen-primary :END: Generating a primary key uses the =create_key= method in a Context. It contains multiple arguments and keyword arguments, including: =userid=, =algorithm=, =expires_in=, =expires=, =sign=, =encrypt=, =certify=, =authenticate=, =passphrase= and =force=. The defaults for all of those except =userid=, =algorithm=, =expires_in=, =expires= and =passphrase= is =False=. The defaults for =algorithm= and =passphrase= is =None=. The default for =expires_in= is =0=. The default for =expires= is =True=. There is no default for =userid=. If =passphrase= is left as =None= then the key will not be generated with a passphrase, if =passphrase= is set to a string then that will be the passphrase and if =passphrase= is set to =True= then gpg-agent will launch pinentry to prompt for a passphrase. For the sake of convenience, these examples will keep =passphrase= set to =None=. #+begin_src python import gpg c = gpg.Context() c.home_dir = "~/.gnupg-dm" userid = "Danger Mouse " - dmkey = c.create_key(userid, algorithm = "rsa3072", expires_in = 31536000, - sign = True, certify = True) + dmkey = c.create_key(userid, algorithm="rsa3072", expires_in=31536000, + sign=True, certify=True) #+end_src One thing to note here is the use of setting the =c.home_dir= 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, =~/.gnupg=, 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 700. + The =temp-homedir-config.py= script in the HOWTO examples directory + will create an alternative homedir with these configuration options + already set and the correct directory and file permissions. + The successful generation of the key can be confirmed via the returned =GenkeyResult= object, which includes the following data: #+begin_src 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)) #+end_src Alternatively the information can be confirmed using the command line program: #+begin_src shell 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 bash-4.4$ #+end_src As with generating keys manually, to preconfigure expanded preferences for the cipher, digest and compression algorithms, the =gpg.conf= 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 =gpg.conf= file in order to be able to generate this: #+begin_src shell 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 [ultimate] (1). Danger Mouse 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$ #+end_src ** Subkeys :PROPERTIES: :CUSTOM_ID: keygen-subkeys :END: Adding subkeys to a primary key is fairly similar to creating the primary key with the =create_subkey= method. Most of the arguments are the same, but not quite all. Instead of the =userid= argument there is now a =key= argument for selecting which primary key to add the subkey to. 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. #+begin_src 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) + key = c.get_key(dmkey.fpr, secret=True) + dmsub = c.create_subkey(key, algorithm="rsa3072", expires_in=15768000, + encrypt=True) #+end_src As with the primary key, the results here can be checked with: #+begin_src 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)) #+end_src As well as on the command line with: #+begin_src shell 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 ssb rsa3072 2018-03-15 [E] [expires: 2018-09-13] bash-4.4$ #+end_src ** User IDs :PROPERTIES: :CUSTOM_ID: keygen-uids :END: - 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 =key_add_uid= and the only arguments it takes are for the - =key= and the new =uid=. - #+begin_src python - import gpg +*** Adding User IDs + :PROPERTIES: + :CUSTOM_ID: keygen-uids-add + :END: - c = gpg.Context() - c.home_dir = "~/.gnupg-dm" + 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 =key_add_uid= and the only arguments it takes are for the + =key= and the new =uid=. - dmfpr = "177B7C25DB99745EE2EE13ED026D2F19E99E63AA" - key = c.get_key(dmfpr, secret = True) - uid = "Danger Mouse " + #+begin_src python + import gpg - c.key_add_uid(key, uid) - #+end_src + c = gpg.Context() + c.home_dir = "~/.gnupg-dm" - Unsurprisingly the result of this is: + dmfpr = "177B7C25DB99745EE2EE13ED026D2F19E99E63AA" + key = c.get_key(dmfpr, secret=True) + uid = "Danger Mouse " - #+begin_src shell - 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 - uid [ultimate] Danger Mouse - ssb rsa3072 2018-03-15 [E] [expires: 2018-09-13] + c.key_add_uid(key, uid) + #+end_src - bash-4.4$ - #+end_src + Unsurprisingly the result of this is: + + #+begin_src shell + 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 + uid [ultimate] Danger Mouse + ssb rsa3072 2018-03-15 [E] [expires: 2018-09-13] + + bash-4.4$ + #+end_src + + +*** Revokinging User IDs + :PROPERTIES: + :CUSTOM_ID: keygen-uids-revoke + :END: + + Revoking a user ID is a fairly similar process, except that it + uses the =key_revoke_uid= method. + + #+begin_src python + import gpg + + c = gpg.Context() + c.home_dir = "~/.gnupg-dm" + + dmfpr = "177B7C25DB99745EE2EE13ED026D2F19E99E63AA" + key = c.get_key(dmfpr, secret=True) + uid = "Danger Mouse " + + c.key_revoke_uid(key, uid) + #+end_src ** Key certification :PROPERTIES: :CUSTOM_ID: key-sign :END: Since key certification is more frequently referred to as key signing, the method used to perform this function is =key_sign=. The =key_sign= method takes four arguments: =key=, =uids=, =expires_in= and =local=. The default value of =uids= is =None= and which results in all user IDs being selected. The default - values of =expires_in= and =local= is =False=; which results in the - signature never expiring and being able to be exported. + value of both =expires_in= and =local= is =False=; which results in + the signature never expiring and being able to be exported. The =key= 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. If the =uids= value is not =None= 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. 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: #+begin_src python import gpg c = gpg.Context() uid = "Danger Mouse " dmfpr = "177B7C25DB99745EE2EE13ED026D2F19E99E63AA" - key = c.get_key(dmfpr, secret = True) - c.key_sign(key, uids = uid, expires_in = 2764800) + key = c.get_key(dmfpr, secret=True) + c.key_sign(key, uids=uid, expires_in=2764800) #+end_src * Miscellaneous work-arounds :PROPERTIES: :CUSTOM_ID: cheats-and-hacks :END: ** Group lines :PROPERTIES: :CUSTOM_ID: group-lines :END: There is not yet an easy way to access groups configured in the gpg.conf file from within GPGME. As a consequence these central groupings of keys cannot be shared amongst multiple programs, such as MUAs readily. The following code, however, provides a work-around for obtaining this information in Python. #+begin_src python import subprocess lines = subprocess.getoutput("gpgconf --list-options gpg").splitlines() for i in range(len(lines)): if lines[i].startswith("group") is True: line = lines[i] else: pass groups = line.split(":")[-1].replace('"', '').split(',') group_lines = groups for i in range(len(group_lines)): group_lines[i] = group_lines[i].split("=") group_lists = group_lines for i in range(len(group_lists)): group_lists[i][1] = group_lists[i][1].split() #+end_src The result of that code is that =group_lines= is a list of lists where =group_lines[i][0]= is the name of the group and =group_lines[i][1]= is the key IDs of the group as a string. The =group_lists= result is very similar in that it is a list of lists. The first part, =group_lists[i][0]= matches =group_lines[i][0]= as the name of the group, but =group_lists[i][1]= is the key IDs of the group as a string. * 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. * Footnotes [fn:1] =Short_History.org= and/or =Short_History.html=. [fn:2] The =lang/python/docs/= directory in the GPGME source. [fn:3] You probably don't really want to do this. Searching the keyservers for "gnupg.org" produces over 400 results, the majority of which aren't actually at the gnupg.org domain, but just included a comment regarding the project in their key somewhere. diff --git a/lang/python/examples/howto/add-userid.py b/lang/python/examples/howto/add-userid.py new file mode 100755 index 00000000..b8689792 --- /dev/null +++ b/lang/python/examples/howto/add-userid.py @@ -0,0 +1,62 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- + +from __future__ import absolute_import, division, unicode_literals + +# Copyright (C) 2018 Ben McGinnes +# +# This program is free software; you can redistribute it and/or modify it under +# the terms of the GNU General Public License as published by the Free Software +# Foundation; either version 2 of the License, or (at your option) any later +# version. +# +# This program is free software; you can redistribute it and/or modify it under +# the terms of the GNU Lesser General Public License as published by the Free +# Software Foundation; either version 2.1 of the License, or (at your option) +# any later version. +# +# This program is distributed in the hope that it will be useful, but WITHOUT +# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS +# FOR A PARTICULAR PURPOSE. See the GNU General Public License and the GNU +# Lesser General Public Licensefor more details. +# +# You should have received a copy of the GNU General Public License and the GNU +# Lesser General Public along with this program; if not, see +# . + +import gpg +import os.path + +print(""" +This script adds a new user ID to an existing key. + +The gpg-agent and pinentry are invoked to enter the passphrase. +""") + +c = gpg.Context() + +homedir = input("Enter the GPG configuration directory path (optional): ") +fpr0 = input("Enter the fingerprint of the key to modify: ") +uid_name = input("Enter the name of the user ID: ") +uid_email = input("Enter the email address of the user ID: ") +uid_cmnt = input("Enter a comment to include (optional): ") + +if homedir.startswith("~"): + if os.path.exists(os.path.expanduser(homedir)) is True: + c.home_dir = os.path.expanduser(homedir) + else: + pass +elif os.path.exists(homedir) is True: + c.home_dir = homedir +else: + pass + +fpr = "".join(fpr0.split()) + +if len(uid_cmnt) > 0: + userid = "{0} ({1}) <{2}>".format(uid_name, uid_cmnt, uid_email) +else: + userid = "{0} <{2}>".format(uid_name, uid_email) + +key = c.get_key(fpr, secret=True) +c.key_add_uid(key, userid) diff --git a/lang/python/examples/howto/create-key.py b/lang/python/examples/howto/create-key.py new file mode 100755 index 00000000..429ab1f7 --- /dev/null +++ b/lang/python/examples/howto/create-key.py @@ -0,0 +1,95 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- + +from __future__ import absolute_import, division, unicode_literals + +# Copyright (C) 2018 Ben McGinnes +# +# This program is free software; you can redistribute it and/or modify it under +# the terms of the GNU General Public License as published by the Free Software +# Foundation; either version 2 of the License, or (at your option) any later +# version. +# +# This program is free software; you can redistribute it and/or modify it under +# the terms of the GNU Lesser General Public License as published by the Free +# Software Foundation; either version 2.1 of the License, or (at your option) +# any later version. +# +# This program is distributed in the hope that it will be useful, but WITHOUT +# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS +# FOR A PARTICULAR PURPOSE. See the GNU General Public License and the GNU +# Lesser General Public Licensefor more details. +# +# You should have received a copy of the GNU General Public License and the GNU +# Lesser General Public along with this program; if not, see +# . + +import gpg +import os.path + +print(""" +This script generates a new key which does not expire. + +The gpg-agent and pinentry are invoked to set the passphrase. +""") + +c = gpg.Context() + +homedir = input("Enter the GPG configuration directory path (optional): ") +uid_name = input("Enter the name of the user ID: ") +uid_email = input("Enter the email address of the user ID: ") +uid_cmnt = input("Enter a comment to include (optional): ") +key_algo = input("Enter the key algorithm, RSA or DSA (default is RSA): ") +key_size = input("Enter the key size (2048-4096, default is 2048): ") + +if homedir.startswith("~"): + if os.path.exists(os.path.expanduser(homedir)) is True: + c.home_dir = os.path.expanduser(homedir) + else: + pass +elif os.path.exists(homedir) is True: + c.home_dir = homedir +else: + pass + +if len(uid_cmnt) > 0: + userid = "{0} ({1}) <{2}>".format(uid_name, uid_cmnt, uid_email) +else: + userid = "{0} <{2}>".format(uid_name, uid_email) + +if key_algo.lower() == "dsa": + ka = "dsa" +else: + ka = "rsa" + +if len(key_size) == 4: + try: + ks0 = int(key_size) + except ValueError: + ks0 = None + if ks0 is None: + ks = "2048" + else: + if ks0 < 2048: + ks = "2048" + elif ka == "dsa" and ks0 > 3072: + ks = "3072" + elif ka == "rsa" and ks0 > 4096: + ks = "4096" + else: + ks = key_size +else: + ks = "2048" + +keyalgo = "{0}{1}".format(ka, ks) + +newkey = c.create_key(userid, algorithm=keyalgo, expires=False, + passphrase=True, certify=True) +key = c.get_key(newkey.fpr, secret=True) + +if ka == "rsa": + newsub = c.create_subkey(key, algorithm=keyalgo, expires=False, + passphrase=True, encrypt=True) +else: + newsub = c.create_subkey(key, expires=False, passphrase=True, + encrypt=True) diff --git a/lang/python/examples/howto/revoke-userid.py b/lang/python/examples/howto/revoke-userid.py new file mode 100755 index 00000000..7a3d190b --- /dev/null +++ b/lang/python/examples/howto/revoke-userid.py @@ -0,0 +1,62 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- + +from __future__ import absolute_import, division, unicode_literals + +# Copyright (C) 2018 Ben McGinnes +# +# This program is free software; you can redistribute it and/or modify it under +# the terms of the GNU General Public License as published by the Free Software +# Foundation; either version 2 of the License, or (at your option) any later +# version. +# +# This program is free software; you can redistribute it and/or modify it under +# the terms of the GNU Lesser General Public License as published by the Free +# Software Foundation; either version 2.1 of the License, or (at your option) +# any later version. +# +# This program is distributed in the hope that it will be useful, but WITHOUT +# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS +# FOR A PARTICULAR PURPOSE. See the GNU General Public License and the GNU +# Lesser General Public Licensefor more details. +# +# You should have received a copy of the GNU General Public License and the GNU +# Lesser General Public along with this program; if not, see +# . + +import gpg +import os.path + +print(""" +This script revokes a user ID on an existing key. + +The gpg-agent and pinentry are invoked to enter the passphrase. +""") + +c = gpg.Context() + +homedir = input("Enter the GPG configuration directory path (optional): ") +fpr0 = input("Enter the fingerprint of the key to modify: ") +uid_name = input("Enter the name of the user ID: ") +uid_email = input("Enter the email address of the user ID: ") +uid_cmnt = input("Enter a comment to include (optional): ") + +if homedir.startswith("~"): + if os.path.exists(os.path.expanduser(homedir)) is True: + c.home_dir = os.path.expanduser(homedir) + else: + pass +elif os.path.exists(homedir) is True: + c.home_dir = homedir +else: + pass + +fpr = "".join(fpr0.split()) + +if len(uid_cmnt) > 0: + userid = "{0} ({1}) <{2}>".format(uid_name, uid_cmnt, uid_email) +else: + userid = "{0} <{2}>".format(uid_name, uid_email) + +key = c.get_key(fpr, secret=True) +c.key_revoke_uid(key, userid) diff --git a/lang/python/examples/howto/sign-key.py b/lang/python/examples/howto/sign-key.py new file mode 100755 index 00000000..b1afe13c --- /dev/null +++ b/lang/python/examples/howto/sign-key.py @@ -0,0 +1,63 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- + +from __future__ import absolute_import, division, unicode_literals + +# Copyright (C) 2018 Ben McGinnes +# +# This program is free software; you can redistribute it and/or modify it under +# the terms of the GNU General Public License as published by the Free Software +# Foundation; either version 2 of the License, or (at your option) any later +# version. +# +# This program is free software; you can redistribute it and/or modify it under +# the terms of the GNU Lesser General Public License as published by the Free +# Software Foundation; either version 2.1 of the License, or (at your option) +# any later version. +# +# This program is distributed in the hope that it will be useful, but WITHOUT +# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS +# FOR A PARTICULAR PURPOSE. See the GNU General Public License and the GNU +# Lesser General Public Licensefor more details. +# +# You should have received a copy of the GNU General Public License and the GNU +# Lesser General Public along with this program; if not, see +# . + +import gpg +import os.path + +print(""" +This script signs or certifies a key. + +The gpg-agent and pinentry are invoked to enter the passphrase. +""") + +c = gpg.Context() + +homedir = input("Enter the GPG configuration directory path (optional): ") +fpr0 = input("Enter the fingerprint of the key to sign: ") +userid = input("Enter the UID to sign (case sensitive, optional): ") +sig_type = input("Enter the certification type (local or normal): ") + +if homedir.startswith("~"): + if os.path.exists(os.path.expanduser(homedir)) is True: + c.home_dir = os.path.expanduser(homedir) + else: + pass +elif os.path.exists(homedir) is True: + c.home_dir = homedir +else: + pass + +fpr = "".join(fpr0.split()) +key = c.get_key(fpr, secret=False) + +if len(userid) > 0 and sig_type.lower() == "local": + c.key_sign(key, uids=userid, local=True) +elif len(userid) > 0 and sig_type.lower() != "local": + c.key_sign(key, uids=userid) +elif len(userid) == 0 and sig_type.lower() == "local": + c.key_sign(key, local=True) +else: + c.key_sign(key) diff --git a/lang/python/examples/howto/temp-homedir-config.py b/lang/python/examples/howto/temp-homedir-config.py new file mode 100755 index 00000000..ddd79327 --- /dev/null +++ b/lang/python/examples/howto/temp-homedir-config.py @@ -0,0 +1,126 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- + +from __future__ import absolute_import, division, unicode_literals + +# Copyright (C) 2018 Ben McGinnes +# +# This program is free software; you can redistribute it and/or modify it under +# the terms of the GNU General Public License as published by the Free Software +# Foundation; either version 2 of the License, or (at your option) any later +# version. +# +# This program is free software; you can redistribute it and/or modify it under +# the terms of the GNU Lesser General Public License as published by the Free +# Software Foundation; either version 2.1 of the License, or (at your option) +# any later version. +# +# This program is distributed in the hope that it will be useful, but WITHOUT +# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS +# FOR A PARTICULAR PURPOSE. See the GNU General Public License and the GNU +# Lesser General Public Licensefor more details. +# +# You should have received a copy of the GNU General Public License and the GNU +# Lesser General Public along with this program; if not, see +# . + +import os +import os.path +import sys + +intro = """ +This script creates a temporary directory to use as a homedir for +testing key generation tasks with the correct permissions, along +with a gpg.conf file containing the same configuration options +listed in the HOWTO. + +You may wish to change the order of the cipher preferences or +remove those not relevant to your installation. These +configuration parameters assume that all ciphers and digests are +installed and available rather than limiting to the default +ciphers and digests. + +The script prompts for a directory name to be installed as a hidden +directory in the user's home directory on POSIX systems. So if you +enter "gnupg-temp" on a Linux, BSD or OS X system, it will create +"~/.gnupg-temp" (you do not need to enter the leading dot). + +This script has not been tested on Windows systems and may have +unpredictable results. That said, it will not delete or copy over +existing data. + +If the directory already exists, the script will terminate with a +message telling you to specify a new directory name. There is no +default directory name. +""" + +gpgconf = """# gpg.conf settings for key generation: +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 +""" + +agentconf = """# gpg-agent.conf settings for key generation: +default-cache-ttl 300 +""" + +if len(sys.argv) == 1: + print(intro) + new_homedir = input("Enter the temporary gnupg homedir name: ") +elif len(sys.argv) == 2: + new_homedir = sys.argv[1] +else: + new_homedir = " ".join(sys.argv[1:]) + +userdir = os.path.expanduser("~") + +if new_homedir.startswith("~"): + new_homdir.replace("~", "") +else: + pass + +if new_homedir.startswith("/"): + new_homdir.replace("/", "") +else: + pass + +if new_homedir.startswith("."): + new_homdir.replace(".", "_") +else: + pass + +if new_homedir.count(" ") > 0: + new_homedir.replace(" ", "_") +else: + pass + +nh = "{0}/.{1}".format(userdir, new_homedir) + +if os.path.exists(nh) is True: + print("The {0} directory already exists.".format(nh)) +else: + print("Creating the {0} directory.".format(nh)) + os.mkdir(nh) + os.chmod(nh, 0o700) + with open("{0}/{1}".format(nh, "gpg.conf"), "w") as f1: + f1.write(gpgconf) + os.chmod("{0}/{1}".format(nh, "gpg.conf"), 0o600) + with open("{0}/{1}".format(nh, "gpg-agent.conf"), "w") as f2: + f2.write(gpgconf) + os.chmod("{0}/{1}".format(nh, "gpg-agent.conf"), 0o600) + print("""You may now use the {0} directory as an alternative GPG homedir: + +gpg --homedir {0} +gpg --homedir --full-gen-key + +Or with GPGME scripts, including the GPGME Python bindings. +""") diff --git a/src/gpgme-json.c b/src/gpgme-json.c index e38f9d89..b54d9a8a 100644 --- a/src/gpgme-json.c +++ b/src/gpgme-json.c @@ -1,1332 +1,1376 @@ /* gpgme-json.c - JSON based interface to gpgme (server) * Copyright (C) 2018 g10 Code GmbH * * This file is part of GPGME. * * GPGME is free software; you can redistribute it and/or modify it * under the terms of the GNU Lesser General Public License as * published by the Free Software Foundation; either version 2.1 of * the License, or (at your option) any later version. * * GPGME is distributed in the hope that it will be useful, but * WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public * License along with this program; if not, see . * SPDX-License-Identifier: LGPL-2.1+ */ /* This is tool implements the Native Messaging protocol of web * browsers and provides the server part of it. A Javascript based * client can be found in lang/javascript. The used data format is * similar to the API of openpgpjs. */ #include #include #include #include #include #ifdef HAVE_LOCALE_H #include #endif #include #define GPGRT_ENABLE_ES_MACROS 1 #define GPGRT_ENABLE_LOG_MACROS 1 #define GPGRT_ENABLE_ARGPARSE_MACROS 1 #include "gpgme.h" #include "cJSON.h" +#if GPGRT_VERSION_NUMBER < 0x011c00 /* 1.28 */ +int main (void){fputs ("Build with Libgpg-error >= 1.28!\n", stderr);return 1;} +#else /* libgpg-error >= 1.28 */ + /* We don't allow a request with more than 64 MiB. */ #define MAX_REQUEST_SIZE (64 * 1024 * 1024) static void xoutofcore (const char *type) GPGRT_ATTR_NORETURN; static cjson_t error_object_v (cjson_t json, const char *message, va_list arg_ptr) GPGRT_ATTR_PRINTF(2,0); static cjson_t error_object (cjson_t json, const char *message, ...) GPGRT_ATTR_PRINTF(2,3); static char *error_object_string (const char *message, ...) GPGRT_ATTR_PRINTF(1,2); /* True if interactive mode is active. */ static int opt_interactive; - +/* True is debug mode is active. */ +static int opt_debug; /* * Helper functions and macros */ #define xtrymalloc(a) gpgrt_malloc ((a)) #define xtrystrdup(a) gpgrt_strdup ((a)) #define xmalloc(a) ({ \ void *_r = gpgrt_malloc ((a)); \ if (!_r) \ xoutofcore ("malloc"); \ _r; }) #define xcalloc(a,b) ({ \ void *_r = gpgrt_calloc ((a), (b)); \ if (!_r) \ xoutofcore ("calloc"); \ _r; }) #define xstrdup(a) ({ \ char *_r = gpgrt_strdup ((a)); \ if (!_r) \ xoutofcore ("strdup"); \ _r; }) #define xstrconcat(a, ...) ({ \ char *_r = gpgrt_strconcat ((a), __VA_ARGS__); \ if (!_r) \ xoutofcore ("strconcat"); \ _r; }) #define xfree(a) gpgrt_free ((a)) #define spacep(p) (*(p) == ' ' || *(p) == '\t') static void xoutofcore (const char *type) { gpg_error_t err = gpg_error_from_syserror (); log_error ("%s failed: %s\n", type, gpg_strerror (err)); exit (2); } /* Call cJSON_CreateObject but terminate in case of an error. */ static cjson_t xjson_CreateObject (void) { cjson_t json = cJSON_CreateObject (); if (!json) xoutofcore ("cJSON_CreateObject"); return json; } /* Wrapper around cJSON_AddStringToObject which returns an gpg-error * code instead of the NULL or the new object. */ static gpg_error_t cjson_AddStringToObject (cjson_t object, const char *name, const char *string) { if (!cJSON_AddStringToObject (object, name, string)) return gpg_error_from_syserror (); return 0; } /* Same as cjson_AddStringToObject but prints an error message and * terminates the process. */ static void xjson_AddStringToObject (cjson_t object, const char *name, const char *string) { if (!cJSON_AddStringToObject (object, name, string)) xoutofcore ("cJSON_AddStringToObject"); } /* Wrapper around cJSON_AddBoolToObject which terminates the process * in case of an error. */ static void xjson_AddBoolToObject (cjson_t object, const char *name, int abool) { if (!cJSON_AddBoolToObject (object, name, abool)) xoutofcore ("cJSON_AddStringToObject"); return ; } /* This is similar to cJSON_AddStringToObject but takes a gpgme DATA * object and adds it under NAME as a base 64 encoded string to * OBJECT. Ownership of DATA is transferred to this function. */ static gpg_error_t add_base64_to_object (cjson_t object, const char *name, gpgme_data_t data) { #if GPGRT_VERSION_NUMBER < 0x011d00 /* 1.29 */ return gpg_error (GPG_ERR_NOT_SUPPORTED); #else gpg_err_code_t err; estream_t fp = NULL; gpgrt_b64state_t state = NULL; cjson_t j_str = NULL; void *buffer = NULL; size_t buflen; fp = es_fopenmem (0, "rwb"); if (!fp) { err = gpg_err_code_from_syserror (); goto leave; } state = gpgrt_b64enc_start (fp, ""); if (!state) { err = gpg_err_code_from_syserror (); goto leave; } gpgme_data_write (data, "", 1); /* Make sure we have a string. */ buffer = gpgme_data_release_and_get_mem (data, &buflen); data = NULL; if (!buffer) { err = gpg_error_from_syserror (); goto leave; } err = gpgrt_b64enc_write (state, buffer, buflen); if (err) goto leave; xfree (buffer); buffer = NULL; err = gpgrt_b64enc_finish (state); state = NULL; if (err) return err; es_fputc (0, fp); if (es_fclose_snatch (fp, &buffer, NULL)) { fp = NULL; err = gpg_error_from_syserror (); goto leave; } fp = NULL; j_str = cJSON_CreateStringConvey (buffer); if (!j_str) { err = gpg_error_from_syserror (); goto leave; } buffer = NULL; if (!cJSON_AddItemToObject (object, name, j_str)) { err = gpg_error_from_syserror (); cJSON_Delete (j_str); j_str = NULL; goto leave; } j_str = NULL; leave: xfree (buffer); cJSON_Delete (j_str); gpgrt_b64enc_finish (state); es_fclose (fp); gpgme_data_release (data); return err; #endif } /* Create a JSON error object. If JSON is not NULL the error message * is appended to that object. An existing "type" item will be replaced. */ static cjson_t error_object_v (cjson_t json, const char *message, va_list arg_ptr) { cjson_t response, j_tmp; char *msg; msg = gpgrt_vbsprintf (message, arg_ptr); if (!msg) xoutofcore ("error_object"); response = json? json : xjson_CreateObject (); if (!(j_tmp = cJSON_GetObjectItem (response, "type"))) xjson_AddStringToObject (response, "type", "error"); else /* Replace existing "type". */ { j_tmp = cJSON_CreateString ("error"); if (!j_tmp) xoutofcore ("cJSON_CreateString"); cJSON_ReplaceItemInObject (response, "type", j_tmp); } xjson_AddStringToObject (response, "msg", msg); xfree (msg); return response; } /* Call cJSON_Print but terminate in case of an error. */ static char * xjson_Print (cjson_t object) { char *buf; buf = cJSON_Print (object); if (!buf) xoutofcore ("cJSON_Print"); return buf; } static cjson_t error_object (cjson_t json, const char *message, ...) { cjson_t response; va_list arg_ptr; va_start (arg_ptr, message); response = error_object_v (json, message, arg_ptr); va_end (arg_ptr); return response; } static char * error_object_string (const char *message, ...) { cjson_t response; va_list arg_ptr; char *msg; va_start (arg_ptr, message); response = error_object_v (NULL, message, arg_ptr); va_end (arg_ptr); msg = xjson_Print (response); cJSON_Delete (response); return msg; } /* Get the boolean property NAME from the JSON object and store true * or valse at R_VALUE. If the name is unknown the value of DEF_VALUE * is returned. If the type of the value is not boolean, * GPG_ERR_INV_VALUE is returned and R_VALUE set to DEF_VALUE. */ static gpg_error_t get_boolean_flag (cjson_t json, const char *name, int def_value, int *r_value) { cjson_t j_item; j_item = cJSON_GetObjectItem (json, name); if (!j_item) *r_value = def_value; else if (cjson_is_true (j_item)) *r_value = 1; else if (cjson_is_false (j_item)) *r_value = 0; else { *r_value = def_value; return gpg_error (GPG_ERR_INV_VALUE); } return 0; } /* Get the boolean property PROTOCOL from the JSON object and store * its value at R_PROTOCOL. The default is OpenPGP. */ static gpg_error_t get_protocol (cjson_t json, gpgme_protocol_t *r_protocol) { cjson_t j_item; *r_protocol = GPGME_PROTOCOL_OpenPGP; j_item = cJSON_GetObjectItem (json, "protocol"); if (!j_item) ; else if (!cjson_is_string (j_item)) return gpg_error (GPG_ERR_INV_VALUE); else if (!strcmp(j_item->valuestring, "openpgp")) ; else if (!strcmp(j_item->valuestring, "cms")) *r_protocol = GPGME_PROTOCOL_CMS; else return gpg_error (GPG_ERR_UNSUPPORTED_PROTOCOL); return 0; } /* Extract the keys from the KEYS array in the JSON object. CTX is a * GPGME context object. On success an array with the keys is stored * at R_KEYS. In failure an error code is returned. */ static gpg_error_t get_keys (gpgme_ctx_t ctx, cjson_t json, gpgme_key_t **r_keys) { gpg_error_t err; cjson_t j_keys, j_item; int i, nkeys; gpgme_key_t *keys; *r_keys = NULL; j_keys = cJSON_GetObjectItem (json, "keys"); if (!j_keys) return gpg_error (GPG_ERR_NO_KEY); if (!cjson_is_array (j_keys) && !cjson_is_string (j_keys)) return gpg_error (GPG_ERR_INV_VALUE); if (cjson_is_string (j_keys)) nkeys = 1; else { nkeys = cJSON_GetArraySize (j_keys); if (!nkeys) return gpg_error (GPG_ERR_NO_KEY); for (i=0; i < nkeys; i++) { j_item = cJSON_GetArrayItem (j_keys, i); if (!j_item || !cjson_is_string (j_item)) return gpg_error (GPG_ERR_INV_VALUE); } } /* Now allocate an array to store the gpgme key objects. */ keys = xcalloc (nkeys + 1, sizeof *keys); if (cjson_is_string (j_keys)) { err = gpgme_get_key (ctx, j_keys->valuestring, &keys[0], 0); if (err) goto leave; } else { for (i=0; i < nkeys; i++) { j_item = cJSON_GetArrayItem (j_keys, i); err = gpgme_get_key (ctx, j_item->valuestring, &keys[i], 0); if (err) goto leave; } } err = 0; *r_keys = keys; keys = NULL; leave: if (keys) { for (i=0; keys[i]; i++) gpgme_key_unref (keys[i]); xfree (keys); } return err; } /* * GPGME support functions. */ /* Helper for get_context. */ static gpgme_ctx_t _create_new_context (gpgme_protocol_t proto) { gpg_error_t err; gpgme_ctx_t ctx; err = gpgme_new (&ctx); if (err) log_fatal ("error creating GPGME context: %s\n", gpg_strerror (err)); gpgme_set_protocol (ctx, proto); gpgme_set_ctx_flag (ctx, "request-origin", "browser"); return ctx; } /* Return a context object for protocol PROTO. This is currently a * statuically allocated context initialized for PROTO. Termnates * process on failure. */ static gpgme_ctx_t get_context (gpgme_protocol_t proto) { static gpgme_ctx_t ctx_openpgp, ctx_cms; if (proto == GPGME_PROTOCOL_OpenPGP) { if (!ctx_openpgp) ctx_openpgp = _create_new_context (proto); return ctx_openpgp; } else if (proto == GPGME_PROTOCOL_CMS) { if (!ctx_cms) ctx_cms = _create_new_context (proto); return ctx_cms; } else log_bug ("invalid protocol %d requested\n", proto); } /* Free context object retrieved by get_context. */ static void release_context (gpgme_ctx_t ctx) { /* Nothing to do right now. */ (void)ctx; } /* Given a Base-64 encoded string object in JSON return a gpgme data * object at R_DATA. */ static gpg_error_t data_from_base64_string (gpgme_data_t *r_data, cjson_t json) { #if GPGRT_VERSION_NUMBER < 0x011d00 /* 1.29 */ *r_data = NULL; return gpg_error (GPG_ERR_NOT_SUPPORTED); #else gpg_error_t err; size_t len; char *buf = NULL; gpgrt_b64state_t state = NULL; gpgme_data_t data = NULL; *r_data = NULL; /* A quick check on the JSON. */ if (!cjson_is_string (json)) { err = gpg_error (GPG_ERR_INV_VALUE); goto leave; } state = gpgrt_b64dec_start (NULL); if (!state) { err = gpg_err_code_from_syserror (); goto leave; } /* Fixme: Data duplication - we should see how to snatch the memory * from the json object. */ len = strlen (json->valuestring); buf = xtrystrdup (json->valuestring); if (!buf) { err = gpg_error_from_syserror (); goto leave; } err = gpgrt_b64dec_proc (state, buf, len, &len); if (err) goto leave; err = gpgrt_b64dec_finish (state); state = NULL; if (err) goto leave; err = gpgme_data_new_from_mem (&data, buf, len, 1); if (err) goto leave; *r_data = data; data = NULL; leave: xfree (data); xfree (buf); gpgrt_b64dec_finish (state); return err; #endif } /* * Implementaion of the commands. */ static const char hlp_encrypt[] = "op: \"encrypt\"\n" "keys: Array of strings with the fingerprints or user-ids\n" " of the keys to encrypt the data. For a single key\n" " a String may be used instead of an array.\n" "data: Input data. \n" "\n" "Optional parameters:\n" "protocol: Either \"openpgp\" (default) or \"cms\".\n" "\n" "Optional boolean flags (default is false):\n" "base64: Input data is base64 encoded.\n" "armor: Request output in armored format.\n" "always-trust: Request --always-trust option.\n" "no-encrypt-to: Do not use a default recipient.\n" "no-compress: Do not compress the plaintext first.\n" "throw-keyids: Request the --throw-keyids option.\n" "wrap: Assume the input is an OpenPGP message.\n" "\n" "Response on success:\n" "type: \"ciphertext\"\n" "data: Unless armor mode is used a Base64 encoded binary\n" " ciphertext. In armor mode a string with an armored\n" " OpenPGP or a PEM message.\n" "base64: Boolean indicating whether data is base64 encoded."; static gpg_error_t op_encrypt (cjson_t request, cjson_t result) { gpg_error_t err; gpgme_ctx_t ctx = NULL; gpgme_protocol_t protocol; int opt_base64; gpgme_key_t *keys = NULL; cjson_t j_input; gpgme_data_t input = NULL; gpgme_data_t output = NULL; int abool, i; gpgme_encrypt_flags_t encrypt_flags = 0; if ((err = get_protocol (request, &protocol))) goto leave; ctx = get_context (protocol); if ((err = get_boolean_flag (request, "base64", 0, &opt_base64))) goto leave; if ((err = get_boolean_flag (request, "armor", 0, &abool))) goto leave; gpgme_set_armor (ctx, abool); if ((err = get_boolean_flag (request, "always-trust", 0, &abool))) goto leave; if (abool) encrypt_flags |= GPGME_ENCRYPT_ALWAYS_TRUST; if ((err = get_boolean_flag (request, "no-encrypt-to", 0,&abool))) goto leave; if (abool) encrypt_flags |= GPGME_ENCRYPT_NO_ENCRYPT_TO; if ((err = get_boolean_flag (request, "no-compress", 0, &abool))) goto leave; if (abool) encrypt_flags |= GPGME_ENCRYPT_NO_COMPRESS; if ((err = get_boolean_flag (request, "throw-keyids", 0, &abool))) goto leave; if (abool) encrypt_flags |= GPGME_ENCRYPT_THROW_KEYIDS; if ((err = get_boolean_flag (request, "wrap", 0, &abool))) goto leave; if (abool) encrypt_flags |= GPGME_ENCRYPT_WRAP; /* Get the keys. */ err = get_keys (ctx, request, &keys); if (err) { /* Provide a custom error response. */ error_object (result, "Error getting keys: %s", gpg_strerror (err)); goto leave; } /* Get the data. Note that INPUT is a shallow data object with the * storage hold in REQUEST. */ j_input = cJSON_GetObjectItem (request, "data"); if (!j_input) { err = gpg_error (GPG_ERR_NO_DATA); goto leave; } if (!cjson_is_string (j_input)) { err = gpg_error (GPG_ERR_INV_VALUE); goto leave; } if (opt_base64) { err = data_from_base64_string (&input, j_input); if (err) { error_object (result, "Error decoding Base-64 encoded 'data': %s", gpg_strerror (err)); goto leave; } } else { err = gpgme_data_new_from_mem (&input, j_input->valuestring, strlen (j_input->valuestring), 0); if (err) { error_object (result, "Error getting 'data': %s", gpg_strerror (err)); goto leave; } } /* Create an output data object. */ err = gpgme_data_new (&output); if (err) { error_object (result, "Error creating output data object: %s", gpg_strerror (err)); goto leave; } /* Encrypt. */ err = gpgme_op_encrypt (ctx, keys, encrypt_flags, input, output); /* encrypt_result = gpgme_op_encrypt_result (ctx); */ if (err) { error_object (result, "Encryption failed: %s", gpg_strerror (err)); goto leave; } gpgme_data_release (input); input = NULL; xjson_AddStringToObject (result, "type", "ciphertext"); /* If armoring is used we do not need to base64 the output. */ xjson_AddBoolToObject (result, "base64", !gpgme_get_armor (ctx)); if (gpgme_get_armor (ctx)) { char *buffer; /* Make sure that we really have a string. */ gpgme_data_write (output, "", 1); buffer = gpgme_data_release_and_get_mem (output, NULL); if (!buffer) { err = gpg_error_from_syserror (); goto leave; } err = cjson_AddStringToObject (result, "data", buffer); gpgme_free (buffer); if (err) goto leave; } else { err = add_base64_to_object (result, "data", output); output = NULL; if (err) goto leave; } leave: if (keys) { for (i=0; keys[i]; i++) gpgme_key_unref (keys[i]); xfree (keys); } release_context (ctx); gpgme_data_release (input); return err; } static const char hlp_help[] = "The tool expects a JSON object with the request and responds with\n" "another JSON object. Even on error a JSON object is returned. The\n" "property \"op\" is mandatory and its string value selects the\n" "operation; if the property \"help\" with the value \"true\" exists, the\n" "operation is not performned but a string with the documentation\n" "returned. To list all operations it is allowed to leave out \"op\" in\n" "help mode. Supported values for \"op\" are:\n\n" " encrypt Encrypt data.\n" " help Help overview."; static gpg_error_t op_help (cjson_t request, cjson_t result) { cjson_t j_tmp; char *buffer = NULL; const char *msg; j_tmp = cJSON_GetObjectItem (request, "interactive_help"); if (opt_interactive && j_tmp && cjson_is_string (j_tmp)) msg = buffer = xstrconcat (hlp_help, "\n", j_tmp->valuestring, NULL); else msg = hlp_help; xjson_AddStringToObject (result, "type", "help"); xjson_AddStringToObject (result, "msg", msg); xfree (buffer); return 0; } /* Process a request and return the response. The response is a newly - * allocated staring or NULL in case of an error. */ + * allocated string or NULL in case of an error. */ static char * process_request (const char *request) { static struct { const char *op; gpg_error_t (*handler)(cjson_t request, cjson_t result); const char * const helpstr; } optbl[] = { { "encrypt", op_encrypt, hlp_encrypt }, { "help", op_help, hlp_help }, { NULL } }; size_t erroff; cjson_t json; cjson_t j_tmp, j_op; cjson_t response; int helpmode; const char *op; char *res; int idx; response = xjson_CreateObject (); json = cJSON_Parse (request, &erroff); if (!json) { log_string (GPGRT_LOGLVL_INFO, request); log_info ("invalid JSON object at offset %zu\n", erroff); error_object (response, "invalid JSON object at offset %zu\n", erroff); goto leave; } j_tmp = cJSON_GetObjectItem (json, "help"); helpmode = (j_tmp && cjson_is_true (j_tmp)); j_op = cJSON_GetObjectItem (json, "op"); if (!j_op || !cjson_is_string (j_op)) { if (!helpmode) { error_object (response, "Property \"op\" missing"); goto leave; } op = "help"; /* Help summary. */ } else op = j_op->valuestring; for (idx=0; optbl[idx].op; idx++) if (!strcmp (op, optbl[idx].op)) break; if (optbl[idx].op) { if (helpmode && strcmp (op, "help")) { xjson_AddStringToObject (response, "type", "help"); xjson_AddStringToObject (response, "op", op); xjson_AddStringToObject (response, "msg", optbl[idx].helpstr); } else { gpg_error_t err; err = optbl[idx].handler (json, response); if (err) { if (!(j_tmp = cJSON_GetObjectItem (response, "type")) || !cjson_is_string (j_tmp) || strcmp (j_tmp->valuestring, "error")) { /* No error type response - provide a generic one. */ error_object (response, "Operation failed: %s", gpg_strerror (err)); } xjson_AddStringToObject (response, "op", op); } } } else /* Operation not supported. */ { error_object (response, "Unknown operation '%s'", op); xjson_AddStringToObject (response, "op", op); } leave: cJSON_Delete (json); - json = NULL; if (opt_interactive) res = cJSON_Print (response); else res = cJSON_PrintUnformatted (response); if (!res) log_error ("Printing JSON data failed\n"); cJSON_Delete (response); return res; } /* * Driver code */ /* Return a malloced line or NULL on EOF. Terminate on read * error. */ static char * get_line (void) { char *line = NULL; size_t linesize = 0; gpg_error_t err; size_t maxlength = 2048; int n; const char *s; char *p; again: n = es_read_line (es_stdin, &line, &linesize, &maxlength); if (n < 0) { err = gpg_error_from_syserror (); log_error ("error reading line: %s\n", gpg_strerror (err)); exit (1); } if (!n) { xfree (line); line = NULL; return NULL; /* EOF */ } if (!maxlength) { log_info ("line too long - skipped\n"); goto again; } if (memchr (line, 0, n)) log_info ("warning: line shortened due to embedded Nul character\n"); if (line[n-1] == '\n') line[n-1] = 0; /* Trim leading spaces. */ for (s=line; spacep (s); s++) ; if (s != line) { for (p=line; *s;) *p++ = *s++; *p = 0; n = p - line; } return line; } /* Process meta commands used with the standard REPL. */ static char * process_meta_commands (const char *request) { char *result = NULL; while (spacep (request)) request++; if (!strncmp (request, "help", 4) && (spacep (request+4) || !request[4])) result = process_request ("{ \"op\": \"help\"," " \"interactive_help\": " "\"\\nMeta commands:\\n" " ,help This help\\n" " ,quit Terminate process\"" "}"); else if (!strncmp (request, "quit", 4) && (spacep (request+4) || !request[4])) exit (0); else log_info ("invalid meta command\n"); return result; } /* If STRING has a help response, return the MSG property in a human * readable format. */ static char * get_help_msg (const char *string) { cjson_t json, j_type, j_msg; const char *msg; char *buffer = NULL; char *p; json = cJSON_Parse (string, NULL); if (json) { j_type = cJSON_GetObjectItem (json, "type"); if (j_type && cjson_is_string (j_type) && !strcmp (j_type->valuestring, "help")) { j_msg = cJSON_GetObjectItem (json, "msg"); if (j_msg || cjson_is_string (j_msg)) { msg = j_msg->valuestring; buffer = malloc (strlen (msg)+1); if (buffer) { for (p=buffer; *msg; msg++) { if (*msg == '\\' && msg[1] == '\n') *p++ = '\n'; else *p++ = *msg; } *p = 0; } } } cJSON_Delete (json); } return buffer; } /* An interactive standard REPL. */ static void interactive_repl (void) { char *line = NULL; char *request = NULL; char *response = NULL; char *p; int first; es_setvbuf (es_stdin, NULL, _IONBF, 0); #if GPGRT_VERSION_NUMBER >= 0x011d00 /* 1.29 */ es_fprintf (es_stderr, "%s %s ready (enter \",help\" for help)\n", gpgrt_strusage (11), gpgrt_strusage (13)); #endif do { es_fputs ("> ", es_stderr); es_fflush (es_stderr); es_fflush (es_stdout); xfree (line); line = get_line (); es_fflush (es_stderr); es_fflush (es_stdout); first = !request; if (line && *line) { if (!request) request = xstrdup (line); else request = xstrconcat (request, "\n", line, NULL); } if (!line) es_fputs ("\n", es_stderr); if (!line || !*line || (first && *request == ',')) { /* Process the input. */ xfree (response); response = NULL; if (request && *request == ',') { response = process_meta_commands (request+1); } else if (request) { response = process_request (request); } xfree (request); request = NULL; if (response) { if (opt_interactive) { char *msg = get_help_msg (response); if (msg) { xfree (response); response = msg; } } es_fputs ("===> ", es_stderr); es_fflush (es_stderr); for (p=response; *p; p++) { if (*p == '\n') { es_fflush (es_stdout); es_fputs ("\n===> ", es_stderr); es_fflush (es_stderr); } else es_putc (*p, es_stdout); } es_fflush (es_stdout); es_fputs ("\n", es_stderr); } } } while (line); xfree (request); xfree (response); xfree (line); } -/* Read and process asingle request. */ +/* Read and process a single request. */ static void read_and_process_single_request (void) { char *line = NULL; char *request = NULL; char *response = NULL; size_t n; for (;;) { xfree (line); line = get_line (); if (line && *line) request = (request? xstrconcat (request, "\n", line, NULL) /**/ : xstrdup (line)); if (!line) { if (request) { xfree (response); response = process_request (request); if (response) { es_fputs (response, es_stdout); if ((n = strlen (response)) && response[n-1] != '\n') es_fputc ('\n', es_stdout); } es_fflush (es_stdout); } break; } } xfree (response); xfree (request); xfree (line); } /* The Native Messaging processing loop. */ static void native_messaging_repl (void) { gpg_error_t err; uint32_t nrequest, nresponse; char *request = NULL; char *response = NULL; size_t n; /* Due to the length octets we need to switch the I/O stream into * binary mode. */ es_set_binary (es_stdin); es_set_binary (es_stdout); + es_setbuf (es_stdin, NULL); /* stdin needs to be unbuffered! */ for (;;) { /* Read length. Note that the protocol uses native endianess. * Is it allowed to call such a thing a well thought out * protocol? */ if (es_read (es_stdin, &nrequest, sizeof nrequest, &n)) { err = gpg_error_from_syserror (); log_error ("error reading request header: %s\n", gpg_strerror (err)); break; } if (!n) break; /* EOF */ if (n != sizeof nrequest) { log_error ("error reading request header: short read\n"); break; } if (nrequest > MAX_REQUEST_SIZE) { log_error ("error reading request: request too long (%zu MiB)\n", (size_t)nrequest / (1024*1024)); - /* Fixme: Shall we read the request t the bit bucket and + /* Fixme: Shall we read the request to the bit bucket and * return an error reponse or just return an error reponse * and terminate? Needs some testing. */ break; } /* Read request. */ request = xtrymalloc (nrequest); if (!request) { err = gpg_error_from_syserror (); log_error ("error reading request: Not enough memory for %zu MiB)\n", (size_t)nrequest / (1024*1024)); /* FIXME: See comment above. */ break; } if (es_read (es_stdin, request, nrequest, &n)) { err = gpg_error_from_syserror (); log_error ("error reading request: %s\n", gpg_strerror (err)); break; } if (n != nrequest) { /* That is a protocol violation. */ xfree (response); response = error_object_string ("Invalid request:" " short read (%zu of %zu bytes)\n", n, (size_t)nrequest); } else /* Process request */ { + if (opt_debug) + log_debug ("request='%s'\n", request); xfree (response); response = process_request (request); + if (opt_debug) + log_debug ("response='%s'\n", response); } nresponse = strlen (response); /* Write response */ if (es_write (es_stdout, &nresponse, sizeof nresponse, &n)) { err = gpg_error_from_syserror (); log_error ("error writing request header: %s\n", gpg_strerror (err)); break; } if (n != sizeof nrequest) { log_error ("error writing request header: short write\n"); break; } if (es_write (es_stdout, response, nresponse, &n)) { err = gpg_error_from_syserror (); log_error ("error writing request: %s\n", gpg_strerror (err)); break; } if (n != nresponse) { log_error ("error writing request: short write\n"); break; } if (es_fflush (es_stdout) || es_ferror (es_stdout)) { err = gpg_error_from_syserror (); log_error ("error writing request: %s\n", gpg_strerror (err)); break; } } xfree (response); xfree (request); } static const char * my_strusage( int level ) { const char *p; switch (level) { case 9: p = "LGPL-2.1-or-later"; break; case 11: p = "gpgme-json"; break; case 13: p = PACKAGE_VERSION; break; case 14: p = "Copyright (C) 2018 g10 Code GmbH"; break; case 19: p = "Please report bugs to <" PACKAGE_BUGREPORT ">.\n"; break; case 1: case 40: p = "Usage: gpgme-json [OPTIONS]"; break; case 41: p = "Native messaging based GPGME operations.\n"; break; case 42: p = "1"; /* Flag print 40 as part of 41. */ break; default: p = NULL; break; } return p; } int main (int argc, char *argv[]) { #if GPGRT_VERSION_NUMBER < 0x011d00 /* 1.29 */ fprintf (stderr, "WARNING: Old libgpg-error - using limited mode\n"); native_messaging_repl (); #else /* This is a modern libgp-error. */ enum { CMD_DEFAULT = 0, CMD_INTERACTIVE = 'i', CMD_SINGLE = 's', - CMD_LIBVERSION = 501 + CMD_LIBVERSION = 501, } cmd = CMD_DEFAULT; + enum { + OPT_DEBUG = 600 + }; + static gpgrt_opt_t opts[] = { ARGPARSE_c (CMD_INTERACTIVE, "interactive", "Interactive REPL"), ARGPARSE_c (CMD_SINGLE, "single", "Single request mode"), ARGPARSE_c (CMD_LIBVERSION, "lib-version", "Show library version"), + ARGPARSE_s_n(OPT_DEBUG, "debug", "Flyswatter"), + ARGPARSE_end() }; gpgrt_argparse_t pargs = { &argc, &argv}; gpgrt_set_strusage (my_strusage); #ifdef HAVE_SETLOCALE setlocale (LC_ALL, ""); #endif gpgme_check_version (NULL); #ifdef LC_CTYPE gpgme_set_locale (NULL, LC_CTYPE, setlocale (LC_CTYPE, NULL)); #endif #ifdef LC_MESSAGES gpgme_set_locale (NULL, LC_MESSAGES, setlocale (LC_MESSAGES, NULL)); #endif while (gpgrt_argparse (NULL, &pargs, opts)) { switch (pargs.r_opt) { case CMD_INTERACTIVE: opt_interactive = 1; /* Fall trough. */ case CMD_SINGLE: case CMD_LIBVERSION: cmd = pargs.r_opt; break; + case OPT_DEBUG: opt_debug = 1; break; + default: pargs.err = ARGPARSE_PRINT_WARNING; break; } } gpgrt_argparse (NULL, &pargs, NULL); + if (!opt_debug) + { + const char *s = getenv ("GPGME_JSON_DEBUG"); + if (s && atoi (s) > 0) + opt_debug = 1; + } + + if (opt_debug) + { + const char *home = getenv ("HOME"); + char *file = xstrconcat ("socket://", + home? home:"/tmp", + "/.gnupg/S.gpgme-json.log", NULL); + log_set_file (file); + xfree (file); + } + + if (opt_debug) + { int i; + for (i=0; argv[i]; i++) + log_debug ("argv[%d]='%s'\n", i, argv[i]); + } + switch (cmd) { case CMD_DEFAULT: native_messaging_repl (); break; case CMD_SINGLE: read_and_process_single_request (); break; case CMD_INTERACTIVE: interactive_repl (); break; case CMD_LIBVERSION: printf ("Version from header: %s (0x%06x)\n", GPGME_VERSION, GPGME_VERSION_NUMBER); printf ("Version from binary: %s\n", gpgme_check_version (NULL)); printf ("Copyright blurb ...:%s\n", gpgme_check_version ("\x01\x01")); break; } + if (opt_debug) + log_debug ("ready"); + #endif /* This is a modern libgp-error. */ return 0; } +#endif /* libgpg-error >= 1.28 */ diff --git a/src/keylist.c b/src/keylist.c index 7956935b..9c5bd4ea 100644 --- a/src/keylist.c +++ b/src/keylist.c @@ -1,1339 +1,1341 @@ /* keylist.c - Listing keys. Copyright (C) 2000 Werner Koch (dd9jn) Copyright (C) 2001, 2002, 2003, 2004, 2006, 2007, 2008, 2009 g10 Code GmbH This file is part of GPGME. GPGME is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version. GPGME is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this program; if not, see . */ #if HAVE_CONFIG_H #include #endif #include #include #include #ifdef HAVE_SYS_TYPES_H /* Solaris 8 needs sys/types.h before time.h. */ # include #endif #include #include #include #include #include /* Suppress warning for accessing deprecated member "class". */ #define _GPGME_IN_GPGME #include "gpgme.h" #include "util.h" #include "context.h" #include "ops.h" #include "debug.h" struct key_queue_item_s { struct key_queue_item_s *next; gpgme_key_t key; }; typedef struct { struct _gpgme_op_keylist_result result; /* The error code from ERROR keydb_search. */ gpgme_error_t keydb_search_err; gpgme_key_t tmp_key; /* This points to the last uid in tmp_key. */ gpgme_user_id_t tmp_uid; /* This points to the last sig in tmp_uid. */ gpgme_key_sig_t tmp_keysig; /* Something new is available. */ int key_cond; struct key_queue_item_s *key_queue; } *op_data_t; static void release_op_data (void *hook) { op_data_t opd = (op_data_t) hook; struct key_queue_item_s *key = opd->key_queue; if (opd->tmp_key) gpgme_key_unref (opd->tmp_key); /* opd->tmp_uid and opd->tmp_keysig are actually part of opd->tmp_key, so we do not need to release them here. */ while (key) { struct key_queue_item_s *next = key->next; gpgme_key_unref (key->key); key = next; } } gpgme_keylist_result_t gpgme_op_keylist_result (gpgme_ctx_t ctx) { void *hook; op_data_t opd; gpgme_error_t err; TRACE_BEG (DEBUG_CTX, "gpgme_op_keylist_result", ctx); err = _gpgme_op_data_lookup (ctx, OPDATA_KEYLIST, &hook, -1, NULL); opd = hook; if (err || !opd) { TRACE_SUC0 ("result=(null)"); return NULL; } TRACE_LOG1 ("truncated = %i", opd->result.truncated); TRACE_SUC1 ("result=%p", &opd->result); return &opd->result; } static gpgme_error_t keylist_status_handler (void *priv, gpgme_status_code_t code, char *args) { gpgme_ctx_t ctx = (gpgme_ctx_t) priv; gpgme_error_t err; void *hook; op_data_t opd; (void)args; err = _gpgme_op_data_lookup (ctx, OPDATA_KEYLIST, &hook, -1, NULL); opd = hook; if (err) return err; switch (code) { case GPGME_STATUS_TRUNCATED: opd->result.truncated = 1; break; case GPGME_STATUS_ERROR: err = _gpgme_parse_failure (args); if (!opd->keydb_search_err && !strcmp (args, "keydb_search")) opd->keydb_search_err = err; err = 0; break; default: break; } return err; } static void set_subkey_trust_info (gpgme_subkey_t subkey, const char *src) { while (*src && !isdigit (*src)) { switch (*src) { case 'e': subkey->expired = 1; break; case 'r': subkey->revoked = 1; break; case 'd': /* Note that gpg 1.3 won't print that anymore but only uses the capabilities field. */ subkey->disabled = 1; break; case 'i': subkey->invalid = 1; break; } src++; } } static void set_mainkey_trust_info (gpgme_key_t key, const char *src) { /* First set the trust info of the main key (the first subkey). */ set_subkey_trust_info (key->subkeys, src); /* Now set the summarized trust info. */ while (*src && !isdigit (*src)) { switch (*src) { case 'e': key->expired = 1; break; case 'r': key->revoked = 1; break; case 'd': /* Note that gpg 1.3 won't print that anymore but only uses the capabilities field. However, it is still used for external key listings. */ key->disabled = 1; break; case 'i': key->invalid = 1; break; } src++; } } static void set_userid_flags (gpgme_key_t key, const char *src) { gpgme_user_id_t uid = key->_last_uid; assert (uid); /* Look at letters and stop at the first digit. */ while (*src && !isdigit (*src)) { switch (*src) { case 'r': uid->revoked = 1; break; case 'i': uid->invalid = 1; break; case 'n': uid->validity = GPGME_VALIDITY_NEVER; break; case 'm': uid->validity = GPGME_VALIDITY_MARGINAL; break; case 'f': uid->validity = GPGME_VALIDITY_FULL; break; case 'u': uid->validity = GPGME_VALIDITY_ULTIMATE; break; } src++; } } static void set_subkey_capability (gpgme_subkey_t subkey, const char *src) { while (*src) { switch (*src) { case 'e': subkey->can_encrypt = 1; break; case 's': subkey->can_sign = 1; break; case 'c': subkey->can_certify = 1; break; case 'a': subkey->can_authenticate = 1; break; case 'q': subkey->is_qualified = 1; break; case 'd': subkey->disabled = 1; break; } src++; } } static void set_mainkey_capability (gpgme_key_t key, const char *src) { /* First set the capabilities of the main key (the first subkey). */ set_subkey_capability (key->subkeys, src); while (*src) { switch (*src) { case 'd': case 'D': /* Note, that this flag is also set using the key validity field for backward compatibility with gpg 1.2. We use d and D, so that a future gpg version will be able to disable certain subkeys. Currently it is expected that gpg sets this for the primary key. */ key->disabled = 1; break; case 'e': case 'E': key->can_encrypt = 1; break; case 's': case 'S': key->can_sign = 1; break; case 'c': case 'C': key->can_certify = 1; break; case 'a': case 'A': key->can_authenticate = 1; break; case 'q': case 'Q': key->is_qualified = 1; break; } src++; } } static void set_ownertrust (gpgme_key_t key, const char *src) { /* Look at letters and stop at the first digit. */ while (*src && !isdigit (*src)) { switch (*src) { case 'n': key->owner_trust = GPGME_VALIDITY_NEVER; break; case 'm': key->owner_trust = GPGME_VALIDITY_MARGINAL; break; case 'f': key->owner_trust = GPGME_VALIDITY_FULL; break; case 'u': key->owner_trust = GPGME_VALIDITY_ULTIMATE; break; default: key->owner_trust = GPGME_VALIDITY_UNKNOWN; break; } src++; } } static gpgme_keyorg_t parse_keyorg (const char *string) { switch (atoi (string)) { case 0: return GPGME_KEYORG_UNKNOWN; case 1: case 2: return GPGME_KEYORG_KS; case 3: return GPGME_KEYORG_DANE; case 4: return GPGME_KEYORG_WKD; case 5: return GPGME_KEYORG_URL; case 6: return GPGME_KEYORG_FILE; case 7: return GPGME_KEYORG_SELF; default: return GPGME_KEYORG_OTHER; } } /* Parse field 15 of a secret key or subkey. This fields holds a reference to smartcards. FIELD is the content of the field and we are allowed to modify it. */ static gpg_error_t parse_sec_field15 (gpgme_key_t key, gpgme_subkey_t subkey, char *field) { if (!*field) ; /* Empty. */ else if (*field == '#') { /* This is a stub for an offline key. We reset the SECRET flag of the subkey here. Note that the secret flag of the entire key will be true even then. We even explicitly set key->secret to make it works for GPGME_KEYLIST_MODE_WITH_SECRET. */ subkey->secret = 0; key->secret = 1; } else if (strchr ("01234567890ABCDEFabcdef", *field)) { /* Fields starts with a hex digit; thus it is a serial number. */ key->secret = 1; subkey->is_cardkey = 1; subkey->card_number = strdup (field); if (!subkey->card_number) return gpg_error_from_syserror (); } else if (*field == '+') { key->secret = 1; subkey->secret = 1; } else { /* RFU. */ } return 0; } /* Parse a tfs record. */ static gpg_error_t parse_tfs_record (gpgme_user_id_t uid, char **field, int nfield) { gpg_error_t err; gpgme_tofu_info_t ti; unsigned long uval; /* We add only the first TOFU record in case future versions emit * several. */ if (uid->tofu) return 0; /* Check that we have enough fields and that the version is supported. */ if (nfield < 8 || atoi(field[1]) != 1) return trace_gpg_error (GPG_ERR_INV_ENGINE); ti = calloc (1, sizeof *ti); if (!ti) return gpg_error_from_syserror (); /* Note that we allow a value of up to 7 which is what we can store * in the ti->validity. */ err = _gpgme_strtoul_field (field[2], &uval); if (err || uval > 7) goto inv_engine; ti->validity = uval; /* Parse the sign-count. */ err = _gpgme_strtoul_field (field[3], &uval); if (err) goto inv_engine; if (uval > USHRT_MAX) uval = USHRT_MAX; ti->signcount = uval; /* Parse the encr-count. */ err = _gpgme_strtoul_field (field[4], &uval); if (err) goto inv_engine; if (uval > USHRT_MAX) uval = USHRT_MAX; ti->encrcount = uval; /* Parse the policy. */ if (!strcmp (field[5], "none")) ti->policy = GPGME_TOFU_POLICY_NONE; else if (!strcmp (field[5], "auto")) ti->policy = GPGME_TOFU_POLICY_AUTO; else if (!strcmp (field[5], "good")) ti->policy = GPGME_TOFU_POLICY_GOOD; else if (!strcmp (field[5], "bad")) ti->policy = GPGME_TOFU_POLICY_BAD; else if (!strcmp (field[5], "ask")) ti->policy = GPGME_TOFU_POLICY_ASK; else /* "unknown" and invalid policy strings. */ ti->policy = GPGME_TOFU_POLICY_UNKNOWN; /* Parse first and last seen timestamps. */ err = _gpgme_strtoul_field (field[6], &uval); if (err) goto inv_engine; ti->signfirst = uval; err = _gpgme_strtoul_field (field[7], &uval); if (err) goto inv_engine; ti->signlast = uval; if (nfield > 9) { /* This condition is only to allow for gpg 2.1.15 - can * eventually be removed. */ err = _gpgme_strtoul_field (field[8], &uval); if (err) goto inv_engine; ti->encrfirst = uval; err = _gpgme_strtoul_field (field[9], &uval); if (err) goto inv_engine; ti->encrlast = uval; } /* Ready. */ uid->tofu = ti; return 0; inv_engine: free (ti); return trace_gpg_error (GPG_ERR_INV_ENGINE); } /* We have read an entire key into tmp_key and should now finish it. It is assumed that this releases tmp_key. */ static void finish_key (gpgme_ctx_t ctx, op_data_t opd) { gpgme_key_t key = opd->tmp_key; opd->tmp_key = NULL; opd->tmp_uid = NULL; opd->tmp_keysig = NULL; if (key) _gpgme_engine_io_event (ctx->engine, GPGME_EVENT_NEXT_KEY, key); } /* Note: We are allowed to modify LINE. */ static gpgme_error_t keylist_colon_handler (void *priv, char *line) { gpgme_ctx_t ctx = (gpgme_ctx_t) priv; enum { RT_NONE, RT_SIG, RT_UID, RT_TFS, RT_SUB, RT_PUB, RT_FPR, RT_GRP, RT_SSB, RT_SEC, RT_CRT, RT_CRS, RT_REV, RT_SPK } rectype = RT_NONE; #define NR_FIELDS 20 char *field[NR_FIELDS]; int fields = 0; void *hook; op_data_t opd; gpgme_error_t err; gpgme_key_t key; gpgme_subkey_t subkey = NULL; gpgme_key_sig_t keysig = NULL; err = _gpgme_op_data_lookup (ctx, OPDATA_KEYLIST, &hook, -1, NULL); opd = hook; if (err) return err; key = opd->tmp_key; TRACE2 (DEBUG_CTX, "gpgme:keylist_colon_handler", ctx, "key = %p, line = %s", key, line ? line : "(null)"); if (!line) { /* End Of File. */ finish_key (ctx, opd); return 0; } while (line && fields < NR_FIELDS) { field[fields++] = line; line = strchr (line, ':'); if (line) *(line++) = '\0'; } if (!strcmp (field[0], "sig")) rectype = RT_SIG; else if (!strcmp (field[0], "rev")) rectype = RT_REV; else if (!strcmp (field[0], "pub")) rectype = RT_PUB; else if (!strcmp (field[0], "sec")) rectype = RT_SEC; else if (!strcmp (field[0], "crt")) rectype = RT_CRT; else if (!strcmp (field[0], "crs")) rectype = RT_CRS; else if (!strcmp (field[0], "fpr") && key) rectype = RT_FPR; else if (!strcmp (field[0], "grp") && key) rectype = RT_GRP; else if (!strcmp (field[0], "uid") && key) rectype = RT_UID; else if (!strcmp (field[0], "tfs") && key) rectype = RT_TFS; else if (!strcmp (field[0], "sub") && key) rectype = RT_SUB; else if (!strcmp (field[0], "ssb") && key) rectype = RT_SSB; else if (!strcmp (field[0], "spk") && key) rectype = RT_SPK; else rectype = RT_NONE; /* Only look at signature and trust info records immediately following a user ID. For this, clear the user ID pointer when encountering anything but a signature or trust record. */ if (rectype != RT_SIG && rectype != RT_REV && rectype != RT_TFS) opd->tmp_uid = NULL; /* Only look at subpackets immediately following a signature. For this, clear the signature pointer when encountering anything but a subpacket. */ if (rectype != RT_SPK) opd->tmp_keysig = NULL; switch (rectype) { case RT_PUB: case RT_SEC: case RT_CRT: case RT_CRS: /* Start a new keyblock. */ err = _gpgme_key_new (&key); if (err) return err; key->keylist_mode = ctx->keylist_mode; err = _gpgme_key_add_subkey (key, &subkey); if (err) { gpgme_key_unref (key); return err; } if (rectype == RT_SEC || rectype == RT_CRS) key->secret = subkey->secret = 1; if (rectype == RT_CRT || rectype == RT_CRS) key->protocol = GPGME_PROTOCOL_CMS; finish_key (ctx, opd); opd->tmp_key = key; /* Field 2 has the trust info. */ if (fields >= 2) set_mainkey_trust_info (key, field[1]); /* Field 3 has the key length. */ if (fields >= 3) { int i = atoi (field[2]); /* Ignore invalid values. */ if (i > 1) subkey->length = i; } /* Field 4 has the public key algorithm. */ if (fields >= 4) { int i = atoi (field[3]); if (i >= 1 && i < 128) subkey->pubkey_algo = _gpgme_map_pk_algo (i, ctx->protocol); } /* Field 5 has the long keyid. Allow short key IDs for the output of an external keyserver listing. */ if (fields >= 5 && strlen (field[4]) <= DIM(subkey->_keyid) - 1) strcpy (subkey->_keyid, field[4]); /* Field 6 has the timestamp (seconds). */ if (fields >= 6) subkey->timestamp = _gpgme_parse_timestamp (field[5], NULL); /* Field 7 has the expiration time (seconds). */ if (fields >= 7) subkey->expires = _gpgme_parse_timestamp (field[6], NULL); /* Field 8 has the X.509 serial number. */ if (fields >= 8 && (rectype == RT_CRT || rectype == RT_CRS)) { key->issuer_serial = strdup (field[7]); if (!key->issuer_serial) return gpg_error_from_syserror (); } /* Field 9 has the ownertrust. */ if (fields >= 9) set_ownertrust (key, field[8]); /* Field 10 is not used for gpg due to --fixed-list-mode option but GPGSM stores the issuer name. */ if (fields >= 10 && (rectype == RT_CRT || rectype == RT_CRS)) if (_gpgme_decode_c_string (field[9], &key->issuer_name, 0)) return gpg_error (GPG_ERR_ENOMEM); /* FIXME */ /* Field 11 has the signature class. */ /* Field 12 has the capabilities. */ if (fields >= 12) set_mainkey_capability (key, field[11]); /* Field 15 carries special flags of a secret key. */ if (fields >= 15 && (key->secret || (ctx->keylist_mode & GPGME_KEYLIST_MODE_WITH_SECRET))) { err = parse_sec_field15 (key, subkey, field[14]); if (err) return err; } /* Field 17 has the curve name for ECC. */ if (fields >= 17 && *field[16]) { subkey->curve = strdup (field[16]); if (!subkey->curve) return gpg_error_from_syserror (); } /* Field 18 has the compliance flags. */ if (fields >= 17 && *field[17]) PARSE_COMPLIANCE_FLAGS (field[17], subkey); if (fields >= 20) { key->last_update = _gpgme_parse_timestamp_ul (field[18]); key->origin = parse_keyorg (field[19]); } break; case RT_SUB: case RT_SSB: /* Start a new subkey. */ err = _gpgme_key_add_subkey (key, &subkey); if (err) return err; if (rectype == RT_SSB) subkey->secret = 1; /* Field 2 has the trust info. */ if (fields >= 2) set_subkey_trust_info (subkey, field[1]); /* Field 3 has the key length. */ if (fields >= 3) { int i = atoi (field[2]); /* Ignore invalid values. */ if (i > 1) subkey->length = i; } /* Field 4 has the public key algorithm. */ if (fields >= 4) { int i = atoi (field[3]); if (i >= 1 && i < 128) subkey->pubkey_algo = _gpgme_map_pk_algo (i, ctx->protocol); } /* Field 5 has the long keyid. */ if (fields >= 5 && strlen (field[4]) == DIM(subkey->_keyid) - 1) strcpy (subkey->_keyid, field[4]); /* Field 6 has the timestamp (seconds). */ if (fields >= 6) subkey->timestamp = _gpgme_parse_timestamp (field[5], NULL); /* Field 7 has the expiration time (seconds). */ if (fields >= 7) subkey->expires = _gpgme_parse_timestamp (field[6], NULL); /* Field 8 is reserved (LID). */ /* Field 9 has the ownertrust. */ /* Field 10, the user ID, is n/a for a subkey. */ /* Field 11 has the signature class. */ /* Field 12 has the capabilities. */ if (fields >= 12) set_subkey_capability (subkey, field[11]); /* Field 15 carries special flags of a secret key. */ if (fields >= 15 && (key->secret || (ctx->keylist_mode & GPGME_KEYLIST_MODE_WITH_SECRET))) { err = parse_sec_field15 (key, subkey, field[14]); if (err) return err; } /* Field 17 has the curve name for ECC. */ if (fields >= 17 && *field[16]) { subkey->curve = strdup (field[16]); if (!subkey->curve) return gpg_error_from_syserror (); } /* Field 18 has the compliance flags. */ if (fields >= 17 && *field[17]) PARSE_COMPLIANCE_FLAGS (field[17], subkey); break; case RT_UID: /* Field 2 has the trust info, and field 10 has the user ID. */ if (fields >= 10) { if (_gpgme_key_append_name (key, field[9], 1)) return gpg_error (GPG_ERR_ENOMEM); /* FIXME */ if (field[1]) set_userid_flags (key, field[1]); opd->tmp_uid = key->_last_uid; if (fields >= 20) { opd->tmp_uid->last_update = _gpgme_parse_timestamp_ul (field[18]); opd->tmp_uid->origin = parse_keyorg (field[19]); } } break; case RT_TFS: if (opd->tmp_uid) { err = parse_tfs_record (opd->tmp_uid, field, fields); if (err) return err; } break; case RT_FPR: /* Field 10 has the fingerprint (take only the first one). */ if (fields >= 10 && field[9] && *field[9]) { /* Need to apply it to the last subkey because all subkeys do have fingerprints. */ subkey = key->_last_subkey; if (!subkey->fpr) { subkey->fpr = strdup (field[9]); if (!subkey->fpr) return gpg_error_from_syserror (); } /* If this is the first subkey, store the fingerprint also in the KEY object. */ if (subkey == key->subkeys) { if (key->fpr && strcmp (key->fpr, subkey->fpr)) { /* FPR already set but mismatch: Should never happen. */ return trace_gpg_error (GPG_ERR_INTERNAL); } if (!key->fpr) { key->fpr = strdup (subkey->fpr); if (!key->fpr) return gpg_error_from_syserror (); } } } /* Field 13 has the gpgsm chain ID (take only the first one). */ if (fields >= 13 && !key->chain_id && *field[12]) { key->chain_id = strdup (field[12]); if (!key->chain_id) return gpg_error_from_syserror (); } break; case RT_GRP: /* Field 10 has the keygrip. */ if (fields >= 10 && field[9] && *field[9]) { /* Need to apply it to the last subkey because all subkeys have a keygrip. */ subkey = key->_last_subkey; if (!subkey->keygrip) { subkey->keygrip = strdup (field[9]); if (!subkey->keygrip) return gpg_error_from_syserror (); } } break; case RT_SIG: case RT_REV: if (!opd->tmp_uid) return 0; /* Start a new (revoked) signature. */ assert (opd->tmp_uid == key->_last_uid); keysig = _gpgme_key_add_sig (key, (fields >= 10) ? field[9] : NULL); if (!keysig) return gpg_error (GPG_ERR_ENOMEM); /* FIXME */ /* Field 2 has the calculated trust ('!', '-', '?', '%'). */ if (fields >= 2) switch (field[1][0]) { case '!': keysig->status = gpg_error (GPG_ERR_NO_ERROR); break; case '-': keysig->status = gpg_error (GPG_ERR_BAD_SIGNATURE); break; case '?': keysig->status = gpg_error (GPG_ERR_NO_PUBKEY); break; case '%': keysig->status = gpg_error (GPG_ERR_GENERAL); break; default: keysig->status = gpg_error (GPG_ERR_NO_ERROR); break; } /* Field 4 has the public key algorithm. */ if (fields >= 4) { int i = atoi (field[3]); if (i >= 1 && i < 128) keysig->pubkey_algo = _gpgme_map_pk_algo (i, ctx->protocol); } /* Field 5 has the long keyid. */ if (fields >= 5 && strlen (field[4]) == DIM(keysig->_keyid) - 1) strcpy (keysig->_keyid, field[4]); /* Field 6 has the timestamp (seconds). */ if (fields >= 6) keysig->timestamp = _gpgme_parse_timestamp (field[5], NULL); /* Field 7 has the expiration time (seconds). */ if (fields >= 7) keysig->expires = _gpgme_parse_timestamp (field[6], NULL); /* Field 11 has the signature class (eg, 0x30 means revoked). */ if (fields >= 11) if (field[10][0] && field[10][1]) { int sig_class = _gpgme_hextobyte (field[10]); if (sig_class >= 0) { keysig->sig_class = sig_class; keysig->class = keysig->sig_class; if (sig_class == 0x30) keysig->revoked = 1; } if (field[10][2] == 'x') keysig->exportable = 1; } opd->tmp_keysig = keysig; break; case RT_SPK: if (!opd->tmp_keysig) return 0; assert (opd->tmp_keysig == key->_last_uid->_last_keysig); if (fields >= 4) { /* Field 2 has the subpacket type. */ int type = atoi (field[1]); /* Field 3 has the flags. */ int flags = atoi (field[2]); /* Field 4 has the length. */ int len = atoi (field[3]); /* Field 5 has the data. */ char *data = field[4]; /* Type 20: Notation data. */ /* Type 26: Policy URL. */ if (type == 20 || type == 26) { gpgme_sig_notation_t notation; keysig = opd->tmp_keysig; /* At this time, any error is serious. */ err = _gpgme_parse_notation (¬ation, type, flags, len, data); if (err) return err; /* Add a new notation. FIXME: Could be factored out. */ if (!keysig->notations) keysig->notations = notation; if (keysig->_last_notation) keysig->_last_notation->next = notation; keysig->_last_notation = notation; } } case RT_NONE: /* Unknown record. */ break; } return 0; } void _gpgme_op_keylist_event_cb (void *data, gpgme_event_io_t type, void *type_data) { gpgme_error_t err; gpgme_ctx_t ctx = (gpgme_ctx_t) data; gpgme_key_t key = (gpgme_key_t) type_data; void *hook; op_data_t opd; struct key_queue_item_s *q, *q2; assert (type == GPGME_EVENT_NEXT_KEY); err = _gpgme_op_data_lookup (ctx, OPDATA_KEYLIST, &hook, -1, NULL); opd = hook; if (err) return; q = malloc (sizeof *q); if (!q) { gpgme_key_unref (key); /* FIXME return GPGME_Out_Of_Core; */ return; } q->key = key; q->next = NULL; /* FIXME: Use a tail pointer? */ if (!(q2 = opd->key_queue)) opd->key_queue = q; else { for (; q2->next; q2 = q2->next) ; q2->next = q; } opd->key_cond = 1; } /* Start a keylist operation within CTX, searching for keys which match PATTERN. If SECRET_ONLY is true, only secret keys are returned. */ gpgme_error_t gpgme_op_keylist_start (gpgme_ctx_t ctx, const char *pattern, int secret_only) { gpgme_error_t err; void *hook; op_data_t opd; int flags = 0; TRACE_BEG2 (DEBUG_CTX, "gpgme_op_keylist_start", ctx, "pattern=%s, secret_only=%i", pattern, secret_only); if (!ctx) return TRACE_ERR (gpg_error (GPG_ERR_INV_VALUE)); err = _gpgme_op_reset (ctx, 2); if (err) return TRACE_ERR (err); err = _gpgme_op_data_lookup (ctx, OPDATA_KEYLIST, &hook, sizeof (*opd), release_op_data); opd = hook; if (err) return TRACE_ERR (err); _gpgme_engine_set_status_handler (ctx->engine, keylist_status_handler, ctx); err = _gpgme_engine_set_colon_line_handler (ctx->engine, keylist_colon_handler, ctx); if (err) return TRACE_ERR (err); if (ctx->offline) flags |= GPGME_ENGINE_FLAG_OFFLINE; err = _gpgme_engine_op_keylist (ctx->engine, pattern, secret_only, ctx->keylist_mode, flags); return TRACE_ERR (err); } /* Start a keylist operation within CTX, searching for keys which match PATTERN. If SECRET_ONLY is true, only secret keys are returned. */ gpgme_error_t gpgme_op_keylist_ext_start (gpgme_ctx_t ctx, const char *pattern[], int secret_only, int reserved) { gpgme_error_t err; void *hook; op_data_t opd; int flags = 0; TRACE_BEG2 (DEBUG_CTX, "gpgme_op_keylist_ext_start", ctx, "secret_only=%i, reserved=0x%x", secret_only, reserved); if (!ctx) return TRACE_ERR (gpg_error (GPG_ERR_INV_VALUE)); err = _gpgme_op_reset (ctx, 2); if (err) return TRACE_ERR (err); err = _gpgme_op_data_lookup (ctx, OPDATA_KEYLIST, &hook, sizeof (*opd), release_op_data); opd = hook; if (err) return TRACE_ERR (err); _gpgme_engine_set_status_handler (ctx->engine, keylist_status_handler, ctx); err = _gpgme_engine_set_colon_line_handler (ctx->engine, keylist_colon_handler, ctx); if (err) return TRACE_ERR (err); if (ctx->offline) flags |= GPGME_ENGINE_FLAG_OFFLINE; err = _gpgme_engine_op_keylist_ext (ctx->engine, pattern, secret_only, reserved, ctx->keylist_mode, flags); return TRACE_ERR (err); } /* Start a keylist operation within CTX to show keys contained * in DATA. */ gpgme_error_t gpgme_op_keylist_from_data_start (gpgme_ctx_t ctx, gpgme_data_t data, int reserved) { gpgme_error_t err; void *hook; op_data_t opd; TRACE_BEG (DEBUG_CTX, "gpgme_op_keylist_from_data_start", ctx); if (!ctx || !data || reserved) return TRACE_ERR (gpg_error (GPG_ERR_INV_VALUE)); err = _gpgme_op_reset (ctx, 2); if (err) return TRACE_ERR (err); err = _gpgme_op_data_lookup (ctx, OPDATA_KEYLIST, &hook, sizeof (*opd), release_op_data); opd = hook; if (err) return TRACE_ERR (err); _gpgme_engine_set_status_handler (ctx->engine, keylist_status_handler, ctx); err = _gpgme_engine_set_colon_line_handler (ctx->engine, keylist_colon_handler, ctx); if (err) return TRACE_ERR (err); err = _gpgme_engine_op_keylist_data (ctx->engine, data); return TRACE_ERR (err); } /* Return the next key from the keylist in R_KEY. */ gpgme_error_t gpgme_op_keylist_next (gpgme_ctx_t ctx, gpgme_key_t *r_key) { gpgme_error_t err; struct key_queue_item_s *queue_item; void *hook; op_data_t opd; TRACE_BEG (DEBUG_CTX, "gpgme_op_keylist_next", ctx); if (!ctx || !r_key) return TRACE_ERR (gpg_error (GPG_ERR_INV_VALUE)); *r_key = NULL; if (!ctx) return TRACE_ERR (gpg_error (GPG_ERR_INV_VALUE)); err = _gpgme_op_data_lookup (ctx, OPDATA_KEYLIST, &hook, -1, NULL); opd = hook; if (err) return TRACE_ERR (err); if (opd == NULL) return TRACE_ERR (gpg_error (GPG_ERR_INV_VALUE)); if (!opd->key_queue) { err = _gpgme_wait_on_condition (ctx, &opd->key_cond, NULL); if (err) return TRACE_ERR (err); if (!opd->key_cond) return TRACE_ERR (opd->keydb_search_err? opd->keydb_search_err /**/ : gpg_error (GPG_ERR_EOF)); opd->key_cond = 0; assert (opd->key_queue); } queue_item = opd->key_queue; opd->key_queue = queue_item->next; if (!opd->key_queue) opd->key_cond = 0; *r_key = queue_item->key; free (queue_item); return TRACE_SUC2 ("key=%p (%s)", *r_key, ((*r_key)->subkeys && (*r_key)->subkeys->fpr) ? (*r_key)->subkeys->fpr : "invalid"); } /* Terminate a pending keylist operation within CTX. */ gpgme_error_t gpgme_op_keylist_end (gpgme_ctx_t ctx) { TRACE (DEBUG_CTX, "gpgme_op_keylist_end", ctx); if (!ctx) return gpg_error (GPG_ERR_INV_VALUE); return 0; } /* Get the key with the fingerprint FPR from the crypto backend. If SECRET is true, get the secret key. */ gpgme_error_t gpgme_get_key (gpgme_ctx_t ctx, const char *fpr, gpgme_key_t *r_key, int secret) { gpgme_ctx_t listctx; gpgme_error_t err; gpgme_key_t result, key; TRACE_BEG2 (DEBUG_CTX, "gpgme_get_key", ctx, "fpr=%s, secret=%i", fpr, secret); if (!ctx || !r_key || !fpr) return TRACE_ERR (gpg_error (GPG_ERR_INV_VALUE)); + *r_key = NULL; + if (strlen (fpr) < 8) /* We have at least a key ID. */ return TRACE_ERR (gpg_error (GPG_ERR_INV_VALUE)); /* FIXME: We use our own context because we have to avoid the user's I/O callback handlers. */ err = gpgme_new (&listctx); if (err) return TRACE_ERR (err); { gpgme_protocol_t proto; gpgme_engine_info_t info; /* Clone the relevant state. */ proto = gpgme_get_protocol (ctx); gpgme_set_protocol (listctx, proto); gpgme_set_keylist_mode (listctx, gpgme_get_keylist_mode (ctx)); info = gpgme_ctx_get_engine_info (ctx); while (info && info->protocol != proto) info = info->next; if (info) gpgme_ctx_set_engine_info (listctx, proto, info->file_name, info->home_dir); } err = gpgme_op_keylist_start (listctx, fpr, secret); if (!err) err = gpgme_op_keylist_next (listctx, &result); if (!err) { try_next_key: err = gpgme_op_keylist_next (listctx, &key); if (gpgme_err_code (err) == GPG_ERR_EOF) err = 0; else { if (!err && result && result->subkeys && result->subkeys->fpr && key && key->subkeys && key->subkeys->fpr && !strcmp (result->subkeys->fpr, key->subkeys->fpr)) { /* The fingerprint is identical. We assume that this is the same key and don't mark it as an ambiguous. This problem may occur with corrupted keyrings and has been noticed often with gpgsm. In fact gpgsm uses a similar hack to sort out such duplicates but it can't do that while listing keys. */ gpgme_key_unref (key); goto try_next_key; } if (!err) { gpgme_key_unref (key); err = gpg_error (GPG_ERR_AMBIGUOUS_NAME); } gpgme_key_unref (result); result = NULL; } } gpgme_release (listctx); if (! err) { *r_key = result; TRACE_LOG2 ("key=%p (%s)", *r_key, ((*r_key)->subkeys && (*r_key)->subkeys->fpr) ? (*r_key)->subkeys->fpr : "invalid"); } return TRACE_ERR (err); }