include/linux/key.h

   1 /* SPDX-License-Identifier: GPL-2.0-or-later */
   2 /* Authentication token and access key management
   3  *
   4  * Copyright (C) 2004, 2007 Red Hat, Inc. All Rights Reserved.
   5  * Written by David Howells (dhowells@redhat.com)
   6  *
   7  * See Documentation/security/keys/core.rst for information on keys/keyrings.
   8  */
   9
  10 #ifndef _LINUX_KEY_H
  11 #define _LINUX_KEY_H
  12
  13 #include <linux/types.h>
  14 #include <linux/list.h>
  15 #include <linux/rbtree.h>
  16 #include <linux/rcupdate.h>
  17 #include <linux/sysctl.h>
  18 #include <linux/rwsem.h>
  19 #include <linux/atomic.h>
  20 #include <linux/assoc_array.h>
  21 #include <linux/refcount.h>
  22 #include <linux/time64.h>
  23
  24 #ifdef __KERNEL__
  25 #include <linux/uidgid.h>
  26
  27 /* key handle serial number */
  28 typedef int32_t key_serial_t;
  29
  30 struct key;
  31 struct net;
  32
  33 #ifdef CONFIG_KEYS
  34
  35 #include <linux/keyctl.h>
  36
  37 #undef KEY_DEBUGGING
  38
  39 struct seq_file;
  40 struct user_struct;
  41 struct signal_struct;
  42 struct cred;
  43
  44 struct key_type;
  45 struct key_owner;
  46 struct key_tag;
  47 struct keyring_list;
  48 struct keyring_name;
  49
  50 struct key_tag {
  51         struct rcu_head         rcu;
  52         refcount_t              usage;
  53         bool                    removed;        /* T when subject removed */
  54 };
  55
  56 struct keyring_index_key {
  57         /* [!] If this structure is altered, the union in struct key must change too! */
  58         unsigned long           hash;                   /* Hash value */
  59         union {
  60                 struct {
  61 #ifdef __LITTLE_ENDIAN /* Put desc_len at the LSB of x */
  62                         u8      desc_len;
  63                         char    desc[sizeof(long) - 1]; /* First few chars of description */
  64 #else
  65                         char    desc[sizeof(long) - 1]; /* First few chars of description */
  66                         u8      desc_len;
  67 #endif
  68                 };
  69                 unsigned long x;
  70         };
  71         struct key_type         *type;
  72         struct key_tag          *domain_tag;    /* Domain of operation */
  73         const char              *description;
  74 };
  75
  76 union key_payload {
  77         void __rcu              *rcu_data0;
  78         void                    *data[4];
  79 };
  80
  81 struct key_ace {
  82         unsigned int            type;
  83         unsigned int            perm;
  84         union {
  85                 kuid_t          uid;
  86                 kgid_t          gid;
  87                 unsigned int    subject_id;
  88         };
  89 };
  90
  91 struct key_acl {
  92         refcount_t              usage;
  93         unsigned short          nr_ace;
  94         bool                    possessor_viewable;
  95         struct rcu_head         rcu;
  96         struct key_ace          aces[];
  97 };
  98
  99 #define KEY_POSSESSOR_ACE(perms) {                      \
 100                 .type = KEY_ACE_SUBJ_STANDARD,          \
 101                 .perm = perms,                          \
 102                 .subject_id = KEY_ACE_POSSESSOR         \
 103         }
 104
 105 #define KEY_OWNER_ACE(perms) {                          \
 106                 .type = KEY_ACE_SUBJ_STANDARD,          \
 107                 .perm = perms,                          \
 108                 .subject_id = KEY_ACE_OWNER             \
 109         }
 110
 111 /*****************************************************************************/
 112 /*
 113  * key reference with possession attribute handling
 114  *
 115  * NOTE! key_ref_t is a typedef'd pointer to a type that is not actually
 116  * defined. This is because we abuse the bottom bit of the reference to carry a
 117  * flag to indicate whether the calling process possesses that key in one of
 118  * its keyrings.
 119  *
 120  * the key_ref_t has been made a separate type so that the compiler can reject
 121  * attempts to dereference it without proper conversion.
 122  *
 123  * the three functions are used to assemble and disassemble references
 124  */
 125 typedef struct __key_reference_with_attributes *key_ref_t;
 126
 127 static inline key_ref_t make_key_ref(const struct key *key,
 128                                      bool possession)
 129 {
 130         return (key_ref_t) ((unsigned long) key | possession);
 131 }
 132
 133 static inline struct key *key_ref_to_ptr(const key_ref_t key_ref)
 134 {
 135         return (struct key *) ((unsigned long) key_ref & ~1UL);
 136 }
 137
 138 static inline bool is_key_possessed(const key_ref_t key_ref)
 139 {
 140         return (unsigned long) key_ref & 1UL;
 141 }
 142
 143 typedef int (*key_restrict_link_func_t)(struct key *dest_keyring,
 144                                         const struct key_type *type,
 145                                         const union key_payload *payload,
 146                                         struct key *restriction_key);
 147
 148 struct key_restriction {
 149         key_restrict_link_func_t check;
 150         struct key *key;
 151         struct key_type *keytype;
 152 };
 153
 154 enum key_state {
 155         KEY_IS_UNINSTANTIATED,
 156         KEY_IS_POSITIVE,                /* Positively instantiated */
 157 };
 158
 159 /*****************************************************************************/
 160 /*
 161  * authentication token / access credential / keyring
 162  * - types of key include:
 163  *   - keyrings
 164  *   - disk encryption IDs
 165  *   - Kerberos TGTs and tickets
 166  */
 167 struct key {
 168         refcount_t              usage;          /* number of references */
 169         key_serial_t            serial;         /* key serial number */
 170         union {
 171                 struct list_head graveyard_link;
 172                 struct rb_node  serial_node;
 173         };
 174         struct rw_semaphore     sem;            /* change vs change sem */
 175         struct key_user         *user;          /* owner of this key */
 176         void                    *security;      /* security data for this key */
 177         struct key_acl          __rcu *acl;
 178         union {
 179                 time64_t        expiry;         /* time at which key expires (or 0) */
 180                 time64_t        revoked_at;     /* time at which key was revoked */
 181         };
 182         time64_t                last_used_at;   /* last time used for LRU keyring discard */
 183         kuid_t                  uid;
 184         kgid_t                  gid;
 185         unsigned short          quotalen;       /* length added to quota */
 186         unsigned short          datalen;        /* payload data length
 187                                                  * - may not match RCU dereferenced payload
 188                                                  * - payload should contain own length
 189                                                  */
 190         short                   state;          /* Key state (+) or rejection error (-) */
 191
 192 #ifdef KEY_DEBUGGING
 193         unsigned                magic;
 194 #define KEY_DEBUG_MAGIC         0x18273645u
 195 #endif
 196
 197         unsigned long           flags;          /* status flags (change with bitops) */
 198 #define KEY_FLAG_DEAD           0       /* set if key type has been deleted */
 199 #define KEY_FLAG_REVOKED        1       /* set if key had been revoked */
 200 #define KEY_FLAG_IN_QUOTA       2       /* set if key consumes quota */
 201 #define KEY_FLAG_USER_CONSTRUCT 3       /* set if key is being constructed in userspace */
 202 #define KEY_FLAG_ROOT_CAN_CLEAR 4       /* set if key can be cleared by root without permission */
 203 #define KEY_FLAG_INVALIDATED    5       /* set if key has been invalidated */
 204 #define KEY_FLAG_BUILTIN        6       /* set if key is built in to the kernel */
 205 #define KEY_FLAG_ROOT_CAN_INVAL 7       /* set if key can be invalidated by root without permission */
 206 #define KEY_FLAG_KEEP           8       /* set if key should not be removed */
 207 #define KEY_FLAG_UID_KEYRING    9       /* set if key is a user or user session keyring */
 208 #define KEY_FLAG_HAS_ACL        10      /* Set if KEYCTL_SETACL called on key */
 209
 210         /* the key type and key description string
 211          * - the desc is used to match a key against search criteria
 212          * - it should be a printable string
 213          * - eg: for krb5 AFS, this might be "afs@REDHAT.COM"
 214          */
 215         union {
 216                 struct keyring_index_key index_key;
 217                 struct {
 218                         unsigned long   hash;
 219                         unsigned long   len_desc;
 220                         struct key_type *type;          /* type of key */
 221                         struct key_tag  *domain_tag;    /* Domain of operation */
 222                         char            *description;
 223                 };
 224         };
 225
 226         /* key data
 227          * - this is used to hold the data actually used in cryptography or
 228          *   whatever
 229          */
 230         union {
 231                 union key_payload payload;
 232                 struct {
 233                         /* Keyring bits */
 234                         struct list_head name_link;
 235                         struct assoc_array keys;
 236                 };
 237         };
 238
 239         /* This is set on a keyring to restrict the addition of a link to a key
 240          * to it.  If this structure isn't provided then it is assumed that the
 241          * keyring is open to any addition.  It is ignored for non-keyring
 242          * keys. Only set this value using keyring_restrict(), keyring_alloc(),
 243          * or key_alloc().
 244          *
 245          * This is intended for use with rings of trusted keys whereby addition
 246          * to the keyring needs to be controlled.  KEY_ALLOC_BYPASS_RESTRICTION
 247          * overrides this, allowing the kernel to add extra keys without
 248          * restriction.
 249          */
 250         struct key_restriction *restrict_link;
 251 };
 252
 253 extern struct key *key_alloc(struct key_type *type,
 254                              const char *desc,
 255                              kuid_t uid, kgid_t gid,
 256                              const struct cred *cred,
 257                              struct key_acl *acl,
 258                              unsigned long flags,
 259                              struct key_restriction *restrict_link);
 260
 261
 262 #define KEY_ALLOC_IN_QUOTA              0x0000  /* add to quota, reject if would overrun */
 263 #define KEY_ALLOC_QUOTA_OVERRUN         0x0001  /* add to quota, permit even if overrun */
 264 #define KEY_ALLOC_NOT_IN_QUOTA          0x0002  /* not in quota */
 265 #define KEY_ALLOC_BUILT_IN              0x0004  /* Key is built into kernel */
 266 #define KEY_ALLOC_BYPASS_RESTRICTION    0x0008  /* Override the check on restricted keyrings */
 267 #define KEY_ALLOC_UID_KEYRING           0x0010  /* allocating a user or user session keyring */
 268
 269 extern void key_revoke(struct key *key);
 270 extern void key_invalidate(struct key *key);
 271 extern void key_put(struct key *key);
 272 extern bool key_put_tag(struct key_tag *tag);
 273 extern void key_remove_domain(struct key_tag *domain_tag);
 274
 275 static inline struct key *__key_get(struct key *key)
 276 {
 277         refcount_inc(&key->usage);
 278         return key;
 279 }
 280
 281 static inline struct key *key_get(struct key *key)
 282 {
 283         return key ? __key_get(key) : key;
 284 }
 285
 286 static inline void key_ref_put(key_ref_t key_ref)
 287 {
 288         key_put(key_ref_to_ptr(key_ref));
 289 }
 290
 291 extern struct key *request_key_tag(struct key_type *type,
 292                                    const char *description,
 293                                    struct key_tag *domain_tag,
 294                                    const char *callout_info,
 295                                    struct key_acl *acl);
 296
 297 extern struct key *request_key_rcu(struct key_type *type,
 298                                    const char *description,
 299                                    struct key_tag *domain_tag);
 300
 301 extern struct key *request_key_with_auxdata(struct key_type *type,
 302                                             const char *description,
 303                                             struct key_tag *domain_tag,
 304                                             const void *callout_info,
 305                                             size_t callout_len,
 306                                             void *aux,
 307                                             struct key_acl *acl);
 308
 309 /**
 310  * request_key - Request a key and wait for construction
 311  * @type: Type of key.
 312  * @description: The searchable description of the key.
 313  * @callout_info: The data to pass to the instantiation upcall (or NULL).
 314  * @acl: The ACL to attach to a new key (or NULL).
 315  *
 316  * As for request_key_tag(), but with the default global domain tag.
 317  */
 318 static inline struct key *request_key(struct key_type *type,
 319                                       const char *description,
 320                                       const char *callout_info,
 321                                       struct key_acl *acl)
 322 {
 323         return request_key_tag(type, description, NULL, callout_info, acl);
 324 }
 325
 326 #ifdef CONFIG_NET
 327 /*
 328  * request_key_net - Request a key for a net namespace and wait for construction
 329  * @type: Type of key.
 330  * @description: The searchable description of the key.
 331  * @net: The network namespace that is the key's domain of operation.
 332  * @callout_info: The data to pass to the instantiation upcall (or NULL).
 333  * @acl: The ACL to attach to a new key (or NULL).
 334  *
 335  * As for request_key() except that it does not add the returned key to a
 336  * keyring if found, new keys are always allocated in the user's quota, the
 337  * callout_info must be a NUL-terminated string and no auxiliary data can be
 338  * passed.  Only keys that operate the specified network namespace are used.
 339  *
 340  * Furthermore, it then works as wait_for_key_construction() to wait for the
 341  * completion of keys undergoing construction with a non-interruptible wait.
 342  */
 343 #define request_key_net(type, description, net, callout_info, acl)      \
 344         request_key_tag(type, description, net->key_domain, callout_info, acl);
 345 #endif /* CONFIG_NET */
 346
 347 extern int wait_for_key_construction(struct key *key, bool intr);
 348
 349 extern int key_validate(const struct key *key);
 350
 351 extern key_ref_t key_create_or_update(key_ref_t keyring,
 352                                       const char *type,
 353                                       const char *description,
 354                                       const void *payload,
 355                                       size_t plen,
 356                                       struct key_acl *acl,
 357                                       unsigned long flags);
 358
 359 extern int key_update(key_ref_t key,
 360                       const void *payload,
 361                       size_t plen);
 362
 363 extern int key_link(struct key *keyring,
 364                     struct key *key);
 365
 366 extern int key_move(struct key *key,
 367                     struct key *from_keyring,
 368                     struct key *to_keyring,
 369                     unsigned int flags);
 370
 371 extern int key_unlink(struct key *keyring,
 372                       struct key *key);
 373
 374 extern struct key *keyring_alloc(const char *description, kuid_t uid, kgid_t gid,
 375                                  const struct cred *cred,
 376                                  struct key_acl *acl,
 377                                  unsigned long flags,
 378                                  struct key_restriction *restrict_link,
 379                                  struct key *dest);
 380
 381 extern int restrict_link_reject(struct key *keyring,
 382                                 const struct key_type *type,
 383                                 const union key_payload *payload,
 384                                 struct key *restriction_key);
 385
 386 extern int keyring_clear(struct key *keyring);
 387
 388 extern key_ref_t keyring_search(key_ref_t keyring,
 389                                 struct key_type *type,
 390                                 const char *description,
 391                                 bool recurse);
 392
 393 extern int keyring_add_key(struct key *keyring,
 394                            struct key *key);
 395
 396 extern int keyring_restrict(key_ref_t keyring, const char *type,
 397                             const char *restriction);
 398
 399 extern struct key *key_lookup(key_serial_t id);
 400
 401 static inline key_serial_t key_serial(const struct key *key)
 402 {
 403         return key ? key->serial : 0;
 404 }
 405
 406 extern void key_set_timeout(struct key *, unsigned);
 407
 408 extern key_ref_t lookup_user_key(key_serial_t id, unsigned long flags,
 409                                  u32 desired_perm);
 410 extern void key_free_user_ns(struct user_namespace *);
 411
 412 /*
 413  * The permissions required on a key that we're looking up.
 414  */
 415 #define KEY_NEED_VIEW   0x001   /* Require permission to view attributes */
 416 #define KEY_NEED_READ   0x002   /* Require permission to read content */
 417 #define KEY_NEED_WRITE  0x004   /* Require permission to update / modify */
 418 #define KEY_NEED_SEARCH 0x008   /* Require permission to search (keyring) or find (key) */
 419 #define KEY_NEED_LINK   0x010   /* Require permission to link */
 420 #define KEY_NEED_SETSEC 0x020   /* Require permission to set owner, group, ACL */
 421 #define KEY_NEED_INVAL  0x040   /* Require permission to invalidate key */
 422 #define KEY_NEED_REVOKE 0x080   /* Require permission to revoke key */
 423 #define KEY_NEED_JOIN   0x100   /* Require permission to join keyring as session */
 424 #define KEY_NEED_CLEAR  0x200   /* Require permission to clear a keyring */
 425 #define KEY_NEED_ALL    0x3ff
 426
 427 #define OLD_KEY_NEED_SETATTR 0x20 /* Used to be Require permission to change attributes */
 428
 429 extern struct key_acl internal_key_acl;
 430 extern struct key_acl internal_keyring_acl;
 431 extern struct key_acl internal_writable_keyring_acl;
 432
 433 static inline short key_read_state(const struct key *key)
 434 {
 435         /* Barrier versus mark_key_instantiated(). */
 436         return smp_load_acquire(&key->state);
 437 }
 438
 439 /**
 440  * key_is_positive - Determine if a key has been positively instantiated
 441  * @key: The key to check.
 442  *
 443  * Return true if the specified key has been positively instantiated, false
 444  * otherwise.
 445  */
 446 static inline bool key_is_positive(const struct key *key)
 447 {
 448         return key_read_state(key) == KEY_IS_POSITIVE;
 449 }
 450
 451 static inline bool key_is_negative(const struct key *key)
 452 {
 453         return key_read_state(key) < 0;
 454 }
 455
 456 #define dereference_key_rcu(KEY)                                        \
 457         (rcu_dereference((KEY)->payload.rcu_data0))
 458
 459 #define dereference_key_locked(KEY)                                     \
 460         (rcu_dereference_protected((KEY)->payload.rcu_data0,            \
 461                                    rwsem_is_locked(&((struct key *)(KEY))->sem)))
 462
 463 #define rcu_assign_keypointer(KEY, PAYLOAD)                             \
 464 do {                                                                    \
 465         rcu_assign_pointer((KEY)->payload.rcu_data0, (PAYLOAD));        \
 466 } while (0)
 467
 468 #ifdef CONFIG_SYSCTL
 469 extern struct ctl_table key_sysctls[];
 470 #endif
 471 /*
 472  * the userspace interface
 473  */
 474 extern int install_thread_keyring_to_cred(struct cred *cred);
 475 extern void key_fsuid_changed(struct cred *new_cred);
 476 extern void key_fsgid_changed(struct cred *new_cred);
 477 extern void key_init(void);
 478
 479 #else /* CONFIG_KEYS */
 480
 481 #define key_validate(k)                 0
 482 #define key_serial(k)                   0
 483 #define key_get(k)                      ({ NULL; })
 484 #define key_revoke(k)                   do { } while(0)
 485 #define key_invalidate(k)               do { } while(0)
 486 #define key_put(k)                      do { } while(0)
 487 #define key_ref_put(k)                  do { } while(0)
 488 #define make_key_ref(k, p)              NULL
 489 #define key_ref_to_ptr(k)               NULL
 490 #define is_key_possessed(k)             0
 491 #define key_fsuid_changed(c)            do { } while(0)
 492 #define key_fsgid_changed(c)            do { } while(0)
 493 #define key_init()                      do { } while(0)
 494 #define key_free_user_ns(ns)            do { } while(0)
 495 #define key_remove_domain(d)            do { } while(0)
 496
 497 #endif /* CONFIG_KEYS */
 498 #endif /* __KERNEL__ */
 499 #endif /* _LINUX_KEY_H */