diff --git a/api/basic_api.yml2 b/api/basic_api.yml2 index ced402f1..bd8483e9 100644 --- a/api/basic_api.yml2 +++ b/api/basic_api.yml2 @@ -7,12 +7,12 @@ // written by Nana Karlstetter and Volker Birk -type ISO639_1 is string size=2 > a-z +type ISO639_1 is string size=2 > a-z; -type hex is string > a-f0-9 +type hexcode is string > a-f0-9; -type hash doc="32bit Key ID to SHA512 in hex" - is hex min=16, max=128; +type hash doc="32bit Key ID to SHA512 in hexcode" + is hexcode min=16, max=128; type hash_list doc="sequence of fingerprints of keys" is list< hash >; @@ -24,11 +24,24 @@ type blob_list is list< blob >; type identity_list is list< identity >; -type string_list is list< string > ; +type string_list is list< string >; type string_pair is pair< string, string >; +enum cipher_suite { + item cipher_suite_default 0; + item cipher_suite_cv25519 1; + item cipher_suite_p256 2; + item cipher_suite_p384 3; + item cipher_suite_p521 4; + item cipher_suite_rsa2k 5; + item cipher_suite_rsa3k 6; + item cipher_suite_rsa4k 7; + item cipher_suite_rsa8k 8; +} + + enum comm_type { hex unknown 0; @@ -91,7 +104,7 @@ enum comm_type { doc > range 0xc0 to 0xff: confirmed encryption and anonymization hex confirmed_enc_anon 0xc0 doc="generic"; - hex pEp 0xff + hex pEp 0xff; } // enum comm_type @@ -103,32 +116,293 @@ struct identity { field string user_id doc="ID for person or entity in M2M case"; field string username doc="descriptive string"; field ISO639_1 lang doc="two-digit language code or null bytes"; +} // struct Identity + + +flags { + flag not_for_sync 0x0001 + doc="don't use this identity for Sync"; - flags { - flag not_for_sync 0x0001 - doc="don't use this identity for Sync"; + flag list 0x0002 + doc="identity of list of persons"; - flag list 0x0002 - doc="identity of list of persons"; + doc | the second octet flags are calculated - doc | the second octet flags are calculated + flag devicegroup 0x0100 + doc="identity of a device group member"; +} + + +protocol session { + callback messageToSend + doc="a message needs to be delivered by application" + { + // parms - flag devicegroup 0x0100 - doc="identity of a device group member" + provide struct_message msg doc="message struct with message to send"; + + // exceptions + + throws any doc="error status"; } -} // struct Identity + method config_passive_mode + doc="enable passive mode" + { + // parms -callback messageToSend - doc="a message needs to be delivered by application" -{ - // parms + use bool enable doc="flag if enabled or disabled"; + } - provide struct_message msg doc="message struct with message to send" - // exceptions + method config_unencrypted_subject + doc="disable subject encryption" + { + // parms - throws any doc="error status" -} + use bool enable doc="flag if enabled or disabled"; + } + + + method config_use_only_own_private_keys + doc="enable passive mode" + { + // parms + + use bool enable doc="flag if enabled or disabled"; + } + + + method config_service_log + doc="log more for service purposes" + { + // parms + + use bool enable doc="flag if enabled or disabled"; + } + + + method config_cipher_suite + doc="cipher suite being used when encrypting" + { + // parms + + use suite cipher_suite doc="cipher suite to use"; + + // exceptions + + throws cannot_config + 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. + """ + { + // parms + + use string title doc="string with event name"; + + use string entity doc="string with name of entity which is logging"; + + 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"; + } + + + method get_default own_userid + doc="get the user_id of the own user" + { + // parms + + create string userid + doc=""" + own user id (if it exists). userid will be NULL if not found; otherwise, + returned string belongs to the caller. + """ + + // exceptions + + throws cannot_find_identity doc="no own_user found in the DB"; + + throws unknown_error + doc=""" + results were returned, but no ID found (no reason this + should ever occur). + """; + } + + + method mark_as_compromised + doc="mark key in trust db as compromised" + { + // parms + + 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 import_key + doc="import key from data" + { + // parms + + use string key_data doc="key data, i.e. ASCII armored OpenPGP key"; + + use size_t size doc="amount of data to handle"; + + create identity_list private_keys + doc=""" + list of private keys that have been imported. private_keys can + be left NULL, it is then ignored. + """; + } + + + method export_key + doc="export ascii armored key" + { + // parms + + use hash fpr doc="key id or fingerprint of key"; + + create string key_data + doc=""" + ASCII armored OpenPGP key. The key_data goes to the ownership of the + caller. The caller is responsible to free() it (on Windoze use pEp_free()) + """; + + return size_t size doc="amount of data to handle"; + + // exceptions + + throws out_of_memory doc="out of memory"; + + throws key_not_found doc="key not found"; + } + + + method export_secret_key + doc="export secret key ascii armored" + { + // parms + + use hash fpr doc="fingerprint of key, at least 16 hex digits" + + create string key_data + doc=""" + ASCII armored OpenPGP secret key. The key_data goes to the ownership of the + caller. The caller is responsible to free() it (on Windoze use pEp_free()). + beware of leaking secret key data - overwrite it in memory after use! + """; + + return size_t size doc="amount of data to handle"; + + // exceptions + + throws out_of_memory doc="out of memory"; + + throws key_not_found doc="key not found"; + + throws cannot_export_key doc="cannot export secret key (i.e. it's on an HKS)"; + } + + + 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" + { + // parms + + use int maxlines doc="maximum number of lines (0 for default)"; + + create string logdata + doc=""" + logdata as string in double quoted CSV format + column1 is title + column2 is entity + column3 is description + column4 is comment + """; + } + + + method get_languagelist + doc="get the list of languages" + { + //parms + + create string language + doc=""" + languages as string in double quoted CSV format + column 1 is the ISO 639-1 language code + column 2 is the name of the language + """; + } + + + method get_phrase + doc="get phrase in a dedicated language through i18n" + { + // parms + + use string lang doc="string with ISO 639-1 language code"; + + use int phrase_id doc="id of phrase in i18n"; + + create string phrase doc="phrase as UTF-8 string"; + } + + + method get_engine_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" + + 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 + + use identity ident + doc=""" + identity containing the user_id to check (this is the only part of + the struct we require to be set). + """; + + return bool is_pEp + doc=""" + boolean pointer - will return true or false by reference with respect + to whether or not user is a known pEp user + """; + + // exceptions + + throws illegal_value doc="if no user_id in input"; + + throws cannot_find_person doc="if user_id doesn't exist"; + } +} diff --git a/api/keymanagement_api.yml2 b/api/keymanagement_api.yml2 index ff4c58e6..ba337e2b 100644 --- a/api/keymanagement_api.yml2 +++ b/api/keymanagement_api.yml2 @@ -41,22 +41,22 @@ protocol session { 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 - """ + // 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 + """ } @@ -198,16 +198,20 @@ protocol session { } -method own_keys_retrieve - doc="retrieve all flagged keypair fingerprints" + method own_keys_retrieve + doc="retrieve all flagged keypair fingerprints/private keypair fingerprints" { // parms - create hashlist keylist doc="list of fingerprints" + create hashlist keylist + doc=""" + list of fingerprints. This function does not return keys without + a private key part. + """ } -method set_own_key + method set_own_key doc="mark a key as own key" { // parms