Lines Matching refs:to
6 user mappings, and similar to be cached in the kernel for the use of
9 Keyrings are permitted; these are a special type of key that can hold links to
54 Userspace programs can use a key's serial numbers as a way to gain access
55 to it, subject to permission checking.
68 type provides an operation to perform a match between the description on a
72 are used to control what a process may do to a key from userspace, and
73 whether a kernel service will be able to find the key.
75 (*) Each key can be set to expire at a specific time by the key type's
79 actual "key". In the case of a keyring, this is a list of keys to which
90 Similarly, when userspace wants to read back the contents of the key, if
91 permitted, another key type operation will be called to convert the key's
103 note saying that a previous call out to userspace failed, and acts as
104 a throttle on key lookups. A negative key can be updated to a normal
108 they traverse to this state. An expired key can be updated back to a
116 Keys in the last three states are subject to garbage collection. See the
143 blob of data. It is intended as a place to store secrets which are
144 accessible to the kernel but not to userspace programs.
152 (*) Each process subscribes to three keyrings: a thread-specific keyring, a
167 by using PR_JOIN_SESSION_KEYRING. It is permitted to request an anonymous
168 new one, or to attempt to create or join one of a specific name.
175 keyring is initialised with a link to the user-specific keyring.
177 When a process changes its real UID, if it used to have no session key, it
178 will be subscribed to the default session key for the new UID.
180 If a process attempts to access its session key when it doesn't have one,
181 it will be subscribed to the default for its current UID.
203 (*) There's a way for the a search done from the kernel to call back to
204 userspace to request a key that can't be found in a process's keyrings.
215 has up to eight bits each for possessor, user, group and other access. Only
220 This permits a key or keyring's attributes to be viewed - including key
225 This permits a key's payload to be viewed or a keyring's list of linked
230 This permits a key's payload to be instantiated or updated, or it allows a
231 link to be added to or removed from a keyring.
235 This permits keyrings to be searched and keys to be found. Searches can
240 This permits a key or keyring to be linked to. To create a link from a
241 keyring to a key, a process must have Write permission on the keyring and
246 This permits a key's UID, GID and permissions mask to be changed.
256 The security class "key" has been added to SELinux so that mandatory access
257 controls can be applied to keys created within various contexts. This support
258 is preliminary, and is likely to change quite significantly in the near future.
264 newly-created keys. If the contents of that file correspond to an SELinux
267 creation request. Tasks must be granted explicit permission to assign a
268 particular context to newly-created keys, using the "create" permission in the
272 context of the user if and only if the login programs have been instrumented to
278 boot process, before root has a chance to log in.
289 Two files have been added to procfs by which an administrator can find out
296 It is not possible to view the payload of the key this way, though some
299 The only keys included in the list are those that grant View permission to
302 the current process is not authorised to view.
322 Q Contributes to user's quota
323 U Under construction by callback to userspace
339 <UID>: User ID to which this applies
363 Root may alter these by writing each new limit as a decimal number string to
375 When referring to a key directly, userspace programs should use the key's
377 values available for referring to special keys and keyrings that relate to the
394 (*) Create a new key of given type, description and payload and add it to the
402 in the keyring, this will try to update it with the given payload, or it
404 type. The process must also have permission to write to the key to be able
405 to update it. The new key will have all user permissions granted and no
408 Otherwise, this will attempt to create a new key of the specified type and
409 description, and to instantiate it with the supplied payload and attach it
410 to the keyring. In this case, an error will be generated if the process
411 does not have permission to write to the keyring.
422 as the description (or NULL) and setting the payload to NULL.
435 (*) Search the process's keyrings for a key, potentially calling out to
436 userspace to create it.
444 KEYCTL_SEARCH, including the optional attachment of the discovered key to
448 /sbin/request-key will be invoked in an attempt to obtain a key. The
449 callout_info string will be passed as an argument to the program.
456 (*) Map a special key ID to a real key ID for this process:
469 (*) Replace the session keyring this process subscribes to with a new one:
473 If name is NULL, an anonymous keyring is created attached to the process
477 attempts to attach it as the session keyring, returning an error if that
481 To attach to a named keyring, the keyring must have search permission for
492 This will try to update the specified key with the given payload, or it
494 type. The process must also have permission to write to the key to be able
495 to update it.
505 This makes a key unavailable for further operations. Further attempts to
514 This function permits a key's owner and group ID to be changed. Either one
515 of uid or gid can be set to -1 to suppress that change.
517 Only the superuser can change a key's owner to something other than the
519 group ID to something other than the calling process's group ID or one of
527 This function permits the owner of a key or the superuser to change the
544 than requested to userspace. If the buffer pointer is NULL then no copy
547 A process must have view permission on the key for this function to be
567 This function clears the list of keys attached to a keyring. The calling
571 This function can also be used to clear special kernel keyrings if they
580 This function creates a link from the keyring to the key. The process must
590 Any links within the keyring to keys that match the new key in terms of
599 This function looks through the keyring for the first link to the
600 specified key, and removes it if found. Subsequent links to that key are
623 If the search succeeds, the function will attempt to link the found key
625 constraints applicable to KEYCTL_LINK apply in this case too.
636 This function attempts to read the payload data from the specified key
637 into the buffer. The process must have read permission on the key to
642 representing the IDs of all the keys to which it is subscribed. The user
646 As much of the data as can be fitted into the buffer will be copied to
662 If the kernel calls back to userspace to complete the instantiation of a
663 key, userspace should use this call to supply data for the key before the
667 The process must have write access on the key to be able to instantiate
687 If the kernel calls back to userspace to complete the instantiation of a
689 invoked process returns if it is unable to fulfill the request.
691 The process must have write access on the key to be able to instantiate
707 This sets the default keyring to which implicitly requested keys will be
724 The default keyring can be overridden by the keyring indicated to the
738 This sets or clears the timeout on a key. The timeout can be 0 to clear
739 the timeout or a number of seconds to set the expiry time that far into
742 The process must have attribute modification access on a key to set its
747 (*) Assume the authority granted to instantiate a key
751 This assumes or divests the authority required to instantiate the
769 (*) Get the LSM security context attached to a key.
775 attached to a key in the buffer provided.
779 than requested to userspace. If the buffer pointer is NULL then no copy
786 A process must have view permission on the key for this function to be
794 This functions attempts to install the calling process's session keyring
795 on to the calling process's parent, replacing the parent's current session
803 Error ENOMEM will be returned if there was insufficient memory to complete
804 the operation, otherwise 0 will be returned to indicate success.
819 Keys that are marked invalidated become invisible to normal key operations
823 A process must have search permission on the key for this function to be
831 The kernel services for key management are fairly simple to deal with. They can
838 call, and the key released upon close. How to deal with conflicting keys due to
839 two different users opening the same file is left to the filesystem author to
847 used to access that type. For keys of type "user", for example, that would be:
851 Note that there are two different types of pointers to keys that may be
856 This simply points to the key structure itself. Key structures will be at
861 This is equivalent to a struct key *, but the least significant bit is set
863 calling processes has a searchable link to the key from one of its
878 When accessing a key's payload contents, certain precautions must be taken to
888 This is used to request a key or keyring with a description that matches
889 the description specified according to the key type's match_preparse()
890 method. This permits approximate matching to occur. If callout_string is
891 not NULL, then /sbin/request-key will be invoked in an attempt to obtain
893 argument to the program.
898 If successful, the key will have been attached to the default keyring for
904 (*) To search for a key, passing auxiliary data to the upcaller, call:
912 This is identical to request_key(), except that the auxiliary data is
913 passed to the key_type->request_key() op if it exists, and the callout_info
941 The function will wait for the key to finish being constructed and then
942 invokes key_validate() to return an appropriate value to indicate the state
961 (*) Extra references can be made to a key by calling one of the following
967 Keys so references will need to be disposed of by calling key_put() when
989 is returned upon failure (use IS_ERR/PTR_ERR to determine). If successful,
990 the returned key will need to be released.
992 The possession attribute from the keyring reference is used to control
993 access through the permissions mask and is propagated to the returned key
1006 is not NULL, the new keyring will be linked into the keyring to which it
1037 Under some circumstances, it may be desirable to deal with a bundle of keys.
1038 The facility provides access to the keyring type for managing such a bundle:
1042 This can be used with a function such as request_key() to find a specific
1044 with keyring_search(). Note that it is not possible to use request_key() to
1053 case, there's no need to indulge in RCU or locking when accessing the payload.
1055 More complex payload contents must be allocated and pointers to them set in the
1056 key->payload.data[] array. One of the following ways must be selected to
1062 be accessed without any form of locking, provided that it's known to be
1067 The semaphore could be used to govern access to the payload and to control
1069 have to be read-locked for general access. The disadvantage of doing this
1070 is that the accessor may be required to sleep.
1076 semaphore must still be used to serialise modifications to the key. The
1083 to read the pointer, and:
1087 to set the pointer and dispose of the old contents after a grace period.
1092 the payload. key->datalen cannot be relied upon to be consistent with the
1097 wrap the RCU calls to this element:
1107 A kernel service may want to define its own key type. For instance, an AFS
1108 filesystem might want to define a Kerberos 5 ticket key type. To do this, it
1119 The name of the key type. This is used to translate a key type name
1120 supplied by userspace into a pointer to the structure.
1126 contributed to the quota. If the key type's payload is always or almost
1127 always the same size, then this is a more efficient way to do things.
1140 This optional method is called to vet a key description. If the key type
1147 This optional method permits the key type to attempt to parse payload
1149 instantiate key). The structure pointed to by prep looks like:
1162 quota size from the key type; expiry will be set to TIME_T_MAX and the
1166 attached as a string to the description field. This will be used for the
1169 The method can attach anything it likes to payload. This is merely passed
1170 along to the instantiate() or update() operations. If set, the expiry
1171 time will be applied to the key if it is instantiated from this data.
1180 otherwise it is unused. It cleans up anything attached to the description
1188 This method is called to attach a payload to a key during construction.
1189 The payload attached need not bear any relation to the data passed to this
1195 If the amount of data attached to the key differs from the size in
1198 This method does not have to lock the key in order to attach a payload.
1200 anything else from gaining access to the key.
1202 It is safe to sleep in this method.
1204 generic_key_instantiate() is provided to simply copy the data from
1205 prep->payload.data[] to key->payload.data[], with RCU-safe assignment on
1213 It is called to update a key's payload from the blob of data provided.
1220 is committed to changing the key because it's already been altered, so all
1224 but this only deters other writers; any changes to the key's payload must
1225 be made under RCU conditions, and call_rcu() must be used to dispose of
1232 It is safe to sleep in this method.
1237 This method is optional. It is called when a key search is about to be
1248 On entry, raw_data will be pointing to the criteria to be used in matching
1250 to the default matcher function (which does an exact description match
1251 against raw_data) and lookup_type will be set to indicate a direct lookup.
1256 description to narrow down the search to a small number of keys.
1262 The method may set cmp to point to a function of its choice that does some
1263 other form of match, may set lookup_type to KEYRING_SEARCH_LOOKUP_ITERATE
1264 and may attach something to the preparsed pointer for use by (*cmp)().
1267 If preparsed is set, it may be necessary to use the match_free() method to
1273 It is permitted to sleep in this method, but (*cmp)() may not sleep as
1282 This method is optional. If given, it called to clean up
1283 match_data->preparsed after a successful call to match_preparse().
1288 This method is optional. It is called to discard part of the payload
1292 It is safe to sleep in this method, though care should be taken to avoid
1298 This method is optional. It is called to discard the payload data on a key
1301 This method does not need to lock the key to access the payload; it can
1305 It is not safe to sleep in this method; the caller may hold spinlocks.
1310 This method is optional. It is called during /proc/keys reading to
1314 should be used to read the payload pointer if the payload is to be
1315 accessed. key->datalen cannot be trusted to stay consistent with the
1320 It is not safe to sleep in this method; the RCU read lock is held by the
1326 This method is optional. It is called by KEYCTL_READ to translate the
1327 key's payload into something a blob of data for userspace to deal with.
1328 Ideally, the blob should be in the same format as that passed in to the
1335 prevent the key's payload changing. It is not necessary to use RCU locking
1336 when accessing the key's payload. It is safe to sleep in this method, such
1344 invoke this function rather than upcalling to /sbin/request-key to operate
1347 The aux parameter is as passed to request_key_async_with_auxdata() and
1349 the key to be operated upon and the operation type (currently only
1352 This method is permitted to return before the upcall is complete, but the
1353 following function must be called under all circumstances to complete the
1364 If this method returns an error, that error will be returned to the
1365 caller of request_key*(). complete_request_key() must be called prior to
1369 key_construction struct pointed to by cons:
1384 To create a new key, the kernel will attempt to execute the following command
1391 keyrings from the process that caused the search to be issued. These are
1395 required to obtain the key, eg: a Kerberos Ticket-Granting Ticket.
1399 This program should set it UID and GID to those specified before attempting to
1400 access any more keys. It may then look around for a user specific process to
1401 hand the request off to (perhaps a path held in placed in another key by, for
1405 calling KEYCTL_INSTANTIATE or KEYCTL_INSTANTIATE_IOV, which also permits it to
1408 or KEYCTL_REJECT; this also permits the key to be cached in one of the
1412 be marked as being negative, it will be added to the session keyring, and an
1413 error will be returned to the key requestor.
1421 Similarly, the kernel may attempt to update an expired or a soon to expire key
1427 In this case, the program isn't required to actually attach the key to a ring;
1436 from those keyrings that point to them and deleted as soon as possible by a