diff --git a/dirmngr/ldap.c b/dirmngr/ldap.c
index f9f6d5f1a..b80012d03 100644
--- a/dirmngr/ldap.c
+++ b/dirmngr/ldap.c
@@ -1,1027 +1,1027 @@
/* ldap.c - LDAP access
* Copyright (C) 2002 Klarälvdalens Datakonsult AB
* Copyright (C) 2003, 2004, 2005, 2007, 2008, 2010, 2021 g10 Code GmbH
*
* This file is part of GnuPG.
*
* GnuPG 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 3 of the License, or
* (at your option) any later version.
*
* DirMngr 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 for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, see .
* SPDX-License-Identifier: GPL-3.0-or-later
*/
#include
#include
#include
#include
#include
#include
#include
#include
#include
#include "dirmngr.h"
#include "../common/exechelp.h"
#include "crlfetch.h"
#include "ldapserver.h"
#include "misc.h"
#include "ldap-wrapper.h"
#include "ldap-url.h"
#include "../common/host2net.h"
#define UNENCODED_URL_CHARS "abcdefghijklmnopqrstuvwxyz" \
"ABCDEFGHIJKLMNOPQRSTUVWXYZ" \
"01234567890" \
"$-_.+!*'(),"
#define USERCERTIFICATE "userCertificate"
#define CACERTIFICATE "caCertificate"
#define X509CACERT "x509caCert"
#define USERSMIMECERTIFICATE "userSMIMECertificate"
/* Definition for the context of the cert fetch functions. */
struct cert_fetch_context_s
{
ksba_reader_t reader; /* The reader used (shallow copy). */
unsigned char *tmpbuf; /* Helper buffer. */
size_t tmpbufsize; /* Allocated size of tmpbuf. */
int truncated; /* Flag to indicate a truncated output. */
};
/* Add HOST and PORT to our list of LDAP servers. Fixme: We should
better use an extra list of servers. */
static void
add_server_to_servers (const char *host, int port)
{
ldap_server_t server;
ldap_server_t last = NULL;
const char *s;
if (!port)
port = 389;
for (server=opt.ldapservers; server; server = server->next)
{
if (!strcmp (server->host, host) && server->port == port)
return; /* already in list... */
last = server;
}
/* We assume that the host names are all supplied by our
configuration files and thus are sane. To keep this assumption
we must reject all invalid host names. */
for (s=host; *s; s++)
if (!strchr ("abcdefghijklmnopqrstuvwxyz"
"ABCDEFGHIJKLMNOPQRSTUVWXYZ"
"01234567890.-", *s))
{
log_error (_("invalid char 0x%02x in host name - not added\n"), *s);
return;
}
log_info (_("adding '%s:%d' to the ldap server list\n"), host, port);
server = xtrycalloc (1, sizeof *s);
if (!server)
log_error (_("malloc failed: %s\n"), strerror (errno));
else
{
server->host = xstrdup (host);
server->port = port;
if (last)
last->next = server;
else
opt.ldapservers = server;
}
}
/* Perform an LDAP query. Returns an gpg error code or 0 on success.
The function returns a new reader object at READER. */
static gpg_error_t
run_ldap_wrapper (ctrl_t ctrl,
int ignore_timeout,
int multi_mode,
int tls_mode,
int ntds,
int areconly,
const char *proxy,
const char *host, int port,
const char *user, const char *pass,
const char *base, const char *filter, const char *attr,
ksba_reader_t *reader)
{
const char *argv[51];
int argc;
char portbuf[30], timeoutbuf[30];
*reader = NULL;
argc = 0;
if (pass && *pass) /* Note, that the password must be the first item. */
{
argv[argc++] = "--pass";
argv[argc++] = pass;
}
if (DBG_LOOKUP)
argv[argc++] = "-vv";
else if (DBG_EXTPROG)
argv[argc++] = "-v";
argv[argc++] = "--log-with-pid";
if (multi_mode)
argv[argc++] = "--multi";
if (tls_mode == 1)
argv[argc++] = "--starttls";
else if (tls_mode)
argv[argc++] = "--ldaptls";
if (ntds)
argv[argc++] = "--ntds";
if (areconly)
argv[argc++] = "--areconly";
if (opt.ldaptimeout)
{
snprintf (timeoutbuf, sizeof timeoutbuf, "%u", opt.ldaptimeout);
argv[argc++] = "--timeout";
argv[argc++] = timeoutbuf;
if (ignore_timeout)
argv[argc++] = "--only-search-timeout";
}
if (proxy)
{
argv[argc++] = "--proxy";
argv[argc++] = proxy;
}
if (host && *host)
{
argv[argc++] = "--host";
argv[argc++] = host;
}
if (port)
{
sprintf (portbuf, "%d", port);
argv[argc++] = "--port";
argv[argc++] = portbuf;
}
if (user && *user)
{
argv[argc++] = "--user";
argv[argc++] = user;
}
if (base && *base)
{
argv[argc++] = "--base";
argv[argc++] = base;
}
if (attr)
{
argv[argc++] = "--attr";
argv[argc++] = attr;
}
if (filter)
argv[argc++] = filter;
argv[argc] = NULL;
return ldap_wrapper (ctrl, reader, argv);
}
/* Perform a LDAP query using a given URL. On success a new ksba
reader is returned. If HOST or PORT are not 0, they are used to
override the values from the URL. */
gpg_error_t
url_fetch_ldap (ctrl_t ctrl, const char *url, ksba_reader_t *reader)
{
gpg_error_t err;
LDAPURLDesc *ludp = NULL;
int tls_mode;
if (!ldap_is_ldap_url (url))
{
log_error (_("'%s' is not an LDAP URL\n"), url);
return gpg_error (GPG_ERR_INV_URI);
}
if (ldap_url_parse (url, &ludp))
{
log_error (_("'%s' is an invalid LDAP URL\n"), url);
return gpg_error (GPG_ERR_INV_URI);
}
if (ludp->lud_filter && ludp->lud_filter[0] != '(')
{
if (!strcmp (ludp->lud_filter, "objectClass=cRLDistributionPoint"))
{
/* Hack for broken DPs in DGN certs. */
log_info ("fixing broken LDAP URL\n");
free (ludp->lud_filter);
ludp->lud_filter
= strdup ("(objectClass=cRLDistributionPoint)");
if (!ludp->lud_filter)
{
err = gpg_error_from_syserror ();
goto leave;
}
}
else
{
log_error (_("'%s' is an invalid LDAP URL\n"), url);
err = gpg_error (GPG_ERR_BAD_URI);
goto leave;
}
}
if (ludp->lud_scheme && !strcmp (ludp->lud_scheme, "ldaps"))
tls_mode = 2; /* LDAP-over-TLS here becuase we get it from certs. */
else
tls_mode = 0;
err = run_ldap_wrapper (ctrl,
1, /* Ignore explicit timeout because CRLs
might be very large. */
0, /* No Multi-mode. */
tls_mode,
0, /* No AD authentication. */
0, /* No areconly. */
opt.ldap_proxy,
ludp->lud_host, ludp->lud_port,
NULL, NULL, /* user, password */
ludp->lud_dn, /* Base DN */
ludp->lud_filter,
ludp->lud_attrs? ludp->lud_attrs[0] : NULL,
reader);
/* FIXME: This option might be used for DoS attacks. Because it
will enlarge the list of servers to consult without a limit and
all LDAP queries w/o a host are will then try each host in
turn. */
if (!err && opt.add_new_ldapservers && !opt.ldap_proxy)
{
if (ludp->lud_host)
add_server_to_servers (ludp->lud_host, ludp->lud_port);
}
/* If the lookup failed and we are not only using the proxy, we try
again using our default list of servers. */
if (err && !(opt.ldap_proxy && opt.only_ldap_proxy))
{
struct ldapserver_iter iter;
if (DBG_LOOKUP)
log_debug ("no hostname in URL or query failed; "
"trying all default hostnames\n");
for (ldapserver_iter_begin (&iter, ctrl);
err && ! ldapserver_iter_end_p (&iter);
ldapserver_iter_next (&iter))
{
ldap_server_t server = iter.server;
if (server->starttls)
tls_mode = 1;
else if (server->ldap_over_tls)
tls_mode = 2;
else
tls_mode = 0;
err = run_ldap_wrapper (ctrl,
0,
0, /* No Multi-mode */
tls_mode,
server->ntds,
server->areconly,
NULL,
server->host, server->port,
server->user, server->pass,
server->base,
ludp->lud_filter,
ludp->lud_attrs? ludp->lud_attrs[0] : NULL,
reader);
if (!err)
break;
}
}
leave:
ldap_free_urldesc (ludp);
return err;
}
/* Perform an LDAP query on all configured servers. On error the
error code of the last try is returned. */
gpg_error_t
attr_fetch_ldap (ctrl_t ctrl,
const char *dn, const char *attr, ksba_reader_t *reader)
{
gpg_error_t err = gpg_error (GPG_ERR_CONFIGURATION);
struct ldapserver_iter iter;
*reader = NULL;
/* FIXME; we might want to look at the Base DN to try matching
servers first. */
for (ldapserver_iter_begin (&iter, ctrl); ! ldapserver_iter_end_p (&iter);
ldapserver_iter_next (&iter))
{
ldap_server_t server = iter.server;
int tls_mode;
if (server->starttls)
tls_mode = 1;
else if (server->ldap_over_tls)
tls_mode = 2;
else
tls_mode = 0;
err = run_ldap_wrapper (ctrl,
0,
0,
tls_mode,
server->ntds,
server->areconly,
opt.ldap_proxy,
server->host, server->port,
server->user, server->pass,
dn,
"(objectClass=*)",
attr,
reader);
if (!err)
break; /* Probably found a result. Ready. */
}
return err;
}
/* Return true if VALUE needs escaping. */
static int
rfc2254_need_escape (const char *value)
{
/* NUL needs to be escaped as well but we can represent that in
* VALUE, so no need for it. */
return !!strpbrk (value, "*()\\");
}
/* Escape VALUE using RFC-2254 rules. Returns NULL on error. */
static char *
rfc2254_escape (const char *value)
{
const char *s;
char *buffer, *p;
size_t length = 0;
for (s=value; *s; s++)
switch (*s)
{
case '*':
case '(':
case ')':
case '\\': length += 3; break;
default: length++; break;
}
buffer = xtrymalloc (length+1);
if (!buffer)
return NULL;
p = buffer;
for (s=value; *s; s++)
switch (*s)
{
case '*': p = stpcpy (p, "\\2a"); break;
case '(': p = stpcpy (p, "\\28"); break;
case ')': p = stpcpy (p, "\\29"); break;
case '\\': p = stpcpy (p, "\\5c"); break;
default: *p++ = *s; break;
}
*p = 0;
return buffer;
}
/* Return true if VALUE needs escaping. */
static int
extfilt_need_escape (const char *value)
{
/* NUL needs to be escaped as well but we can represent that in
* VALUE, so no need for it. */
return !!strchr (value, '&');
}
/* Escape VALUE using our extended filter rules from dirmngr_ldap.c.
* Returns NULL on error. */
static char *
extfilt_escape (const char *value)
{
const char *s;
char *buffer, *p;
size_t length = 0;
for (s=value; *s; s++)
{
length++;
if (*s == '&')
length++;
}
buffer = xtrymalloc (length+1);
if (!buffer)
return NULL;
p = buffer;
for (s=value; *s; s++)
{
*p++ = *s;
if (*s == '&')
*p++ = '&';
}
*p = 0;
return buffer;
}
/* Parse PATTERN and return a new filter expression for an LDAP query.
* The extended filter syntax as known by dirmngr_ldap.c is used.
* Caller must release the returned value. R_RESULT is set to NULL on
* error.
*
* Supported patterns:
*
* | Ok | gpg style user id type |
* |-----+------------------------------------------------------|
* | no | KeyID |
* | no | Fingerprint |
* | no | OpenPGP userid |
* | yes | Email address Indicated by a left angle bracket. |
* | no | Exact word match in user id or subj. name |
* | yes | Subj. DN indicated by a leading slash |
* | no | Issuer DN |
* | no | Serial number + subj. DN |
* | yes | Substring match indicated by a leading '*; (default) |
*/
static gpg_error_t
make_one_filter (const char *pattern, char **r_result)
{
gpg_error_t err = 0;
char *pattern_buffer = NULL;
char *result = NULL;
size_t n;
*r_result = NULL;
switch (*pattern)
{
case '<': /* Email. */
{
pattern++;
if (rfc2254_need_escape (pattern)
&& !(pattern = pattern_buffer = rfc2254_escape (pattern)))
{
err = gpg_error_from_syserror ();
goto leave;
}
result = strconcat ("(mail=", pattern, ")", NULL);
if (!result)
{
err = gpg_error_from_syserror ();
goto leave;
}
n = strlen (result);
if (result[n-2] == '>') /* Strip trailing '>' */
{
result[n-2] = ')';
result[n-1] = 0;
}
break;
}
case '/': /* Subject DN. */
pattern++;
if (*pattern)
{
/* We need just the BaseDN. This assumes that the Subject
* is correcly stored in the DT. This is however not always
- * the case and the actual DN is different ffrom the
+ * the case and the actual DN is different from the
* subject. In this case we won't find anything. */
if (extfilt_need_escape (pattern)
&& !(pattern = pattern_buffer = extfilt_escape (pattern)))
{
err = gpg_error_from_syserror ();
goto leave;
}
result = strconcat ("^", pattern, "&base&", NULL);
if (!result)
{
err = gpg_error_from_syserror ();
goto leave;
}
}
break;
case '#': /* Issuer DN - Not yet working. */
pattern++;
if (*pattern == '/') /* Just issuer DN. */
{
pattern++;
if (extfilt_need_escape (pattern)
&& !(pattern = pattern_buffer = extfilt_escape (pattern)))
{
err = gpg_error_from_syserror ();
goto leave;
}
result = strconcat ("^", pattern, "&base&", NULL);
if (!result)
{
err = gpg_error_from_syserror ();
goto leave;
}
}
else /* Serial number + issuer DN */
{
}
break;
case '*':
pattern++;
/* fall through */
default: /* Take as substring match. */
if (*pattern)
{
if (rfc2254_need_escape (pattern)
&& !(pattern = pattern_buffer = rfc2254_escape (pattern)))
{
err = gpg_error_from_syserror ();
goto leave;
}
result = strconcat ("(|(sn=*", pattern,
"*)(|(cn=*", pattern,
"*)(mail=*", pattern,
"*)))", NULL);
if (!result)
{
err = gpg_error_from_syserror ();
goto leave;
}
}
break;
}
if (!result)
err = gpg_error (GPG_ERR_INV_USER_ID);
leave:
xfree (pattern_buffer);
if (err)
xfree (result);
else
*r_result = result;
return err;
}
/* Prepare an LDAP query to return the cACertificate attribute for DN.
* All configured default servers are queried until one responds.
* This function returns an error code or 0 and stored a newly
* allocated contect object at CONTEXT on success. */
gpg_error_t
start_cacert_fetch_ldap (ctrl_t ctrl, cert_fetch_context_t *r_context,
const char *dn)
{
gpg_error_t err;
struct ldapserver_iter iter;
*r_context = xtrycalloc (1, sizeof **r_context);
if (!*r_context)
return gpg_error_from_errno (errno);
/* FIXME; we might want to look at the Base DN to try matching
servers first. */
err = gpg_error (GPG_ERR_CONFIGURATION);
for (ldapserver_iter_begin (&iter, ctrl); ! ldapserver_iter_end_p (&iter);
ldapserver_iter_next (&iter))
{
ldap_server_t server = iter.server;
err = run_ldap_wrapper (ctrl,
0,
1, /* --multi (record format) */
0, /* No TLS */
0, /* No AD authentication. */
server->areconly,
opt.ldap_proxy,
server->host, server->port,
server->user, server->pass,
dn, "objectClass=*", "cACertificate",
&(*r_context)->reader);
if (!err)
break; /* Probably found a result. */
}
if (err)
{
xfree (*r_context);
*r_context = NULL;
}
return err;
}
/* Prepare an LDAP query to return certificates matching PATTERNS
* using the SERVER. This function returns an error code or 0 and
* stores a newly allocated object at R_CONTEXT on success. */
gpg_error_t
start_cert_fetch_ldap (ctrl_t ctrl, cert_fetch_context_t *r_context,
strlist_t patterns, const ldap_server_t server)
{
gpg_error_t err;
char *proxy = NULL;
char *host = NULL;
int port;
char *user = NULL;
char *pass = NULL;
char *base = NULL;
char *argv[50];
int argc = 0;
int argc_malloced = 0;
char portbuf[30], timeoutbuf[30];
int starttls, ldaptls, ntds;
*r_context = NULL;
if (opt.ldap_proxy && !(proxy = xtrystrdup (opt.ldap_proxy)))
{
err = gpg_error_from_syserror ();
goto leave;
}
if (server)
{
if (server->host && !(host = xtrystrdup (server->host)))
{
err = gpg_error_from_syserror ();
goto leave;
}
port = server->port;
if (server->user && !(user = xtrystrdup (server->user)))
{
err = gpg_error_from_syserror ();
goto leave;
}
if (server->pass && !(pass = xtrystrdup (server->pass)))
{
err = gpg_error_from_syserror ();
goto leave;
}
if (server->base && !(base = xtrystrdup (server->base)))
{
err = gpg_error_from_syserror ();
goto leave;
}
starttls = server->starttls;
ldaptls = server->ldap_over_tls;
ntds = server->ntds;
}
else /* Use a default server. */
{
err = gpg_error (GPG_ERR_NOT_IMPLEMENTED);
goto leave;
}
if (pass && *pass) /* Note: Must be the first item. */
{
argv[argc++] = "--pass";
argv[argc++] = pass;
}
if (DBG_LOOKUP)
argv[argc++] = "-vv";
else if (DBG_EXTPROG)
argv[argc++] = "-v";
argv[argc++] = "--log-with-pid";
argv[argc++] = "--multi";
if (starttls)
argv[argc++] = "--starttls";
else if (ldaptls)
argv[argc++] = "--ldaptls";
if (ntds)
argv[argc++] = "--ntds";
if (opt.ldaptimeout)
{
snprintf (timeoutbuf, sizeof timeoutbuf, "%u", opt.ldaptimeout);
argv[argc++] = "--timeout";
argv[argc++] = timeoutbuf;
}
if (proxy && *proxy)
{
argv[argc++] = "--proxy";
argv[argc++] = proxy;
}
if (host && *host)
{
argv[argc++] = "--host";
argv[argc++] = host;
}
if (port)
{
snprintf (portbuf, sizeof portbuf, "%d", port);
argv[argc++] = "--port";
argv[argc++] = portbuf;
}
if (user && *user)
{
argv[argc++] = "--user";
argv[argc++] = user;
}
if (base && *base)
{
argv[argc++] = "--base";
argv[argc++] = base;
}
/* All entries in argv from this index on are malloc'ed. */
argc_malloced = argc;
for (; patterns; patterns = patterns->next)
{
if (argc >= DIM (argv) - 1)
{
/* Too many patterns. It does not make sense to allow an
arbitrary number of patters because the length of the
command line is limited anyway. */
err = gpg_error (GPG_ERR_RESOURCE_LIMIT);
goto leave;
}
if (*patterns->d)
{
err = make_one_filter (patterns->d, &argv[argc]);
if (err)
goto leave;
argc++;
}
}
argv[argc] = NULL;
*r_context = xtrycalloc (1, sizeof **r_context);
if (!*r_context)
{
err = gpg_error_from_syserror ();
goto leave;
}
err = ldap_wrapper (ctrl, &(*r_context)->reader, (const char**)argv);
if (err)
{
xfree (*r_context);
*r_context = NULL;
}
leave:
for (; argc_malloced < argc; argc_malloced++)
xfree (argv[argc_malloced]);
xfree (proxy);
xfree (host);
xfree (base);
xfree (user);
xfree (pass);
return err;
}
/* Read a fixed amount of data from READER into BUFFER. */
static gpg_error_t
read_buffer (ksba_reader_t reader, unsigned char *buffer, size_t count)
{
gpg_error_t err;
size_t nread;
while (count)
{
err = ksba_reader_read (reader, buffer, count, &nread);
if (err)
return err;
buffer += nread;
count -= nread;
}
return 0;
}
/* Fetch the next certificate. Return 0 on success, GPG_ERR_EOF if no
(more) certificates are available or any other error
code. GPG_ERR_TRUNCATED may be returned to indicate that the result
has been truncated. */
gpg_error_t
fetch_next_cert_ldap (cert_fetch_context_t context,
unsigned char **value, size_t *valuelen)
{
gpg_error_t err;
unsigned char hdr[5];
char *p, *pend;
unsigned long n;
int okay = 0;
/* int is_cms = 0; */
*value = NULL;
*valuelen = 0;
err = 0;
while (!err)
{
err = read_buffer (context->reader, hdr, 5);
if (err)
break;
n = buf32_to_ulong (hdr+1);
if (*hdr == 'V' && okay)
{
#if 0 /* That code to extra a cert from a CMS object is not yet ready. */
if (is_cms)
{
/* The certificate needs to be parsed from CMS data. */
ksba_cms_t cms;
ksba_stop_reason_t stopreason;
int i;
err = ksba_cms_new (&cms);
if (err)
goto leave;
err = ksba_cms_set_reader_writer (cms, context->reader, NULL);
if (err)
{
log_error ("ksba_cms_set_reader_writer failed: %s\n",
gpg_strerror (err));
goto leave;
}
do
{
err = ksba_cms_parse (cms, &stopreason);
if (err)
{
log_error ("ksba_cms_parse failed: %s\n",
gpg_strerror (err));
goto leave;
}
if (stopreason == KSBA_SR_BEGIN_DATA)
log_error ("userSMIMECertificate is not "
"a certs-only message\n");
}
while (stopreason != KSBA_SR_READY);
for (i=0; (cert=ksba_cms_get_cert (cms, i)); i++)
{
check_and_store (ctrl, stats, cert, 0);
ksba_cert_release (cert);
cert = NULL;
}
if (!i)
log_error ("no certificate found\n");
else
any = 1;
}
else
#endif /* End unfinished code to extract from a CMS object. */
{
*value = xtrymalloc (n);
if (!*value)
return gpg_error_from_errno (errno);
*valuelen = n;
err = read_buffer (context->reader, *value, n);
break; /* Ready or error. */
}
}
else if (!n && *hdr == 'A')
okay = 0;
else if (n)
{
if (n > context->tmpbufsize)
{
xfree (context->tmpbuf);
context->tmpbufsize = 0;
context->tmpbuf = xtrymalloc (n+1);
if (!context->tmpbuf)
return gpg_error_from_errno (errno);
context->tmpbufsize = n;
}
err = read_buffer (context->reader, context->tmpbuf, n);
if (err)
break;
if (*hdr == 'A')
{
p = context->tmpbuf;
p[n] = 0; /*(we allocated one extra byte for this.)*/
/* fixme: is_cms = 0; */
if ( (pend = strchr (p, ';')) )
*pend = 0; /* Strip off the extension. */
if (!ascii_strcasecmp (p, USERCERTIFICATE))
{
if (DBG_LOOKUP)
log_debug ("fetch_next_cert_ldap: got attribute '%s'\n",
USERCERTIFICATE);
okay = 1;
}
else if (!ascii_strcasecmp (p, CACERTIFICATE))
{
if (DBG_LOOKUP)
log_debug ("fetch_next_cert_ldap: got attribute '%s'\n",
CACERTIFICATE);
okay = 1;
}
else if (!ascii_strcasecmp (p, X509CACERT))
{
if (DBG_LOOKUP)
log_debug ("fetch_next_cert_ldap: got attribute '%s'\n",
CACERTIFICATE);
okay = 1;
}
/* else if (!ascii_strcasecmp (p, USERSMIMECERTIFICATE)) */
/* { */
/* if (DBG_LOOKUP) */
/* log_debug ("fetch_next_cert_ldap: got attribute '%s'\n", */
/* USERSMIMECERTIFICATE); */
/* okay = 1; */
/* is_cms = 1; */
/* } */
else
{
if (DBG_LOOKUP)
log_debug ("fetch_next_cert_ldap: got attribute '%s'"
" - ignored\n", p);
okay = 0;
}
}
else if (*hdr == 'E')
{
p = context->tmpbuf;
p[n] = 0; /*(we allocated one extra byte for this.)*/
if (!strcmp (p, "truncated"))
{
context->truncated = 1;
log_info (_("ldap_search hit the size limit of"
" the server\n"));
}
}
}
}
if (err)
{
xfree (*value);
*value = NULL;
*valuelen = 0;
if (gpg_err_code (err) == GPG_ERR_EOF && context->truncated)
{
context->truncated = 0; /* So that the next call would return EOF. */
err = gpg_error (GPG_ERR_TRUNCATED);
}
}
return err;
}
void
end_cert_fetch_ldap (cert_fetch_context_t context)
{
if (context)
{
ksba_reader_t reader = context->reader;
xfree (context->tmpbuf);
xfree (context);
ldap_wrapper_release_context (reader);
ksba_reader_release (reader);
}
}
diff --git a/doc/DETAILS b/doc/DETAILS
index 0d86e4750..10307bae0 100644
--- a/doc/DETAILS
+++ b/doc/DETAILS
@@ -1,1798 +1,1804 @@
# doc/DETAILS -*- org -*-
#+TITLE: GnuPG Details
# Globally disable superscripts and subscripts:
#+OPTIONS: ^:{}
#+STARTUP: showall
# Note: This file uses org-mode; it should be easy to read as plain
# text but be aware of some markup peculiarities: Verbatim code is
# enclosed in #+begin-example, #+end-example blocks or marked by a
# colon as the first non-white-space character, words bracketed with
# equal signs indicate a monospace font, and the usual /italics/,
# *bold*, and _underline_ conventions are recognized.
This is the DETAILS file for GnuPG which specifies some internals and
parts of the external API for GPG and GPGSM.
* Format of the colon listings
The format is a based on colon separated record, each recods starts
with a tag string and extends to the end of the line. Here is an
example:
#+begin_example
$ gpg --with-colons --list-keys \
--with-fingerprint --with-fingerprint wk@gnupg.org
pub:f:1024:17:6C7EE1B8621CC013:899817715:1055898235::m:::scESC:
fpr:::::::::ECAF7590EB3443B5C7CF3ACB6C7EE1B8621CC013:
uid:f::::::::Werner Koch :
uid:f::::::::Werner Koch :
sub:f:1536:16:06AD222CADF6A6E1:919537416:1036177416:::::e:
fpr:::::::::CF8BCC4B18DE08FCD8A1615906AD222CADF6A6E1:
sub:r:1536:20:5CE086B5B5A18FF4:899817788:1025961788:::::esc:
fpr:::::::::AB059359A3B81F410FCFF97F5CE086B5B5A18FF4:
#+end_example
Note that new version of GnuPG or the use of certain options may add
new fields to the output. Parsers should not assume a limit on the
number of fields per line. Some fields are not yet used or only used
with certain record types; parsers should ignore fields they are not
aware of. New versions of GnuPG or the use of certain options may add
new types of records as well. Parsers should ignore any record whose
type they do not recognize for forward-compatibility.
The double =--with-fingerprint= prints the fingerprint for the subkeys
too. Old versions of gpg used a slightly different format and required
the use of the option =--fixed-list-mode= to conform to the format
described here.
** Description of the fields
*** Field 1 - Type of record
- pub :: Public key
- crt :: X.509 certificate
- crs :: X.509 certificate and private key available
- sub :: Subkey (secondary key)
- sec :: Secret key
- ssb :: Secret subkey (secondary key)
- uid :: User id
- uat :: User attribute (same as user id except for field 10).
- sig :: Signature
- rev :: Revocation signature
- rvs :: Revocation signature (standalone) [since 2.2.9]
- fpr :: Fingerprint (fingerprint is in field 10)
- fp2 :: SHA-256 fingerprint (fingerprint is in field 10)
- pkd :: Public key data [*]
- grp :: Keygrip
- rvk :: Revocation key
- tfs :: TOFU statistics [*]
- tru :: Trust database information [*]
- spk :: Signature subpacket [*]
- cfg :: Configuration data [*]
Records marked with an asterisk are described at [[*Special%20field%20formats][*Special fields]].
*** Field 2 - Validity
This is a letter describing the computed validity of a key.
Currently this is a single letter, but be prepared that additional
information may follow in some future versions. Note that GnuPG <
2.1 does not set this field for secret key listings.
- o :: Unknown (this key is new to the system)
- i :: The key is invalid (e.g. due to a missing self-signature)
- d :: The key has been disabled
(deprecated - use the 'D' in field 12 instead)
- r :: The key has been revoked
- e :: The key has expired
- - :: Unknown validity (i.e. no value assigned)
- q :: Undefined validity. '-' and 'q' may safely be treated as
the same value for most purposes
- n :: The key is not valid
- m :: The key is marginal valid.
- f :: The key is fully valid
- u :: The key is ultimately valid. This often means that the
secret key is available, but any key may be marked as
ultimately valid.
- w :: The key has a well known private part.
- s :: The key has special validity. This means that it might be
self-signed and expected to be used in the STEED system.
If the validity information is given for a UID or UAT record, it
describes the validity calculated based on this user ID. If given
for a key record it describes the validity taken from the best
rated user ID.
For X.509 certificates a 'u' is used for a trusted root
certificate (i.e. for the trust anchor) and an 'f' for all other
valid certificates.
In "sig" records, this field may have one of these values as first
character:
- ! :: Signature is good.
- - :: Signature is bad.
- ? :: No public key to verify signature or public key is not usable.
- % :: Other error verifying a signature
More values may be added later. The field may also be empty if
gpg has been invoked in a non-checking mode (--list-sigs) or in a
fast checking mode. Since 2.2.7 '?' will also be printed by the
command --list-sigs if the key is not in the local keyring.
*** Field 3 - Key length
The length of key in bits.
*** Field 4 - Public key algorithm
The values here are those from the OpenPGP specs or if they are
greater than 255 the algorithm ids as used by Libgcrypt.
*** Field 5 - KeyID
This is the 64 bit keyid as specified by OpenPGP and the last 64
bit of the SHA-1 fingerprint of an X.509 certifciate.
*** Field 6 - Creation date
The creation date of the key is given in UTC. For UID and UAT
records, this is used for the self-signature date. Note that the
date is usually printed in seconds since epoch, however, we are
migrating to an ISO 8601 format (e.g. "19660205T091500"). This is
currently only relevant for X.509. A simple way to detect the new
format is to scan for the 'T'. Note that old versions of gpg
without using the =--fixed-list-mode= option used a "yyyy-mm-tt"
format.
*** Field 7 - Expiration date
Key or UID/UAT expiration date or empty if it does not expire.
*** Field 8 - Certificate S/N, UID hash, trust signature info
Used for serial number in crt records. For UID and UAT records,
this is a hash of the user ID contents used to represent that
exact user ID. For trust signatures, this is the trust depth
separated by the trust value by a space.
*** Field 9 - Ownertrust
This is only used on primary keys. This is a single letter, but
be prepared that additional information may follow in future
versions. For trust signatures with a regular expression, this is
the regular expression value, quoted as in field 10.
*** Field 10 - User-ID
The value is quoted like a C string to avoid control characters
(the colon is quoted =\x3a=). For a "pub" record this field is
not used on --fixed-list-mode. A UAT record puts the attribute
subpacket count here, a space, and then the total attribute
subpacket size. In gpgsm the issuer name comes here. The FPR and FP2
records store the fingerprints here. The fingerprint of a
revocation key is stored here.
*** Field 11 - Signature class
Signature class as per RFC-4880. This is a 2 digit hexnumber
followed by either the letter 'x' for an exportable signature or
the letter 'l' for a local-only signature. The class byte of an
revocation key is also given here, by a 2 digit hexnumber and
optionally followed by the letter 's' for the "sensitive"
flag. This field is not used for X.509.
"rev" and "rvs" may be followed by a comma and a 2 digit hexnumber
with the revocation reason.
*** Field 12 - Key capabilities
The defined capabilities are:
- e :: Encrypt
- s :: Sign
- c :: Certify
- a :: Authentication
- r :: Restricted encryption (subkey only use)
- t :: Timestamping
- g :: Group key
- ? :: Unknown capability
A key may have any combination of them in any order. In addition
to these letters, the primary key has uppercase versions of the
letters to denote the _usable_ capabilities of the entire key, and
a potential letter 'D' to indicate a disabled key.
*** Field 13 - Issuer certificate fingerprint or other info
Used in FPR records for S/MIME keys to store the fingerprint of
the issuer certificate. This is useful to build the certificate
path based on certificates stored in the local key database it is
only filled if the issuer certificate is available. The root has
been reached if this is the same string as the fingerprint. The
advantage of using this value is that it is guaranteed to have
been built by the same lookup algorithm as gpgsm uses.
For "uid" records this field lists the preferences in the same way
gpg's --edit-key menu does.
For "sig", "rev" and "rvs" records, this is the fingerprint of the
key that issued the signature. Note that this may only be filled
if the signature verified correctly. Note also that for various
technical reasons, this fingerprint is only available if
--no-sig-cache is used. Since 2.2.7 this field will also be set
if the key is missing but the signature carries an issuer
fingerprint as meta data.
*** Field 14 - Flag field
Flag field used in the --edit-key menu output
*** Field 15 - S/N of a token
Used in sec/ssb to print the serial number of a token (internal
protect mode 1002) or a '#' if that key is a simple stub (internal
protect mode 1001). If the option --with-secret is used and a
secret key is available for the public key, a '+' indicates this.
*** Field 16 - Hash algorithm
For sig records, this is the used hash algorithm. For example:
2 = SHA-1, 8 = SHA-256.
*** Field 17 - Curve name
For pub, sub, sec, ssb, crt, and crs records this field is used
for the ECC curve name.
*** Field 18 - Compliance flags
Space separated list of asserted compliance modes and
screening result for this key.
Valid values are:
- 8 :: The key is compliant with RFC4880bis
- 23 :: The key is compliant with compliance mode "de-vs".
- 6001 :: Screening hit on the ROCA vulnerability.
*** Field 19 - Last update
The timestamp of the last update of a key or user ID. The update
time of a key is defined a lookup of the key via its unique
identifier (fingerprint); the field is empty if not known. The
update time of a user ID is defined by a lookup of the key using a
trusted mapping from mail address to key.
*** Field 20 - Origin
The origin of the key or the user ID. This is an integer
optionally followed by a space and an URL. This goes along with
the previous field. The URL is quoted in C style.
*** Field 21 - Comment
This is currently only used in "rev" and "rvs" records to carry
the the comment field of the recocation reason. The value is
quoted in C style.
** Special fields
*** PKD - Public key data
If field 1 has the tag "pkd", a listing looks like this:
#+begin_example
pkd:0:1024:B665B1435F4C2 .... FF26ABB:
! ! !-- the value
! !------ for information number of bits in the value
!--------- index (eg. DSA goes from 0 to 3: p,q,g,y)
#+end_example
*** TFS - TOFU statistics
This field may follows a UID record to convey information about
the TOFU database. The information is similar to a TOFU_STATS
status line.
- Field 2 :: tfs record version (must be 1)
- Field 3 :: validity - A number with validity code.
- Field 4 :: signcount - The number of signatures seen.
- Field 5 :: encrcount - The number of encryptions done.
- Field 6 :: policy - A string with the policy
- Field 7 :: signture-first-seen - a timestamp or 0 if not known.
- Field 8 :: signature-most-recent-seen - a timestamp or 0 if not known.
- Field 9 :: encryption-first-done - a timestamp or 0 if not known.
- Field 10 :: encryption-most-recent-done - a timestamp or 0 if not known.
*** TRU - Trust database information
Example for a "tru" trust base record:
#+begin_example
tru:o:0:1166697654:1:3:1:5
#+end_example
- Field 2 :: Reason for staleness of trust. If this field is
empty, then the trustdb is not stale. This field may
have multiple flags in it:
- o :: Trustdb is old
- t :: Trustdb was built with a different trust model
than the one we are using now.
- Field 3 :: Trust model
- 0 :: Classic trust model, as used in PGP 2.x.
- 1 :: PGP trust model, as used in PGP 6 and later.
This is the same as the classic trust model,
except for the addition of trust signatures.
GnuPG before version 1.4 used the classic trust model
by default. GnuPG 1.4 and later uses the PGP trust
model by default.
- Field 4 :: Date trustdb was created in seconds since Epoch.
- Field 5 :: Date trustdb will expire in seconds since Epoch.
- Field 6 :: Number of marginally trusted users to introduce a new
key signer (gpg's option --marginals-needed).
- Field 7 :: Number of completely trusted users to introduce a new
key signer. (gpg's option --completes-needed)
- Field 8 :: Maximum depth of a certification chain. (gpg's option
--max-cert-depth)
*** SPK - Signature subpacket records
- Field 2 :: Subpacket number as per RFC-4880 and later.
- Field 3 :: Flags in hex. Currently the only two bits assigned
are 1, to indicate that the subpacket came from the
hashed part of the signature, and 2, to indicate the
subpacket was marked critical.
- Field 4 :: Length of the subpacket. Note that this is the
length of the subpacket, and not the length of field
5 below. Due to the need for %-encoding, the length
of field 5 may be up to 3x this value.
- Field 5 :: The subpacket data. Printable ASCII is shown as
ASCII, but other values are rendered as %XX where XX
is the hex value for the byte.
*** CFG - Configuration data
--list-config outputs information about the GnuPG configuration
for the benefit of frontends or other programs that call GnuPG.
There are several list-config items, all colon delimited like the
rest of the --with-colons output. The first field is always "cfg"
to indicate configuration information. The second field is one of
(with examples):
- version :: The third field contains the version of GnuPG.
: cfg:version:1.3.5
- pubkey :: The third field contains the public key algorithms
this version of GnuPG supports, separated by
semicolons. The algorithm numbers are as specified in
RFC-4880. Note that in contrast to the --status-fd
interface these are _not_ the Libgcrypt identifiers.
Using =pubkeyname= prints names instead of numbers.
: cfg:pubkey:1;2;3;16;17
- cipher :: The third field contains the symmetric ciphers this
version of GnuPG supports, separated by semicolons.
The cipher numbers are as specified in RFC-4880.
Using =ciphername= prints names instead of numbers.
: cfg:cipher:2;3;4;7;8;9;10
- digest :: The third field contains the digest (hash) algorithms
this version of GnuPG supports, separated by
semicolons. The digest numbers are as specified in
RFC-4880. Using =digestname= prints names instead of
numbers.
: cfg:digest:1;2;3;8;9;10
- compress :: The third field contains the compression algorithms
this version of GnuPG supports, separated by
semicolons. The algorithm numbers are as specified
in RFC-4880.
: cfg:compress:0;1;2;3
- group :: The third field contains the name of the group, and the
fourth field contains the values that the group expands
to, separated by semicolons.
For example, a group of:
: group mynames = paige 0x12345678 joe patti
would result in:
: cfg:group:mynames:patti;joe;0x12345678;paige
- curve :: The third field contains the curve names this version
of GnuPG supports, separated by semicolons. Using
=curveoid= prints OIDs instead of numbers.
: cfg:curve:ed25519;nistp256;nistp384;nistp521
* Format of the --status-fd output
Every line is prefixed with "[GNUPG:] ", followed by a keyword with
the type of the status line and some arguments depending on the type
(maybe none); an application should always be willing to ignore
unknown keywords that may be emitted by future versions of GnuPG.
Also, new versions of GnuPG may add arguments to existing keywords.
Any additional arguments should be ignored for forward-compatibility.
** General status codes
*** NEWSIG []
Is issued right before a signature verification starts. This is
useful to define a context for parsing ERROR status messages.
If SIGNERS_UID is given and is not "-" this is the percent-escaped
value of the OpenPGP Signer's User ID signature sub-packet.
*** GOODSIG
The signature with the keyid is good. For each signature only one
of the codes GOODSIG, BADSIG, EXPSIG, EXPKEYSIG, REVKEYSIG or
ERRSIG will be emitted. In the past they were used as a marker
for a new signature; new code should use the NEWSIG status
instead. The username is the primary one encoded in UTF-8 and %XX
escaped. The fingerprint may be used instead of the long keyid if
it is available. This is the case with CMS and might eventually
also be available for OpenPGP.
*** EXPSIG
The signature with the keyid is good, but the signature is
expired. The username is the primary one encoded in UTF-8 and %XX
escaped. The fingerprint may be used instead of the long keyid if
it is available. This is the case with CMS and might eventually
also be available for OpenPGP.
*** EXPKEYSIG
The signature with the keyid is good, but the signature was made
by an expired key. The username is the primary one encoded in
UTF-8 and %XX escaped. The fingerprint may be used instead of the
long keyid if it is available. This is the case with CMS and
might eventually also be available for OpenPGP.
*** REVKEYSIG
The signature with the keyid is good, but the signature was made
by a revoked key. The username is the primary one encoded in UTF-8
and %XX escaped. The fingerprint may be used instead of the long
keyid if it is available. This is the case with CMS and might
eventually also beñ available for OpenPGP.
*** BADSIG
The signature with the keyid has not been verified okay. The
username is the primary one encoded in UTF-8 and %XX escaped. The
fingerprint may be used instead of the long keyid if it is
available. This is the case with CMS and might eventually also be
available for OpenPGP.
*** ERRSIG