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.

289 lines
10 KiB

3 years ago
3 years ago
2 years ago
2 years ago
4 months ago
3 years ago
2 years ago
3 years ago
2 years ago
4 months ago
2 years ago
3 years ago
2 years ago
3 years ago
2 years ago
3 years ago
2 years ago
3 years ago
2 years ago
4 months ago
2 years ago
3 years ago
2 years ago
3 years ago
2 years ago
4 months ago
2 years ago
3 years ago
2 years ago
3 years ago
2 years ago
4 months ago
3 years ago
2 years ago
3 years ago
2 years ago
3 years ago
2 years ago
3 years ago
2 years ago
4 months ago
3 years ago
2 years ago
3 years ago
2 years ago
3 years ago
2 years ago
4 months ago
3 years ago
2 years ago
3 years ago
2 years ago
3 years ago
2 years ago
3 years ago
2 years ago
4 months ago
3 years ago
2 years ago
3 years ago
2 years ago
3 years ago
2 years ago
4 months ago
2 years ago
4 months ago
3 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 Nana Karlstetter and Volker Birk
  6. protocol session {
  7. method update_identity doc="update identity information"
  8. {
  9. // parms
  10. lend identity identity
  11. doc="""
  12. identity information of communication partner
  13. (identity->fpr is OUT ONLY), and at least
  14. .address must be set.
  15. If .username is set, it will be used to set or patch
  16. the username record for this identity.
  17. at least identity->address must be a non-empty UTF-8 string as input
  18. update_identity() never writes flags; use set_identity_flags() for
  19. writing
  20. this function NEVER reads the incoming fpr, only writes to it.
  21. this function will fail if called on an identity which, with its input
  22. values, *explicitly* indicates it is an own identity (i.e. .me is set
  23. to true on input, or a user_id is given AND it is a known own user_id).
  24. however, it can RETURN an own identity if this is not indicated a
  25. priori, and in fact will do so with prejudice when not faced with a
  26. matching default (i.e. it is forced to search by address only).
  27. if the identity is known to be an own identity (or the caller wishes
  28. to make it one), call myself() on the identity instead.
  29. FIXME: is this next point accurate?
  30. if this function returns PEP_ct_unknown or PEP_ct_key_expired in
  31. identity->comm_type, the caller must insert the identity into the
  32. asynchronous management implementation, so retrieve_next_identity()
  33. will return this identity later
  34. END FIXME
  35. """;
  36. // exceptions
  37. throws illegal_value
  38. doc="""
  39. if called with illegal inputs, including an identity
  40. with .me set or with an own user_id specified in the
  41. *input* (see caveats)
  42. """;
  43. throws any doc="any other value on error";
  44. }
  45. method myself doc="ensures that an own identity is complete"
  46. {
  47. // parms
  48. lend identity ident
  49. doc="""
  50. identity of local user
  51. both .address and .user_id must be set.
  52. if .fpr is set, an attempt will be made to make
  53. that the default key for this identity after key validation
  54. if .fpr is not set, key retrieval is performed.
  55. If .username is set, it will be used to set or patch
  56. the username record for this identity.
  57. If an fpr was entered and is not a valid key, the reason for failure
  58. is immediately returned in the status and, possibly, identity->comm_type
  59. If a default own user_id exists in the database, an alias will
  60. be created for the default for the input user_id. The ENGINE'S default
  61. user_id is always returned in the .user_id field
  62. myself() NEVER elects keys from the keyring; it will only choose keys
  63. which have been set up explicitly via myself(), or which were imported
  64. during a first time DB setup from an OpenPGP keyring (compatibility only)
  65. this function generates a keypair on demand; because it's synchronous
  66. it can need a decent amount of time to return
  67. if you need to do this asynchronous, you need to return an identity
  68. with retrieve_next_identity() where identity.me is true.
  69. """;
  70. // exceptions
  71. throws illegal_value doc="illegal parameter values";
  72. throws out_of_memory doc="out of memory";
  73. throws any doc="any other value on error";
  74. }
  75. method key_mistrusted doc="mark key as being compromised"
  76. {
  77. //parms
  78. use identity ident
  79. doc="""
  80. person and key which was compromised
  81. ident is INPUT ONLY. If you want updated trust on the identity, you'll have
  82. to call update_identity or myself respectively after this.
  83. N.B. If you are calling this on a key that is the identity or user default,
  84. it will be removed as the default key for ANY identity and user for which
  85. it is the default. Please keep in mind that the undo in undo_last_mistrust
  86. will only undo the current identity's / it's user's default, not any
  87. other identities which may be impacted (this will not affect most use
  88. cases)
  89. """;
  90. }
  91. method trust_personal_key doc="mark a key as trusted for a user"
  92. {
  93. // parms
  94. use identity ident
  95. doc="""
  96. person and key to trust in - this must not be an own_identity in which
  97. the .me flag is set or the user_id is an own user_id. The fields user_id,
  98. address and fpr must be supplied own identities will result in a return
  99. of illegal_value.
  100. For non-own users, this will 1) set the trust bit on its comm type in the DB,
  101. 2) set this key as the identity default if the current identity default
  102. is not trusted, and 3) set this key as the user default if the current user
  103. default is not trusted.
  104. """;
  105. // exceptions
  106. throws key_unsuitable;
  107. throws illegal_value doc="illegal parameter values";
  108. throws out_of_memory doc="out of memory";
  109. throws any doc="any other value on error";
  110. }
  111. method trust_own_key
  112. doc="""
  113. mark a key as trusted for self, generally used when we need to trust
  114. a public key associated with outselves for issues like manual key import.
  115. """
  116. {
  117. // parms
  118. use identity ident
  119. doc="""
  120. own ident containing fpr to trust.
  121. If this is a public key only, keep in mind that if the private part of the
  122. keypair is later added, it will not undergo separate trust evaluation. This
  123. is fine - even desired - as long as the semantics of this function are
  124. understood as both trusting the key and verifying it as an own key. This will
  125. NEVER cause replacement of or setting of a default *alone*. However, if a
  126. private key is ever associated with this fpr, please keep in mind that trusting
  127. it here makes it an eligible key for selection for encryption later. So use
  128. this function on purpose with an understanding of what you're doing!
  129. """;
  130. // exceptions
  131. throws key_unsuitable;
  132. throws illegal_value doc="illegal parameter values";
  133. throws out_of_memory doc="out of memory";
  134. throws any doc="any other value on error";
  135. }
  136. method key_reset_trust
  137. doc="""
  138. reset trust bit or explicitly mistrusted status for an identity and its
  139. accompanying key/user_id pair.
  140. """
  141. {
  142. // parms
  143. use ientity ident
  144. doc="""
  145. identity for person and key whose trust status is to be reset.
  146. Ident is INPUT ONLY. If you want updated trust on the identity, you'll have
  147. to call update_identity or myself respectively after this.
  148. N.B. If you are calling this on a key that is the identity or user default,
  149. it will be removed as the default key for the identity and user (but is still
  150. available for key election, it is just not the cached default anymore).
  151. """;
  152. // exceptions
  153. throws illegal_value doc="illegal parameter values";
  154. throws out_of_memory doc="out of memory";
  155. throws any doc="any other value on error";
  156. }
  157. method own_key_is_listed doc="returns true id key is listed as own key"
  158. {
  159. // parms
  160. use hash fpr doc="fingerprint of key to test";
  161. return bool listed doc="flags if key is own";
  162. // exceptions
  163. throws illegal_value doc="illegal parameter values";
  164. throws any doc="any other value on error";
  165. }
  166. method own_identities_retrieve doc="retrieve all own identities"
  167. {
  168. // parms
  169. create identity_list own_identities
  170. doc="""
  171. list of own identities.
  172. The ownership of the copy of own_identities goes to the caller.
  173. """;
  174. // exceptions
  175. throws illegal_value doc="illegal parameter values";
  176. throws out_of_memory doc="out of memory";
  177. throws any doc="any other value on error";
  178. }
  179. method own_keys_retrieve doc="retrieve all flagged keypair fingerprints/private keypair fingerprints"
  180. {
  181. // parms
  182. create hashlist keylist
  183. doc="""
  184. list of fingerprints. This function does not return keys without
  185. a private key part.
  186. """;
  187. // exceptions
  188. throws illegal_value doc="illegal parameter values";
  189. throws out_of_memory doc="out of memory";
  190. throws any doc="any other value on error";
  191. }
  192. method set_own_key doc="mark a key as own key"
  193. {
  194. // parms
  195. lend identity me
  196. doc="""
  197. own identity this key is used for.
  198. The key has to be in the key ring already identity->address must be set to valid
  199. data update_identity() is called by this function and will create a TOFU user_id +
  200. new entry if none is indicated and heuristic fails to match extant identity identity-
  201. >fpr will NOT be updated with the set identity fpr; it is only in,out because
  202. update_identity() is called before setting it.
  203. """;
  204. use hash fpr doc="fingerprint of the key to mark as own key";
  205. // exceptions
  206. throws key_unsuitable;
  207. throws illegal_value
  208. doc="""
  209. illegal parameter values, including if update_identity determines this is an own
  210. identity""";
  211. throws out_of_memory doc="out of memory";
  212. throws any doc="any other value on error";
  213. }
  214. }