Branch data     Line data    Source code

       1                 :            : /* SPDX-License-Identifier: GPL-2.0-or-later */
       2                 :            : /* Definitions for key type implementations
       3                 :            :  *
       4                 :            :  * Copyright (C) 2007 Red Hat, Inc. All Rights Reserved.
       5                 :            :  * Written by David Howells (dhowells@redhat.com)
       6                 :            :  */
       7                 :            : 
       8                 :            : #ifndef _LINUX_KEY_TYPE_H
       9                 :            : #define _LINUX_KEY_TYPE_H
      10                 :            : 
      11                 :            : #include <linux/key.h>
      12                 :            : #include <linux/errno.h>
      13                 :            : 
      14                 :            : #ifdef CONFIG_KEYS
      15                 :            : 
      16                 :            : struct kernel_pkey_query;
      17                 :            : struct kernel_pkey_params;
      18                 :            : 
      19                 :            : /*
      20                 :            :  * Pre-parsed payload, used by key add, update and instantiate.
      21                 :            :  *
      22                 :            :  * This struct will be cleared and data and datalen will be set with the data
      23                 :            :  * and length parameters from the caller and quotalen will be set from
      24                 :            :  * def_datalen from the key type.  Then if the preparse() op is provided by the
      25                 :            :  * key type, that will be called.  Then the struct will be passed to the
      26                 :            :  * instantiate() or the update() op.
      27                 :            :  *
      28                 :            :  * If the preparse() op is given, the free_preparse() op will be called to
      29                 :            :  * clear the contents.
      30                 :            :  */
      31                 :            : struct key_preparsed_payload {
      32                 :            :         char            *description;   /* Proposed key description (or NULL) */
      33                 :            :         union key_payload payload;      /* Proposed payload */
      34                 :            :         const void      *data;          /* Raw data */
      35                 :            :         size_t          datalen;        /* Raw datalen */
      36                 :            :         size_t          quotalen;       /* Quota length for proposed payload */
      37                 :            :         time64_t        expiry;         /* Expiry time of key */
      38                 :            : } __randomize_layout;
      39                 :            : 
      40                 :            : typedef int (*request_key_actor_t)(struct key *auth_key, void *aux);
      41                 :            : 
      42                 :            : /*
      43                 :            :  * Preparsed matching criterion.
      44                 :            :  */
      45                 :            : struct key_match_data {
      46                 :            :         /* Comparison function, defaults to exact description match, but can be
      47                 :            :          * overridden by type->match_preparse().  Should return true if a match
      48                 :            :          * is found and false if not.
      49                 :            :          */
      50                 :            :         bool (*cmp)(const struct key *key,
      51                 :            :                     const struct key_match_data *match_data);
      52                 :            : 
      53                 :            :         const void      *raw_data;      /* Raw match data */
      54                 :            :         void            *preparsed;     /* For ->match_preparse() to stash stuff */
      55                 :            :         unsigned        lookup_type;    /* Type of lookup for this search. */
      56                 :            : #define KEYRING_SEARCH_LOOKUP_DIRECT    0x0000  /* Direct lookup by description. */
      57                 :            : #define KEYRING_SEARCH_LOOKUP_ITERATE   0x0001  /* Iterative search. */
      58                 :            : };
      59                 :            : 
      60                 :            : /*
      61                 :            :  * kernel managed key type definition
      62                 :            :  */
      63                 :            : struct key_type {
      64                 :            :         /* name of the type */
      65                 :            :         const char *name;
      66                 :            : 
      67                 :            :         /* default payload length for quota precalculation (optional)
      68                 :            :          * - this can be used instead of calling key_payload_reserve(), that
      69                 :            :          *   function only needs to be called if the real datalen is different
      70                 :            :          */
      71                 :            :         size_t def_datalen;
      72                 :            : 
      73                 :            :         unsigned int flags;
      74                 :            : #define KEY_TYPE_NET_DOMAIN     0x00000001 /* Keys of this type have a net namespace domain */
      75                 :            : 
      76                 :            :         /* vet a description */
      77                 :            :         int (*vet_description)(const char *description);
      78                 :            : 
      79                 :            :         /* Preparse the data blob from userspace that is to be the payload,
      80                 :            :          * generating a proposed description and payload that will be handed to
      81                 :            :          * the instantiate() and update() ops.
      82                 :            :          */
      83                 :            :         int (*preparse)(struct key_preparsed_payload *prep);
      84                 :            : 
      85                 :            :         /* Free a preparse data structure.
      86                 :            :          */
      87                 :            :         void (*free_preparse)(struct key_preparsed_payload *prep);
      88                 :            : 
      89                 :            :         /* instantiate a key of this type
      90                 :            :          * - this method should call key_payload_reserve() to determine if the
      91                 :            :          *   user's quota will hold the payload
      92                 :            :          */
      93                 :            :         int (*instantiate)(struct key *key, struct key_preparsed_payload *prep);
      94                 :            : 
      95                 :            :         /* update a key of this type (optional)
      96                 :            :          * - this method should call key_payload_reserve() to recalculate the
      97                 :            :          *   quota consumption
      98                 :            :          * - the key must be locked against read when modifying
      99                 :            :          */
     100                 :            :         int (*update)(struct key *key, struct key_preparsed_payload *prep);
     101                 :            : 
     102                 :            :         /* Preparse the data supplied to ->match() (optional).  The
     103                 :            :          * data to be preparsed can be found in match_data->raw_data.
     104                 :            :          * The lookup type can also be set by this function.
     105                 :            :          */
     106                 :            :         int (*match_preparse)(struct key_match_data *match_data);
     107                 :            : 
     108                 :            :         /* Free preparsed match data (optional).  This should be supplied it
     109                 :            :          * ->match_preparse() is supplied. */
     110                 :            :         void (*match_free)(struct key_match_data *match_data);
     111                 :            : 
     112                 :            :         /* clear some of the data from a key on revokation (optional)
     113                 :            :          * - the key's semaphore will be write-locked by the caller
     114                 :            :          */
     115                 :            :         void (*revoke)(struct key *key);
     116                 :            : 
     117                 :            :         /* clear the data from a key (optional) */
     118                 :            :         void (*destroy)(struct key *key);
     119                 :            : 
     120                 :            :         /* describe a key */
     121                 :            :         void (*describe)(const struct key *key, struct seq_file *p);
     122                 :            : 
     123                 :            :         /* read a key's data (optional)
     124                 :            :          * - permission checks will be done by the caller
     125                 :            :          * - the key's semaphore will be readlocked by the caller
     126                 :            :          * - should return the amount of data that could be read, no matter how
     127                 :            :          *   much is copied into the buffer
     128                 :            :          * - shouldn't do the copy if the buffer is NULL
     129                 :            :          */
     130                 :            :         long (*read)(const struct key *key, char *buffer, size_t buflen);
     131                 :            : 
     132                 :            :         /* handle request_key() for this type instead of invoking
     133                 :            :          * /sbin/request-key (optional)
     134                 :            :          * - key is the key to instantiate
     135                 :            :          * - authkey is the authority to assume when instantiating this key
     136                 :            :          * - op is the operation to be done, usually "create"
     137                 :            :          * - the call must not return until the instantiation process has run
     138                 :            :          *   its course
     139                 :            :          */
     140                 :            :         request_key_actor_t request_key;
     141                 :            : 
     142                 :            :         /* Look up a keyring access restriction (optional)
     143                 :            :          *
     144                 :            :          * - NULL is a valid return value (meaning the requested restriction
     145                 :            :          *   is known but will never block addition of a key)
     146                 :            :          * - should return -EINVAL if the restriction is unknown
     147                 :            :          */
     148                 :            :         struct key_restriction *(*lookup_restriction)(const char *params);
     149                 :            : 
     150                 :            :         /* Asymmetric key accessor functions. */
     151                 :            :         int (*asym_query)(const struct kernel_pkey_params *params,
     152                 :            :                           struct kernel_pkey_query *info);
     153                 :            :         int (*asym_eds_op)(struct kernel_pkey_params *params,
     154                 :            :                            const void *in, void *out);
     155                 :            :         int (*asym_verify_signature)(struct kernel_pkey_params *params,
     156                 :            :                                      const void *in, const void *in2);
     157                 :            : 
     158                 :            :         /* internal fields */
     159                 :            :         struct list_head        link;           /* link in types list */
     160                 :            :         struct lock_class_key   lock_class;     /* key->sem lock class */
     161                 :            : } __randomize_layout;
     162                 :            : 
     163                 :            : extern struct key_type key_type_keyring;
     164                 :            : 
     165                 :            : extern int register_key_type(struct key_type *ktype);
     166                 :            : extern void unregister_key_type(struct key_type *ktype);
     167                 :            : 
     168                 :            : extern int key_payload_reserve(struct key *key, size_t datalen);
     169                 :            : extern int key_instantiate_and_link(struct key *key,
     170                 :            :                                     const void *data,
     171                 :            :                                     size_t datalen,
     172                 :            :                                     struct key *keyring,
     173                 :            :                                     struct key *authkey);
     174                 :            : extern int key_reject_and_link(struct key *key,
     175                 :            :                                unsigned timeout,
     176                 :            :                                unsigned error,
     177                 :            :                                struct key *keyring,
     178                 :            :                                struct key *authkey);
     179                 :            : extern void complete_request_key(struct key *authkey, int error);
     180                 :            : 
     181                 :            : static inline int key_negate_and_link(struct key *key,
     182                 :            :                                       unsigned timeout,
     183                 :            :                                       struct key *keyring,
     184                 :            :                                       struct key *authkey)
     185                 :            : {
     186                 :          0 :         return key_reject_and_link(key, timeout, ENOKEY, keyring, authkey);
     187                 :            : }
     188                 :            : 
     189                 :            : extern int generic_key_instantiate(struct key *key, struct key_preparsed_payload *prep);
     190                 :            : 
     191                 :            : #endif /* CONFIG_KEYS */
     192                 :            : #endif /* _LINUX_KEY_TYPE_H */