core: Deprecate the non-working trustlist functions.

* src/gpgme.h.in: Clarify that the trustlist function should not be
used.
* src/engine.c (_gpgme_engine_op_trustlist): Always return an error.
* src/engine-backend.h (struct engine_ops): Remove trustlist member.
* src/engine-gpg.c (gpg_trustlist): Remove.
(struct engine_ops): Remove that member.  Also in all other engines.
* tests/gpg/t-trustlist.c: Remove.
* lang/python/tests/t-trustlist.py: Remove.
--

This never worked in reality because the required feature has been
removed from GnuPG version 1.3.2 soon after introduction of this
feature in gpgme - 17 years ago.  It was anyway marked as
experimental.  We keep the API and ABI, though.

GnuPG-bug-id: 4834
Signed-off-by: Werner Koch <wk@gnupg.org>
This commit is contained in:
Werner Koch 2020-07-15 16:34:24 +02:00
parent c8048bf8eb
commit 8589091682
No known key found for this signature in database
GPG Key ID: E3FDFF218E45B72B
16 changed files with 17 additions and 374 deletions

2
NEWS
View File

@ -5,6 +5,8 @@ Noteworthy changes in version 1.14.0 (unreleased)
* New context flag "extended-edit" to enable expert key edit. [#4734]
* Deprecate the anyway non working trustlist functions. [#4834]
* cpp: Add convenience API to obtain remarks. [#4734]
* cpp: The sign key edit-interactor now supports multiple signatures

View File

@ -182,7 +182,6 @@ Contexts
* Result Management:: Managing the result of crypto operations.
* Context Attributes:: Setting properties of a context.
* Key Management:: Managing keys with @acronym{GPGME}.
* Trust Item Management:: Managing trust items with @acronym{GPGME}.
* Crypto Operations:: Using a context for cryptography.
* Miscellaneous:: Miscellaneous operations.
* Run Control:: Controlling how operations are run.
@ -217,11 +216,6 @@ Key Management
* Changing TOFU Data:: Changing data pertaining to TOFU.
* Advanced Key Editing:: Advanced key edit operation.
Trust Item Management
* Listing Trust Items:: Browsing the list of available trust items.
* Manipulating Trust Items:: Operations on trust items.
Crypto Operations
* Decrypt:: Decrypting a ciphertext.
@ -2353,7 +2347,6 @@ cryptographic operations.
* Result Management:: Managing the result of crypto operations.
* Context Attributes:: Setting properties of a context.
* Key Management:: Managing keys with @acronym{GPGME}.
* Trust Item Management:: Managing trust items with @acronym{GPGME}.
* Crypto Operations:: Using a context for cryptography.
* Miscellaneous:: Miscellaneous operations
* Run Control:: Controlling how operations are run.
@ -5263,114 +5256,6 @@ is not a valid pointer.
@end deftypefun
@node Trust Item Management
@section Trust Item Management
@cindex trust item
@strong{Caution:} The trust items interface is experimental.
@deftp {Data type} gpgme_trust_item_t
The @code{gpgme_trust_item_t} type is a pointer to a trust item object.
It has the following members:
@table @code
@item char *keyid
This is a string describing the key to which this trust items belongs.
@item int type
This is the type of the trust item. A value of 1 refers to a key, a
value of 2 refers to a user ID.
@item int level
This is the trust level.
@item char *owner_trust
The owner trust if @code{type} is 1.
@item char *validity
The calculated validity.
@item char *name
The user name if @code{type} is 2.
@end table
@end deftp
@menu
* Listing Trust Items:: Browsing the list of available trust items.
* Manipulating Trust Items:: Operations on trust items.
@end menu
@node Listing Trust Items
@subsection Listing Trust Items
@cindex trust item list
@deftypefun gpgme_error_t gpgme_op_trustlist_start (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{pattern}}, @w{int @var{max_level}})
The function @code{gpgme_op_trustlist_start} initiates a trust item
listing operation inside the context @var{ctx}. It sets everything up
so that subsequent invocations of @code{gpgme_op_trustlist_next} return
the trust items in the list.
The string @var{pattern} contains an engine specific expression that
is used to limit the list to all trust items matching the pattern. It
can not be the empty string.
The argument @var{max_level} is currently ignored.
The context will be busy until either all trust items are received
(and @code{gpgme_op_trustlist_next} returns @code{GPG_ERR_EOF}), or
@code{gpgme_op_trustlist_end} is called to finish the operation.
The function returns the error code @code{GPG_ERR_INV_VALUE} if
@var{ctx} is not a valid pointer, and passes through any errors that
are reported by the crypto engine support routines.
@end deftypefun
@deftypefun gpgme_error_t gpgme_op_trustlist_next (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_trust_item_t *@var{r_item}})
The function @code{gpgme_op_trustlist_next} returns the next trust
item in the list created by a previous @code{gpgme_op_trustlist_start}
operation in the context @var{ctx}. The trust item can be destroyed
with @code{gpgme_trust_item_release}. @xref{Manipulating Trust Items}.
This is the only way to get at @code{gpgme_trust_item_t} objects in
@acronym{GPGME}.
If the last trust item in the list has already been returned,
@code{gpgme_op_trustlist_next} returns @code{GPG_ERR_EOF}.
The function returns the error code @code{GPG_ERR_INV_VALUE} if @var{ctx} or
@var{r_item} is not a valid pointer, and @code{GPG_ERR_ENOMEM} if
there is not enough memory for the operation.
@end deftypefun
@deftypefun gpgme_error_t gpgme_op_trustlist_end (@w{gpgme_ctx_t @var{ctx}})
The function @code{gpgme_op_trustlist_end} ends a pending trust list
operation in the context @var{ctx}.
The function returns the error code @code{GPG_ERR_INV_VALUE} if
@var{ctx} is not a valid pointer, and @code{GPG_ERR_ENOMEM} if at some
time during the operation there was not enough memory available.
@end deftypefun
@node Manipulating Trust Items
@subsection Manipulating Trust Items
@cindex trust item, manipulation
@deftypefun void gpgme_trust_item_ref (@w{gpgme_trust_item_t @var{item}})
The function @code{gpgme_trust_item_ref} acquires an additional
reference for the trust item @var{item}.
@end deftypefun
@deftypefun void gpgme_trust_item_unref (@w{gpgme_trust_item_t @var{item}})
The function @code{gpgme_trust_item_unref} releases a reference for
the trust item @var{item}. If this was the last reference, the trust
item will be destroyed and all resources associated to it will be
released.
@end deftypefun
@node Crypto Operations
@section Crypto Operations
@cindex cryptographic operation
@ -7067,11 +6952,6 @@ received from the crypto engine. The accompanying @var{type_data} is
a @code{gpgme_key_t} variable that contains the key with one reference
for the user.
@item GPGME_EVENT_NEXT_TRUSTITEM
In a @code{gpgme_op_trustlist_start} operation, the next trust item
was received from the crypto engine. The accompanying @var{type_data}
is a @code{gpgme_trust_item_t} variable that contains the trust item with
one reference for the user.
@end table
@end deftp
@ -7686,12 +7566,6 @@ The function @code{gpgme_key_release} is equivalent to
@code{gpgme_key_unref}.
@end deftypefun
@deftypefun void gpgme_trust_item_release (@w{gpgme_trust_item_t @var{item}})
The function @code{gpgme_trust_item_release} is an alias for
@code{gpgme_trust_item_unref}.
@end deftypefun
@deftypefun gpgme_error_t gpgme_op_import_ext (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{keydata}}, @w{int *@var{nr}})
@since{0.3.9}
@ -7830,8 +7704,6 @@ attribute. The following attributes are defined:
@item GPGME_ATTR_KEYID
This is the key ID of a sub key. It is representable as a string.
For trust items, the trust item refers to the key with this ID.
@item GPGME_ATTR_FPR
This is the fingerprint of a sub key. It is representable as a
string.
@ -7853,16 +7725,11 @@ representable as a number.
This is the expiration time of a sub key. It is representable as a
number.
@item GPGME_ATTR_OTRUST
XXX FIXME (also for trust items)
@item GPGME_ATTR_USERID
This is a user ID. There can be more than one user IDs in a
@var{gpgme_key_t} object. The first one (with index 0) is the primary
user ID. The user ID is representable as a number.
For trust items, this is the user ID associated with this trust item.
@item GPGME_ATTR_NAME
This is the name belonging to a user ID. It is representable as a string.
@ -7878,9 +7745,6 @@ string.
This is the validity belonging to a user ID. It is representable as a
string and as a number. See below for a list of available validities.
For trust items, this is the validity that is associated with this
trust item.
@item GPGME_ATTR_UID_REVOKED
This specifies if a user ID is revoked. It is representable as a
number, and is @code{1} if the user ID is revoked, and @code{0}
@ -7891,13 +7755,10 @@ This specifies if a user ID is invalid. It is representable as a
number, and is @code{1} if the user ID is invalid, and @code{0}
otherwise.
@item GPGME_ATTR_LEVEL
This is the trust level of a trust item.
@item GPGME_ATTR_TYPE
This returns information about the type of key. For the string function
this will eother be "PGP" or "X.509". The integer function returns 0
for PGP and 1 for X.509. It is also used for the type of a trust item.
for PGP and 1 for X.509.
@item GPGME_ATTR_IS_SECRET
This specifies if the key is a secret key. It is representable as a
@ -8084,43 +7945,6 @@ out of range, or @var{reserved} not @code{NULL}.
@end deftypefun
@c node Information About Trust Items
@c subsection Information About Trust Items
@c cindex trust item, information about
@c cindex trust item, attributes
@c cindex attributes, of a trust item
Trust items have attributes which can be queried using the interfaces
below. The attribute identifiers are shared with those for key
attributes. @xref{Information About Keys}.
@deftypefun {const char *} gpgme_trust_item_get_string_attr (@w{gpgme_trust_item_t @var{item}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
The function @code{gpgme_trust_item_get_string_attr} returns the value
of the string-representable attribute @var{what} of trust item
@var{item}. The arguments @var{idx} and @var{reserved} are reserved
for later use and should be @code{0} and @code{NULL} respectively.
The string returned is only valid as long as the key is valid.
The function returns @code{0} if an attribute can't be returned as a
string, @var{key} is not a valid pointer, @var{idx} out of range,
or @var{reserved} not @code{NULL}.
@end deftypefun
@deftypefun int gpgme_trust_item_get_int_attr (@w{gpgme_trust_item_t @var{item}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
The function @code{gpgme_trust_item_get_int_attr} returns the value of
the number-representable attribute @var{what} of trust item
@var{item}. If the attribute occurs more than once in the trust item,
the index is specified by @var{idx}. However, currently no such
attribute exists, so @var{idx} should be @code{0}. The argument
@var{reserved} is reserved for later use and should be @code{NULL}.
The function returns @code{0} if the attribute can't be returned as a
number, @var{key} is not a valid pointer, @var{idx} out of range,
or @var{reserved} not @code{NULL}.
@end deftypefun
@deftp {Data type} {enum gpgme_sig_stat_t}
@tindex gpgme_sig_stat_t
The @code{gpgme_sig_stat_t} type holds the result of a signature check, or

View File

@ -42,7 +42,6 @@ py_tests ?= t-wrapper.py \
t-sig-notation.py \
t-export.py \
t-import.py \
t-trustlist.py \
t-edit.py \
t-keylist.py \
t-keylist-from-data.py \

View File

@ -1,46 +0,0 @@
#!/usr/bin/env python
# Copyright (C) 2016 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 General Public License as published by
# the Free Software Foundation; either version 2 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 <https://www.gnu.org/licenses/>.
from __future__ import absolute_import, print_function, unicode_literals
import gpg
import support
_ = support # to appease pyflakes.
del absolute_import, print_function, unicode_literals
c = gpg.Context()
def dump_item(item):
print("l={} k={} t={} o={} v={} u={}".format(item.level, item.keyid,
item.type, item.owner_trust,
item.validity, item.name))
c.op_trustlist_start("alice", 0)
while True:
item = c.op_trustlist_next()
if not item:
break
dump_item(item)
c.op_trustlist_end()
for item in c.op_trustlist_all("alice", 0):
dump_item(item)

View File

@ -826,7 +826,6 @@ struct engine_ops _gpgme_engine_ops_assuan =
NULL, /* keysign */
NULL, /* tofu_policy */
NULL, /* sign */
NULL, /* trustlist */
NULL, /* verify */
NULL, /* getauditlog */
llass_transact, /* opassuan_transact */

View File

@ -115,7 +115,6 @@ struct engine_ops
gpgme_sig_mode_t mode, int use_armor,
int use_textmode, int include_certs,
gpgme_ctx_t ctx /* FIXME */);
gpgme_error_t (*trustlist) (void *engine, const char *pattern);
gpgme_error_t (*verify) (void *engine, gpgme_data_t sig,
gpgme_data_t signed_text, gpgme_data_t plaintext,
gpgme_ctx_t ctx);

View File

@ -806,7 +806,6 @@ struct engine_ops _gpgme_engine_ops_g13 =
NULL, /* keysign */
NULL, /* tofu_policy */
NULL, /* sign */
NULL, /* trustlist */
NULL, /* verify */
NULL, /* getauditlog */
g13_transact,

View File

@ -3302,29 +3302,6 @@ gpg_sign (void *engine, gpgme_data_t in, gpgme_data_t out,
return err;
}
static gpgme_error_t
gpg_trustlist (void *engine, const char *pattern)
{
engine_gpg_t gpg = engine;
gpgme_error_t err;
err = add_arg (gpg, "--with-colons");
if (!err)
err = add_arg (gpg, "--list-trust-path");
/* Tell the gpg object about the data. */
if (!err)
err = add_arg (gpg, "--");
if (!err)
err = add_arg (gpg, pattern);
if (!err)
err = start (gpg);
return err;
}
static gpgme_error_t
gpg_verify (void *engine, gpgme_data_t sig, gpgme_data_t signed_text,
gpgme_data_t plaintext, gpgme_ctx_t ctx)
@ -3475,7 +3452,6 @@ struct engine_ops _gpgme_engine_ops_gpg =
gpg_keysign,
gpg_tofu_policy, /* tofu_policy */
gpg_sign,
gpg_trustlist,
gpg_verify,
gpg_getauditlog,
NULL, /* opassuan_transact */

View File

@ -1304,7 +1304,6 @@ struct engine_ops _gpgme_engine_ops_gpgconf =
NULL, /* keysign */
NULL, /* tofu_policy */
NULL, /* sign */
NULL, /* trustlist */
NULL, /* verify */
NULL, /* getauditlog */
NULL, /* opassuan_transact */

View File

@ -2324,7 +2324,6 @@ struct engine_ops _gpgme_engine_ops_gpgsm =
NULL, /* keysign */
NULL, /* tofu_policy */
gpgsm_sign,
NULL, /* trustlist */
gpgsm_verify,
gpgsm_getauditlog,
NULL, /* opassuan_transact */

View File

@ -466,7 +466,6 @@ struct engine_ops _gpgme_engine_ops_spawn =
NULL, /* keysign */
NULL, /* tofu_policy */
NULL, /* sign */
NULL, /* trustlist */
NULL, /* verify */
NULL, /* getauditlog */
NULL, /* opassuan_transact */

View File

@ -1437,7 +1437,6 @@ struct engine_ops _gpgme_engine_ops_uiserver =
NULL, /* keysign */
NULL, /* tofu_policy */
uiserver_sign,
NULL, /* trustlist */
uiserver_verify,
NULL, /* getauditlog */
NULL, /* opassuan_transact */

View File

@ -917,13 +917,12 @@ _gpgme_engine_op_sign (engine_t engine, gpgme_data_t in, gpgme_data_t out,
gpgme_error_t
_gpgme_engine_op_trustlist (engine_t engine, const char *pattern)
{
(void)pattern;
if (!engine)
return gpg_error (GPG_ERR_INV_VALUE);
if (!engine->ops->trustlist)
return gpg_error (GPG_ERR_NOT_IMPLEMENTED);
return (*engine->ops->trustlist) (engine->engine, pattern);
}

View File

@ -313,7 +313,7 @@ typedef enum
gpgme_sig_mode_t;
/* The available validities for a trust item or key. */
/* The available validities for a key. */
typedef enum
{
GPGME_VALIDITY_UNKNOWN = 0,
@ -1054,7 +1054,7 @@ typedef enum
GPGME_EVENT_START,
GPGME_EVENT_DONE,
GPGME_EVENT_NEXT_KEY,
GPGME_EVENT_NEXT_TRUSTITEM
GPGME_EVENT_NEXT_TRUSTITEM /* NOT USED. */
}
gpgme_event_io_t;
@ -2002,63 +2002,32 @@ gpgme_error_t gpgme_op_passwd (gpgme_ctx_t ctx, gpgme_key_t key,
/*
* Trust items and operations.
* Trust items and operations. DO NOT USE.
* Note: This does not work because the experimental support in the
* GnuPG engine has been removed a very long time; for API and ABI
* compatibilty we keep the functions but let them return an error.
* See https://dev.gnupg.org/T4834
*/
/* An object to hold data of a trust item.
* This structure shall be considered read-only and an application
* must not allocate such a structure on its own. */
struct _gpgme_trust_item
{
/* Internal to GPGME, do not use. */
unsigned int _refs;
/* The key ID to which the trust item belongs. */
char *keyid;
/* Internal to GPGME, do not use. */
char _keyid[16 + 1];
/* The type of the trust item, 1 refers to a key, 2 to a user ID. */
int type;
/* The trust level. */
int level;
/* The owner trust if TYPE is 1. */
char *owner_trust;
/* Internal to GPGME, do not use. */
char _owner_trust[2];
/* The calculated validity. */
char *validity;
/* Internal to GPGME, do not use. */
char _validity[2];
/* The user name if TYPE is 2. */
char *name;
};
typedef struct _gpgme_trust_item *gpgme_trust_item_t;
/* Start a trustlist operation within CTX, searching for trust items
which match PATTERN. */
gpgme_error_t gpgme_op_trustlist_start (gpgme_ctx_t ctx,
const char *pattern, int max_level);
/* Return the next trust item from the trustlist in R_ITEM. */
gpgme_error_t gpgme_op_trustlist_next (gpgme_ctx_t ctx,
gpgme_trust_item_t *r_item);
/* Terminate a pending trustlist operation within CTX. */
gpgme_error_t gpgme_op_trustlist_end (gpgme_ctx_t ctx);
/* Acquire a reference to ITEM. */
void gpgme_trust_item_ref (gpgme_trust_item_t item);
/* Release a reference to ITEM. If this was the last one the trust
* item is destroyed. */
void gpgme_trust_item_unref (gpgme_trust_item_t item);
@ -2740,22 +2709,16 @@ unsigned long gpgme_key_sig_get_ulong_attr (gpgme_key_t key, int uid_idx,
gpgme_error_t gpgme_op_import_ext (gpgme_ctx_t ctx, gpgme_data_t keydata,
int *nr) _GPGME_DEPRECATED(0,4);
/* Release the trust item ITEM. Deprecated, use
* gpgme_trust_item_unref. */
/* DO NOT USE. */
void gpgme_trust_item_release (gpgme_trust_item_t item) _GPGME_DEPRECATED(0,4);
/* Return the value of the attribute WHAT of ITEM, which has to be
* representable by a string. Deprecated, use trust item structure
* directly. */
/* DO NOT USE. */
const char *gpgme_trust_item_get_string_attr (gpgme_trust_item_t item,
_gpgme_attr_t what,
const void *reserved, int idx)
_GPGME_DEPRECATED(0,4);
/* Return the value of the attribute WHAT of KEY, which has to be
* representable by an integer. IDX specifies a running index if the
* attribute appears more than once in the key. Deprecated, use trust
* item structure directly. */
/* DO NOT USE. */
int gpgme_trust_item_get_int_attr (gpgme_trust_item_t item, _gpgme_attr_t what,
const void *reserved, int idx)
_GPGME_DEPRECATED(0,4);

View File

@ -38,7 +38,7 @@ endif
c_tests = \
t-encrypt t-encrypt-sym t-encrypt-sign t-sign t-signers \
t-decrypt t-verify t-decrypt-verify t-sig-notation t-export \
t-import t-trustlist t-edit t-keylist t-keylist-sig t-wait \
t-import t-edit t-keylist t-keylist-sig t-wait \
t-encrypt-large t-file-name t-gpgconf t-encrypt-mixed \
$(tests_unix)

View File

@ -1,67 +0,0 @@
/* t-trustlist.c - Regression test.
* Copyright (C) 2000 Werner Koch (dd9jn)
* Copyright (C) 2001, 2003, 2004 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 <https://gnu.org/licenses/>.
* SPDX-License-Identifier: LGPL-2.1-or-later
*/
/* We need to include config.h so that we know whether we are building
with large file system (LFS) support. */
#ifdef HAVE_CONFIG_H
#include <config.h>
#endif
#include <stdlib.h>
#include <stdio.h>
#include <string.h>
#include <gpgme.h>
#include "t-support.h"
int
main (int argc, char *argv[])
{
gpgme_ctx_t ctx;
gpgme_error_t err;
gpgme_trust_item_t item;
(void)argc;
(void)argv;
init_gpgme (GPGME_PROTOCOL_OpenPGP);
err = gpgme_new (&ctx);
fail_if_err (err);
err = gpgme_op_trustlist_start (ctx, "alice", 0);
fail_if_err (err);
while (!(err = gpgme_op_trustlist_next (ctx, &item)))
{
printf ("l=%d k=%s t=%d o=%s v=%s u=%s\n",
item->level, item->keyid, item->type, item->owner_trust,
item->validity, item->name);
gpgme_trust_item_unref (item);
}
if (gpgme_err_code (err) != GPG_ERR_EOF)
fail_if_err (err);
gpgme_release (ctx);
return 0;
}