Commit f93b3cc7 authored by David Howells's avatar David Howells

KEYS: Update the keyrings documentation for match changes

Signed-off-by: default avatarDavid Howells <dhowells@redhat.com>
Acked-by: default avatarVivek Goyal <vgoyal@redhat.com>
parent 0c903ab6
...@@ -888,11 +888,11 @@ payload contents" for more information. ...@@ -888,11 +888,11 @@ payload contents" for more information.
const char *callout_info); const char *callout_info);
This is used to request a key or keyring with a description that matches This is used to request a key or keyring with a description that matches
the description specified according to the key type's match function. This the description specified according to the key type's match_preparse()
permits approximate matching to occur. If callout_string is not NULL, then method. This permits approximate matching to occur. If callout_string is
/sbin/request-key will be invoked in an attempt to obtain the key from not NULL, then /sbin/request-key will be invoked in an attempt to obtain
userspace. In that case, callout_string will be passed as an argument to the key from userspace. In that case, callout_string will be passed as an
the program. argument to the program.
Should the function fail error ENOKEY, EKEYEXPIRED or EKEYREVOKED will be Should the function fail error ENOKEY, EKEYEXPIRED or EKEYREVOKED will be
returned. returned.
...@@ -1170,7 +1170,7 @@ The structure has a number of fields, some of which are mandatory: ...@@ -1170,7 +1170,7 @@ The structure has a number of fields, some of which are mandatory:
The method should return 0 if successful or a negative error code The method should return 0 if successful or a negative error code
otherwise. otherwise.
(*) void (*free_preparse)(struct key_preparsed_payload *prep); (*) void (*free_preparse)(struct key_preparsed_payload *prep);
This method is only required if the preparse() method is provided, This method is only required if the preparse() method is provided,
...@@ -1225,16 +1225,55 @@ The structure has a number of fields, some of which are mandatory: ...@@ -1225,16 +1225,55 @@ The structure has a number of fields, some of which are mandatory:
It is safe to sleep in this method. It is safe to sleep in this method.
(*) int (*match)(const struct key *key, const void *desc); (*) int (*match_preparse)(struct key_match_data *match_data);
This method is optional. It is called when a key search is about to be
performed. It is given the following structure:
This method is called to match a key against a description. It should struct key_match_data {
return non-zero if the two match, zero if they don't. bool (*cmp)(const struct key *key,
const struct key_match_data *match_data);
const void *raw_data;
void *preparsed;
unsigned lookup_type;
};
This method should not need to lock the key in any way. The type and On entry, raw_data will be pointing to the criteria to be used in matching
description can be considered invariant, and the payload should not be a key by the caller and should not be modified. (*cmp)() will be pointing
accessed (the key may not yet be instantiated). to the default matcher function (which does an exact description match
against raw_data) and lookup_type will be set to indicate a direct lookup.
It is not safe to sleep in this method; the caller may hold spinlocks. The following lookup_type values are available:
[*] KEYRING_SEARCH_LOOKUP_DIRECT - A direct lookup hashes the type and
description to narrow down the search to a small number of keys.
[*] KEYRING_SEARCH_LOOKUP_ITERATE - An iterative lookup walks all the
keys in the keyring until one is matched. This must be used for any
search that's not doing a simple direct match on the key description.
The method may set cmp to point to a function of its choice that does some
other form of match, may set lookup_type to KEYRING_SEARCH_LOOKUP_ITERATE
and may attach something to the preparsed pointer for use by (*cmp)().
(*cmp)() should return true if a key matches and false otherwise.
If preparsed is set, it may be necessary to use the match_free() method to
clean it up.
The method should return 0 if successful or a negative error code
otherwise.
It is permitted to sleep in this method, but (*cmp)() may not sleep as
locks will be held over it.
If match_preparse() is not provided, keys of this type will be matched
exactly by their description.
(*) void (*match_free)(struct key_match_data *match_data);
This method is optional. If given, it called to clean up
match_data->preparsed after a successful call to match_preparse().
(*) void (*revoke)(struct key *key); (*) void (*revoke)(struct key *key);
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment