Lines Matching refs:be
6 user mappings, and similar to be cached in the kernel for the use of
13 The key service can be configured on by enabling:
57 (*) Each key is of a defined "type". Types must be registered inside the
59 can be added or used. Userspace programs cannot define new types directly.
62 number of operations that can be performed on a key of that type.
64 Should a type be removed from the system, all the keys of that type will
65 be invalidated.
67 (*) Each key has a description. This should be a printable string. The key
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
76 instantiation function. Keys can also be immortal.
83 Having a payload is not required; and the payload can, in fact, just be a
91 permitted, another key type operation will be called to convert the key's
94 (*) Each key can be in one of a number of basic states:
97 Keys being requested from userspace will be in this state.
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
111 (*) Revoked. A key is put in this state by userspace action. It can't be
131 lists can be modified using various system calls. Keyrings should not
132 be given a payload when created.
137 blobs of data. These can be created, updated and read by userspace,
146 The description can be arbitrary, but must be prefixed with a non-zero
149 be created and updated from userspace, but the payload is only
178 will be subscribed to the default session key for the new UID.
181 it will be subscribed to the default for its current UID.
185 amount of description and payload space that can be consumed.
204 userspace to request a key that can't be found in a process's keyrings.
206 (*) An optional filesystem is available through which the key database can be
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
246 This permits a key's UID, GID and permissions mask to be changed.
257 controls can be applied to keys created within various contexts. This support
265 security context, then the key will be assigned that context. Otherwise, the
266 key will be assigned the current context of the task that invoked the key
267 creation request. Tasks must be granted explicit permission to assign a
271 The default keyrings associated with users will be labeled with the default
274 be labeled with the context of the login program itself.
297 information about it may be given.
404 type. The process must also have permission to write to the key to be able
410 to the keyring. In this case, an error will be generated if the process
417 The payload is optional, and the pointer can be NULL if not required by
418 the type. The payload is plen in size, and plen can be zero for an empty
421 A new keyring can be generated by setting type "keyring", the keyring name
424 User defined keys can be created by specifying type "user". It is
447 If a key cannot be found, and if callout_info is not NULL, then
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.
465 If the key does not yet exist, the key will be created if "create" is
466 non-zero; and the error ENOKEY will be returned if "create" is zero.
494 type. The process must also have permission to write to the key to be able
497 The payload is of length plen, and may be absent or empty as for
506 use the key will be met with error EKEYREVOKED, and the key will no longer
507 be findable.
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.
531 error EINVAL will be returned.
547 A process must have view permission on the key for this function to be
558 This can be parsed with
568 process must have write permission on the keyring, and it must be a
571 This function can also be used to clear special kernel keyrings if they
584 Should the keyring not be a keyring, error ENOTDIR will result; and if the
591 type and description will be discarded from the keyring as the new one is
604 is not present, error ENOENT will be the result.
619 permission on will be recursed into, and only keys and keyrings for which
620 a process has search permission can be matched. If the specified keyring
627 Error ENOKEY, EKEYREVOKED or EKEYEXPIRED will be returned if the search
628 fails. On success, the resulting key ID will be returned.
640 The returned data will be processed for presentation by the key type. For
646 As much of the data as can be fitted into the buffer will be copied to
664 invoked process returns, or else the key will be marked negative
667 The process must have write access on the key to be able to instantiate
668 it, and the key must be uninstantiated.
670 If a keyring is specified (non-zero), the key will also be linked into
691 The process must have write access on the key to be able to instantiate
692 it, and the key must be uninstantiated.
694 If a keyring is specified (non-zero), the key will also be linked into
707 This sets the default keyring to which implicitly requested keys will be
708 attached for this thread. reqkey_defl should be one of these constants:
721 The old default will be returned if successful and error EINVAL 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
743 timeout. Timeouts may not be set with this function on negative, revoked
752 specified key. Authority can only be assumed if the thread has the
760 If the requested authority is unavailable, error EPERM will be returned,
764 If the specified key is 0, then any assumed authority will be divested.
784 in force then an empty string will be returned.
786 A process must have view permission on the key for this function to be
801 mustn't deny permission, otherwise error EPERM will be returned.
803 Error ENOMEM will be returned if there was insufficient memory to complete
804 the operation, otherwise 0 will be returned to indicate success.
806 The keyring will be replaced next time the parent process leaves the
823 A process must have search permission on the key for this function to be
832 be broken down into two areas: keys and key types.
837 filesystem or device file, a search would probably be performed during the open
842 To access the key manager, the following header must be #included:
846 Specific key types should have a header file under include/keys/ that should be
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
873 possession information (which must be true or false).
878 When accessing a key's payload contents, certain precautions must be taken to
891 not NULL, then /sbin/request-key will be invoked in an attempt to obtain
892 the key from userspace. In that case, callout_string will be passed as an
895 Should the function fail error ENOKEY, EKEYEXPIRED or EKEYREVOKED will be
914 is a blob of length callout_len, if given (the length may be 0).
917 (*) A key can be requested asynchronously by calling one of:
936 construction. To wait for construction completion, the following should be
945 If intr is true, then the wait can be interrupted by a signal, in which
946 case error ERESTARTSYS will be returned.
949 (*) When it is no longer required, the key should be released using:
957 These can be called from interrupt context. If CONFIG_KEYS is not set then
958 the argument will not be parsed.
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
968 they've been finished with. The key pointer passed in will be returned.
971 then the key will not be dereferenced and no increment will take place.
974 (*) A key's serial number can be obtained by calling:
978 If key is NULL or if CONFIG_KEYS is not set then 0 will be returned (in the
982 (*) If a keyring was found in the search, this can be further searched by:
990 the returned key will need to be released.
997 (*) A keyring can be created by:
1006 is not NULL, the new keyring will be linked into the keyring to which it
1009 Error EDQUOT can be returned if the keyring would overload the quota (pass
1010 KEY_ALLOC_NOT_IN_QUOTA in flags if the keyring shouldn't be accounted
1011 towards the user's quota). Error ENOMEM can also be returned.
1014 (*) To check the validity of a key, this function can be called:
1019 revoked. Should the key be invalid, error EKEYEXPIRED or EKEYREVOKED will
1020 be returned. If the key is NULL or if CONFIG_KEYS is not set then 0 will be
1024 (*) To register a key type, the following function should be called:
1037 Under some circumstances, it may be desirable to deal with a bundle of keys.
1042 This can be used with a function such as request_key() to find a specific
1043 keyring in a process's keyrings. A keyring thus found can then be searched
1055 More complex payload contents must be allocated and a pointer to them set in
1056 key->payload.data. One of the following ways must be selected to access the
1062 be accessed without any form of locking, provided that it's known to be
1063 instantiated (uninstantiated keys cannot be "found").
1067 The semaphore could be used to govern access to the payload and to control
1068 the payload pointer. It must be write-locked for modifications and would
1069 have to be read-locked for general access. The disadvantage of doing this
1070 is that the accessor may be required to sleep.
1074 RCU must be used when the semaphore isn't already held; if the semaphore
1076 semaphore must still be used to serialise modifications to the key. The
1092 the payload. key->datalen cannot be relied upon to be consistent with the
1122 The data length (and quota) on a particular key can always be changed
1127 With the revised data length. Error EDQUOT will be returned if this is not
1155 the payload blob parameters; quotalen will be filled in with the default
1156 quota size from the key type; expiry will be set to TIME_T_MAX and the
1157 rest will be cleared.
1159 If a description can be proposed from the payload contents, that should be
1160 attached as a string to the description field. This will be used for the
1165 set, the expiry time will be applied to the key if it is instantiated from
1177 struct as filled in by the preparse() method. It will always be called
1189 blob. If preparse() was supplied then other fields may be filled in also.
1192 keytype->def_datalen, then key_payload_reserve() should be called.
1203 If this type of key can be updated, then this method should be provided.
1207 blob. If preparse() was supplied then other fields may be filled in also.
1209 key_payload_reserve() should be called if the data length might change
1212 memory allocation must be done first.
1216 be made under RCU conditions, and call_rcu() must be used to dispose of
1219 key_payload_reserve() should be called before the changes are made, but
1228 This method is optional. It is called when a key search is about to be
1239 On entry, raw_data will be pointing to the criteria to be used in matching
1240 a key by the caller and should not be modified. (*cmp)() will be pointing
1242 against raw_data) and lookup_type will be set to indicate a direct lookup.
1250 keys in the keyring until one is matched. This must be used for any
1258 If preparsed is set, it may be necessary to use the match_free() method to
1265 locks will be held over it.
1267 If match_preparse() is not provided, keys of this type will be matched
1283 It is safe to sleep in this method, though care should be taken to avoid
1304 This method will be called with the RCU read lock held. rcu_dereference()
1305 should be used to read the payload pointer if the payload is to be
1306 accessed. key->datalen cannot be trusted to stay consistent with the
1319 Ideally, the blob should be in the same format as that passed in to the
1322 If successful, the blob size that could be produced should be returned
1325 This method will be called with the key's semaphore read-locked. This will
1340 the key to be operated upon and the operation type (currently only
1344 following function must be called under all circumstances to complete the
1350 The error parameter should be 0 on success, -ve on error. The
1352 will be revoked. If an error is indicated, the key under construction
1353 will be negatively instantiated if it wasn't already instantiated.
1355 If this method returns an error, that error will be returned to the
1356 caller of request_key*(). complete_request_key() must be called prior to
1359 The key under construction and the authorisation key can be found in the
1382 keyrings from the process that caused the search to be issued. These are
1385 (1) There may be an authentication token in one of the keyrings that is
1388 (2) The new key should probably be cached in one of these rings.
1398 returning. Alternatively, the key can be marked as negative with KEYCTL_NEGATE
1399 or KEYCTL_REJECT; this also permits the key to be cached in one of the
1403 be marked as being negative, it will be added to the session keyring, and an
1404 error will be returned to the key requestor.
1406 Supplementary information may be provided from whoever or whatever invoked this
1407 service. This will be passed as the <callout_info> parameter. If no such
1408 information was made available, then "-" will be passed as this parameter
1426 Dead keys (for which the type has been removed) will be automatically unlinked
1430 Similarly, revoked and expired keys will be garbage collected, but only after a