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