home *** CD-ROM | disk | FTP | other *** search
/ PC Welt 2006 November (DVD) / PCWELT_11_2006.ISO / casper / filesystem.squashfs / usr / src / linux-headers-2.6.17-6 / include / linux / key.h < prev    next >
Encoding:
C/C++ Source or Header  |  2006-08-11  |  11.1 KB  |  361 lines
  1. /* key.h: authentication token and access key management
  2.  *
  3.  * Copyright (C) 2004 Red Hat, Inc. All Rights Reserved.
  4.  * Written by David Howells (dhowells@redhat.com)
  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/keys.txt 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 <asm/atomic.h>
  23.  
  24. #ifdef __KERNEL__
  25.  
  26. /* key handle serial number */
  27. typedef int32_t key_serial_t;
  28.  
  29. /* key handle permissions mask */
  30. typedef uint32_t key_perm_t;
  31.  
  32. struct key;
  33.  
  34. #ifdef CONFIG_KEYS
  35.  
  36. #undef KEY_DEBUGGING
  37.  
  38. #define KEY_POS_VIEW    0x01000000    /* possessor can view a key's attributes */
  39. #define KEY_POS_READ    0x02000000    /* possessor can read key payload / view keyring */
  40. #define KEY_POS_WRITE    0x04000000    /* possessor can update key payload / add link to keyring */
  41. #define KEY_POS_SEARCH    0x08000000    /* possessor can find a key in search / search a keyring */
  42. #define KEY_POS_LINK    0x10000000    /* possessor can create a link to a key/keyring */
  43. #define KEY_POS_SETATTR    0x20000000    /* possessor can set key attributes */
  44. #define KEY_POS_ALL    0x3f000000
  45.  
  46. #define KEY_USR_VIEW    0x00010000    /* user permissions... */
  47. #define KEY_USR_READ    0x00020000
  48. #define KEY_USR_WRITE    0x00040000
  49. #define KEY_USR_SEARCH    0x00080000
  50. #define KEY_USR_LINK    0x00100000
  51. #define KEY_USR_SETATTR    0x00200000
  52. #define KEY_USR_ALL    0x003f0000
  53.  
  54. #define KEY_GRP_VIEW    0x00000100    /* group permissions... */
  55. #define KEY_GRP_READ    0x00000200
  56. #define KEY_GRP_WRITE    0x00000400
  57. #define KEY_GRP_SEARCH    0x00000800
  58. #define KEY_GRP_LINK    0x00001000
  59. #define KEY_GRP_SETATTR    0x00002000
  60. #define KEY_GRP_ALL    0x00003f00
  61.  
  62. #define KEY_OTH_VIEW    0x00000001    /* third party permissions... */
  63. #define KEY_OTH_READ    0x00000002
  64. #define KEY_OTH_WRITE    0x00000004
  65. #define KEY_OTH_SEARCH    0x00000008
  66. #define KEY_OTH_LINK    0x00000010
  67. #define KEY_OTH_SETATTR    0x00000020
  68. #define KEY_OTH_ALL    0x0000003f
  69.  
  70. struct seq_file;
  71. struct user_struct;
  72. struct signal_struct;
  73.  
  74. struct key_type;
  75. struct key_owner;
  76. struct keyring_list;
  77. struct keyring_name;
  78.  
  79. /*****************************************************************************/
  80. /*
  81.  * key reference with possession attribute handling
  82.  *
  83.  * NOTE! key_ref_t is a typedef'd pointer to a type that is not actually
  84.  * defined. This is because we abuse the bottom bit of the reference to carry a
  85.  * flag to indicate whether the calling process possesses that key in one of
  86.  * its keyrings.
  87.  *
  88.  * the key_ref_t has been made a separate type so that the compiler can reject
  89.  * attempts to dereference it without proper conversion.
  90.  *
  91.  * the three functions are used to assemble and disassemble references
  92.  */
  93. typedef struct __key_reference_with_attributes *key_ref_t;
  94.  
  95. static inline key_ref_t make_key_ref(const struct key *key,
  96.                      unsigned long possession)
  97. {
  98.     return (key_ref_t) ((unsigned long) key | possession);
  99. }
  100.  
  101. static inline struct key *key_ref_to_ptr(const key_ref_t key_ref)
  102. {
  103.     return (struct key *) ((unsigned long) key_ref & ~1UL);
  104. }
  105.  
  106. static inline unsigned long is_key_possessed(const key_ref_t key_ref)
  107. {
  108.     return (unsigned long) key_ref & 1UL;
  109. }
  110.  
  111. /*****************************************************************************/
  112. /*
  113.  * authentication token / access credential / keyring
  114.  * - types of key include:
  115.  *   - keyrings
  116.  *   - disk encryption IDs
  117.  *   - Kerberos TGTs and tickets
  118.  */
  119. struct key {
  120.     atomic_t        usage;        /* number of references */
  121.     key_serial_t        serial;        /* key serial number */
  122.     struct rb_node        serial_node;
  123.     struct key_type        *type;        /* type of key */
  124.     struct rw_semaphore    sem;        /* change vs change sem */
  125.     struct key_user        *user;        /* owner of this key */
  126.     void            *security;    /* security data for this key */
  127.     time_t            expiry;        /* time at which key expires (or 0) */
  128.     uid_t            uid;
  129.     gid_t            gid;
  130.     key_perm_t        perm;        /* access permissions */
  131.     unsigned short        quotalen;    /* length added to quota */
  132.     unsigned short        datalen;    /* payload data length
  133.                          * - may not match RCU dereferenced payload
  134.                          * - payload should contain own length
  135.                          */
  136.  
  137. #ifdef KEY_DEBUGGING
  138.     unsigned        magic;
  139. #define KEY_DEBUG_MAGIC        0x18273645u
  140. #define KEY_DEBUG_MAGIC_X    0xf8e9dacbu
  141. #endif
  142.  
  143.     unsigned long        flags;        /* status flags (change with bitops) */
  144. #define KEY_FLAG_INSTANTIATED    0    /* set if key has been instantiated */
  145. #define KEY_FLAG_DEAD        1    /* set if key type has been deleted */
  146. #define KEY_FLAG_REVOKED    2    /* set if key had been revoked */
  147. #define KEY_FLAG_IN_QUOTA    3    /* set if key consumes quota */
  148. #define KEY_FLAG_USER_CONSTRUCT    4    /* set if key is being constructed in userspace */
  149. #define KEY_FLAG_NEGATIVE    5    /* set if key is negative */
  150.  
  151.     /* the description string
  152.      * - this is used to match a key against search criteria
  153.      * - this should be a printable string
  154.      * - eg: for krb5 AFS, this might be "afs@REDHAT.COM"
  155.      */
  156.     char            *description;
  157.  
  158.     /* type specific data
  159.      * - this is used by the keyring type to index the name
  160.      */
  161.     union {
  162.         struct list_head    link;
  163.     } type_data;
  164.  
  165.     /* key data
  166.      * - this is used to hold the data actually used in cryptography or
  167.      *   whatever
  168.      */
  169.     union {
  170.         unsigned long        value;
  171.         void            *data;
  172.         struct keyring_list    *subscriptions;
  173.     } payload;
  174. };
  175.  
  176. /*****************************************************************************/
  177. /*
  178.  * kernel managed key type definition
  179.  */
  180. typedef int (*request_key_actor_t)(struct key *key, struct key *authkey, const char *op);
  181.  
  182. struct key_type {
  183.     /* name of the type */
  184.     const char *name;
  185.  
  186.     /* default payload length for quota precalculation (optional)
  187.      * - this can be used instead of calling key_payload_reserve(), that
  188.      *   function only needs to be called if the real datalen is different
  189.      */
  190.     size_t def_datalen;
  191.  
  192.     /* instantiate a key of this type
  193.      * - this method should call key_payload_reserve() to determine if the
  194.      *   user's quota will hold the payload
  195.      */
  196.     int (*instantiate)(struct key *key, const void *data, size_t datalen);
  197.  
  198.     /* update a key of this type (optional)
  199.      * - this method should call key_payload_reserve() to recalculate the
  200.      *   quota consumption
  201.      * - the key must be locked against read when modifying
  202.      */
  203.     int (*update)(struct key *key, const void *data, size_t datalen);
  204.  
  205.     /* match a key against a description */
  206.     int (*match)(const struct key *key, const void *desc);
  207.  
  208.     /* clear the data from a key (optional) */
  209.     void (*destroy)(struct key *key);
  210.  
  211.     /* describe a key */
  212.     void (*describe)(const struct key *key, struct seq_file *p);
  213.  
  214.     /* read a key's data (optional)
  215.      * - permission checks will be done by the caller
  216.      * - the key's semaphore will be readlocked by the caller
  217.      * - should return the amount of data that could be read, no matter how
  218.      *   much is copied into the buffer
  219.      * - shouldn't do the copy if the buffer is NULL
  220.      */
  221.     long (*read)(const struct key *key, char __user *buffer, size_t buflen);
  222.  
  223.     /* handle request_key() for this type instead of invoking
  224.      * /sbin/request-key (optional)
  225.      * - key is the key to instantiate
  226.      * - authkey is the authority to assume when instantiating this key
  227.      * - op is the operation to be done, usually "create"
  228.      * - the call must not return until the instantiation process has run
  229.      *   its course
  230.      */
  231.     request_key_actor_t request_key;
  232.  
  233.     /* internal fields */
  234.     struct list_head    link;        /* link in types list */
  235. };
  236.  
  237. extern struct key_type key_type_keyring;
  238.  
  239. extern int register_key_type(struct key_type *ktype);
  240. extern void unregister_key_type(struct key_type *ktype);
  241.  
  242. extern struct key *key_alloc(struct key_type *type,
  243.                  const char *desc,
  244.                  uid_t uid, gid_t gid, key_perm_t perm,
  245.                  int not_in_quota);
  246. extern int key_payload_reserve(struct key *key, size_t datalen);
  247. extern int key_instantiate_and_link(struct key *key,
  248.                     const void *data,
  249.                     size_t datalen,
  250.                     struct key *keyring,
  251.                     struct key *instkey);
  252. extern int key_negate_and_link(struct key *key,
  253.                    unsigned timeout,
  254.                    struct key *keyring,
  255.                    struct key *instkey);
  256. extern void key_revoke(struct key *key);
  257. extern void key_put(struct key *key);
  258.  
  259. static inline struct key *key_get(struct key *key)
  260. {
  261.     if (key)
  262.         atomic_inc(&key->usage);
  263.     return key;
  264. }
  265.  
  266. static inline void key_ref_put(key_ref_t key_ref)
  267. {
  268.     key_put(key_ref_to_ptr(key_ref));
  269. }
  270.  
  271. extern struct key *request_key(struct key_type *type,
  272.                    const char *description,
  273.                    const char *callout_info);
  274.  
  275. extern int key_validate(struct key *key);
  276.  
  277. extern key_ref_t key_create_or_update(key_ref_t keyring,
  278.                       const char *type,
  279.                       const char *description,
  280.                       const void *payload,
  281.                       size_t plen,
  282.                       int not_in_quota);
  283.  
  284. extern int key_update(key_ref_t key,
  285.               const void *payload,
  286.               size_t plen);
  287.  
  288. extern int key_link(struct key *keyring,
  289.             struct key *key);
  290.  
  291. extern int key_unlink(struct key *keyring,
  292.               struct key *key);
  293.  
  294. extern struct key *keyring_alloc(const char *description, uid_t uid, gid_t gid,
  295.                  int not_in_quota, struct key *dest);
  296.  
  297. extern int keyring_clear(struct key *keyring);
  298.  
  299. extern key_ref_t keyring_search(key_ref_t keyring,
  300.                 struct key_type *type,
  301.                 const char *description);
  302.  
  303. extern int keyring_add_key(struct key *keyring,
  304.                struct key *key);
  305.  
  306. extern struct key *key_lookup(key_serial_t id);
  307.  
  308. extern void keyring_replace_payload(struct key *key, void *replacement);
  309.  
  310. #define key_serial(key) ((key) ? (key)->serial : 0)
  311.  
  312. /*
  313.  * the userspace interface
  314.  */
  315. extern struct key root_user_keyring, root_session_keyring;
  316. extern int alloc_uid_keyring(struct user_struct *user);
  317. extern void switch_uid_keyring(struct user_struct *new_user);
  318. extern int copy_keys(unsigned long clone_flags, struct task_struct *tsk);
  319. extern int copy_thread_group_keys(struct task_struct *tsk);
  320. extern void exit_keys(struct task_struct *tsk);
  321. extern void exit_thread_group_keys(struct signal_struct *tg);
  322. extern int suid_keys(struct task_struct *tsk);
  323. extern int exec_keys(struct task_struct *tsk);
  324. extern void key_fsuid_changed(struct task_struct *tsk);
  325. extern void key_fsgid_changed(struct task_struct *tsk);
  326. extern void key_init(void);
  327.  
  328. #define __install_session_keyring(tsk, keyring)            \
  329. ({                                \
  330.     struct key *old_session = tsk->signal->session_keyring;    \
  331.     tsk->signal->session_keyring = keyring;            \
  332.     old_session;                        \
  333. })
  334.  
  335. #else /* CONFIG_KEYS */
  336.  
  337. #define key_validate(k)            0
  338. #define key_serial(k)            0
  339. #define key_get(k)             ({ NULL; })
  340. #define key_put(k)            do { } while(0)
  341. #define key_ref_put(k)            do { } while(0)
  342. #define make_key_ref(k)            ({ NULL; })
  343. #define key_ref_to_ptr(k)        ({ NULL; })
  344. #define is_key_possessed(k)        0
  345. #define alloc_uid_keyring(u)        0
  346. #define switch_uid_keyring(u)        do { } while(0)
  347. #define __install_session_keyring(t, k)    ({ NULL; })
  348. #define copy_keys(f,t)            0
  349. #define copy_thread_group_keys(t)    0
  350. #define exit_keys(t)            do { } while(0)
  351. #define exit_thread_group_keys(tg)    do { } while(0)
  352. #define suid_keys(t)            do { } while(0)
  353. #define exec_keys(t)            do { } while(0)
  354. #define key_fsuid_changed(t)        do { } while(0)
  355. #define key_fsgid_changed(t)        do { } while(0)
  356. #define key_init()            do { } while(0)
  357.  
  358. #endif /* CONFIG_KEYS */
  359. #endif /* __KERNEL__ */
  360. #endif /* _LINUX_KEY_H */
  361.