p≡p engine
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

219 lines
6.8 KiB

4 years ago
4 years ago
  1. // p≡p Keymanagement API version 0.1
  2. // Copyleft (c) 2019, p≡p foundation
  3. // this file is under GNU General Public License 3.0
  4. // see LICENSE.txt
  5. // written by Volker Birk
  6. protocol session {
  7. method update_identity
  8. doc="update identity information"
  9. {
  10. // parms
  11. supply identity identity
  12. doc="""
  13. identity information of communication partner
  14. (identity->fpr is OUT ONLY), and at least
  15. .address must be set.
  16. If .username is set, it will be used to set or patch
  17. the username record for this identity.
  18. at least identity->address must be a non-empty UTF-8 string as input
  19. update_identity() never writes flags; use set_identity_flags() for
  20. writing
  21. this function NEVER reads the incoming fpr, only writes to it.
  22. this function will fail if called on an identity which, with its input
  23. values, *explicitly* indicates it is an own identity (i.e. .me is set
  24. to true on input, or a user_id is given AND it is a known own user_id).
  25. however, it can RETURN an own identity if this is not indicated a
  26. priori, and in fact will do so with prejudice when not faced with a
  27. matching default (i.e. it is forced to search by address only).
  28. if the identity is known to be an own identity (or the caller wishes
  29. to make it one), call myself() on the identity instead.
  30. FIXME: is this next point accurate?
  31. if this function returns PEP_ct_unknown or PEP_ct_key_expired in
  32. identity->comm_type, the caller must insert the identity into the
  33. asynchronous management implementation, so retrieve_next_identity()
  34. will return this identity later
  36. """
  37. // exceptions
  38. throws illegal_value
  39. doc="""
  40. if called with illegal inputs, including an identity
  41. with .me set or with an own user_id specified in the
  42. *input* (see caveats)
  43. """;
  44. throws key_unsuitable
  45. doc="""
  46. if a default key was found for this identity, no
  47. other acceptable keys were found; if this is returned,
  48. the reason for rejecting the first default key found
  49. may be found in the comm_type
  50. """
  51. }
  52. method initialise_own_identities
  53. doc="ensures that an own identity is complete"
  54. {
  55. // parms
  56. supply identity_list my_idents
  57. doc="""
  58. identities of local user to quick-set
  59. For these, at least .address must be set.
  60. if no .user_id is set, AND the DB doesn't contain
  61. a default user_id, own_userid will be used and
  62. become the perennial default for the DB.
  63. This function does NOT generate keypairs. It is intended to
  64. precede running of the engine on actual messages. It effectively
  65. behaves like myself(), but when there would normally be key generation
  66. (when there is no valid key, for example),
  67. it instead stores an identity without keys.
  68. N.B. to adapter devs - this function is likely unnecessary, so please
  69. do not put work into exposing it yet. Tickets will be filed if need be.
  70. """
  71. }
  72. method myself
  73. doc="ensures that an own identity is complete"
  74. {
  75. // parms
  76. supply identity identity
  77. doc="""
  78. identity of local user
  79. both .address and .user_id must be set.
  80. if .fpr is set, an attempt will be made to make
  81. that the default key for this identity after key validation
  82. if .fpr is not set, key retrieval is performed.
  83. If .username is set, it will be used to set or patch
  84. the username record for this identity.
  85. If an fpr was entered and is not a valid key, the reason for failure
  86. is immediately returned in the status and, possibly, identity->comm_type
  87. If a default own user_id exists in the database, an alias will
  88. be created for the default for the input user_id. The ENGINE'S default
  89. user_id is always returned in the .user_id field
  90. myself() NEVER elects keys from the keyring; it will only choose keys
  91. which have been set up explicitly via myself(), or which were imported
  92. during a first time DB setup from an OpenPGP keyring (compatibility only)
  93. this function generates a keypair on demand; because it's synchronous
  94. it can need a decent amount of time to return
  95. if you need to do this asynchronous, you need to return an identity
  96. with retrieve_next_identity() where identity.me is true.
  97. """
  98. }
  99. method retrieve_next_identity
  100. doc="callback being called by do_keymanagement"
  101. {
  102. // parms
  103. XXXXXX
  104. method examine_identity
  105. doc="callback for appending to queue"
  106. {
  107. // parms
  108. XXXX
  109. method register_examine_function
  110. doc="register examine_identity() callback"
  111. {
  112. //parms
  113. provide?? examine_identity?? examine_identity doc="examine_identity() function to register";
  114. provide void management doc="data structure to deliver (implementation defined)"
  115. XXX?
  116. // do_keymanagement() - function to be run on an extra thread
  117. //
  118. // parameters:
  119. // retrieve_next_identity (in) pointer to retrieve_next_identity()
  120. // callback which returns at least a valid
  121. // address field in the identity struct
  122. //
  123. // return value:
  124. // PEP_STATUS_OK if thread has to terminate successfully or any other
  125. // value on failure
  126. //
  127. // caveat:
  128. // to ensure proper working of this library, a thread has to be started
  129. // with this function immediately after initialization
  130. //
  131. // do_keymanagement() calls retrieve_next_identity(management)
  132. //
  133. // messageToSend can only be null if no transport is application based
  134. // if transport system is not used it must not be NULL
  135. DYNAMIC_API PEP_STATUS do_keymanagement(
  136. retrieve_next_identity_t retrieve_next_identity,
  137. void *management
  138. method key_mistrusted
  139. doc="mark key as being compromised"
  140. {
  141. //parms
  142. use identity ident
  143. doc="""
  144. person and key which was compromised
  145. ident is INPUT ONLY. If you want updated trust on the identity, you'll have
  146. to call update_identity or myself respectively after this.
  147. N.B. If you are calling this on a key that is the identity or user default,
  148. it will be removed as the default key for ANY identity and user for which
  149. it is the default. Please keep in mind that the undo in undo_last_mistrust
  150. will only undo the current identity's / it's user's default, not any
  151. other identities which may be impacted (this will not affect most use
  152. cases)
  153. """
  154. }
  155. method trust_personal_key
  156. doc="mark a key as trusted for a user"
  157. {
  158. // parms
  159. ident (in) person and key to trust in - this must not be an
  160. // own_identity in which the .me flag is set or
  161. // the user_id is an own user_id.
  162. //
  163. // caveat:
  164. // the fields user_id, address and fpr must be supplied
  165. // own identities will result in a return of PEP_ILLEGAL_VALUE.
  166. // for non-own users, this will 1) set the trust bit on its comm type in the DB,
  167. // 2) set this key as the identity default if the current identity default
  168. // is not trusted, and 3) set this key as the user default if the current
  169. // user default is not trusted.
  170. DYNAMIC_API PEP_STATUS trust_personal_key(
  171. PEP_SESSION session,
  172. pEp_identity *ident