From 7b0c7f293c19d9c18aa218de7b6d9edfc2d82c25 Mon Sep 17 00:00:00 2001 From: nk Date: Fri, 15 Feb 2019 15:16:43 +0100 Subject: [PATCH] version 2: ist edits from nana --- api/message_api.yml2 | 107 ++++++++++++++++--------------------------- 1 file changed, 39 insertions(+), 68 deletions(-) diff --git a/api/message_api.yml2 b/api/message_api.yml2 index 7428078d..b2a4887a 100644 --- a/api/message_api.yml2 +++ b/api/message_api.yml2 @@ -28,7 +28,7 @@ protocol session { take place """ - use encformat format doc="encrypted format"; + use enc_format enc_format doc="encrypted format"; // flags @@ -53,26 +53,22 @@ protocol session { and key is attached to it """ } -} -protocol session { method encrypt_message_and_add_priv_key doc="encrypt message in memory, adding an encrypted private key (encrypted separately and sent within the inner message)" { // parms - use message src - doc="message to encrypt"; + use message src doc="message to encrypt"; create message dst doc="pointer to new encrypted message or NULL if no encryption could take place"; - to_fpr + const char to_fpr doc="fingerprint of the recipient key to which the private key should be encrypted"; - use format enc_format? - doc="encrypted format"; + use enc_format enc_format doc="encrypted format"; // flags @@ -97,10 +93,8 @@ protocol session { and key is attached to it """ } -} -protocol session { method encrypt_message_for_self doc=""" encrypt message in memory for user's identity only, @@ -109,20 +103,19 @@ protocol session { { // parms - use message target_id - doc="self identity this message should be encrypted for"; + use identity target_id + doc=""" + self identity this message should be encrypted for. message is NOT encrypted for + identities other than the target_id (and then, only if the target_id refers to self!) + """; - use message src - doc="message to encrypt"; + use message src doc="message to encrypt"; - provide key? extra - doc="extra keys for encryption"; + provide hash_list extra doc="extra keys for encryption"; - create message dst - doc="pointer to new encrypted message or NULL on failure"; + create message dst doc="pointer to new encrypted message or NULL on failure"; - use format enc_format? - doc="encrypted format"; + use enc_format enc_format? doc="encrypted format"; // flags @@ -147,16 +140,14 @@ protocol session { throws get_key_failed doc="cannot retrieve key" } -} -protocol session { method color_from_rating doc="calculate color from rating" { // parms - provide message rating? + provide color_from_rating rating doc="color representing that rating"; // ratings @@ -189,10 +180,8 @@ protocol session { // return value doc="color representing that rating" } -} -protocol session { method decrypt_message doc="decrypt message in memory" { @@ -209,7 +198,7 @@ protocol session { create message dst doc="pointer to new decrypted message or NULL on failure"; - supply message keylist + supply hash_list keylist doc=""" in: stringlist with additional keyids for reencryption if needed (will be freed and replaced with output keylist) @@ -218,7 +207,7 @@ protocol session { to. Only signer and whichever of the user's keys was used are reliable. """; - return message rating + return rating rating doc="rating for the message"; // flags @@ -262,10 +251,8 @@ protocol session { dst to NULL. """ } -} -protocol session { method own_message_private_key_details doc="details on own key in own message" { @@ -277,13 +264,11 @@ protocol session { can check own signature. """; - create @type? ident + create identity ident doc="identity containing uid, address and fpr of key" } -} -protocol session { method outgoing_message_rating doc="get rating for an outgoing message" { @@ -295,13 +280,11 @@ protocol session { Dir must be dir_outgoing. """; - create message rating + create rating rating doc="rating for the message" } -} -protocol session { method outgoing_message_rating_preview doc="get rating preview" { @@ -313,28 +296,24 @@ protocol session { Dir must be dir_outgoing. """; - create message rating + create rating rating doc="rating preview for the message" } -} -protocol session { method identity_rating doc="get rating for a single identity" { //parms - use @type ident + use identity ident doc="identity to get the rating for"; - create identity rating + create rating rating doc="rating for the identity" } -} -protocol session { method get_binary_path doc="retrieve path of cryptotech binary if available" { @@ -349,25 +328,23 @@ protocol session { the library, do not change it! """ } -} -protocol session { method get_trustwords doc="get full trustwords string for a *pair* of identities" { //parms - provide message id1 + provide const identity id1 doc="identity of first party in communication - fpr can't be NULL"; - provide message id2 + provide const identity id2 doc="identity of second party in communication - fpr can't be NULL"; - provide message lang + provide const char lang doc="C string with ISO 639-1 language code"; - create message words + create char words doc=""" pointer to C string with all trustwords UTF-8 encoded, separated by a blank each NULL if language is not supported or trustword @@ -376,10 +353,10 @@ protocol session { The caller is responsible to free() it (on Windoze use pEp_free()) """; - create @type? wsize + create size_t wsize doc="length of full trustwords string"; - provide @type full + provide bool full doc=""" if true, generate ALL trustwords for these identities. else, generate a fixed-size subset. (TODO: fixed-minimum-entropy @@ -394,28 +371,26 @@ protocol session { throws trustword_not_found doc="at least one trustword not found" } -} -protocol session method get_message_trustwords doc="get full trustwords string for message sender and reciever identities" { //parms - provide @type msg + provide message msg doc="message to get sender identity from"; - provide message keylist + provide hash_list keylist doc="NULL if message to be decrypted, keylist returned by decrypt_message() otherwise."; - provide message received_by + provide identity received_by doc="identity for account receiving message can't be NULL"; - provide @type? lang + provide const char lang doc="C string with ISO 639-1 language code"; - create message words + create char words doc=""" pointer to C string with all trustwords UTF-8 encoded, separated by a blank each. NULL if language is not supported or trustword wordlist is damaged or unavailable. @@ -423,7 +398,7 @@ protocol session The caller is responsible to free() it (on Windoze use pEp_free()) """; - provide @type full + provide bool full doc=""" if true, generate ALL trustwords for these identities. else, generate a fixed-size subset. (TODO: fixed-minimum-entropy @@ -438,22 +413,20 @@ protocol session throws trustword_not_found doc="at least one trustword not found" } -} -protocol session method re_evaluate_message_rating doc="re-evaluate already decrypted message rating" { //parms - use @type msg + use message msg doc="message to get the rating for. msg->from must point to a valid pEp_identity"; - use message x_keylist + use hash_list x_keylist doc="decrypted message recipients keys fpr"; - provide message x_enc_status + provide rating x_enc_status doc="original rating for the decrypted message"; create message rating @@ -471,22 +444,20 @@ protocol session throws out_of_memory doc="if not enough memory could be allocated" } -} -protocol session method get_key_rating_for_user doc="get the rating of a certain key for a certain user" { //parms - provide @type? user_id + provide const char user_id doc="string with user ID"; - provide @type fpr + provide const char fpr doc="string with fingerprint"; - create @type rating + create rating rating doc="rating of key for this user" // exceptions