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