From d1f57c9bdf6a1f1b27b8d883dde89db362345137 Mon Sep 17 00:00:00 2001 From: nk Date: Tue, 12 Nov 2019 17:07:47 +0100 Subject: [PATCH] updates --- api/basic_api.yml2 | 102 +++++------ api/keymanagement_api.yml2 | 354 ++++++++++++++++++------------------- api/message_api.yml2 | 280 ++++++++++++++++------------- api/pEp.yml2 | 10 +- 4 files changed, 383 insertions(+), 363 deletions(-) diff --git a/api/basic_api.yml2 b/api/basic_api.yml2 index bd8483e9..4b3a2e19 100644 --- a/api/basic_api.yml2 +++ b/api/basic_api.yml2 @@ -54,7 +54,7 @@ enum comm_type { hex key_revoked 0x05; hex key_b0rken 0x06; - hex key_expired_but_confirmed 0x07 + hex key_expired_but_confirmed 0x07 doc="NOT with confirmed bit. Just retaining info here in case of renewal."; hex my_key_not_included 0x09; @@ -110,7 +110,6 @@ enum comm_type { struct identity { - field string address doc="SMTP address or URI"; field hash fpr doc="fingerprint of key being used as ID"; field string user_id doc="ID for person or entity in M2M case"; @@ -134,8 +133,7 @@ flags { protocol session { - callback messageToSend - doc="a message needs to be delivered by application" + callback messageToSend doc="a message needs to be delivered by application" { // parms @@ -147,8 +145,7 @@ protocol session { } - method config_passive_mode - doc="enable passive mode" + method config_passive_mode doc="enable passive mode" { // parms @@ -156,8 +153,7 @@ protocol session { } - method config_unencrypted_subject - doc="disable subject encryption" + method config_unencrypted_subject doc="disable subject encryption" { // parms @@ -165,8 +161,7 @@ protocol session { } - method config_use_only_own_private_keys - doc="enable passive mode" + method config_use_only_own_private_keys doc="enable passive mode" { // parms @@ -174,8 +169,7 @@ protocol session { } - method config_service_log - doc="log more for service purposes" + method config_service_log doc="log more for service purposes" { // parms @@ -183,8 +177,7 @@ protocol session { } - method config_cipher_suite - doc="cipher suite being used when encrypting" + method config_cipher_suite doc="cipher suite being used when encrypting" { // parms @@ -193,19 +186,19 @@ protocol session { // exceptions throws cannot_config - doc=""" - configuration failed; falling back to default. the default - ciphersuite for a crypt tech implementation is implementation - defined. - """; + doc=""" + configuration failed; falling back to default. the default + ciphersuite for a crypt tech implementation is implementation + defined. + """; } method log_event - doc=""" - log a user defined event defined by UTF-8 encoded strings into - management log. - """ + doc=""" + log a user defined event defined by UTF-8 encoded strings into + management log. + """ { // parms @@ -219,8 +212,7 @@ protocol session { } - method get_default own_userid - doc="get the user_id of the own user" + method get_default own_userid doc="get the user_id of the own user" { // parms @@ -228,7 +220,7 @@ protocol session { doc=""" own user id (if it exists). userid will be NULL if not found; otherwise, returned string belongs to the caller. - """ + """; // exceptions @@ -242,21 +234,18 @@ protocol session { } - method mark_as_compromised - doc="mark key in trust db as compromised" + method mark_as_compromised doc="mark key in trust db as compromised" { // parms - use hash fpr doc="fingerprint of key to mark" + use hash fpr doc="fingerprint of key to mark"; } - method mark_as_compromized - doc="deprecated to fix misspelling. Please move to mark_as_compromised" + method mark_as_compromized doc="deprecated to fix misspelling. Please move to mark_as_compromised" - method import_key - doc="import key from data" + method import_key doc="import key from data" { // parms @@ -272,8 +261,7 @@ protocol session { } - method export_key - doc="export ascii armored key" + method export_key doc="export ascii armored key" { // parms @@ -295,12 +283,11 @@ protocol session { } - method export_secret_key - doc="export secret key ascii armored" + method export_secret_key doc="export secret key ascii armored" { // parms - use hash fpr doc="fingerprint of key, at least 16 hex digits" + use hash fpr doc="fingerprint of key, at least 16 hex digits"; create string key_data doc=""" @@ -321,12 +308,10 @@ protocol session { } - method export_secrect_key - doc="deprecated misspelled function. Please replace with export_secret_key" + method export_secrect_key doc="deprecated misspelled function. Please replace with export_secret_key" - method get_crashdump_log - doc="get the last log messages out" + method get_crashdump_log doc="get the last log messages out" { // parms @@ -343,8 +328,7 @@ protocol session { } - method get_languagelist - doc="get the list of languages" + method get_languagelist doc="get the list of languages" { //parms @@ -357,8 +341,7 @@ protocol session { } - method get_phrase - doc="get phrase in a dedicated language through i18n" + method get_phrase doc="get phrase in a dedicated language through i18n" { // parms @@ -371,19 +354,24 @@ protocol session { method get_engine_version - doc=""" - returns the current version of pEpEngine (this is different - from the pEp protocol version!). - """ + doc=""" + returns the current version of pEpEngine (this is different + from the pEp protocol version!). + """ { - // parms doc="none. return_value: const char* to the engine version string constant" + // parms doc="none" - method is_pEp_user - doc=""" - returns true if the USER corresponding to this identity has been listed - in the *person* table as a pEp user. - This *does not check comm_type*. - """ + // exceptions + + throws any doc="string to the engine version string constant"; + } + + method is_pEp_user + doc=""" + returns true if the USER corresponding to this identity has been listed + in the *person* table as a pEp user. + This *does not check comm_type*. + """ { // parms diff --git a/api/keymanagement_api.yml2 b/api/keymanagement_api.yml2 index ba337e2b..277216d5 100644 --- a/api/keymanagement_api.yml2 +++ b/api/keymanagement_api.yml2 @@ -4,229 +4,221 @@ // this file is under GNU General Public License 3.0 // see LICENSE.txt -// written by Volker Birk +// written by Nana Karlstetter and Volker Birk protocol session { - method update_identity - doc="update identity information" - { - // parms - - supply identity identity - doc=""" - identity information of communication partner - (identity->fpr is OUT ONLY), and at least - .address must be set. - If .username is set, it will be used to set or patch - the username record for this identity. - at least identity->address must be a non-empty UTF-8 string as input - update_identity() never writes flags; use set_identity_flags() for - writing - this function NEVER reads the incoming fpr, only writes to it. - this function will fail if called on an identity which, with its input - values, *explicitly* indicates it is an own identity (i.e. .me is set - to true on input, or a user_id is given AND it is a known own user_id). - however, it can RETURN an own identity if this is not indicated a - priori, and in fact will do so with prejudice when not faced with a - matching default (i.e. it is forced to search by address only). - if the identity is known to be an own identity (or the caller wishes - to make it one), call myself() on the identity instead. - - FIXME: is this next point accurate? - if this function returns PEP_ct_unknown or PEP_ct_key_expired in - identity->comm_type, the caller must insert the identity into the - asynchronous management implementation, so retrieve_next_identity() - will return this identity later - END FIXME - """ - - // exceptions - - throws illegal_value - doc=""" - if called with illegal inputs, including an identity - with .me set or with an own user_id specified in the - *input* (see caveats) - """; - - throws key_unsuitable - doc=""" - if a default key was found for this identity, no - other acceptable keys were found; if this is returned, - the reason for rejecting the first default key found - may be found in the comm_type - """ - } - - - method myself - doc="ensures that an own identity is complete" - { - // parms - - supply identity ident - doc=""" - identity of local user - both .address and .user_id must be set. - if .fpr is set, an attempt will be made to make - that the default key for this identity after key validation - if .fpr is not set, key retrieval is performed. - If .username is set, it will be used to set or patch - the username record for this identity. - - If an fpr was entered and is not a valid key, the reason for failure - is immediately returned in the status and, possibly, identity->comm_type - If a default own user_id exists in the database, an alias will - be created for the default for the input user_id. The ENGINE'S default - user_id is always returned in the .user_id field - myself() NEVER elects keys from the keyring; it will only choose keys - which have been set up explicitly via myself(), or which were imported - during a first time DB setup from an OpenPGP keyring (compatibility only) - this function generates a keypair on demand; because it's synchronous - it can need a decent amount of time to return - if you need to do this asynchronous, you need to return an identity - with retrieve_next_identity() where identity.me is true. - """ - } - - - method key_mistrusted - doc="mark key as being compromised" - { - //parms - - use identity ident - doc=""" - person and key which was compromised - ident is INPUT ONLY. If you want updated trust on the identity, you'll have - to call update_identity or myself respectively after this. - N.B. If you are calling this on a key that is the identity or user default, - it will be removed as the default key for ANY identity and user for which - it is the default. Please keep in mind that the undo in undo_last_mistrust - will only undo the current identity's / it's user's default, not any - other identities which may be impacted (this will not affect most use - cases) - """ - } - - - method trust_personal_key - doc="mark a key as trusted for a user" - { - // parms - - use identity ident - doc=""" - person and key to trust in - this must not be an own_identity in which - the .me flag is set or the user_id is an own user_id. The fields user_id, - address and fpr must be supplied own identities will result in a return - of illegal_value. - For non-own users, this will 1) set the trust bit on its comm type in the DB, - 2) set this key as the identity default if the current identity default - is not trusted, and 3) set this key as the user default if the current user - default is not trusted. - """ + method update_identity doc="update identity information" + { + // parms + + lend identity identity + doc=""" + identity information of communication partner + (identity->fpr is OUT ONLY), and at least + .address must be set. + If .username is set, it will be used to set or patch + the username record for this identity. + at least identity->address must be a non-empty UTF-8 string as input + update_identity() never writes flags; use set_identity_flags() for + writing + this function NEVER reads the incoming fpr, only writes to it. + this function will fail if called on an identity which, with its input + values, *explicitly* indicates it is an own identity (i.e. .me is set + to true on input, or a user_id is given AND it is a known own user_id). + however, it can RETURN an own identity if this is not indicated a + priori, and in fact will do so with prejudice when not faced with a + matching default (i.e. it is forced to search by address only). + if the identity is known to be an own identity (or the caller wishes + to make it one), call myself() on the identity instead. + + FIXME: is this next point accurate? + if this function returns PEP_ct_unknown or PEP_ct_key_expired in + identity->comm_type, the caller must insert the identity into the + asynchronous management implementation, so retrieve_next_identity() + will return this identity later + END FIXME + """; + + // exceptions + + throws illegal_value + doc=""" + if called with illegal inputs, including an identity + with .me set or with an own user_id specified in the + *input* (see caveats) + """; + + throws key_unsuitable + doc=""" + if a default key was found for this identity, no + other acceptable keys were found; if this is returned, + the reason for rejecting the first default key found + may be found in the comm_type + """; } - method trust_own_key + method myself doc="ensures that an own identity is complete" + { + // parms + + lend identity ident doc=""" - mark a key as trusted for self, generally used when we need to trust - a public key associated with outselves for issues like manual key import. - """ + identity of local user + both .address and .user_id must be set. + if .fpr is set, an attempt will be made to make + that the default key for this identity after key validation + if .fpr is not set, key retrieval is performed. + If .username is set, it will be used to set or patch + the username record for this identity. + + If an fpr was entered and is not a valid key, the reason for failure + is immediately returned in the status and, possibly, identity->comm_type + If a default own user_id exists in the database, an alias will + be created for the default for the input user_id. The ENGINE'S default + user_id is always returned in the .user_id field + myself() NEVER elects keys from the keyring; it will only choose keys + which have been set up explicitly via myself(), or which were imported + during a first time DB setup from an OpenPGP keyring (compatibility only) + this function generates a keypair on demand; because it's synchronous + it can need a decent amount of time to return + if you need to do this asynchronous, you need to return an identity + with retrieve_next_identity() where identity.me is true. + """; + } + + + method key_mistrusted doc="mark key as being compromised" { - // parms + //parms - use identity ident - doc=""" - own ident containing fpr to trust. - If this is a public key only, keep in mind that if the private part of the - keypair is later added, it will not undergo separate trust evaluation. This - is fine - even desired - as long as the semantics of this function are - understood as both trusting the key and verifying it as an own key. This will - NEVER cause replacement of or setting of a default *alone*. However, if a - private key is ever associated with this fpr, please keep in mind that trusting - it here makes it an eligible key for selection for encryption later. So use - this function on purpose with an understanding of what you're doing! - """ + use identity ident + doc=""" + person and key which was compromised + ident is INPUT ONLY. If you want updated trust on the identity, you'll have + to call update_identity or myself respectively after this. + N.B. If you are calling this on a key that is the identity or user default, + it will be removed as the default key for ANY identity and user for which + it is the default. Please keep in mind that the undo in undo_last_mistrust + will only undo the current identity's / it's user's default, not any + other identities which may be impacted (this will not affect most use + cases) + """; } - method key_reset_trust + method trust_personal_key doc="mark a key as trusted for a user" + { + // parms + + use identity ident doc=""" - reset trust bit or explicitly mistrusted status for an identity and its - accompanying key/user_id pair. - """ + person and key to trust in - this must not be an own_identity in which + the .me flag is set or the user_id is an own user_id. The fields user_id, + address and fpr must be supplied own identities will result in a return + of illegal_value. + For non-own users, this will 1) set the trust bit on its comm type in the DB, + 2) set this key as the identity default if the current identity default + is not trusted, and 3) set this key as the user default if the current user + default is not trusted. + """; + } + + + method trust_own_key + doc=""" + mark a key as trusted for self, generally used when we need to trust + a public key associated with outselves for issues like manual key import. + """ { - // parms + // parms - use ientity ident + use identity ident + doc=""" + own ident containing fpr to trust. + If this is a public key only, keep in mind that if the private part of the + keypair is later added, it will not undergo separate trust evaluation. This + is fine - even desired - as long as the semantics of this function are + understood as both trusting the key and verifying it as an own key. This will + NEVER cause replacement of or setting of a default *alone*. However, if a + private key is ever associated with this fpr, please keep in mind that trusting + it here makes it an eligible key for selection for encryption later. So use + this function on purpose with an understanding of what you're doing! + """; + } + + + method key_reset_trust doc=""" - identity for person and key whose trust status is to be reset. - Ident is INPUT ONLY. If you want updated trust on the identity, you'll have - to call update_identity or myself respectively after this. - N.B. If you are calling this on a key that is the identity or user default, - it will be removed as the default key for the identity and user (but is still - available for key election, it is just not the cached default anymore). + reset trust bit or explicitly mistrusted status for an identity and its + accompanying key/user_id pair. """ + { + // parms + + use ientity ident + doc=""" + identity for person and key whose trust status is to be reset. + Ident is INPUT ONLY. If you want updated trust on the identity, you'll have + to call update_identity or myself respectively after this. + N.B. If you are calling this on a key that is the identity or user default, + it will be removed as the default key for the identity and user (but is still + available for key election, it is just not the cached default anymore). + """; } - method own_key_is_listed - doc="returns true id key is listed as own key" + method own_key_is_listed doc="returns true id key is listed as own key" { - // parms + // parms - use hash fpr doc="fingerprint of key to test" + use hash fpr doc="fingerprint of key to test"; - return bool listed doc="flags if key is own" + return bool listed doc="flags if key is own"; } - method own_identities_retrieve - doc="retrieve all own identities" + method own_identities_retrieve doc="retrieve all own identities" { - // parms + // parms - create identity_list own_identities - doc=""" - list of own identities. - The ownership of the copy of own_identities goes to the caller. - """ + create identity_list own_identities + doc=""" + list of own identities. + The ownership of the copy of own_identities goes to the caller. + """; } - method own_keys_retrieve - doc="retrieve all flagged keypair fingerprints/private keypair fingerprints" + method own_keys_retrieve doc="retrieve all flagged keypair fingerprints/private keypair fingerprints" { - // parms + // parms - create hashlist keylist + create hashlist keylist doc=""" list of fingerprints. This function does not return keys without a private key part. - """ + """; } - method set_own_key - doc="mark a key as own key" + method set_own_key doc="mark a key as own key" { - // parms + // parms - supply identity me - doc=""" - own identity this key is used for. The key has to be in the key ring already. - me->address, me->user_id and me->username must be set to valid data. - myself is called by set_own_key without key generation. - me->flags are ignored - me->address must not be an alias - me->fpr will be ignored and replaced by fpr. - """ - - use hash fpr (in) fingerprint of the key to mark as own key + lend identity me + doc=""" + own identity this key is used for. The key has to be in the key ring already. + me->address, me->user_id and me->username must be set to valid data. + myself is called by set_own_key without key generation. + me->flags are ignored + me->address must not be an alias + me->fpr will be ignored and replaced by fpr. + """; + + use hash fpr doc="fingerprint of the key to mark as own key"; } } diff --git a/api/message_api.yml2 b/api/message_api.yml2 index 1f87d0d3..b1993a6f 100644 --- a/api/message_api.yml2 +++ b/api/message_api.yml2 @@ -4,7 +4,7 @@ // this file is under GNU General Public License 3.0 // see LICENSE.txt -// written by Volker Birk +// written by Volker Birk and Nana Karlstetter enum text_format { @@ -86,12 +86,11 @@ struct message { protocol session { - method encrypt_message - doc="encrypt message in memory" + method encrypt_message doc="encrypt message in memory" { // parms - supply message src + lend message src doc=""" message to encrypt - usually in-only, but can be in-out for unencrypted messages; in that case, we may attach the key and @@ -106,7 +105,7 @@ protocol session { take place """; - use enc_format format doc="encrypted format"; + use enc_format format doc="The desired format this message should be encrypted with"; // flags @@ -117,7 +116,11 @@ protocol session { flag force_no_attached_key 0x4; flag inner_message 0x8 doc='This is mainly used by pEp clients to send private keys to their own PGP-only device.'; flag force_version_1 0x10 doc='This is mainly used by pEp clients to send private keys to their own PGP-only device'; - flag key_reset_only 0x20; + flag key_reset_only 0x20 + doc="""This flag is used to let internal functions know that an encryption call is being + used as part of a reencryption operation + """; + flag encrypt_reencrypt 0x40; } // exceptions @@ -133,7 +136,10 @@ 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)" + doc=""" + encrypt message in memory, adding an encrypted private key (encrypted separately + and sent within the inner message) + """ { // parms @@ -172,10 +178,10 @@ protocol session { method encrypt_message_for_self - doc=""" - encrypt message in memory for user's identity only, - ignoring recipients and other identities from the message - """ + doc=""" + encrypt message in memory for user's identity only, + ignoring recipients and other identities from the message + """ { // parms @@ -215,12 +221,11 @@ protocol session { } - method decrypt_message - doc="decrypt message in memory" + method decrypt_message doc="decrypt message in memory" { // parms - supply message src + lend message src doc=""" message to decrypt. The ownership of src remains with the caller - however, the contents @@ -230,7 +235,7 @@ protocol session { create message dst doc="pointer to new decrypted message or empty on failure"; - supply hash_list keylist + lend hash_list keylist doc=""" in: stringlist with additional keyids for reencryption if needed (will be freed and replaced with output keylist) @@ -265,118 +270,114 @@ protocol session { input flag. Used to signal that decrypt function should engage in behaviour specified for when the server storing the source is untrusted. """; - flag decrypt_flag_dont_trigger_sync 0x200 + flag decrypt_flag_dont_trigger_sync 0x200; } - // exceptions + // exceptions - throws decrypted doc="if message decrypted but not verified"; + throws decrypted doc="if message decrypted but not verified"; - throws cannot_reencrypt + throws cannot_reencrypt doc=""" if message was decrypted (and possibly verified) but a reencryption operation is expected by the caller and failed. """; - throws unencrypted + throws unencrypted doc=""" if src is unencrypted this function returns unencrypted and sets dst to empty. """; - throws any doc="all error status values allowed"; + throws any doc="all error status values allowed"; } method own_message_private_key_details - doc=""" - details on own key in own message. Note: In order to obtain details about key - to be possibly imported as a replacement of key currently used as own identity, - application passes message that have been previously flagged by decrypt_message() - as own message containing own key to this function. - """ + doc=""" + details on own key in own message. Note: In order to obtain details about key + to be possibly imported as a replacement of key currently used as own identity, + application passes message that have been previously flagged by decrypt_message() + as own message containing own key to this function. + """ { - //parms + // parms - use message msg - doc=""" - message to decrypt. msg MUST be encrypted so that this function - can check own signature. - """; + use message msg + doc=""" + message to decrypt. msg MUST be encrypted so that this function + can check own signature. + """; - create identity ident doc="identity containing uid, address and fpr of key"; + create identity ident doc="identity containing uid, address and fpr of key"; - // exceptions + // exceptions - throws any doc="error status" + throws any doc="error status"; } - method outgoing_message_rating - doc="get rating for an outgoing message" + method outgoing_message_rating doc="get rating for an outgoing message" { - //parms + // parms - use message msg - doc=""" - message to get the rating for. From must point to a valid pEp_identity. - Dir must be dir_outgoing. - """; + use message msg + doc=""" + message to get the rating for. From must point to a valid pEp_identity. + Dir must be dir_outgoing. + """; - return rating msg_rating doc="rating for the message"; + return rating msg_rating doc="rating for the message"; - // exceptions + // exceptions - throws any doc="error status" + throws any doc="error status"; } - method outgoing_message_rating_preview - doc="get rating preview" + method outgoing_message_rating_preview doc="get rating preview" { - //parms + // parms - use message msg - doc=""" - message to get the rating for. From must point to a valid pEp_identity. - Dir must be dir_outgoing. - """; + use message msg + doc=""" + message to get the rating for. From must point to a valid pEp_identity. + Dir must be dir_outgoing. + """; - return rating msg_rating doc="rating preview for the message"; + return rating msg_rating doc="rating preview for the message"; - // exceptions + // exceptions - throws any doc="error status" + throws any doc="error status"; } - method identity_rating - doc="get rating for a single identity" + method identity_rating doc="get rating for a single identity" { - //parms + // parms - use identity ident doc="identity to get the rating for"; + use identity ident doc="identity to get the rating for"; - return rating identity_rating doc="rating for the identity"; + return rating identity_rating doc="rating for the identity"; - // exceptions + // exceptions - throws any doc="error status" + throws any doc="error status"; } - method get_trustwords - doc="get full trustwords string for a *pair* of identities" + method get_trustwords doc="get full trustwords string for a *pair* of identities" { - //parms + // parms - use identity id1 doc="identity of first party in communication - fpr can't be empty"; + use identity id1 doc="identity of first party in communication - fpr can't be empty"; - use identity id2 doc="identity of second party in communication - fpr can't be empty"; + use identity id2 doc="identity of second party in communication - fpr can't be empty"; - use ISO639_1 lang doc="string with ISO 639-1 language code"; + use ISO639_1 lang doc="string with ISO 639-1 language code"; - create string words + create string words doc=""" string with all trustwords, separated by a blank each. Empty if language is not supported or trustword @@ -385,129 +386,164 @@ protocol session { The caller is responsible to free() it (on Windoze use pEp_free()) """; - use bool full + use bool full doc=""" if true, generate ALL trustwords for these identities. else, generate a fixed-size subset. (TODO: fixed-minimum-entropy subset in next version) """; - // exceptions + // exceptions - throws out_of_memory - doc="out of memory"; + throws out_of_memory doc="out of memory"; - throws trustword_not_found - doc="at least one trustword not found"; + throws trustword_not_found doc="at least one trustword not found"; } - method get_message_trustwords - doc="get full trustwords string for message sender and reciever identities" + method get_message_trustwords doc="get full trustwords string for message sender and reciever identities" { - //parms + // parms - use message msg doc="message to get sender identity from"; + use message msg doc="message to get sender identity from"; - use hash_list keylist - doc="empty if message to be decrypted, keylist returned by decrypt_message() otherwise."; + use hash_list keylist doc="empty if message to be decrypted, keylist returned by decrypt_message() otherwise."; - use identity received_by doc="identity for account receiving message can't be empty"; + use identity received_by doc="identity for account receiving message can't be empty"; - use ISO639_1 lang doc="string with ISO 639-1 language code"; + use ISO639_1 lang doc="string with ISO 639-1 language code"; - create string words + create string words doc=""" string with all trustwords, separated by a blank each. Empty if language is not supported or trustword wordlist is damaged or unavailable. """; - use bool full + use bool full doc=""" if true, generate ALL trustwords for these identities. else, generate a fixed-size subset. (TODO: fixed-minimum-entropy subset in next version) """; - // exceptions + // exceptions - throws out_of_memory doc="out of memory"; + throws out_of_memory doc="out of memory"; - throws trustword_not_found doc="at least one trustword not found"; + throws trustword_not_found doc="at least one trustword not found"; - throws like decrypt_message doc="error status of decrypt_message() if decryption fails" + throws like decrypt_message doc="error status of decrypt_message() if decryption fails"; } - method re_evaluate_message_rating - doc="re-evaluate already decrypted message rating" + method get_trustwords_for_fprs doc="get full trustwords string for a pair of fingerprints" { - //parms + // parms - use message msg - doc="message to get the rating for. msg->from must point to a valid pEp_identity"; + use string fpr1 doc="fingerprint 1"; - use hash_list x_keylist doc="decrypted message recipients keys fpr"; + use string fpr2 doc="fingerprint 2"; - use rating x_enc_status doc="original rating for the decrypted message"; + use ISO639_1 lang doc="string with ISO 639-1 language code"; - return rating msg_rating doc="rating for the message"; + create string words + doc=""" + pointer to 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. + The caller is responsible to free() it (on Windoze use pEp_free()). + """; - // exceptions + return size_t wsize doc="length of full trustwords string"; - throws illegal_value + use bool full + doc=""" + if true, generate ALL trustwords for these identities. Else, generate a fixed-size + subset. (TODO: fixed-minimum-entropy subset in next version) + """; + + // exceptions + + throws out_of_memory doc="out of memory"; + + throws trustword_not_found doc="at least one trustword not found"; + } + + + method re_evaluate_message_rating doc="re-evaluate already decrypted message rating" + { + // parms + + use message msg doc="message to get the rating for. msg->from must point to a valid pEp_identity"; + + use hash_list x_keylist doc="decrypted message recipients keys fpr"; + + use rating x_enc_status doc="original rating for the decrypted message"; + + return rating msg_rating doc="rating for the message"; + + // exceptions + + throws illegal_value doc=""" if decrypted message doesn't contain X-EncStatus optional field and x_enc_status is pEp_rating_udefined or if decrypted message doesn't contain X-Keylist optional field and x_keylist is empty. """; - throws out_of_memory doc="if not enough memory could be allocated"; + throws out_of_memory doc="if not enough memory could be allocated"; } - method get_key_rating_for_user - doc="get the rating of a certain key for a certain user" + method get_key_rating_for_user doc="get the rating of a certain key for a certain user" { - //parms + // parms - use string user_id doc="string with user ID"; + use string user_id doc="string with user ID"; - use string fpr doc="string with fingerprint"; + use string fpr doc="string with fingerprint"; - return rating key_rating doc="rating of key for this user"; + return rating key_rating doc="rating of key for this user"; - // exceptions + // exceptions + + throws record_not_found doc="if no trust record for user_id and fpr can be found"; + } - throws record_not_found - doc="if no trust record for user_id and fpr can be found" + + method rating_from_comm_type doc="get the rating for a comm type" + { + // parms + + use comm_type ct doc="the comm type to deliver the rating for"; + + // exceptions + + throws any doc="rating value for comm type ct"; } } -func color_from_rating - doc="calculate color from rating" +func color_from_rating doc="calculate color from rating" { // parms - use color_from_rating rating doc="color representing that rating" + use color_from_rating rating doc="color representing that rating"; // return value - return color rating_color doc="color representing that rating" + + return color rating_color doc="color representing that rating"; } -func get_binary_path - doc="retrieve path of cryptotech binary if available" +func get_binary_path doc="retrieve path of cryptotech binary if available" { //parms - use cryptotech tech - doc="cryptotech to get the binary for"; + use cryptotech tech doc="cryptotech to get the binary for"; use string path doc=""" path to cryptotech binary or empty if not available. **path is owned by - the library, do not change it!; - """ + the library, do not change it! + """; } diff --git a/api/pEp.yml2 b/api/pEp.yml2 index d4bc0387..9dfdf24c 100644 --- a/api/pEp.yml2 +++ b/api/pEp.yml2 @@ -4,7 +4,7 @@ // this file is under GNU General Public License 3.0 // see LICENSE.txt -// written by Volker Birk +// written by Volker Birk and Nana Karlstetter decl package @name; @@ -24,7 +24,7 @@ decl construct, new is construct; // use: readonly in parm, ownership remains with caller decl use @type @name (mode=use) alias parm; -// supply: inout parm, ownership remains with caller +// lend: inout parm, ownership remains with caller decl supply @type @name (mode=supply) alias parm; // create: factory delivers this, ownership goes to caller @@ -42,7 +42,11 @@ decl caveat(mode=caveat) alias doc; // base types -// string: text +// string: text + doc=""" + p≡p engine uses UTF-8 strings which are NFC normalized. + Cf. https://dev.pep.foundation/Engine/Basic%20Concepts%20of%20the%20pEp%20Engine + """ // int: integer number // blob: Binary Large Object // size_t: size in memory