Linux Kernel  3.7.1
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
key-type.h
Go to the documentation of this file.
1 /* Definitions for key type implementations
2  *
3  * Copyright (C) 2007 Red Hat, Inc. All Rights Reserved.
4  * Written by David Howells ([email protected])
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 };
49 
50 typedef int (*request_key_actor_t)(struct key_construction *key,
51  const char *op, void *aux);
52 
53 /*
54  * kernel managed key type definition
55  */
56 struct key_type {
57  /* name of the type */
58  const char *name;
59 
60  /* default payload length for quota precalculation (optional)
61  * - this can be used instead of calling key_payload_reserve(), that
62  * function only needs to be called if the real datalen is different
63  */
64  size_t def_datalen;
65 
66  /* vet a description */
67  int (*vet_description)(const char *description);
68 
69  /* Preparse the data blob from userspace that is to be the payload,
70  * generating a proposed description and payload that will be handed to
71  * the instantiate() and update() ops.
72  */
73  int (*preparse)(struct key_preparsed_payload *prep);
74 
75  /* Free a preparse data structure.
76  */
77  void (*free_preparse)(struct key_preparsed_payload *prep);
78 
79  /* instantiate a key of this type
80  * - this method should call key_payload_reserve() to determine if the
81  * user's quota will hold the payload
82  */
83  int (*instantiate)(struct key *key, struct key_preparsed_payload *prep);
84 
85  /* update a key of this type (optional)
86  * - this method should call key_payload_reserve() to recalculate the
87  * quota consumption
88  * - the key must be locked against read when modifying
89  */
90  int (*update)(struct key *key, struct key_preparsed_payload *prep);
91 
92  /* match a key against a description */
93  int (*match)(const struct key *key, const void *desc);
94 
95  /* clear some of the data from a key on revokation (optional)
96  * - the key's semaphore will be write-locked by the caller
97  */
98  void (*revoke)(struct key *key);
99 
100  /* clear the data from a key (optional) */
101  void (*destroy)(struct key *key);
102 
103  /* describe a key */
104  void (*describe)(const struct key *key, struct seq_file *p);
105 
106  /* read a key's data (optional)
107  * - permission checks will be done by the caller
108  * - the key's semaphore will be readlocked by the caller
109  * - should return the amount of data that could be read, no matter how
110  * much is copied into the buffer
111  * - shouldn't do the copy if the buffer is NULL
112  */
113  long (*read)(const struct key *key, char __user *buffer, size_t buflen);
114 
115  /* handle request_key() for this type instead of invoking
116  * /sbin/request-key (optional)
117  * - key is the key to instantiate
118  * - authkey is the authority to assume when instantiating this key
119  * - op is the operation to be done, usually "create"
120  * - the call must not return until the instantiation process has run
121  * its course
122  */
123  request_key_actor_t request_key;
124 
125  /* internal fields */
126  struct list_head link; /* link in types list */
127  struct lock_class_key lock_class; /* key->sem lock class */
128 };
129 
130 extern struct key_type key_type_keyring;
131 
132 extern int register_key_type(struct key_type *ktype);
133 extern void unregister_key_type(struct key_type *ktype);
134 
135 extern int key_payload_reserve(struct key *key, size_t datalen);
136 extern int key_instantiate_and_link(struct key *key,
137  const void *data,
138  size_t datalen,
139  struct key *keyring,
140  struct key *instkey);
141 extern int key_reject_and_link(struct key *key,
142  unsigned timeout,
143  unsigned error,
144  struct key *keyring,
145  struct key *instkey);
146 extern void complete_request_key(struct key_construction *cons, int error);
147 
148 static inline int key_negate_and_link(struct key *key,
149  unsigned timeout,
150  struct key *keyring,
151  struct key *instkey)
152 {
153  return key_reject_and_link(key, timeout, ENOKEY, keyring, instkey);
154 }
155 
156 #endif /* CONFIG_KEYS */
157 #endif /* _LINUX_KEY_TYPE_H */