buff
/
pEpEngine
forked from pEp.foundation/pEpEngine
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

changes

Browse Source
generate_api
nk 4 years ago
parent ca1fb50054
commit ee4130ee64
1 changed files with 361 additions and 361 deletions
Show Stats Download Patch File Download Diff File

722
api/message_api.yml2
Unescape View File

@ -8,49 +8,49 @@
enum text_format {
hex text_format_plain 0;
hex text_format_html 1;
hex text_format_other 0xff;
hex text_format_plain 0;
hex text_format_html 1;
hex text_format_other 0xff;
}
enum msg_direction {
item dir_incoming 0;
item dir_outgoing 1;
item dir_incoming 0;
item dir_outgoing 1;
}
enum enc_format {
item enc_none 0 doc='message is not encrypted';
item enc_pieces 1 doc='inline PGP + PGP extensions';
item enc_S_MIME 2 doc='RFC5751';
item enc_PGP_MIME 3 doc='RFC3156';
item enc_PEP 4 doc='pEp encryption format';
item enc_PGP_MIME_Outlook1 5 doc='Message B0rken by Outlook type 1';
item enc_none 0 doc='message is not encrypted';
item enc_pieces 1 doc='inline PGP + PGP extensions';
item enc_S_MIME 2 doc='RFC5751';
item enc_PGP_MIME 3 doc='RFC3156';
item enc_PEP 4 doc='pEp encryption format';
item enc_PGP_MIME_Outlook1 5 doc='Message B0rken by Outlook type 1';
}
struct message {
field msg_direction dir;
field string id doc='string of message ID';
field string shortmsg doc='string of short message';
field string longmsg doc='string of long message'(plain)';
field string longmsg_formatted doc='string of long message (formatted)';
field bloblist attachments doc='blobs with attachements';
field char rawmsg_ref doc='reference to raw message data';
field size rawmsg_size doc='size of raw message data';
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';
field string in_reply_to doc='list of strings with MessageIDs of refering messages';
field struct _message refering_msg_ref doc='reference to refering message';
field string references doc='list of strings with references';
field struct _message_ref_list refered_by doc='list of references to messages being refered';
field string id doc='string of message ID';
field string shortmsg doc='string of short message';
field string longmsg doc='string of long message'(plain)';
field string longmsg_formatted doc='string of long message (formatted)';
field bloblist attachments doc='blobs with attachements';
field char rawmsg_ref doc='reference to raw message data';
field size rawmsg_size doc='size of raw message data';
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';
field string in_reply_to doc='list of strings with MessageIDs of refering messages';
field struct _message refering_msg_ref doc='reference to refering message';
field string references doc='list of strings with references';
field struct _message_ref_list refered_by doc='list of references to messages being refered';
field string keywords doc='list of strings with keywords';
field string char comments doc='string with comments';
field stringpair_list opt_fields doc='optional fields';
@ -92,11 +92,11 @@ protocol session {
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;
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
@ -111,423 +111,423 @@ 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
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";
create message dst
doc="pointer to new encrypted message or NULL if no encryption could take place";
use const char to_fpr
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
""";
}
use message src doc="message to encrypt";
create message dst
doc="pointer to new encrypted message or NULL if no encryption could take place";
method encrypt_message_for_self
doc="""
encrypt message in memory for user's identity only,
ignoring recipients and other identities from the message
"""
{
// 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";
create message dst doc="pointer to new encrypted message or NULL on failure";
use enc_format format doc="encrypted format";
use const char to_fpr
doc="fingerprint of the recipient key to which the private key should be encrypted";
// flags
use enc_format format doc="encrypted format";
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;
}
// flags
// exceptions doc="(FIXME: This may not be correct or complete)"
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
""";
}
method encrypt_message_for_self
doc="""
encrypt message in memory for user's identity only,
ignoring recipients and other identities from the message
"""
{
// 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";
create message dst doc="pointer to new encrypted message or NULL on failure";
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 doc="(FIXME: This may not be correct or complete)"
throws key_not_found doc="at least one of the receipient keys could not be found";
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";
}
method decrypt_message
doc="decrypt message in memory"
{
// parms
supply message src
doc="""
message to decrypt.
The ownership of src remains with the caller - however, the contents
might be modified (strings freed and allocated anew or set to NULL,
etc) intentionally; when this happens, decrypt_flag_src_modified is set.
""";
create message dst doc="pointer to new decrypted message or NULL on failure";
supply hash_list keylist
doc="""
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 NULL.
""";
return rating msg_rating doc="rating for the message";
// flags
decrypt_flags {
decrypt_flag_own_private_key 0x1
doc="""
private key was imported for one of our addresses (NOT trusted
or set to be used - handshake/trust is required for that)
""";
decrypt_flag_consume 0x2 doc=’used by sync';
decrypt_flag_ignore 0x4 doc=’used by sync';
decrypt_flag_src_modified 0x8
doc="""
indicates that the src object has been modified. At the moment,
this is always as a direct result of the behaviour driven
by the input flags. This flag is the ONLY value that should be
relied upon to see if such changes have taken place.
""";
decrypt_flag_untrusted_server 0x100
doc="""
input flags. Used to signal that decrypt function should engage in behaviour
specified for when the server storing the source is untrusted.
""";
}
throws key_not_found doc="at least one of the receipient keys could not be found";
// exceptions
throws decrypted doc="if message decrypted but not verified";
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";
}
throws cannot_reencrypt
doc="""
if message was decrypted (and possibly verified) but a reencryption
operation is expected by the caller and failed.
""";
throws unencrypted
doc="""
if src is unencrypted this function returns unencrypted and sets
dst to NULL.
""";
method decrypt_message
doc="decrypt message in memory"
{
// parms
supply message src
doc="""
message to decrypt.
The ownership of src remains with the caller - however, the contents
might be modified (strings freed and allocated anew or set to NULL,
etc) intentionally; when this happens, decrypt_flag_src_modified is set.
""";
create message dst doc="pointer to new decrypted message or NULL on failure";
supply hash_list keylist
doc="""
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 NULL.
""";
return rating msg_rating doc="rating for the message";
// flags
decrypt_flags {
decrypt_flag_own_private_key 0x1
doc="""
private key was imported for one of our addresses (NOT trusted
or set to be used - handshake/trust is required for that)
""";
decrypt_flag_consume 0x2 doc=’used by sync';
decrypt_flag_ignore 0x4 doc=’used by sync';
decrypt_flag_src_modified 0x8
doc="""
indicates that the src object has been modified. At the moment,
this is always as a direct result of the behaviour driven
by the input flags. This flag is the ONLY value that should be
relied upon to see if such changes have taken place.
""";
decrypt_flag_untrusted_server 0x100
doc="""
input flags. Used to signal that decrypt function should engage in behaviour
specified for when the server storing the source is untrusted.
""";
}
// exceptions
throws decrypted doc="if message decrypted but not verified";
throws any doc="error status";
}
throws cannot_reencrypt
doc="""
if message was decrypted (and possibly verified) but a reencryption
operation is expected by the caller and failed.
""";
throws unencrypted
doc="""
if src is unencrypted this function returns unencrypted and sets
dst to NULL.
""";
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.
"""
{
//parms
use message msg
doc="""
message to decrypt. msg MUST be encrypted so that this function
can check own signature.
""";
throws any doc="error status";
}
create identity ident doc="identity containing uid, address and fpr of key";
// exceptions
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.
"""
{
//parms
throws any doc="error status"
}
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";
method outgoing_message_rating
doc="get rating for an outgoing message"
{
//parms
// exceptions
use message msg
doc="""
message to get the rating for. From must point to a valid pEp_identity.
Dir must be dir_outgoing.
""";
throws any doc="error status"
}
return rating msg_rating doc="rating for the message";
// exceptions
method outgoing_message_rating
doc="get rating for an outgoing message"
{
//parms
throws any doc="error status"
}
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";
method outgoing_message_rating_preview
doc="get rating preview"
{
//parms
// exceptions
use message msg
doc="""
message to get the rating for. From must point to a valid pEp_identity.
Dir must be dir_outgoing.
""";
throws any doc="error status"
}
return rating msg_rating doc="rating preview for the message";
// exceptions
method outgoing_message_rating_preview
doc="get rating preview"
{
//parms
throws any doc="error status"
}
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";
method identity_rating
doc="get rating for a single identity"
{
//parms
// exceptions
use identity ident doc="identity to get the rating for";
throws any doc="error status"
}
return rating identity_rating doc="rating for the identity";
// exceptions
method identity_rating
doc="get rating for a single identity"
{
//parms
throws any doc="error status"
}
use identity ident doc="identity to get the rating for";
return rating identity_rating doc="rating for the identity";
method get_trustwords
doc="get full trustwords string for a *pair* of identities"
{
//parms
// exceptions
use const identity id1 doc="identity of first party in communication - fpr can't be NULL";
throws any doc="error status"
}
use const identity id2 doc="identity of second party in communication - fpr can't be NULL";
use const char lang doc="C string with ISO 639-1 language code";
method get_trustwords
doc="get full trustwords string for a *pair* of identities"
{
//parms
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.
The word pointer goes to the ownership of the caller.
The caller is responsible to free() it (on Windoze use pEp_free())
""";
use const identity id1 doc="identity of first party in communication - fpr can't be NULL";
create size_t wsize doc="length of full trustwords string";
use const identity id2 doc="identity of second party in communication - fpr can't be NULL";
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)
""";
use const char lang doc="C string with ISO 639-1 language code";
// exceptions
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.
The word pointer goes to the ownership of the caller.
The caller is responsible to free() it (on Windoze use pEp_free())
""";
throws out_of_memory
doc="out of memory";
create size_t wsize doc="length of full trustwords string";
throws trustword_not_found
doc="at least one trustword not found";
}
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
method get_message_trustwords
doc="get full trustwords string for message sender and reciever identities"
{
//parms
throws out_of_memory
doc="out of memory";
use message msg doc="message to get sender identity from";
throws trustword_not_found
doc="at least one trustword not found";
}
use hash_list keylist
doc="NULL if message to be decrypted, keylist returned by decrypt_message() otherwise.";
use identity received_by doc="identity for account receiving message can't be NULL";
method get_message_trustwords
doc="get full trustwords string for message sender and reciever identities"
{
//parms
use string lang doc="C string with ISO 639-1 language code";
use message msg doc="message to get sender identity from";
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.
The word pointer goes to the ownership of the caller.
The caller is responsible to free() it (on Windoze use pEp_free())
""";
use hash_list keylist
doc="NULL if message to be decrypted, keylist returned by decrypt_message() otherwise.";
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)
""";
use identity received_by doc="identity for account receiving message can't be NULL";
// exceptions
use string lang doc="C string with ISO 639-1 language code";
throws out_of_memory doc="out of memory";
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.
The word pointer goes to the ownership of the caller.
The caller is responsible to free() it (on Windoze use pEp_free())
""";
throws trustword_not_found doc="at least one trustword not found";
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)
""";
throws like decrypt_message doc="error status of decrypt_message() if decryption fails"
}
// exceptions
throws out_of_memory doc="out of memory";
method re_evaluate_message_rating
doc="re-evaluate already decrypted message rating"
{
//parms
throws trustword_not_found doc="at least one trustword not found";
use message msg
doc="message to get the rating for. msg->from must point to a valid pEp_identity";
throws like decrypt_message doc="error status of decrypt_message() if decryption fails"
}
use hash_list x_keylist doc="decrypted message recipients keys fpr";
use rating x_enc_status doc="original rating for the decrypted message";
method re_evaluate_message_rating
doc="re-evaluate already decrypted message rating"
{
//parms
return rating msg_rating doc="rating for the message";
use message msg
doc="message to get the rating for. msg->from must point to a valid pEp_identity";
// exceptions
use hash_list x_keylist doc="decrypted message recipients keys fpr";
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 NULL.
""";
use rating x_enc_status doc="original rating for the decrypted message";
throws out_of_memory doc="if not enough memory could be allocated";
}
return rating msg_rating doc="rating for the message";
// exceptions
method get_key_rating_for_user
doc="get the rating of a certain key for a certain user"
{
//parms
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 NULL.
""";
use string user_id doc="string with user ID";
throws out_of_memory doc="if not enough memory could be allocated";
}
use string fpr doc="string with fingerprint";
return rating key_rating doc="rating of key for this user";
// exceptions
method get_key_rating_for_user
doc="get the rating of a certain key for a certain user"
{
//parms
throws record_not_found
doc="if no trust record for user_id and fpr can be found"
}
}
use string user_id doc="string with user ID";
use string fpr doc="string with fingerprint";
// ratings
return rating key_rating doc="rating of key for this user";
// exceptions
ratings {
item rating_undefined 0;
item rating_cannot_decrypt 1;
item rating_have_no_key 2;
item rating_unencrypted 3;
item rating_unencrypted_for_some doc="don't use this any more",
item rating_unreliable 4;
item rating_reliable 5;
item rating_trusted 6;
item rating_trusted_and_anonymized 7;
item rating_fully_anonymous 8;
item rating_mistrust -1;
item rating_b0rken -2;
item rating_under_attack -3;
}
throws record_not_found
doc="if no trust record for user_id and fpr can be found"
}
}
// ratings
ratings {
item rating_undefined 0;
item rating_cannot_decrypt 1;
item rating_have_no_key 2;
item rating_unencrypted 3;
item rating_unencrypted_for_some doc="don't use this any more",
item rating_unreliable 4;
item rating_reliable 5;
item rating_trusted 6;
item rating_trusted_and_anonymized 7;
item rating_fully_anonymous 8;
item rating_mistrust -1;
item rating_b0rken -2;
item rating_under_attack -3;
}
// colors
// colors
colors {
item color_no_color 0;
item color_yellow 1;
item color_green 2;
item color_red -1;
}
colors {
item color_no_color 0;
item color_yellow 1;
item color_green 2;
item color_red -1;
}
func color_from_rating
doc="calculate color from rating"
{
// parms
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 value
return color rating_color doc="color representing that rating"
}
func get_binary_path
doc="retrieve path of cryptotech binary if available"
{
//parms
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 NULL if not available. **path is owned by
the library, do not change it!;
"""
use string path
doc="""
path to cryptotech binary or NULL if not available. **path is owned by
the library, do not change it!;
"""
}

Write Preview
Loading…
Cancel
Save