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 /* key handle permissions mask */ 31 typedef uint32_t key_perm_t; 32 33 struct key; 34 struct net; 35 36 #ifdef CONFIG_KEYS 37 38 #undef KEY_DEBUGGING 39 40 #define KEY_POS_VIEW 0x01000000 /* possessor can view a key's attributes */ 41 #define KEY_POS_READ 0x02000000 /* possessor can read key payload / view keyring */ 42 #define KEY_POS_WRITE 0x04000000 /* possessor can update key payload / add link to keyring */ 43 #define KEY_POS_SEARCH 0x08000000 /* possessor can find a key in search / search a keyring */ 44 #define KEY_POS_LINK 0x10000000 /* possessor can create a link to a key/keyring */ 45 #define KEY_POS_SETATTR 0x20000000 /* possessor can set key attributes */ 46 #define KEY_POS_ALL 0x3f000000 47 48 #define KEY_USR_VIEW 0x00010000 /* user permissions... */ 49 #define KEY_USR_READ 0x00020000 50 #define KEY_USR_WRITE 0x00040000 51 #define KEY_USR_SEARCH 0x00080000 52 #define KEY_USR_LINK 0x00100000 53 #define KEY_USR_SETATTR 0x00200000 54 #define KEY_USR_ALL 0x003f0000 55 56 #define KEY_GRP_VIEW 0x00000100 /* group permissions... */ 57 #define KEY_GRP_READ 0x00000200 58 #define KEY_GRP_WRITE 0x00000400 59 #define KEY_GRP_SEARCH 0x00000800 60 #define KEY_GRP_LINK 0x00001000 61 #define KEY_GRP_SETATTR 0x00002000 62 #define KEY_GRP_ALL 0x00003f00 63 64 #define KEY_OTH_VIEW 0x00000001 /* third party permissions... */ 65 #define KEY_OTH_READ 0x00000002 66 #define KEY_OTH_WRITE 0x00000004 67 #define KEY_OTH_SEARCH 0x00000008 68 #define KEY_OTH_LINK 0x00000010 69 #define KEY_OTH_SETATTR 0x00000020 70 #define KEY_OTH_ALL 0x0000003f 71 72 #define KEY_PERM_UNDEF 0xffffffff 73 74 /* 75 * The permissions required on a key that we're looking up. 76 */ 77 enum key_need_perm { 78 KEY_NEED_UNSPECIFIED, /* Needed permission unspecified */ 79 KEY_NEED_VIEW, /* Require permission to view attributes */ 80 KEY_NEED_READ, /* Require permission to read content */ 81 KEY_NEED_WRITE, /* Require permission to update / modify */ 82 KEY_NEED_SEARCH, /* Require permission to search (keyring) or find (key) */ 83 KEY_NEED_LINK, /* Require permission to link */ 84 KEY_NEED_SETATTR, /* Require permission to change attributes */ 85 KEY_NEED_UNLINK, /* Require permission to unlink key */ 86 KEY_SYSADMIN_OVERRIDE, /* Special: override by CAP_SYS_ADMIN */ 87 KEY_AUTHTOKEN_OVERRIDE, /* Special: override by possession of auth token */ 88 KEY_DEFER_PERM_CHECK, /* Special: permission check is deferred */ 89 }; 90 91 enum key_lookup_flag { 92 KEY_LOOKUP_CREATE = 0x01, 93 KEY_LOOKUP_PARTIAL = 0x02, 94 KEY_LOOKUP_ALL = (KEY_LOOKUP_CREATE | KEY_LOOKUP_PARTIAL), 95 }; 96 97 struct seq_file; 98 struct user_struct; 99 struct signal_struct; 100 struct cred; 101 102 struct key_type; 103 struct key_owner; 104 struct key_tag; 105 struct keyring_list; 106 struct keyring_name; 107 108 struct key_tag { 109 struct rcu_head rcu; 110 atomic64_t index_id; /* Opaque keyring index ID */ 111 refcount_t usage; 112 bool removed; /* T when subject removed */ 113 }; 114 115 struct keyring_index_key { 116 /* [!] If this structure is altered, the union in struct key must change too! */ 117 unsigned long hash; /* Hash value */ 118 union { 119 struct { 120 #ifdef __LITTLE_ENDIAN /* Put desc_len at the LSB of x */ 121 u16 desc_len; 122 char desc[sizeof(long) - 2]; /* First few chars of description */ 123 #else 124 char desc[sizeof(long) - 2]; /* First few chars of description */ 125 u16 desc_len; 126 #endif 127 }; 128 unsigned long x; 129 }; 130 struct key_type *type; 131 struct key_tag *domain_tag; /* Domain of operation */ 132 const char *description; 133 u64 type_id; /* Cached index IDs */ 134 u64 domain_id; 135 }; 136 137 union key_payload { 138 void __rcu *rcu_data0; 139 void *data[4]; 140 }; 141 142 /*****************************************************************************/ 143 /* 144 * key reference with possession attribute handling 145 * 146 * NOTE! key_ref_t is a typedef'd pointer to a type that is not actually 147 * defined. This is because we abuse the bottom bit of the reference to carry a 148 * flag to indicate whether the calling process possesses that key in one of 149 * its keyrings. 150 * 151 * the key_ref_t has been made a separate type so that the compiler can reject 152 * attempts to dereference it without proper conversion. 153 * 154 * the three functions are used to assemble and disassemble references 155 */ 156 typedef struct __key_reference_with_attributes *key_ref_t; 157 158 static inline key_ref_t make_key_ref(const struct key *key, 159 bool possession) 160 { 161 return (key_ref_t) ((unsigned long) key | possession); 162 } 163 164 static inline struct key *key_ref_to_ptr(const key_ref_t key_ref) 165 { 166 return (struct key *) ((unsigned long) key_ref & ~1UL); 167 } 168 169 static inline bool is_key_possessed(const key_ref_t key_ref) 170 { 171 return (unsigned long) key_ref & 1UL; 172 } 173 174 typedef int (*key_restrict_link_func_t)(struct key *dest_keyring, 175 const struct key_type *type, 176 const union key_payload *payload, 177 struct key *restriction_key); 178 179 struct key_restriction { 180 key_restrict_link_func_t check; 181 struct key *key; 182 struct key_type *keytype; 183 }; 184 185 enum key_state { 186 KEY_IS_UNINSTANTIATED, 187 KEY_IS_POSITIVE, /* Positively instantiated */ 188 }; 189 190 /*****************************************************************************/ 191 /* 192 * authentication token / access credential / keyring 193 * - types of key include: 194 * - keyrings 195 * - disk encryption IDs 196 * - Kerberos TGTs and tickets 197 */ 198 struct key { 199 refcount_t usage; /* number of references */ 200 key_serial_t serial; /* key serial number */ 201 union { 202 struct list_head graveyard_link; 203 struct rb_node serial_node; 204 }; 205 #ifdef CONFIG_KEY_NOTIFICATIONS 206 struct watch_list *watchers; /* Entities watching this key for changes */ 207 #endif 208 struct rw_semaphore sem; /* change vs change sem */ 209 struct key_user *user; /* owner of this key */ 210 void *security; /* security data for this key */ 211 union { 212 time64_t expiry; /* time at which key expires (or 0) */ 213 time64_t revoked_at; /* time at which key was revoked */ 214 }; 215 time64_t last_used_at; /* last time used for LRU keyring discard */ 216 kuid_t uid; 217 kgid_t gid; 218 key_perm_t perm; /* access permissions */ 219 unsigned short quotalen; /* length added to quota */ 220 unsigned short datalen; /* payload data length 221 * - may not match RCU dereferenced payload 222 * - payload should contain own length 223 */ 224 short state; /* Key state (+) or rejection error (-) */ 225 226 #ifdef KEY_DEBUGGING 227 unsigned magic; 228 #define KEY_DEBUG_MAGIC 0x18273645u 229 #endif 230 231 unsigned long flags; /* status flags (change with bitops) */ 232 #define KEY_FLAG_DEAD 0 /* set if key type has been deleted */ 233 #define KEY_FLAG_REVOKED 1 /* set if key had been revoked */ 234 #define KEY_FLAG_IN_QUOTA 2 /* set if key consumes quota */ 235 #define KEY_FLAG_USER_CONSTRUCT 3 /* set if key is being constructed in userspace */ 236 #define KEY_FLAG_ROOT_CAN_CLEAR 4 /* set if key can be cleared by root without permission */ 237 #define KEY_FLAG_INVALIDATED 5 /* set if key has been invalidated */ 238 #define KEY_FLAG_BUILTIN 6 /* set if key is built in to the kernel */ 239 #define KEY_FLAG_ROOT_CAN_INVAL 7 /* set if key can be invalidated by root without permission */ 240 #define KEY_FLAG_KEEP 8 /* set if key should not be removed */ 241 #define KEY_FLAG_UID_KEYRING 9 /* set if key is a user or user session keyring */ 242 #define KEY_FLAG_USER_ALIVE 10 /* set if final put has not happened on key yet */ 243 244 /* the key type and key description string 245 * - the desc is used to match a key against search criteria 246 * - it should be a printable string 247 * - eg: for krb5 AFS, this might be "afs@REDHAT.COM" 248 */ 249 union { 250 struct keyring_index_key index_key; 251 struct { 252 unsigned long hash; 253 unsigned long len_desc; 254 struct key_type *type; /* type of key */ 255 struct key_tag *domain_tag; /* Domain of operation */ 256 char *description; 257 u64 type_id; 258 u64 domain_id; 259 }; 260 }; 261 262 /* key data 263 * - this is used to hold the data actually used in cryptography or 264 * whatever 265 */ 266 union { 267 union key_payload payload; 268 struct { 269 /* Keyring bits */ 270 struct list_head name_link; 271 struct assoc_array keys; 272 }; 273 }; 274 275 /* This is set on a keyring to restrict the addition of a link to a key 276 * to it. If this structure isn't provided then it is assumed that the 277 * keyring is open to any addition. It is ignored for non-keyring 278 * keys. Only set this value using keyring_restrict(), keyring_alloc(), 279 * or key_alloc(). 280 * 281 * This is intended for use with rings of trusted keys whereby addition 282 * to the keyring needs to be controlled. KEY_ALLOC_BYPASS_RESTRICTION 283 * overrides this, allowing the kernel to add extra keys without 284 * restriction. 285 */ 286 struct key_restriction *restrict_link; 287 }; 288 289 extern struct key *key_alloc(struct key_type *type, 290 const char *desc, 291 kuid_t uid, kgid_t gid, 292 const struct cred *cred, 293 key_perm_t perm, 294 unsigned long flags, 295 struct key_restriction *restrict_link); 296 297 298 #define KEY_ALLOC_IN_QUOTA 0x0000 /* add to quota, reject if would overrun */ 299 #define KEY_ALLOC_QUOTA_OVERRUN 0x0001 /* add to quota, permit even if overrun */ 300 #define KEY_ALLOC_NOT_IN_QUOTA 0x0002 /* not in quota */ 301 #define KEY_ALLOC_BUILT_IN 0x0004 /* Key is built into kernel */ 302 #define KEY_ALLOC_BYPASS_RESTRICTION 0x0008 /* Override the check on restricted keyrings */ 303 #define KEY_ALLOC_UID_KEYRING 0x0010 /* allocating a user or user session keyring */ 304 #define KEY_ALLOC_SET_KEEP 0x0020 /* Set the KEEP flag on the key/keyring */ 305 306 extern void key_revoke(struct key *key); 307 extern void key_invalidate(struct key *key); 308 extern void key_put(struct key *key); 309 extern bool key_put_tag(struct key_tag *tag); 310 extern void key_remove_domain(struct key_tag *domain_tag); 311 312 static inline struct key *__key_get(struct key *key) 313 { 314 refcount_inc(&key->usage); 315 return key; 316 } 317 318 static inline struct key *key_get(struct key *key) 319 { 320 return key ? __key_get(key) : key; 321 } 322 323 static inline void key_ref_put(key_ref_t key_ref) 324 { 325 key_put(key_ref_to_ptr(key_ref)); 326 } 327 328 extern struct key *request_key_tag(struct key_type *type, 329 const char *description, 330 struct key_tag *domain_tag, 331 const char *callout_info); 332 333 extern struct key *request_key_rcu(struct key_type *type, 334 const char *description, 335 struct key_tag *domain_tag); 336 337 extern struct key *request_key_with_auxdata(struct key_type *type, 338 const char *description, 339 struct key_tag *domain_tag, 340 const void *callout_info, 341 size_t callout_len, 342 void *aux); 343 344 /** 345 * request_key - Request a key and wait for construction 346 * @type: Type of key. 347 * @description: The searchable description of the key. 348 * @callout_info: The data to pass to the instantiation upcall (or NULL). 349 * 350 * As for request_key_tag(), but with the default global domain tag. 351 */ 352 static inline struct key *request_key(struct key_type *type, 353 const char *description, 354 const char *callout_info) 355 { 356 return request_key_tag(type, description, NULL, callout_info); 357 } 358 359 #ifdef CONFIG_NET 360 /** 361 * request_key_net - Request a key for a net namespace and wait for construction 362 * @type: Type of key. 363 * @description: The searchable description of the key. 364 * @net: The network namespace that is the key's domain of operation. 365 * @callout_info: The data to pass to the instantiation upcall (or NULL). 366 * 367 * As for request_key() except that it does not add the returned key to a 368 * keyring if found, new keys are always allocated in the user's quota, the 369 * callout_info must be a NUL-terminated string and no auxiliary data can be 370 * passed. Only keys that operate the specified network namespace are used. 371 * 372 * Furthermore, it then works as wait_for_key_construction() to wait for the 373 * completion of keys undergoing construction with a non-interruptible wait. 374 */ 375 #define request_key_net(type, description, net, callout_info) \ 376 request_key_tag(type, description, net->key_domain, callout_info) 377 378 /** 379 * request_key_net_rcu - Request a key for a net namespace under RCU conditions 380 * @type: Type of key. 381 * @description: The searchable description of the key. 382 * @net: The network namespace that is the key's domain of operation. 383 * 384 * As for request_key_rcu() except that only keys that operate the specified 385 * network namespace are used. 386 */ 387 #define request_key_net_rcu(type, description, net) \ 388 request_key_rcu(type, description, net->key_domain) 389 #endif /* CONFIG_NET */ 390 391 extern int wait_for_key_construction(struct key *key, bool intr); 392 393 extern int key_validate(const struct key *key); 394 395 extern key_ref_t key_create(key_ref_t keyring, 396 const char *type, 397 const char *description, 398 const void *payload, 399 size_t plen, 400 key_perm_t perm, 401 unsigned long flags); 402 403 extern key_ref_t key_create_or_update(key_ref_t keyring, 404 const char *type, 405 const char *description, 406 const void *payload, 407 size_t plen, 408 key_perm_t perm, 409 unsigned long flags); 410 411 extern int key_update(key_ref_t key, 412 const void *payload, 413 size_t plen); 414 415 extern int key_link(struct key *keyring, 416 struct key *key); 417 418 extern int key_move(struct key *key, 419 struct key *from_keyring, 420 struct key *to_keyring, 421 unsigned int flags); 422 423 extern int key_unlink(struct key *keyring, 424 struct key *key); 425 426 extern struct key *keyring_alloc(const char *description, kuid_t uid, kgid_t gid, 427 const struct cred *cred, 428 key_perm_t perm, 429 unsigned long flags, 430 struct key_restriction *restrict_link, 431 struct key *dest); 432 433 extern int restrict_link_reject(struct key *keyring, 434 const struct key_type *type, 435 const union key_payload *payload, 436 struct key *restriction_key); 437 438 extern int keyring_clear(struct key *keyring); 439 440 extern key_ref_t keyring_search(key_ref_t keyring, 441 struct key_type *type, 442 const char *description, 443 bool recurse); 444 445 extern int keyring_restrict(key_ref_t keyring, const char *type, 446 const char *restriction); 447 448 extern struct key *key_lookup(key_serial_t id); 449 450 static inline key_serial_t key_serial(const struct key *key) 451 { 452 return key ? key->serial : 0; 453 } 454 455 extern void key_set_timeout(struct key *, unsigned); 456 457 extern key_ref_t lookup_user_key(key_serial_t id, unsigned long flags, 458 enum key_need_perm need_perm); 459 extern void key_free_user_ns(struct user_namespace *); 460 461 static inline short key_read_state(const struct key *key) 462 { 463 /* Barrier versus mark_key_instantiated(). */ 464 return smp_load_acquire(&key->state); 465 } 466 467 /** 468 * key_is_positive - Determine if a key has been positively instantiated 469 * @key: The key to check. 470 * 471 * Return true if the specified key has been positively instantiated, false 472 * otherwise. 473 */ 474 static inline bool key_is_positive(const struct key *key) 475 { 476 return key_read_state(key) == KEY_IS_POSITIVE; 477 } 478 479 static inline bool key_is_negative(const struct key *key) 480 { 481 return key_read_state(key) < 0; 482 } 483 484 #define dereference_key_rcu(KEY) \ 485 (rcu_dereference((KEY)->payload.rcu_data0)) 486 487 #define dereference_key_locked(KEY) \ 488 (rcu_dereference_protected((KEY)->payload.rcu_data0, \ 489 rwsem_is_locked(&((struct key *)(KEY))->sem))) 490 491 #define rcu_assign_keypointer(KEY, PAYLOAD) \ 492 do { \ 493 rcu_assign_pointer((KEY)->payload.rcu_data0, (PAYLOAD)); \ 494 } while (0) 495 496 /* 497 * the userspace interface 498 */ 499 extern int install_thread_keyring_to_cred(struct cred *cred); 500 extern void key_fsuid_changed(struct cred *new_cred); 501 extern void key_fsgid_changed(struct cred *new_cred); 502 extern void key_init(void); 503 504 #else /* CONFIG_KEYS */ 505 506 #define key_validate(k) 0 507 #define key_serial(k) 0 508 #define key_get(k) ({ NULL; }) 509 #define key_revoke(k) do { } while(0) 510 #define key_invalidate(k) do { } while(0) 511 #define key_put(k) do { } while(0) 512 #define key_ref_put(k) do { } while(0) 513 #define make_key_ref(k, p) NULL 514 #define key_ref_to_ptr(k) NULL 515 #define is_key_possessed(k) 0 516 #define key_fsuid_changed(c) do { } while(0) 517 #define key_fsgid_changed(c) do { } while(0) 518 #define key_init() do { } while(0) 519 #define key_free_user_ns(ns) do { } while(0) 520 #define key_remove_domain(d) do { } while(0) 521 #define key_lookup(k) NULL 522 523 #endif /* CONFIG_KEYS */ 524 #endif /* __KERNEL__ */ 525 #endif /* _LINUX_KEY_H */ 526