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.
 
 
 
 

420 lines
11 KiB

// p≡p Basic API
// Copyleft (c) 2019, p≡p foundation
// this file is under GNU General Public License 3.0
// see LICENSE.txt
// written by Nana Karlstetter and Volker Birk
type ISO639_1 is string size=2 > a-z;
type hexcode is string > a-f0-9;
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 >;
type TID doc="UUID version 4 variant 1"
is binary size=16;
type blob_list is list< blob >;
type identity_list is list< identity >;
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;
doc > range 0x01 to 0x09: no encryption, 0x0a to 0x0e: nothing reasonable
hex no_encryption 0x01 doc="generic";
hex no_encrypted_channel 0x02;
hex key_not_found 0x03;
hex key_expired 0x04;
hex key_revoked 0x05;
hex key_b0rken 0x06;
hex key_expired_but_confirmed 0x07
doc="NOT with confirmed bit. Just retaining info here in case of renewal.";
hex my_key_not_included 0x09;
hex security_by_obscurity 0x0a;
hex b0rken_crypto 0x0b;
hex key_too_short 0x0c;
hex compromised 0x0e doc="known compromised connection";
hex compromized 0x0e doc="deprecated misspelling";
hex mistrusted 0x0f doc="known mistrusted key";
doc > range 0x10 to 0x3f: unconfirmed encryption
hex unconfirmed_encryption 0x10 doc="generic";
hex OpenPGP_weak_unconfirmed 0x11 doc="RSA 1024 is weak";
hex to_be_checked 0x20 doc="generic";
hex SMIME_unconfirmed 0x21 doc="encrypted with S/MIME";
hex CMS_unconfirmed 0x22;
hex strong_but_unconfirmed 0x30 doc="generic";
hex OpenPGP_unconfirmed 0x38 doc="key at least 2048 bit RSA, EC, or anything useful";
hex OTR_unconfirmed 0x3a doc="encrypted with OTR";
doc > range 0x40 to 0x7f: unconfirmed encryption and anonymization
hex unconfirmed_enc_anon 0x40 doc="generic";
hex pEp_unconfirmed 0x7f doc="encrypted with pEp";
hex confirmed 0x80 doc="this bit decides if trust is confirmed";
doc > range 0x81 to 0x8f: reserved
doc > range 0x90 to 0xbf: confirmed encryption
hex confirmed_encryption 0x90 doc="generic";
hex OpenPGP_weak 0x91 doc="RSA 1024 is weak (unused)";
hex to_be_checked_confirmed 0xa0 doc="generic";
hex SMIME 0xa1;
hex CMS 0xa2;
hex strong_encryption 0xb0 doc="generic";
hex OpenPGP 0xb8 doc="key at least 2048 bit RSA or EC";
hex OTR 0xba;
doc > range 0xc0 to 0xff: confirmed encryption and anonymization
hex confirmed_enc_anon 0xc0 doc="generic";
hex pEp 0xff;
} // enum comm_type
struct identity {
field string address doc="SMTP address or URI. String with address UTF-8 encoded";
field hash fpr doc="fingerprint of key being used as ID. String with fingerprint UTF-8 encoded";
field string user_id doc="ID for person or system in case of M2M";
doc ||
user_id MIGHT be set to "pEp_own_userId" (use PEP_OWN_USERID preprocessor define)
if this is own user's identity. But it is not REQUIRED to be.
||
field string username doc="descriptive string. String with user name UTF-8 encoded";
field comm_type comm_type doc="type of communication with this ID";
field ISO639_1 lang[3] doc="ISO 639-1 ALPHA-2, last byte is 0";
field bool me doc="if this is the local user herself/himself";
field unsigned major_ver doc="highest version of pEp message received, if any";
field unsigned minor_ver doc="highest version of pEp message received, if any";
field identity_flags_t flags doc="identity_flag1 | identity_flag2 | ...";
} // struct Identity
flags {
flag not_for_sync 0x0001
doc="don't use this identity for Sync";
flag list 0x0002
doc="identity of list of persons";
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
provide struct_message msg doc="message struct with message to send";
// exceptions
throws any doc="error status";
}
method config_passive_mode doc="enable passive mode"
{
// parms
use bool enable doc="flag if enabled or disabled";
}
method config_unencrypted_subject doc="disable subject encryption"
{
// parms
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"
// exceptions
throws any doc="string 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";
}
method per_user_directory doc="returns the directory for pEp management db"
{
// exceptions
throws any doc="path to actual per user directory or NULL 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";
}
}