Branch data Line data Source code
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 : : */
24 : : struct 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 : : */
41 : : struct key_preparsed_payload {
42 : : char *description; /* Proposed key description (or NULL) */
43 : : void *type_data[2]; /* Private key-type data */
44 : : void *payload; /* Proposed payload */
45 : : const void *data; /* Raw data */
46 : : size_t datalen; /* Raw datalen */
47 : : size_t quotalen; /* Quota length for proposed payload */
48 : : bool trusted; /* True if key is trusted */
49 : : };
50 : :
51 : : typedef int (*request_key_actor_t)(struct key_construction *key,
52 : : const char *op, void *aux);
53 : :
54 : : /*
55 : : * kernel managed key type definition
56 : : */
57 : : struct key_type {
58 : : /* name of the type */
59 : : const char *name;
60 : :
61 : : /* default payload length for quota precalculation (optional)
62 : : * - this can be used instead of calling key_payload_reserve(), that
63 : : * function only needs to be called if the real datalen is different
64 : : */
65 : : size_t def_datalen;
66 : :
67 : : /* Default key search algorithm. */
68 : : unsigned def_lookup_type;
69 : : #define KEYRING_SEARCH_LOOKUP_DIRECT 0x0000 /* Direct lookup by description. */
70 : : #define KEYRING_SEARCH_LOOKUP_ITERATE 0x0001 /* Iterative search. */
71 : :
72 : : /* vet a description */
73 : : int (*vet_description)(const char *description);
74 : :
75 : : /* Preparse the data blob from userspace that is to be the payload,
76 : : * generating a proposed description and payload that will be handed to
77 : : * the instantiate() and update() ops.
78 : : */
79 : : int (*preparse)(struct key_preparsed_payload *prep);
80 : :
81 : : /* Free a preparse data structure.
82 : : */
83 : : void (*free_preparse)(struct key_preparsed_payload *prep);
84 : :
85 : : /* instantiate a key of this type
86 : : * - this method should call key_payload_reserve() to determine if the
87 : : * user's quota will hold the payload
88 : : */
89 : : int (*instantiate)(struct key *key, struct key_preparsed_payload *prep);
90 : :
91 : : /* update a key of this type (optional)
92 : : * - this method should call key_payload_reserve() to recalculate the
93 : : * quota consumption
94 : : * - the key must be locked against read when modifying
95 : : */
96 : : int (*update)(struct key *key, struct key_preparsed_payload *prep);
97 : :
98 : : /* match a key against a description */
99 : : int (*match)(const struct key *key, const void *desc);
100 : :
101 : : /* clear some of the data from a key on revokation (optional)
102 : : * - the key's semaphore will be write-locked by the caller
103 : : */
104 : : void (*revoke)(struct key *key);
105 : :
106 : : /* clear the data from a key (optional) */
107 : : void (*destroy)(struct key *key);
108 : :
109 : : /* describe a key */
110 : : void (*describe)(const struct key *key, struct seq_file *p);
111 : :
112 : : /* read a key's data (optional)
113 : : * - permission checks will be done by the caller
114 : : * - the key's semaphore will be readlocked by the caller
115 : : * - should return the amount of data that could be read, no matter how
116 : : * much is copied into the buffer
117 : : * - shouldn't do the copy if the buffer is NULL
118 : : */
119 : : long (*read)(const struct key *key, char __user *buffer, size_t buflen);
120 : :
121 : : /* handle request_key() for this type instead of invoking
122 : : * /sbin/request-key (optional)
123 : : * - key is the key to instantiate
124 : : * - authkey is the authority to assume when instantiating this key
125 : : * - op is the operation to be done, usually "create"
126 : : * - the call must not return until the instantiation process has run
127 : : * its course
128 : : */
129 : : request_key_actor_t request_key;
130 : :
131 : : /* internal fields */
132 : : struct list_head link; /* link in types list */
133 : : struct lock_class_key lock_class; /* key->sem lock class */
134 : : };
135 : :
136 : : extern struct key_type key_type_keyring;
137 : :
138 : : extern int register_key_type(struct key_type *ktype);
139 : : extern void unregister_key_type(struct key_type *ktype);
140 : :
141 : : extern int key_payload_reserve(struct key *key, size_t datalen);
142 : : extern int key_instantiate_and_link(struct key *key,
143 : : const void *data,
144 : : size_t datalen,
145 : : struct key *keyring,
146 : : struct key *instkey);
147 : : extern int key_reject_and_link(struct key *key,
148 : : unsigned timeout,
149 : : unsigned error,
150 : : struct key *keyring,
151 : : struct key *instkey);
152 : : extern void complete_request_key(struct key_construction *cons, int error);
153 : :
154 : : static inline int key_negate_and_link(struct key *key,
155 : : unsigned timeout,
156 : : struct key *keyring,
157 : : struct key *instkey)
158 : : {
159 : 0 : return key_reject_and_link(key, timeout, ENOKEY, keyring, instkey);
160 : : }
161 : :
162 : : #endif /* CONFIG_KEYS */
163 : : #endif /* _LINUX_KEY_TYPE_H */
|
