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