1/* Definitions for key type implementations
2 *
3 * Copyright (C) 2007 Red Hat, Inc. All Rights Reserved.
4 * Written by David Howells (dhowells@redhat.com)
5 *
6 * This program is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU General Public Licence
8 * as published by the Free Software Foundation; either version
9 * 2 of the Licence, or (at your option) any later version.
10 */
11
12#ifndef _LINUX_KEY_TYPE_H
13#define _LINUX_KEY_TYPE_H
14
15#include <linux/key.h>
16#include <linux/errno.h>
17
18#ifdef CONFIG_KEYS
19
20/*
21 * key under-construction record
22 * - passed to the request_key actor if supplied
23 */
24struct key_construction {
25	struct key	*key;	/* key being constructed */
26	struct key	*authkey;/* authorisation for key being constructed */
27};
28
29/*
30 * Pre-parsed payload, used by key add, update and instantiate.
31 *
32 * This struct will be cleared and data and datalen will be set with the data
33 * and length parameters from the caller and quotalen will be set from
34 * def_datalen from the key type.  Then if the preparse() op is provided by the
35 * key type, that will be called.  Then the struct will be passed to the
36 * instantiate() or the update() op.
37 *
38 * If the preparse() op is given, the free_preparse() op will be called to
39 * clear the contents.
40 */
41struct key_preparsed_payload {
42	char		*description;	/* Proposed key description (or NULL) */
43	void		*type_data[2];	/* Private key-type data */
44	void		*payload[2];	/* Proposed payload */
45	const void	*data;		/* Raw data */
46	size_t		datalen;	/* Raw datalen */
47	size_t		quotalen;	/* Quota length for proposed payload */
48	time_t		expiry;		/* Expiry time of key */
49	bool		trusted;	/* True if key is trusted */
50};
51
52typedef int (*request_key_actor_t)(struct key_construction *key,
53				   const char *op, void *aux);
54
55/*
56 * Preparsed matching criterion.
57 */
58struct key_match_data {
59	/* Comparison function, defaults to exact description match, but can be
60	 * overridden by type->match_preparse().  Should return true if a match
61	 * is found and false if not.
62	 */
63	bool (*cmp)(const struct key *key,
64		    const struct key_match_data *match_data);
65
66	const void	*raw_data;	/* Raw match data */
67	void		*preparsed;	/* For ->match_preparse() to stash stuff */
68	unsigned	lookup_type;	/* Type of lookup for this search. */
69#define KEYRING_SEARCH_LOOKUP_DIRECT	0x0000	/* Direct lookup by description. */
70#define KEYRING_SEARCH_LOOKUP_ITERATE	0x0001	/* Iterative search. */
71};
72
73/*
74 * kernel managed key type definition
75 */
76struct key_type {
77	/* name of the type */
78	const char *name;
79
80	/* default payload length for quota precalculation (optional)
81	 * - this can be used instead of calling key_payload_reserve(), that
82	 *   function only needs to be called if the real datalen is different
83	 */
84	size_t def_datalen;
85
86	/* vet a description */
87	int (*vet_description)(const char *description);
88
89	/* Preparse the data blob from userspace that is to be the payload,
90	 * generating a proposed description and payload that will be handed to
91	 * the instantiate() and update() ops.
92	 */
93	int (*preparse)(struct key_preparsed_payload *prep);
94
95	/* Free a preparse data structure.
96	 */
97	void (*free_preparse)(struct key_preparsed_payload *prep);
98
99	/* instantiate a key of this type
100	 * - this method should call key_payload_reserve() to determine if the
101	 *   user's quota will hold the payload
102	 */
103	int (*instantiate)(struct key *key, struct key_preparsed_payload *prep);
104
105	/* update a key of this type (optional)
106	 * - this method should call key_payload_reserve() to recalculate the
107	 *   quota consumption
108	 * - the key must be locked against read when modifying
109	 */
110	int (*update)(struct key *key, struct key_preparsed_payload *prep);
111
112	/* Preparse the data supplied to ->match() (optional).  The
113	 * data to be preparsed can be found in match_data->raw_data.
114	 * The lookup type can also be set by this function.
115	 */
116	int (*match_preparse)(struct key_match_data *match_data);
117
118	/* Free preparsed match data (optional).  This should be supplied it
119	 * ->match_preparse() is supplied. */
120	void (*match_free)(struct key_match_data *match_data);
121
122	/* clear some of the data from a key on revokation (optional)
123	 * - the key's semaphore will be write-locked by the caller
124	 */
125	void (*revoke)(struct key *key);
126
127	/* clear the data from a key (optional) */
128	void (*destroy)(struct key *key);
129
130	/* describe a key */
131	void (*describe)(const struct key *key, struct seq_file *p);
132
133	/* read a key's data (optional)
134	 * - permission checks will be done by the caller
135	 * - the key's semaphore will be readlocked by the caller
136	 * - should return the amount of data that could be read, no matter how
137	 *   much is copied into the buffer
138	 * - shouldn't do the copy if the buffer is NULL
139	 */
140	long (*read)(const struct key *key, char __user *buffer, size_t buflen);
141
142	/* handle request_key() for this type instead of invoking
143	 * /sbin/request-key (optional)
144	 * - key is the key to instantiate
145	 * - authkey is the authority to assume when instantiating this key
146	 * - op is the operation to be done, usually "create"
147	 * - the call must not return until the instantiation process has run
148	 *   its course
149	 */
150	request_key_actor_t request_key;
151
152	/* internal fields */
153	struct list_head	link;		/* link in types list */
154	struct lock_class_key	lock_class;	/* key->sem lock class */
155};
156
157extern struct key_type key_type_keyring;
158
159extern int register_key_type(struct key_type *ktype);
160extern void unregister_key_type(struct key_type *ktype);
161
162extern int key_payload_reserve(struct key *key, size_t datalen);
163extern int key_instantiate_and_link(struct key *key,
164				    const void *data,
165				    size_t datalen,
166				    struct key *keyring,
167				    struct key *instkey);
168extern int key_reject_and_link(struct key *key,
169			       unsigned timeout,
170			       unsigned error,
171			       struct key *keyring,
172			       struct key *instkey);
173extern void complete_request_key(struct key_construction *cons, int error);
174
175static inline int key_negate_and_link(struct key *key,
176				      unsigned timeout,
177				      struct key *keyring,
178				      struct key *instkey)
179{
180	return key_reject_and_link(key, timeout, ENOKEY, keyring, instkey);
181}
182
183extern int generic_key_instantiate(struct key *key, struct key_preparsed_payload *prep);
184
185#endif /* CONFIG_KEYS */
186#endif /* _LINUX_KEY_TYPE_H */
187