Linux Kernel  3.7.1
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Functions | Variables
key.c File Reference
#include <linux/module.h>
#include <linux/init.h>
#include <linux/poison.h>
#include <linux/sched.h>
#include <linux/slab.h>
#include <linux/security.h>
#include <linux/workqueue.h>
#include <linux/random.h>
#include <linux/err.h>
#include "internal.h"

Go to the source code of this file.

Functions

 DEFINE_SPINLOCK (key_serial_lock)
 
 DEFINE_SPINLOCK (key_user_lock)
 
 DEFINE_MUTEX (key_construction_mutex)
 
struct key_userkey_user_lookup (kuid_t uid)
 
void key_user_put (struct key_user *user)
 
struct keykey_alloc (struct key_type *type, const char *desc, kuid_t uid, kgid_t gid, const struct cred *cred, key_perm_t perm, unsigned long flags)
 
 EXPORT_SYMBOL (key_alloc)
 
int key_payload_reserve (struct key *key, size_t datalen)
 
 EXPORT_SYMBOL (key_payload_reserve)
 
int key_instantiate_and_link (struct key *key, const void *data, size_t datalen, struct key *keyring, struct key *authkey)
 
 EXPORT_SYMBOL (key_instantiate_and_link)
 
int key_reject_and_link (struct key *key, unsigned timeout, unsigned error, struct key *keyring, struct key *authkey)
 
 EXPORT_SYMBOL (key_reject_and_link)
 
void key_put (struct key *key)
 
 EXPORT_SYMBOL (key_put)
 
struct keykey_lookup (key_serial_t id)
 
struct key_type * key_type_lookup (const char *type)
 
void key_set_timeout (struct key *key, unsigned timeout)
 
 EXPORT_SYMBOL_GPL (key_set_timeout)
 
void key_type_put (struct key_type *ktype)
 
key_ref_t key_create_or_update (key_ref_t keyring_ref, const char *type, const char *description, const void *payload, size_t plen, key_perm_t perm, unsigned long flags)
 
 EXPORT_SYMBOL (key_create_or_update)
 
int key_update (key_ref_t key_ref, const void *payload, size_t plen)
 
 EXPORT_SYMBOL (key_update)
 
void key_revoke (struct key *key)
 
 EXPORT_SYMBOL (key_revoke)
 
void key_invalidate (struct key *key)
 
 EXPORT_SYMBOL (key_invalidate)
 
int register_key_type (struct key_type *ktype)
 
 EXPORT_SYMBOL (register_key_type)
 
void unregister_key_type (struct key_type *ktype)
 
 EXPORT_SYMBOL (unregister_key_type)
 
void __init key_init (void)
 

Variables

struct kmem_cachekey_jar
 
struct rb_root key_serial_tree
 
struct rb_root key_user_tree
 
unsigned int key_quota_root_maxkeys = 200
 
unsigned int key_quota_root_maxbytes = 20000
 
unsigned int key_quota_maxkeys = 200
 
unsigned int key_quota_maxbytes = 20000
 

Function Documentation

DEFINE_MUTEX ( key_construction_mutex  )
DEFINE_SPINLOCK ( key_serial_lock  )
DEFINE_SPINLOCK ( key_user_lock  )
EXPORT_SYMBOL ( key_alloc  )
EXPORT_SYMBOL ( key_payload_reserve  )
EXPORT_SYMBOL ( key_instantiate_and_link  )
EXPORT_SYMBOL ( key_reject_and_link  )
EXPORT_SYMBOL ( key_put  )
EXPORT_SYMBOL ( key_create_or_update  )
EXPORT_SYMBOL ( key_update  )
EXPORT_SYMBOL ( key_revoke  )
EXPORT_SYMBOL ( key_invalidate  )
EXPORT_SYMBOL ( register_key_type  )
EXPORT_SYMBOL ( unregister_key_type  )
EXPORT_SYMBOL_GPL ( key_set_timeout  )
struct key* key_alloc ( struct key_type *  type,
const char desc,
kuid_t  uid,
kgid_t  gid,
const struct cred cred,
key_perm_t  perm,
unsigned long  flags 
)
read

key_alloc - Allocate a key of the specified type. : The type of key to allocate. : The key description to allow the key to be searched out. : The owner of the new key. : The group ID for the new key's group permissions. : The credentials specifying UID namespace. : The permissions mask of the new key. : Flags specifying quota properties.

Allocate a key of the specified type with the attributes given. The key is returned in an uninstantiated state and the caller needs to instantiate the key before returning.

The user's key count quota is updated to reflect the creation of the key and the user's key data quota has the default for the key type reserved. The instantiation function should amend this as necessary. If insufficient quota is available, -EDQUOT will be returned.

The LSM security modules can prevent a key being created, in which case -EACCES will be returned.

Returns a pointer to the new key if successful and an error code otherwise.

Note that the caller needs to ensure the key type isn't uninstantiated. Internally this can be done by locking key_types_sem. Externally, this can be done by either never unregistering the key type, or making sure key_alloc() calls don't race with module unloading.

Definition at line 224 of file key.c.

key_ref_t key_create_or_update ( key_ref_t  keyring_ref,
const char type,
const char description,
const void payload,
size_t  plen,
key_perm_t  perm,
unsigned long  flags 
)

key_create_or_update - Update or create and instantiate a key. : A pointer to the destination keyring with possession flag. : The type of key. : The searchable description for the key. : The data to use to instantiate or update the key. : The length of . : The permissions mask for a new key. : The quota flags for a new key.

Search the destination keyring for a key of the same description and if one is found, update it, otherwise create and instantiate a new one and create a link to it from that keyring.

If perm is KEY_PERM_UNDEF then an appropriate key permissions mask will be concocted.

Returns a pointer to the new key if successful, -ENODEV if the key type wasn't available, -ENOTDIR if the keyring wasn't a keyring, -EACCES if the caller isn't permitted to modify the keyring or the LSM did not permit creation of the key.

On success, the possession flag from the keyring ref will be tacked on to the key ref before it is returned.

Definition at line 775 of file key.c.

void __init key_init ( void  )

Definition at line 1080 of file key.c.

int key_instantiate_and_link ( struct key key,
const void data,
size_t  datalen,
struct key keyring,
struct key authkey 
)

key_instantiate_and_link - Instantiate a key and link it into the keyring. : The key to instantiate. : The data to use to instantiate the keyring. : The length of . : Keyring to create a link in on success (or NULL). : The authorisation token permitting instantiation.

Instantiate a key that's in the uninstantiated state using the provided data and, if successful, link it in to the destination keyring if one is supplied.

If successful, 0 is returned, the authorisation token is revoked and anyone waiting for the key is woken up. If the key was already instantiated, -EBUSY will be returned.

Definition at line 471 of file key.c.

void key_invalidate ( struct key key)

key_invalidate - Invalidate a key. : The key to be invalidated.

Mark a key as being invalidated and have it cleaned up immediately. The key is ignored by all searches and other operations from this point.

Definition at line 1007 of file key.c.

struct key* key_lookup ( key_serial_t  id)
read

Definition at line 616 of file key.c.

int key_payload_reserve ( struct key key,
size_t  datalen 
)

key_payload_reserve - Adjust data quota reservation for the key's payload : The key to make the reservation for. : The amount of data payload the caller now wants.

Adjust the amount of the owning user's key data quota that a key reserves. If the amount is increased, then -EDQUOT may be returned if there isn't enough free quota available.

If successful, 0 is returned.

Definition at line 367 of file key.c.

void key_put ( struct key key)

key_put - Discard a reference to a key. : The key to discard a reference from.

Discard a reference to a key, and when all the references are gone, we schedule the cleanup task to come and pull it out of the tree in process context at some later time.

Definition at line 602 of file key.c.

int key_reject_and_link ( struct key key,
unsigned  timeout,
unsigned  error,
struct key keyring,
struct key authkey 
)

key_reject_and_link - Negatively instantiate a key and link it into the keyring. : The key to instantiate. : The timeout on the negative key. : The error to return when the key is hit. : Keyring to create a link in on success (or NULL). : The authorisation token permitting instantiation.

Negatively instantiate a key that's in the uninstantiated state and, if successful, set its timeout and stored error and link it in to the destination keyring if one is supplied. The key and any links to the key will be automatically garbage collected after the timeout expires.

Negative keys are used to rate limit repeated request_key() calls by causing them to return the stored error code (typically ENOKEY) until the negative key expires.

If successful, 0 is returned, the authorisation token is revoked and anyone waiting for the key is woken up. If the key was already instantiated, -EBUSY will be returned.

Definition at line 534 of file key.c.

void key_revoke ( struct key key)

key_revoke - Revoke a key. : The key to be revoked.

Mark a key as being revoked and ask the type to free up its resources. The revocation timeout is set and the key and all its links will be automatically garbage collected after key_gc_delay amount of time if they are not manually dealt with first.

Definition at line 971 of file key.c.

void key_set_timeout ( struct key key,
unsigned  timeout 
)

Definition at line 681 of file key.c.

struct key_type* key_type_lookup ( const char type)
read

Definition at line 661 of file key.c.

void key_type_put ( struct key_type *  ktype)

Definition at line 704 of file key.c.

int key_update ( key_ref_t  key_ref,
const void payload,
size_t  plen 
)

key_update - Update a key's contents. : The pointer (plus possession flag) to the key. : The data to be used to update the key. : The length of .

Attempt to update the contents of a key with the given payload data. The caller must be granted Write permission on the key. Negative keys can be instantiated by this method.

Returns 0 on success, -EACCES if not permitted and -EOPNOTSUPP if the key type does not support updating. The key type may return other errors.

Definition at line 918 of file key.c.

struct key_user* key_user_lookup ( kuid_t  uid)
read

Definition at line 54 of file key.c.

void key_user_put ( struct key_user user)

Definition at line 123 of file key.c.

int register_key_type ( struct key_type *  ktype)

register_key_type - Register a type of key. : The new key type.

Register a new key type.

Returns 0 on success or -EEXIST if a type of this name already exists.

Definition at line 1030 of file key.c.

void unregister_key_type ( struct key_type *  ktype)

unregister_key_type - Unregister a type of key. : The key type.

Unregister a key type and mark all the extant keys of this type as dead. Those keys of this type are then destroyed to get rid of their payloads and they and their links will be garbage collected as soon as possible.

Definition at line 1066 of file key.c.

Variable Documentation

struct kmem_cache* key_jar

Definition at line 23 of file key.c.

unsigned int key_quota_maxbytes = 20000

Definition at line 33 of file key.c.

unsigned int key_quota_maxkeys = 200

Definition at line 32 of file key.c.

unsigned int key_quota_root_maxbytes = 20000

Definition at line 31 of file key.c.

unsigned int key_quota_root_maxkeys = 200

Definition at line 30 of file key.c.

struct rb_root key_serial_tree

Definition at line 24 of file key.c.

struct rb_root key_user_tree

Definition at line 27 of file key.c.