key-type.h 5.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157
  1. /* Definitions for key type implementations
  2. *
  3. * Copyright (C) 2007 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 Licence
  8. * as published by the Free Software Foundation; either version
  9. * 2 of the Licence, or (at your option) any later version.
  10. */
  11. #ifndef _LINUX_KEY_TYPE_H
  12. #define _LINUX_KEY_TYPE_H
  13. #include <linux/key.h>
  14. #include <linux/errno.h>
  15. #ifdef CONFIG_KEYS
  16. /*
  17. * key under-construction record
  18. * - passed to the request_key actor if supplied
  19. */
  20. struct key_construction {
  21. struct key *key; /* key being constructed */
  22. struct key *authkey;/* authorisation for key being constructed */
  23. };
  24. /*
  25. * Pre-parsed payload, used by key add, update and instantiate.
  26. *
  27. * This struct will be cleared and data and datalen will be set with the data
  28. * and length parameters from the caller and quotalen will be set from
  29. * def_datalen from the key type. Then if the preparse() op is provided by the
  30. * key type, that will be called. Then the struct will be passed to the
  31. * instantiate() or the update() op.
  32. *
  33. * If the preparse() op is given, the free_preparse() op will be called to
  34. * clear the contents.
  35. */
  36. struct key_preparsed_payload {
  37. char *description; /* Proposed key description (or NULL) */
  38. void *type_data[2]; /* Private key-type data */
  39. void *payload; /* Proposed payload */
  40. const void *data; /* Raw data */
  41. size_t datalen; /* Raw datalen */
  42. size_t quotalen; /* Quota length for proposed payload */
  43. };
  44. typedef int (*request_key_actor_t)(struct key_construction *key,
  45. const char *op, void *aux);
  46. /*
  47. * kernel managed key type definition
  48. */
  49. struct key_type {
  50. /* name of the type */
  51. const char *name;
  52. /* default payload length for quota precalculation (optional)
  53. * - this can be used instead of calling key_payload_reserve(), that
  54. * function only needs to be called if the real datalen is different
  55. */
  56. size_t def_datalen;
  57. /* vet a description */
  58. int (*vet_description)(const char *description);
  59. /* Preparse the data blob from userspace that is to be the payload,
  60. * generating a proposed description and payload that will be handed to
  61. * the instantiate() and update() ops.
  62. */
  63. int (*preparse)(struct key_preparsed_payload *prep);
  64. /* Free a preparse data structure.
  65. */
  66. void (*free_preparse)(struct key_preparsed_payload *prep);
  67. /* instantiate a key of this type
  68. * - this method should call key_payload_reserve() to determine if the
  69. * user's quota will hold the payload
  70. */
  71. int (*instantiate)(struct key *key, struct key_preparsed_payload *prep);
  72. /* update a key of this type (optional)
  73. * - this method should call key_payload_reserve() to recalculate the
  74. * quota consumption
  75. * - the key must be locked against read when modifying
  76. */
  77. int (*update)(struct key *key, struct key_preparsed_payload *prep);
  78. /* match a key against a description */
  79. int (*match)(const struct key *key, const void *desc);
  80. /* clear some of the data from a key on revokation (optional)
  81. * - the key's semaphore will be write-locked by the caller
  82. */
  83. void (*revoke)(struct key *key);
  84. /* clear the data from a key (optional) */
  85. void (*destroy)(struct key *key);
  86. /* describe a key */
  87. void (*describe)(const struct key *key, struct seq_file *p);
  88. /* read a key's data (optional)
  89. * - permission checks will be done by the caller
  90. * - the key's semaphore will be readlocked by the caller
  91. * - should return the amount of data that could be read, no matter how
  92. * much is copied into the buffer
  93. * - shouldn't do the copy if the buffer is NULL
  94. */
  95. long (*read)(const struct key *key, char __user *buffer, size_t buflen);
  96. /* handle request_key() for this type instead of invoking
  97. * /sbin/request-key (optional)
  98. * - key is the key to instantiate
  99. * - authkey is the authority to assume when instantiating this key
  100. * - op is the operation to be done, usually "create"
  101. * - the call must not return until the instantiation process has run
  102. * its course
  103. */
  104. request_key_actor_t request_key;
  105. /* internal fields */
  106. struct list_head link; /* link in types list */
  107. struct lock_class_key lock_class; /* key->sem lock class */
  108. };
  109. extern struct key_type key_type_keyring;
  110. extern int register_key_type(struct key_type *ktype);
  111. extern void unregister_key_type(struct key_type *ktype);
  112. extern int key_payload_reserve(struct key *key, size_t datalen);
  113. extern int key_instantiate_and_link(struct key *key,
  114. const void *data,
  115. size_t datalen,
  116. struct key *keyring,
  117. struct key *instkey);
  118. extern int key_reject_and_link(struct key *key,
  119. unsigned timeout,
  120. unsigned error,
  121. struct key *keyring,
  122. struct key *instkey);
  123. extern void complete_request_key(struct key_construction *cons, int error);
  124. static inline int key_negate_and_link(struct key *key,
  125. unsigned timeout,
  126. struct key *keyring,
  127. struct key *instkey)
  128. {
  129. return key_reject_and_link(key, timeout, ENOKEY, keyring, instkey);
  130. }
  131. #endif /* CONFIG_KEYS */
  132. #endif /* _LINUX_KEY_TYPE_H */