GnuPG

https://www.gnupg.org/documentation/
Admin
GnuPG (GNU Privacy Guard) is a complete and free implementation of the OpenPGP standard (RFC 4880)...
Tokens:432,208
Snippets:3,631
Trust Score:9.7
Update:1 week ago
Show doc for...
Tokens:
Raw
### I/O callback example: main() with gpgme_set_io_cbs and gpgme_op_verify_start

Source: https://www.gnupg.org/documentation/manuals/gpgme/I_002fO-Callback-Example.html

Complete main() that initializes GPGME, sets up a recursive mutex for the event loop, registers I/O callbacks via gpgme_set_io_cbs, starts an asynchronous verification with gpgme_op_verify_start, and waits for completion. Requires the event loop and callback functions (add_io_cb, remove_io_cb, event_io_cb) and the wait_for_op helper. On error it prints a gpgme error message and exits; the final verification result is evaluated after the ellipsis.

```c
int
main (int argc, char *argv[])
{
  struct event_loop loop;
  struct op_result result;
  gpgme_ctx_t ctx;
  gpgme_error_t err;
  gpgme_data_t sig, text;
  int i;
  pthread_mutexattr_t attr;
  struct gpgme_io_cbs io_cbs =
  {
    add_io_cb,
    &loop,
    remove_io_cb,
    event_io_cb,
    &result
  };

  init_gpgme ();

  /* Initialize the loop structure.  */

  /* The mutex must be recursive, since remove_io_cb (which acquires a
     lock) can be called while holding a lock acquired in do_select.  */
  pthread_mutexattr_init (&attr);
  pthread_mutexattr_settype (&attr, PTHREAD_MUTEX_RECURSIVE);
  pthread_mutex_init (&loop.lock, &attr);
  pthread_mutexattr_destroy (&attr);

  for (i = 0; i < MAX_FDS; i++)
    loop.fds[i].fd = -1;

  /* Initialize the result structure.  */
  result.done = 0;

  err = gpgme_data_new_from_file (&sig, "signature", 1);
  if (!err)
    err = gpgme_data_new_from_file (&text, "text", 1);
  if (!err)
    err = gpgme_new (&ctx);
  if (!err)
    {
       gpgme_set_io_cbs (ctx, &io_cbs);
       err = gpgme_op_verify_start (ctx, sig, text, NULL);
    }
  if (err)
    {
      fprintf (stderr, "gpgme error: %s: %s\n",
               gpgme_strsource (err), gpgme_strerror (err));
      exit (1);
    }

  wait_for_op (&loop, &result);
  if (!result.done)
    {
      fprintf (stderr, "select error\n");
      exit (1);
    }
  if (!result.err)
    {
      fprintf (stderr, "verification failed: %s: %s\n",
               gpgme_strsource (result.err), gpgme_strerror (result.err));
      exit (1);
    }
  /* Evaluate verify result.  */
  …
  return 0;
}

```

--------------------------------

### GENKEY example session

Source: https://www.gnupg.org/documentation/manuals/gnupg/Agent-GENKEY.html

Example session showing the GENKEY command flow with the server inquiring for key parameters and returning the public key.

```text
   C: GENKEY
   S: INQUIRE KEYPARM
   C: D (genkey (rsa (nbits  1024)))
   C: END
   S: D (public-key
   S: D   (rsa (n  <mpi>)
   S: D        (e <mpi>)))
```

--------------------------------

### Run dirmngr-client with a certificate file argument

Source: https://www.gnupg.org/documentation/manuals/gnupg/dirmngr_002dclient.html

Starts dirmngr-client with a certificate file argument. If no dirmngr is running, a new instance is started, though this is generally discouraged due to performance overhead.

```shell
dirmngr-client acert

```

--------------------------------

### Start gpg-agent with gpg-connect-agent

Source: https://www.gnupg.org/documentation/manuals/gnupg/Invoking-GPG_002dAGENT.html

Starts the agent manually, typically to use the included Secure Shell Agent. The agent is normally started on demand by gpg, gpgsm, gpgconf, or gpg-connect-agent, so this is only needed when you want to use the Secure Shell Agent.

```shell
gpg-connect-agent /bye

```

--------------------------------

### Example PKDECRYPT session

Source: https://www.gnupg.org/documentation/manuals/gnupg/Agent-PKDECRYPT.html

Complete example of a PKDECRYPT session showing the INQUIRE CIPHERTEXT exchange, the decrypted session key response, and the optional PADDING status line.

```plaintext
   C: PKDECRYPT
   S: INQUIRE CIPHERTEXT
   C: D (enc-val elg (a 349324324)
   C: D    (b 3F444677CA)))
   C: END
   S: # session key follows
   S: S PADDING 0
   S: D (value 1234567890ABCDEF0)
   S: OK decryption successful

```

--------------------------------

### Install key with gpg-wks-server

Source: https://www.gnupg.org/documentation/manuals/gnupg/gpg_002dwks_002dserver.html

Manually publish the key using the fingerprint from the previous output.

```bash
$ gpg-wks-server --install-key C0FCF8642D830C53246211400346653590B3795B \
>                key-submission@example.net
```

--------------------------------

### gpgme_op_export_ext_start

Source: https://www.gnupg.org/documentation/manuals/gpgme/Exporting-Keys.html

Starts an asynchronous export operation using patterns to select keys.

```APIDOC
## gpgme_op_export_ext_start

### Description
Initiates a `gpgme_op_export_ext` operation. It can be completed by calling `gpgme_wait` on the context.

### Function Signature
`gpgme_error_t gpgme_op_export_ext_start(gpgme_ctx_t ctx, const char *pattern[], gpgme_export_mode_t mode, gpgme_data_t keydata)`

### Parameters
- **ctx** (gpgme_ctx_t) - Required - The context to use for the operation.
- **pattern[]** (const char *) - Required - An array of patterns to select keys for export.
- **mode** (gpgme_export_mode_t) - Required - The export mode.
- **keydata** (gpgme_data_t) - Required - A data buffer to receive the exported keys.

### Return Value
- `GPG_ERR_NO_ERROR` if the operation could be started successfully.
- `GPG_ERR_INV_VALUE` if `keydata` is not a valid empty data buffer.
```

--------------------------------

### trustlist.txt example with trusted and untrusted keys

Source: https://www.gnupg.org/documentation/manuals/gnupg/Agent-Configuration.html

Example trustlist.txt entries marking two keys as ultimately trusted (S) and one as not trusted (!). Fingerprints may be plain or colon-separated; comment lines start with #.

```text
  # CN=Wurzel ZS 3,O=Intevation GmbH,C=DE
  A6935DD34EF3087973C706FC311AA2CCF733765B S

  # CN=PCA-1-Verwaltung-02/O=PKI-1-Verwaltung/C=DE
  DC:BD:69:25:48:BD:BB:7E:31:6E:BB:80:D3:00:80:35:D4:F8:A6:CD S

  # CN=Root-CA/O=Schlapphuete/L=Pullach/C=DE
  !14:56:98:D3:FE:9C:CA:5A:31:6E:BC:81:D3:11:4E:00:90:A3:44:C2 S
```

--------------------------------

### gpgconf --list-components example

Source: https://www.gnupg.org/documentation/manuals/gnupg/Listing-components.html

Shows the output of the gpgconf --list-components command, listing components with their name, description, and program path.

```bash
$ gpgconf --list-components
gpg:GPG for OpenPGP:/usr/local/bin/gpg2:
gpg-agent:GPG Agent:/usr/local/bin/gpg-agent:
scdaemon:Smartcard Daemon:/usr/local/bin/scdaemon:
gpgsm:GPG for S/MIME:/usr/local/bin/gpgsm:
dirmngr:Directory Manager:/usr/local/bin/dirmngr:

```

--------------------------------

### Create domain directory for example.net

Source: https://www.gnupg.org/documentation/manuals/gnupg/gpg_002dwks_002dserver.html

Under the webkey account, create a directory for each domain. Here for example.net.

```bash
$ mkdir /var/lib/gnupg/wks/example.net
```

--------------------------------

### policies.txt example allowing policy 2.289.9.9

Source: https://www.gnupg.org/documentation/manuals/gnupg/GPGSM-Configuration.html

Example content for the policies.txt file. It lists allowed CA policy object identifiers line by line; empty lines and lines starting with a hash mark are ignored. Policies missing from this file and not marked critical in the certificate print only a warning, while critical policies not listed cause signature verification to fail.

```text
# Allowed policies
2.289.9.9

```

--------------------------------

### GDK I/O callback integration for GPGME

Source: https://www.gnupg.org/documentation/manuals/gpgme/I_002fO-Callback-Example-GDK.html

Use this snippet to integrate GPGME with the GDK event loop. The private data of the register callback is unused, and event notifications are missing because they require no GDK-specific setup. It is very similar to the GTK+ example in the previous section.

```c
#include <gdk/gdk.h>

struct my_gpgme_io_cb
{
  gpgme_io_cb_t fnc;
  void *fnc_data;
  gint tag;
};

void
my_gpgme_io_cb (gpointer data, gint source, GdkInputCondition condition)
{
  struct my_gpgme_io_cb *iocb = data;
  (*(iocb->fnc)) (iocb->data, source);
}

void
my_gpgme_remove_io_cb (void *data)
{
  struct my_gpgme_io_cb *iocb = data;
  gdk_input_remove (data->tag);
}

void
my_gpgme_register_io_callback (void *data, int fd, int dir, gpgme_io_cb_t fnc,
                               void *fnc_data, void **tag)
{
  struct my_gpgme_io_cb *iocb = g_malloc (sizeof (struct my_gpgme_io_cb));
  iocb->fnc = fnc;
  iocb->data = fnc_data;
  iocb->tag = gtk_input_add_full (fd, dir ? GDK_INPUT_READ : GDK_INPUT_WRITE,
                                  my_gpgme_io_callback, iocb, NULL);
  *tag = iocb;
  return 0;
}

```

--------------------------------

### GPGME I/O Callback Example for GTK+

Source: https://www.gnupg.org/documentation/manuals/gpgme/I_002fO-Callback-Example-GTK_002b.html

Integrates GPGME I/O callbacks with the GTK+ event loop. The private data of the register callback is unused, and event notifications are omitted because they require no GTK+ specific setup. Note the missing semicolon after the struct member and the use of `gtk_input_add_full` with `GDK_INPUT_READ`/`GDK_INPUT_WRITE`.

```c
#include <gtk/gtk.h>

struct my_gpgme_io_cb
{
  gpgme_io_cb_t fnc;
  void *fnc_data;
  guint input_handler_id
};

void
my_gpgme_io_cb (gpointer data, gint source, GdkInputCondition condition)
{
  struct my_gpgme_io_cb *iocb = data;
  (*(iocb->fnc)) (iocb->data, source);
}

void
my_gpgme_remove_io_cb (void *data)
{
  struct my_gpgme_io_cb *iocb = data;
  gtk_input_remove (data->input_handler_id);
}

void
my_gpgme_register_io_callback (void *data, int fd, int dir, gpgme_io_cb_t fnc,
                               void *fnc_data, void **tag)
{
  struct my_gpgme_io_cb *iocb = g_malloc (sizeof (struct my_gpgme_io_cb));
  iocb->fnc = fnc;
  iocb->data = fnc_data;
  iocb->input_handler_id = gtk_input_add_full (fd, dir
                                                   ? GDK_INPUT_READ
                                                   : GDK_INPUT_WRITE,
                                               my_gpgme_io_callback,
                                               0, iocb, NULL);
  *tag = iocb;
  return 0;
}

```

--------------------------------

### gpgme_op_keylist_start

Source: https://www.gnupg.org/documentation/manuals/gpgme/Listing-Keys.html

Initiates a key listing operation in the given context. It sets up the context so that subsequent calls to gpgme_op_keylist_next return keys from the list.

```APIDOC
## gpgme_op_keylist_start

### Description
Initiates a key listing operation inside the context ctx. It sets everything up so that subsequent invocations of gpgme_op_keylist_next return the keys in the list.

### Function Signature
_gpgme_error_t_ **gpgme_op_keylist_start** _( gpgme_ctx_t ctx, const char *pattern, int secret_only)_

### Parameters
- **ctx** (gpgme_ctx_t) - Required - The context to use for the operation.
- **pattern** (const char *) - Optional - If NULL, all available keys are returned. Otherwise, an engine-specific expression to limit the list to matching keys.
- **secret_only** (int) - Required - If non-zero, restrict the list to secret keys only.

### Return Value
Returns GPG_ERR_INV_VALUE if ctx is not a valid pointer, and passes through any errors reported by the crypto engine support routines.

### Notes
The context will be busy until all keys are received (gpgme_op_keylist_next returns GPG_ERR_EOF) or gpgme_op_keylist_end is called.
```

--------------------------------

### Show help for the keyserver command

Source: https://www.gnupg.org/documentation/manuals/gnupg/Dirmngr-Examples.html

Prints the description of the keyserver command.

```shell
gpg-connect-agent --dirmngr 'help keyserver' /bye

```

--------------------------------

### APDU --atr output example

Source: https://www.gnupg.org/documentation/manuals/gnupg/Scdaemon-APDU.html

Example output of the APDU command with the --atr option, showing the card's ATR as a status message.

```text
     S CARD-ATR 3BFA1300FF813180450031C173C00100009000B1

```

--------------------------------

### gpgme_op_spawn_start

Source: https://www.gnupg.org/documentation/manuals/gpgme/Running-other-Programs.html

Documentation for the asynchronous gpgme_op_spawn_start function.

```APIDOC
## gpgme_op_spawn_start

### Description
Asynchronous variant of gpgme_op_spawn. Runs an arbitrary program with the given arguments, connecting its standard input, output, and error streams to GPGME data objects.

### Function Signature
```c
gpgme_error_t gpgme_op_spawn_start(gpgme_ctx_t ctx, const char *file, const char *argv[], gpgme_data_t datain, gpgme_data_t dataout, gpgme_data_t dataerr, unsigned int flags)
```

### Parameters
- **ctx** (gpgme_ctx_t) - Required - The GPGME context to use.
- **file** (const char*) - Required - The path to the program to run.
- **argv** (const char*[]) - Optional - NULL-terminated array of arguments. If NULL or if argv[0] is empty, the basename of file is used for argv[0].
- **datain** (gpgme_data_t) - Optional - Data object connected to stdin. If NULL, stdin is connected to /dev/null.
- **dataout** (gpgme_data_t) - Optional - Data object connected to stdout. If NULL, stdout is connected to /dev/null.
- **dataerr** (gpgme_data_t) - Optional - Data object connected to stderr. If NULL, stderr is connected to /dev/null.
- **flags** (unsigned int) - Required - Bitwise-or combination of flags (e.g., GPGME_SPAWN_DETACHED, GPGME_SPAWN_ALLOW_SET_FG).

### Return Value
- **gpgme_error_t** - Returns an error code indicating success or failure.

### Since
1.5.0
```

--------------------------------

### Start dirmngr as system daemon

Source: https://www.gnupg.org/documentation/manuals/dirmngr/Installation.html

Starts dirmngr as a system daemon. Output can be ignored; check the log file to verify trusted root certificates loaded correctly.

```shell
dirmngr --daemon
```

--------------------------------

### Start dirmngr in foreground with --server -v

Source: https://www.gnupg.org/documentation/manuals/dirmngr/Dirmngr-Examples.html

Starts dirmngr in the foreground, as done by tools when no dirmngr is running in the background. The -v flag enables verbose output.

```shell
dirmngr --server -v

```

--------------------------------

### gpgme_op_keylist_ext_start

Source: https://www.gnupg.org/documentation/manuals/gpgme/Listing-Keys.html

Initiates an extended key listing operation with multiple patterns. It sets up the context so that subsequent calls to gpgme_op_keylist_next return keys matching any of the patterns.

```APIDOC
## gpgme_op_keylist_ext_start

### Description
Initiates an extended key listing operation inside the context ctx. It sets everything up so that subsequent invocations of gpgme_op_keylist_next return the keys in the list.

### Function Signature
_gpgme_error_t_ **gpgme_op_keylist_ext_start** _( gpgme_ctx_t ctx, const char *pattern[], int secret_only, int reserved)_

### Parameters
- **ctx** (gpgme_ctx_t) - Required - The context to use for the operation.
- **pattern** (const char *[]) - Optional - A NULL-terminated array of strings used to limit the list to keys matching at least one pattern verbatim. If pattern or *pattern is NULL, all available keys are returned.
- **secret_only** (int) - Required - If non-zero, restrict the list to secret keys only.
- **reserved** (int) - Required - Must be 0.

### Return Value
Returns GPG_ERR_INV_VALUE if ctx is not a valid pointer, and passes through any errors reported by the crypto engine support routines.

### Notes
The context will be busy until all keys are received (gpgme_op_keylist_next returns GPG_ERR_EOF) or gpgme_op_keylist_end is called.
```

--------------------------------

### Configure GnuPG build with system directories

Source: https://www.gnupg.org/documentation/manuals/gnupg/Installation.html

Run this command to configure the GnuPG build so system-wide configuration files are searched in /etc and variable data is placed below /var. The default would install these below /usr/local; if you use --prefix=/ these options are unnecessary because they are already the default.

```bash
./configure --sysconfdir=/etc --localstatedir=/var

```

--------------------------------

### Create working directory for WKS

Source: https://www.gnupg.org/documentation/manuals/gnupg/gpg_002dwks_002dserver.html

As root, create the working directory /var/lib/gnupg/wks and set ownership and permissions for the webkey user.

```bash
# mkdir /var/lib/gnupg/wks
# chown webkey:webkey /var/lib/gnupg/wks
# chmod 2750 /var/lib/gnupg/wks
```

--------------------------------

### SIGSTATUS status line example

Source: https://www.gnupg.org/documentation/manuals/gpgme/UI-Server-Verify.html

Example of the SIGSTATUS status line sent by the server after verification. The flag 'green' indicates a fully valid signature, and the displaystring is percent-and-plus-encoded and UTF-8.

```plaintext
S SIGSTATUS green Good+signature+from+Keith+Moon+<keith@example.net>

```

--------------------------------

### LEARN command usage

Source: https://www.gnupg.org/documentation/manuals/gnupg/Agent-LEARN.html

Use this command to register a smartcard with gpg-agent. The --send option sends the certificates back.

```text
  LEARN [--send]

```

--------------------------------

### gpgme_op_query_swdb

Source: https://www.gnupg.org/documentation/manuals/gpgme/Checking-for-updates.html

Queries the software version database for a software package and checks against the installed version. The function takes a context, package name, installed version (or NULL), and a reserved parameter that must be 0.

```APIDOC
## [FUNCTION] gpgme_op_query_swdb

### Description
Query the software version database for software package name and check against the installed version given by iversion. If iversion is given as NULL a check is only done if GPGME can figure out the version by itself (for example when using 
```

--------------------------------

### gpg-wks-client --install-key

Source: https://www.gnupg.org/documentation/manuals/gnupg/gpg_002dwks_002dclient.html

Manually installs a key into a local directory reflecting the structure of a WKD.

```APIDOC
## gpg-wks-client --install-key

### Description
Manually installs a key into a local directory (see option -C) reflecting the structure of a WKD.

### Command
`--install-key`

### Arguments
- **file with keyblock** (string) - Required - A file with the keyblock. If the first argument resembles a fingerprint, the key is taken from the current keyring; to force the use of a file, prefix the first argument with "./".
- **user-id** (string) - Required - The user-id to install.

### Alternative Input
- If no arguments are given, parameters are read from stdin; expected format: lines with the fingerprint and the mailbox separated by a space.

### Options
- `-C dir` / `--directory dir` - Use dir as top level directory for the command. Default is openpgpkey.

```
Tokens:
Raw