Browse Source

DSL update

pull/55/head
Nana 2 months ago
parent
commit
3c658e9825
3 changed files with 255 additions and 60 deletions
  1. +81
    -9
      api/basic_api.yml2
  2. +78
    -15
      api/keymanagement_api.yml2
  3. +96
    -36
      api/message_api.yml2

+ 81
- 9
api/basic_api.yml2 View File

@ -169,7 +169,7 @@ protocol session {
// exceptions
throws any doc="error status";
throws any doc="any other value on error";
}
@ -219,6 +219,8 @@ protocol session {
ciphersuite for a crypt tech implementation is implementation
defined.
""";
throws illegal_value doc="illegal parameter values";
}
@ -237,6 +239,10 @@ protocol session {
use string description doc="string with long description for event or NULL if omitted";
use string comment doc="string with user defined comment or NULL if omitted";
// exceptions
throws illegal_value doc="illegal parameter values";
}
@ -259,6 +265,10 @@ protocol session {
results were returned, but no ID found (no reason this
should ever occur).
""";
throws illegal_value doc="illegal parameter value";
throws out_of_memory doc="out of memory";
}
@ -267,13 +277,22 @@ protocol session {
// parms
use hash fpr doc="fingerprint of key to mark";
// exceptions
throws illegal_value doc="illegal parameter value";
throws cannot_set_trust:
}
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_with_fpr_return
doc="""
import keys from data, return optional list of fprs imported
""";
{
// parms
@ -283,9 +302,29 @@ protocol session {
create identity_list private_keys
doc="""
list of private keys that have been imported. private_keys can
be left NULL, it is then ignored.
list of identities containing the private keys that have been imported. Private_keys
and imported_keys can be left NULL, it is then ignored.
*** THIS IS THE ACTUAL FUNCTION IMPLEMENTED BY CRYPTOTECH "import_key" ***
""";
create identity_list imported keys doc="if non-NULL, list of actual keys imported"
create identity_list changed_public_keys
doc="""
if non-NULL AND imported_keys is non-NULL: bitvector - corresponds to the first
64 keys imported. If nth bit is set, import changed a key corresponding to the nth
element in imported keys (i.e. key was in DB and was changed by import).
""";
// exceptions
throws out_of_memory doc="out of memory";
throws illegal_value
doc="""
there is no key data to import, or imported keys was NULL and changed_public_keys
was not.
""";
}
@ -293,7 +332,7 @@ protocol session {
{
// parms
use hash fpr doc="key id or fingerprint of key";
use hash fpr doc="fingerprint of key";
create string key_data
doc="""
@ -308,6 +347,8 @@ protocol session {
throws out_of_memory doc="out of memory";
throws key_not_found doc="key not found";
throws illegal_value doc="illegal parameter value";
}
@ -333,6 +374,8 @@ protocol session {
throws key_not_found doc="key not found";
throws cannot_export_key doc="cannot export secret key (i.e. it's on an HKS)";
throws illegal_value doc="illegal parameter value";
}
@ -353,6 +396,14 @@ protocol session {
column3 is description
column4 is comment
""";
// exceptions
throws out_of_memory doc="out of memory";
throws illegal_value doc="illegal parameter value";
throws unknown_error;
}
@ -366,6 +417,14 @@ protocol session {
column 1 is the ISO 639-1 language code
column 2 is the name of the language
""";
// exceptions
throws out_of_memory doc="out of memory";
throws illegal_value doc="illegal parameter value";
throws unknown_error;
}
@ -378,6 +437,16 @@ protocol session {
use int phrase_id doc="id of phrase in i18n";
create string phrase doc="phrase as UTF-8 string";
// exceptions
throws out_of_memory doc="out of memory";
throws illegal_value doc="illegal parameter value";
throws unknown_db_error:
throws phrase_not_found;
}
@ -391,14 +460,13 @@ protocol session {
// exceptions
throws any doc="string to the engine version string constant";
throws engine_version;
}
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
@ -427,13 +495,17 @@ protocol session {
{
// exceptions
throws any doc="path to actual per user directory or NULL on failure";
throws char* doc="path to actual per user directory";
throws NULL doc="on failure";
}
method per_machine_directory doc="returns the directory for pEp system db"
{
// exceptions
throws any doc="path to actual per user directory or NULL on failure";
throws char* doc="path to actual per machine directory";
throws NULL doc="on failure";
}
}

+ 78
- 15
api/keymanagement_api.yml2 View File

@ -49,13 +49,7 @@ protocol session {
*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
""";
throws any doc="any other value on error";
}
@ -86,6 +80,14 @@ protocol session {
if you need to do this asynchronous, you need to return an identity
with retrieve_next_identity() where identity.me is true.
""";
// exceptions
throws illegal_value doc="illegal parameter values";
throws out_of_memory doc="out of memory";
throws any doc="any other value on error";
}
@ -123,6 +125,16 @@ protocol session {
is not trusted, and 3) set this key as the user default if the current user
default is not trusted.
""";
// exceptions
throws key_unsuitable;
throws illegal_value doc="illegal parameter values";
throws out_of_memory doc="out of memory";
throws any doc="any other value on error";
}
@ -146,6 +158,16 @@ protocol session {
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!
""";
// exceptions
throws key_unsuitable;
throws illegal_value doc="illegal parameter values";
throws out_of_memory doc="out of memory";
throws any doc="any other value on error";
}
@ -166,6 +188,14 @@ protocol session {
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).
""";
// exceptions
throws illegal_value doc="illegal parameter values";
throws out_of_memory doc="out of memory";
throws any doc="any other value on error";
}
@ -176,6 +206,12 @@ protocol session {
use hash fpr doc="fingerprint of key to test";
return bool listed doc="flags if key is own";
// exceptions
throws illegal_value doc="illegal parameter values";
throws any doc="any other value on error";
}
@ -189,6 +225,14 @@ protocol session {
list of own identities.
The ownership of the copy of own_identities goes to the caller.
""";
// exceptions
throws illegal_value doc="illegal parameter values";
throws out_of_memory doc="out of memory";
throws any doc="any other value on error";
}
@ -201,6 +245,14 @@ protocol session {
list of fingerprints. This function does not return keys without
a private key part.
""";
// exceptions
throws illegal_value doc="illegal parameter values";
throws out_of_memory doc="out of memory";
throws any doc="any other value on error";
}
@ -210,17 +262,28 @@ protocol session {
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, but caller MUST surrender ownership of the
me->fpr reference, because it may be freed and replaced within the myself call. caller
owns me->fpr memory again upon return.
own identity this key is used for.
The key has to be in the key ring already identity->address must be set to valid
data update_identity() is called by this function and will create a TOFU user_id +
new entry if none is indicated and heuristic fails to match extant identity identity-
>fpr will NOT be updated with the set identity fpr; it is only in,out because
update_identity() is called before setting it.
""";
use hash fpr doc="fingerprint of the key to mark as own key";
// exceptions
throws key_unsuitable;
throws illegal_value
doc="""
illegal parameter values, including if update_identity determines this is an own
identity""";
throws out_of_memory doc="out of memory";
throws any doc="any other value on error";
}
}

+ 96
- 36
api/message_api.yml2 View File

@ -152,6 +152,12 @@ protocol session {
on demand or no recipients with usable key, is left unencrypted,
and key is attached to it
""";
throws illegal_value doc="illegal parameter values";
throws out_of_memory doc="out of memory";
throws any doc="any other value on error";
}
@ -194,6 +200,16 @@ protocol session {
on demand or no recipients with usable key, is left unencrypted,
and key is attached to it
""";
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";
}
@ -231,13 +247,19 @@ protocol session {
flag key_reset_only 0x20;
}
doc | (FIXME: The exceptions may not be correct or complete)
// exceptions
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";
throws cannot_find_identity;
throws illegal_value;
throws out_of_memory;
}
@ -248,9 +270,23 @@ protocol session {
lend 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 empty,
The ownership of src remains with the caller - HOWEVER, the contents
might be modified (strings freed and allocated anew or set to empty,
etc) intentionally; when this happens, decrypt_flag_src_modified is set.
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)
""";
create message dst doc="pointer to new decrypted message or empty on failure";
@ -271,30 +307,33 @@ protocol session {
// flags
flags {
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.
""";
flag decrypt_flag_own_private_key 0x1
doc="""
private key was imported for one of our addresses (NOT trusted
outgoing flag: private key was imported for one of our addresses (NOT trusted
or set to be used - handshake/trust is required for that)
""";
flag decrypt_flag_consume 0x2 doc='used by sync';
flag decrypt_flag_ignore 0x4 doc='used by sync';
flag 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.
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.
""";
flag decrypt_flag_untrusted_server 0x100
flag decrypt_flag_consume 0x2
doc="""
input flag. Used to signal that decrypt function should engage in behaviour
specified for when the server storing the source is untrusted.
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
""";
flag decrypt_flag_dont_trigger_sync 0x200;
flag decrypt_flag_ignore 0x4 doc='used by sync';
}
// exceptions
throws error doc="any error status";
throws decrypted doc="if message decrypted but not verified";
throws cannot_reencrypt
@ -308,18 +347,10 @@ protocol session {
if src is unencrypted this function returns unencrypted and sets
dst to empty.
""";
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.
"""
method own_message_private_key_details doc="details on own key in own message."
{
// parms
@ -329,11 +360,20 @@ protocol session {
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.
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.
""";
// exceptions
throws any doc="error status";
throws illegal_value doc="illegal parameter values";
throws any doc="any other value on error";
}
@ -343,15 +383,15 @@ protocol session {
use message msg
doc="""
message to get the rating for. From must point to a valid pEp_identity.
Dir must be dir_outgoing.
message to get the rating for. From must point to a valid pEp_identity
msg->dir must be PEP_dir_outgoing
""";
return rating msg_rating doc="rating for the message";
// exceptions
throws any doc="error status";
throws illegal_value doc="illegal parameter values";
}
@ -362,14 +402,14 @@ protocol session {
use message msg
doc="""
message to get the rating for. From must point to a valid pEp_identity.
Dir must be dir_outgoing.
msg->dir must be dir_outgoing.
""";
return rating msg_rating doc="rating preview for the message";
// exceptions
throws any doc="error status";
throws illegal_value doc="illegal parameter values";
}
@ -383,7 +423,9 @@ protocol session {
// exceptions
throws any doc="error status";
throws illegal_value doc="illegal parameter values";
throws any doc="any other value on error";
}
@ -399,12 +441,14 @@ protocol session {
create string words
doc="""
string with all trustwords, separated
pointer to string with all trustwords, separated
by a blank each. Empty 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())
""";
create size_t wsize doc="length of full trustwords string";
use bool full
doc="""
@ -416,6 +460,8 @@ protocol session {
// exceptions
throws out_of_memory doc="out of memory";
throws illegal_value doc="illegal parameter values";
throws trustword_not_found doc="at least one trustword not found";
}
@ -435,7 +481,7 @@ protocol session {
create string words
doc="""
string with all trustwords, separated by a blank each.
pointer to string with all trustwords, separated by a blank each.
Empty if language is not supported or trustword wordlist is damaged or unavailable.
""";
@ -448,11 +494,15 @@ protocol session {
// exceptions
throws illegal_value doc="illegal parameter values";
throws out_of_memory doc="out of memory";
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 cannot_find_identity doc="identity not found";
throws error doc="status of decrypt_message() if decryption fails.";
}
@ -469,7 +519,7 @@ protocol session {
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.
Empty if language is not supported or trustword wordlist is damaged or unavailable.
The caller is responsible to free() it (on Windoze use pEp_free()).
""";
@ -484,6 +534,8 @@ protocol session {
// exceptions
throws out_of_memory doc="out of memory";
throws illegal_value doc="illegal parameter values";
throws trustword_not_found doc="at least one trustword not found";
}
@ -511,6 +563,8 @@ protocol session {
""";
throws out_of_memory doc="if not enough memory could be allocated";
throws any doc="any other value on error";
}
@ -526,7 +580,13 @@ protocol session {
// exceptions
throws illegal_value doc="illegal parameter values";
throws out_of_memory doc="out of memory";
throws record_not_found doc="if no trust record for user_id and fpr can be found";
throws any doc="any other value on error";
}
@ -538,7 +598,7 @@ protocol session {
// exceptions
throws any doc="rating value for comm type ct";
throws rating doc="rating value for comm type ct";
}
}


Loading…
Cancel
Save