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.
pEpEngine/api/message_api.yml2

630 lines
20 KiB

4 years ago
// p≡p Message API
3 years ago
// Copyleft (c) 2019-2020, p≡p foundation
4 years ago
// this file is under GNU General Public License 3.0
// see LICENSE.txt
3 years ago
// written by Volker Birk and Nana Karlstetter
enum text_format {
3 years ago
hex plain 0;
hex html 1;
hex other 0xff;
}
3 years ago
enum direction {
item incoming 0;
item outgoing 1;
}
enum enc_format {
3 years ago
item none 0 doc='message is not encrypted';
item pieces 1 doc='inline PGP + PGP extensions';
item S_MIME 2 doc='RFC5751';
item PGP_MIME 3 doc='RFC3156';
item PEP 4 doc='pEp encryption format';
item PGP_MIME_Outlook1 5 doc='Message B0rken by Outlook type 1';
}
3 years ago
enum rating {
item undefined 0 doc="no rating available";
doc "no color";
item cannot_decrypt 1;
item have_no_key 2;
item unencrypted 3;
3 years ago
// 4 is reserved
3 years ago
item unreliable 5;
doc "yellow";
item reliable 6;
doc "green";
item trusted 7;
item trusted_and_anonymized 8;
item fully_anonymous 9;
doc "red";
item mistrust -1;
item b0rken -2;
item under_attack -3;
4 years ago
}
3 years ago
enum color {
item no_color 0;
item yellow 1;
item green 2;
item red -1;
4 years ago
}
struct message {
3 years ago
field direction dir;
4 years ago
field string id doc='string of message ID';
field string shortmsg doc='string of short message';
4 years ago
field string longmsg doc='string of long message (plain)';
4 years ago
field string longmsg_formatted doc='string of long message (formatted)';
4 years ago
field blob_list attachments doc='blobs with attachements';
3 years ago
field binary_ref rawmsg_ref doc='reference to raw message data';
4 years ago
field size_t rawmsg_size doc='size of raw message data';
4 years ago
field timestamp sent doc='when the message is sent';
field timestamp recv doc='when the message is received';
field identity from doc='whom the message is from';
field identity_list to doc='whom the message is to';
field identity recv_by doc='via which identity the message is received';
field identity_list cc doc='whom a CC is being sent';
field identity_list bcc doc='whom a BCC is being sent';
field identity_list reply_to doc='where a reply should go to';
4 years ago
field string_list in_reply_to doc='list of strings with MessageIDs of refering messages';
3 years ago
field any_ref refering_msg_ref doc='reference to refering message';
4 years ago
field string_list references doc='list of strings with references';
3 years ago
field string_list refered_by doc='list of references to messages being refered';
4 years ago
field string_list keywords doc='list of strings with keywords';
field string comments doc='string with comments';
3 years ago
field string_pair_list opt_fields doc='optional fields';
4 years ago
field enc_format format doc='format of encrypted data';
4 years ago
new (msg_direction dir);
}
protocol session {
3 years ago
method encrypt_message
doc="""
encrypt message in memory. enc_format PEP_enc_inline_EA:
internal format of the encrypted attachments is changing, see
https://dev.pep.foundation/Engine/ElevatedAttachments
Only use this for transports without support for attachments
when attached data must be sent inline
"""
{
// parms
3 years ago
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
decorate the message
""";
use hash_list extra doc="extra keys for encryption";
create message dst
doc="""
pointer to new encrypted message or #NV if no encryption could
take place
""";
3 years ago
use enc_format format doc="The desired format this message should be encrypted with";
// flags
flags {
4 years ago
flag default 0x0 doc='"default" means whatever the default behaviour for the function is.';
flag force_encryption 0x1;
4 years ago
flag force_unsigned 0x2 doc='This flag is for special use cases and should not be used by normal pEp clients!';
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';
3 years ago
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
throws key_has_ambig_name doc="at least one of the receipient keys has an ambiguous name";
throws unencrypted
doc="""
on demand or no recipients with usable key, is left unencrypted,
and key is attached to it
""";
2 years ago
throws illegal_value doc="illegal parameter values";
throws out_of_memory doc="out of memory";
throws any doc="any other value on error";
}
4 years ago
method encrypt_message_and_add_priv_key
3 years ago
doc="""
encrypt message in memory, adding an encrypted private key (encrypted separately
and sent within the inner message)
"""
4 years ago
{
// parms
use message src doc="message to encrypt";
create message dst
4 years ago
doc="pointer to new encrypted message or empty if no encryption could take place";
4 years ago
4 years ago
use hash to_fpr
4 years ago
doc="fingerprint of the recipient key to which the private key should be encrypted";
use enc_format format doc="encrypted format";
// flags
flags {
flag default 0x0 doc='"default" means whatever the default behaviour for the function is.';
flag force_encryption 0x1;
flag force_unsigned 0x2 doc='This flag is for special use cases and should not be used by normal pEp clients!';
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;
}
// exceptions
throws key_has_ambig_name doc="at least one of the receipient keys has an ambiguous name";
throws unencrypted
doc="""
on demand or no recipients with usable key, is left unencrypted,
and key is attached to it
""";
2 years ago
throws illegal_value doc="illegal parameter values";
throws out_of_memory doc="out of memory";
throws any doc="any other value on error";
throws unknown_error;
throws any doc="any other value on error";
4 years ago
}
4 years ago
method encrypt_message_for_self
3 years ago
doc="""
encrypt message in memory for user's identity only,
ignoring recipients and other identities from the message
"""
4 years ago
{
// parms
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 hash_list extra doc="extra keys for encryption";
4 years ago
create message dst doc="pointer to new encrypted message or empty on failure";
4 years ago
use enc_format format doc="encrypted format";
4 years ago
// flags
4 years ago
flags {
flag default 0x0 doc='"default" means whatever the default behaviour for the function is.';
flag force_encryption 0x1;
flag force_unsigned 0x2 doc='This flag is for special use cases and should not be used by normal pEp clients!';
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;
}
2 years ago
// exceptions
4 years ago
throws key_not_found doc="at least one of the receipient keys could not be found";
4 years ago
throws key_has_ambig_name doc="at least one of the receipient keys has an ambiguous name";
throws get_key_failed doc="cannot retrieve key";
2 years ago
throws cannot_find_identity;
throws illegal_value;
throws out_of_memory;
4 years ago
}
3 years ago
method decrypt_message doc="decrypt message in memory"
4 years ago
{
4 years ago
// parms
4 years ago
3 years ago
lend message src
4 years ago
doc="""
4 years ago
message to decrypt.
2 years ago
The ownership of src remains with the caller - HOWEVER, the contents
might be modified (strings freed and allocated anew or set to empty,
4 years ago
etc) intentionally; when this happens, decrypt_flag_src_modified is set.
2 years ago
if src is unencrypted this function returns PEP_UNENCRYPTED and sets dst to NULL
if src->enc_format is PEP_enc_inline_EA on input then elevated attachments
will be expected
decrypt_message RELIES on the fact that identity information provided in src
for recips and sender is AS TAKEN FROM THE ORIGINAL PARSED MESSAGE. This means
that if update_identity or myself is called on those identities by the caller
before passing the message struct to decrypt_message, the caller will have to
cache and restore those to their original state before sending them to this
function. ADAPTERS AND APPLICATIONS PLEASE TAKE NOTE OF THIS. (Obviously, this
doesn't include information like user_ids, but we very specifically need the
incoming usernames preserved so that they can be handled by the internal
algorithm appropriately)
4 years ago
""";
4 years ago
create message dst doc="pointer to new decrypted message or empty on failure";
3 years ago
lend hash_list keylist
4 years ago
doc="""
4 years ago
in: stringlist with additional keyids for reencryption if needed
(will be freed and replaced with output keylist)
out: stringlist with keyids used for signing and encryption. first
first key is signer, additional keys are the ones it was encrypted
to. Only signer and whichever of the user's keys was used are reliable.
The ownership of keylist goes to the caller.
If src is unencrypted this function returns unencrypted and sets dst to empty.
4 years ago
""";
4 years ago
return rating msg_rating doc="rating for the message";
// flags
4 years ago
flags {
2 years ago
flag decrypt_flag_untrusted_server 0x100
doc="""
incoming flag. Used to signal that decrypt function should engage in behaviour
specified for when the server storing the source is untrusted.
""";
4 years ago
flag decrypt_flag_own_private_key 0x1
4 years ago
doc="""
2 years ago
outgoing flag: private key was imported for one of our addresses (NOT trusted
4 years ago
or set to be used - handshake/trust is required for that)
""";
4 years ago
flag decrypt_flag_src_modified 0x8
4 years ago
doc="""
2 years ago
outgoing flag: indicates that the modified_src field should contain a modified
version of the source, at the moment always as a result of the input flags.
4 years ago
""";
2 years ago
flag decrypt_flag_consume 0x2
4 years ago
doc="""
2 years ago
used by sync to indicate this was a pEp internal message and should be consumed
externally without showing it as a normal message to the user
4 years ago
""";
2 years ago
flag decrypt_flag_ignore 0x4 doc='used by sync';
4 years ago
}
4 years ago
3 years ago
// exceptions
4 years ago
2 years ago
throws error doc="any error status";
3 years ago
throws decrypted doc="if message decrypted but not verified";
3 years ago
throws cannot_reencrypt
4 years ago
doc="""
if message was decrypted (and possibly verified) but a reencryption
operation is expected by the caller and failed.
""";
3 years ago
throws unencrypted
4 years ago
doc="""
if src is unencrypted this function returns unencrypted and sets
4 years ago
dst to empty.
4 years ago
""";
}
2 years ago
method own_message_private_key_details doc="details on own key in own message."
4 years ago
{
3 years ago
// parms
3 years ago
use message msg
doc="""
message to decrypt. msg MUST be encrypted so that this function
can check own signature.
""";
2 years ago
create identity ident
doc="""
identity containing uid, address and fpr of key.
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.
""";
3 years ago
// exceptions
2 years ago
throws illegal_value doc="illegal parameter values";
throws any doc="any other value on error";
4 years ago
}
3 years ago
method outgoing_message_rating doc="get rating for an outgoing message"
4 years ago
{
3 years ago
// parms
3 years ago
use message msg
doc="""
2 years ago
message to get the rating for. From must point to a valid pEp_identity
msg->dir must be PEP_dir_outgoing
3 years ago
""";
3 years ago
return rating msg_rating doc="rating for the message";
3 years ago
// exceptions
2 years ago
throws illegal_value doc="illegal parameter values";
4 years ago
}
3 years ago
method outgoing_message_rating_preview doc="get rating preview"
4 years ago
{
3 years ago
// parms
3 years ago
use message msg
doc="""
message to get the rating for. From must point to a valid pEp_identity.
2 years ago
msg->dir must be dir_outgoing.
3 years ago
""";
3 years ago
return rating msg_rating doc="rating preview for the message";
3 years ago
// exceptions
2 years ago
throws illegal_value doc="illegal parameter values";
4 years ago
}
3 years ago
method identity_rating doc="get rating for a single identity"
4 years ago
{
3 years ago
// parms
3 years ago
use identity ident doc="identity to get the rating for";
3 years ago
return rating identity_rating doc="rating for the identity";
3 years ago
// exceptions
2 years ago
throws illegal_value doc="illegal parameter values";
throws any doc="any other value on error";
4 years ago
}
3 years ago
method get_trustwords doc="get full trustwords string for a *pair* of identities"
4 years ago
{
3 years ago
// parms
3 years ago
use identity id1 doc="identity of first party in communication - fpr can't be empty";
3 years ago
use identity id2 doc="identity of second party in communication - fpr can't be empty";
3 years ago
use ISO639_1 lang doc="string with ISO 639-1 language code";
3 years ago
create string words
4 years ago
doc="""
2 years ago
pointer to string with all trustwords, separated
4 years ago
by a blank each. Empty if language is not supported or trustword
4 years ago
wordlist is damaged or unavailable.
The word pointer goes to the ownership of the caller.
The caller is responsible to free() it (on Windoze use pEp_free())
""";
2 years ago
create size_t wsize doc="length of full trustwords string";
3 years ago
use bool full
4 years ago
doc="""
if true, generate ALL trustwords for these identities.
else, generate a fixed-size subset. (TODO: fixed-minimum-entropy
subset in next version)
""";
3 years ago
// exceptions
3 years ago
throws out_of_memory doc="out of memory";
2 years ago
throws illegal_value doc="illegal parameter values";
3 years ago
throws trustword_not_found doc="at least one trustword not found";
4 years ago
}
3 years ago
method get_message_trustwords doc="get full trustwords string for message sender and reciever identities"
4 years ago
{
3 years ago
// parms
3 years ago
use message msg doc="message to get sender identity from";
3 years ago
use hash_list keylist doc="empty if message to be decrypted, keylist returned by decrypt_message() otherwise.";
3 years ago
use identity received_by doc="identity for account receiving message can't be empty";
3 years ago
use ISO639_1 lang doc="string with ISO 639-1 language code";
3 years ago
create string words
4 years ago
doc="""
2 years ago
pointer to string with all trustwords, separated by a blank each.
4 years ago
Empty if language is not supported or trustword wordlist is damaged or unavailable.
4 years ago
""";
3 years ago
use bool full
4 years ago
doc="""
if true, generate ALL trustwords for these identities.
else, generate a fixed-size subset. (TODO: fixed-minimum-entropy
subset in next version)
""";
3 years ago
// exceptions
2 years ago
throws illegal_value doc="illegal parameter values";
3 years ago
throws out_of_memory doc="out of memory";
3 years ago
throws trustword_not_found doc="at least one trustword not found";
2 years ago
throws cannot_find_identity doc="identity not found";
throws error doc="status of decrypt_message() if decryption fails.";
4 years ago
}
3 years ago
method get_trustwords_for_fprs doc="get full trustwords string for a pair of fingerprints"
4 years ago
{
3 years ago
// parms
3 years ago
use string fpr1 doc="fingerprint 1";
3 years ago
use string fpr2 doc="fingerprint 2";
3 years ago
use ISO639_1 lang doc="string with ISO 639-1 language code";
3 years ago
create string words
doc="""
pointer to string with all trustwords UTF-8 encoded, separated by a blank each.
2 years ago
Empty if language is not supported or trustword wordlist is damaged or unavailable.
3 years ago
The caller is responsible to free() it (on Windoze use pEp_free()).
""";
3 years ago
return size_t wsize doc="length of full trustwords string";
3 years ago
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";
2 years ago
throws illegal_value doc="illegal parameter values";
3 years ago
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
4 years ago
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
4 years ago
contain X-Keylist optional field and x_keylist is empty.
4 years ago
""";
3 years ago
throws out_of_memory doc="if not enough memory could be allocated";
2 years ago
throws any doc="any other value on error";
4 years ago
}
3 years ago
method get_key_rating_for_user doc="get the rating of a certain key for a certain user"
4 years ago
{
3 years ago
// parms
3 years ago
use string user_id doc="string with user ID";
3 years ago
use string fpr doc="string with fingerprint";
3 years ago
return rating key_rating doc="rating of key for this user";
4 years ago
3 years ago
// exceptions
2 years ago
throws illegal_value doc="illegal parameter values";
throws out_of_memory doc="out of memory";
3 years ago
throws record_not_found doc="if no trust record for user_id and fpr can be found";
2 years ago
throws any doc="any other value on error";
3 years ago
}
3 years ago
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
2 years ago
throws rating doc="rating value for comm type ct";
4 years ago
}
4 years ago
}
4 years ago
3 years ago
func color_from_rating doc="calculate color from rating"
4 years ago
{
// parms
4 years ago
3 years ago
use color_from_rating rating doc="color representing that rating";
4 years ago
4 years ago
// return value
3 years ago
return color rating_color doc="color representing that rating";
4 years ago
}
4 years ago
3 years ago
func get_binary_path doc="retrieve path of cryptotech binary if available"
4 years ago
{
4 years ago
//parms
4 years ago
3 years ago
use cryptotech tech doc="cryptotech to get the binary for";
4 years ago
4 years ago
use string path
doc="""
4 years ago
path to cryptotech binary or empty if not available. **path is owned by
3 years ago
the library, do not change it!
""";
4 years ago
}