aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/security/keys.txt
diff options
context:
space:
mode:
authorDavid Howells <dhowells@redhat.com>2012-09-13 08:06:29 -0400
committerDavid Howells <dhowells@redhat.com>2012-09-13 08:06:29 -0400
commitd4f65b5d2497b2fd9c45f06b71deb4ab084a5b66 (patch)
tree57128a75a755e2b4a6521408cc2eaf73c88e54aa /Documentation/security/keys.txt
parenteeea3ac912207dcf759b95b2b4c36f96bce583bf (diff)
KEYS: Add payload preparsing opportunity prior to key instantiate or update
Give the key type the opportunity to preparse the payload prior to the instantiation and update routines being called. This is done with the provision of two new key type operations: int (*preparse)(struct key_preparsed_payload *prep); void (*free_preparse)(struct key_preparsed_payload *prep); If the first operation is present, then it is called before key creation (in the add/update case) or before the key semaphore is taken (in the update and instantiate cases). The second operation is called to clean up if the first was called. preparse() is given the opportunity to fill in the following structure: struct key_preparsed_payload { char *description; void *type_data[2]; void *payload; const void *data; size_t datalen; size_t quotalen; }; Before the preparser is called, the first three fields will have been cleared, the payload pointer and size will be stored in data and datalen and the default quota size from the key_type struct will be stored into quotalen. The preparser may parse the payload in any way it likes and may store data in the type_data[] and payload fields for use by the instantiate() and update() ops. The preparser may also propose a description for the key by attaching it as a string to the description field. This can be used by passing a NULL or "" description to the add_key() system call or the key_create_or_update() function. This cannot work with request_key() as that required the description to tell the upcall about the key to be created. This, for example permits keys that store PGP public keys to generate their own name from the user ID and public key fingerprint in the key. The instantiate() and update() operations are then modified to look like this: int (*instantiate)(struct key *key, struct key_preparsed_payload *prep); int (*update)(struct key *key, struct key_preparsed_payload *prep); and the new payload data is passed in *prep, whether or not it was preparsed. Signed-off-by: David Howells <dhowells@redhat.com>
Diffstat (limited to 'Documentation/security/keys.txt')
-rw-r--r--Documentation/security/keys.txt50
1 files changed, 49 insertions, 1 deletions
diff --git a/Documentation/security/keys.txt b/Documentation/security/keys.txt
index aa0dbd74b71b..7d9ca92022d8 100644
--- a/Documentation/security/keys.txt
+++ b/Documentation/security/keys.txt
@@ -412,6 +412,10 @@ The main syscalls are:
412 to the keyring. In this case, an error will be generated if the process 412 to the keyring. In this case, an error will be generated if the process
413 does not have permission to write to the keyring. 413 does not have permission to write to the keyring.
414 414
415 If the key type supports it, if the description is NULL or an empty
416 string, the key type will try and generate a description from the content
417 of the payload.
418
415 The payload is optional, and the pointer can be NULL if not required by 419 The payload is optional, and the pointer can be NULL if not required by
416 the type. The payload is plen in size, and plen can be zero for an empty 420 the type. The payload is plen in size, and plen can be zero for an empty
417 payload. 421 payload.
@@ -1114,12 +1118,53 @@ The structure has a number of fields, some of which are mandatory:
1114 it should return 0. 1118 it should return 0.
1115 1119
1116 1120
1117 (*) int (*instantiate)(struct key *key, const void *data, size_t datalen); 1121 (*) int (*preparse)(struct key_preparsed_payload *prep);
1122
1123 This optional method permits the key type to attempt to parse payload
1124 before a key is created (add key) or the key semaphore is taken (update or
1125 instantiate key). The structure pointed to by prep looks like:
1126
1127 struct key_preparsed_payload {
1128 char *description;
1129 void *type_data[2];
1130 void *payload;
1131 const void *data;
1132 size_t datalen;
1133 size_t quotalen;
1134 };
1135
1136 Before calling the method, the caller will fill in data and datalen with
1137 the payload blob parameters; quotalen will be filled in with the default
1138 quota size from the key type and the rest will be cleared.
1139
1140 If a description can be proposed from the payload contents, that should be
1141 attached as a string to the description field. This will be used for the
1142 key description if the caller of add_key() passes NULL or "".
1143
1144 The method can attach anything it likes to type_data[] and payload. These
1145 are merely passed along to the instantiate() or update() operations.
1146
1147 The method should return 0 if success ful or a negative error code
1148 otherwise.
1149
1150
1151 (*) void (*free_preparse)(struct key_preparsed_payload *prep);
1152
1153 This method is only required if the preparse() method is provided,
1154 otherwise it is unused. It cleans up anything attached to the
1155 description, type_data and payload fields of the key_preparsed_payload
1156 struct as filled in by the preparse() method.
1157
1158
1159 (*) int (*instantiate)(struct key *key, struct key_preparsed_payload *prep);
1118 1160
1119 This method is called to attach a payload to a key during construction. 1161 This method is called to attach a payload to a key during construction.
1120 The payload attached need not bear any relation to the data passed to this 1162 The payload attached need not bear any relation to the data passed to this
1121 function. 1163 function.
1122 1164
1165 The prep->data and prep->datalen fields will define the original payload
1166 blob. If preparse() was supplied then other fields may be filled in also.
1167
1123 If the amount of data attached to the key differs from the size in 1168 If the amount of data attached to the key differs from the size in
1124 keytype->def_datalen, then key_payload_reserve() should be called. 1169 keytype->def_datalen, then key_payload_reserve() should be called.
1125 1170
@@ -1135,6 +1180,9 @@ The structure has a number of fields, some of which are mandatory:
1135 If this type of key can be updated, then this method should be provided. 1180 If this type of key can be updated, then this method should be provided.
1136 It is called to update a key's payload from the blob of data provided. 1181 It is called to update a key's payload from the blob of data provided.
1137 1182
1183 The prep->data and prep->datalen fields will define the original payload
1184 blob. If preparse() was supplied then other fields may be filled in also.
1185
1138 key_payload_reserve() should be called if the data length might change 1186 key_payload_reserve() should be called if the data length might change
1139 before any changes are actually made. Note that if this succeeds, the type 1187 before any changes are actually made. Note that if this succeeds, the type
1140 is committed to changing the key because it's already been altered, so all 1188 is committed to changing the key because it's already been altered, so all