LXR linux/include/linux/key-type.h

   1/* Definitions for key type implementations
   2 *
   3 * Copyright (C) 2007 Red Hat, Inc. All Rights Reserved.
   4 * Written by David Howells (dhowells@redhat.com)
   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 */
  24struct 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 */
  41struct key_preparsed_payload {
  42        char            *description;   /* Proposed key description (or NULL) */
  43        union key_payload payload;      /* Proposed payload */
  44        const void      *data;          /* Raw data */
  45        size_t          datalen;        /* Raw datalen */
  46        size_t          quotalen;       /* Quota length for proposed payload */
  47        time_t          expiry;         /* Expiry time of key */
  48        bool            trusted;        /* True if key is trusted */
  49};
  50
  51typedef int (*request_key_actor_t)(struct key_construction *key,
  52                                   const char *op, void *aux);
  53
  54/*
  55 * Preparsed matching criterion.
  56 */
  57struct key_match_data {
  58        /* Comparison function, defaults to exact description match, but can be
  59         * overridden by type->match_preparse().  Should return true if a match
  60         * is found and false if not.
  61         */
  62        bool (*cmp)(const struct key *key,
  63                    const struct key_match_data *match_data);
  64
  65        const void      *raw_data;      /* Raw match data */
  66        void            *preparsed;     /* For ->match_preparse() to stash stuff */
  67        unsigned        lookup_type;    /* Type of lookup for this search. */
  68#define KEYRING_SEARCH_LOOKUP_DIRECT    0x0000  /* Direct lookup by description. */
  69#define KEYRING_SEARCH_LOOKUP_ITERATE   0x0001  /* Iterative search. */
  70};
  71
  72/*
  73 * kernel managed key type definition
  74 */
  75struct key_type {
  76        /* name of the type */
  77        const char *name;
  78
  79        /* default payload length for quota precalculation (optional)
  80         * - this can be used instead of calling key_payload_reserve(), that
  81         *   function only needs to be called if the real datalen is different
  82         */
  83        size_t def_datalen;
  84
  85        /* vet a description */
  86        int (*vet_description)(const char *description);
  87
  88        /* Preparse the data blob from userspace that is to be the payload,
  89         * generating a proposed description and payload that will be handed to
  90         * the instantiate() and update() ops.
  91         */
  92        int (*preparse)(struct key_preparsed_payload *prep);
  93
  94        /* Free a preparse data structure.
  95         */
  96        void (*free_preparse)(struct key_preparsed_payload *prep);
  97
  98        /* instantiate a key of this type
  99         * - this method should call key_payload_reserve() to determine if the
 100         *   user's quota will hold the payload
 101         */
 102        int (*instantiate)(struct key *key, struct key_preparsed_payload *prep);
 103
 104        /* update a key of this type (optional)
 105         * - this method should call key_payload_reserve() to recalculate the
 106         *   quota consumption
 107         * - the key must be locked against read when modifying
 108         */
 109        int (*update)(struct key *key, struct key_preparsed_payload *prep);
 110
 111        /* Preparse the data supplied to ->match() (optional).  The
 112         * data to be preparsed can be found in match_data->raw_data.
 113         * The lookup type can also be set by this function.
 114         */
 115        int (*match_preparse)(struct key_match_data *match_data);
 116
 117        /* Free preparsed match data (optional).  This should be supplied it
 118         * ->match_preparse() is supplied. */
 119        void (*match_free)(struct key_match_data *match_data);
 120
 121        /* clear some of the data from a key on revokation (optional)
 122         * - the key's semaphore will be write-locked by the caller
 123         */
 124        void (*revoke)(struct key *key);
 125
 126        /* clear the data from a key (optional) */
 127        void (*destroy)(struct key *key);
 128
 129        /* describe a key */
 130        void (*describe)(const struct key *key, struct seq_file *p);
 131
 132        /* read a key's data (optional)
 133         * - permission checks will be done by the caller
 134         * - the key's semaphore will be readlocked by the caller
 135         * - should return the amount of data that could be read, no matter how
 136         *   much is copied into the buffer
 137         * - shouldn't do the copy if the buffer is NULL
 138         */
 139        long (*read)(const struct key *key, char __user *buffer, size_t buflen);
 140
 141        /* handle request_key() for this type instead of invoking
 142         * /sbin/request-key (optional)
 143         * - key is the key to instantiate
 144         * - authkey is the authority to assume when instantiating this key
 145         * - op is the operation to be done, usually "create"
 146         * - the call must not return until the instantiation process has run
 147         *   its course
 148         */
 149        request_key_actor_t request_key;
 150
 151        /* internal fields */
 152        struct list_head        link;           /* link in types list */
 153        struct lock_class_key   lock_class;     /* key->sem lock class */
 154};
 155
 156extern struct key_type key_type_keyring;
 157
 158extern int register_key_type(struct key_type *ktype);
 159extern void unregister_key_type(struct key_type *ktype);
 160
 161extern int key_payload_reserve(struct key *key, size_t datalen);
 162extern int key_instantiate_and_link(struct key *key,
 163                                    const void *data,
 164                                    size_t datalen,
 165                                    struct key *keyring,
 166                                    struct key *instkey);
 167extern int key_reject_and_link(struct key *key,
 168                               unsigned timeout,
 169                               unsigned error,
 170                               struct key *keyring,
 171                               struct key *instkey);
 172extern void complete_request_key(struct key_construction *cons, int error);
 173
 174static inline int key_negate_and_link(struct key *key,
 175                                      unsigned timeout,
 176                                      struct key *keyring,
 177                                      struct key *instkey)
 178{
 179        return key_reject_and_link(key, timeout, ENOKEY, keyring, instkey);
 180}
 181
 182extern int generic_key_instantiate(struct key *key, struct key_preparsed_payload *prep);
 183
 184#endif /* CONFIG_KEYS */
 185#endif /* _LINUX_KEY_TYPE_H */
 186