Browse Source

neu

generate_api
nk 3 years ago
parent
commit
52c7cb5bfa
2 changed files with 321 additions and 43 deletions
  1. +297
    -23
      api/basic_api.yml2
  2. +24
    -20
      api/keymanagement_api.yml2

+ 297
- 23
api/basic_api.yml2 View File

@ -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";
}
}

+ 24
- 20
api/keymanagement_api.yml2 View File

@ -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


Loading…
Cancel
Save