buff
/
pEpEngine
forked from pEp.foundation/pEpEngine
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

neuer stand

Browse Source
generate_api
nk 4 years ago
parent 703fd993e2
commit 4e1cc6aaf9
4 changed files with 122 additions and 152 deletions
Show Stats Download Patch File Download Diff File

13
api/basic_api.yml2
Unescape View File

@ -28,18 +28,6 @@ type string_list is list< string > ;
type string_pair is pair< string, string >;
// string: text
// int: integer number
// blob: Binary Large Object
// size_t: size in memory
// const:
// identity:
// message:
// rating:
// enc_format:
// bool:
// cryptotech:
enum comm_type {
hex unknown 0;
@ -131,3 +119,4 @@ struct identity {
} // struct Identity

211
api/keymanagement_api.yml2
Unescape View File

@ -60,31 +60,6 @@ protocol session {
}
method initialise_own_identities
doc="ensures that an own identity is complete"
{
// parms
supply identity_list my_idents
doc="""
identities of local user to quick-set
For these, at least .address must be set.
if no .user_id is set, AND the DB doesn't contain
a default user_id, own_userid will be used and
become the perennial default for the DB.
This function does NOT generate keypairs. It is intended to
precede running of the engine on actual messages. It effectively
behaves like myself(), but when there would normally be key generation
(when there is no valid key, for example),
it instead stores an identity without keys.
N.B. to adapter devs - this function is likely unnecessary, so please
do not put work into exposing it yet. Tickets will be filed if need be.
"""
}
method myself
doc="ensures that an own identity is complete"
{
@ -115,53 +90,6 @@ protocol session {
"""
}
method retrieve_next_identity
doc="callback being called by do_keymanagement"
{
// parms
XXXXXX
method examine_identity
doc="callback for appending to queue"
{
// parms
XXXX
method register_examine_function
doc="register examine_identity() callback"
{
//parms
provide?? examine_identity?? examine_identity doc="examine_identity() function to register";
provide void management doc="data structure to deliver (implementation defined)"
XXX?
// do_keymanagement() - function to be run on an extra thread
//
// parameters:
// retrieve_next_identity (in) pointer to retrieve_next_identity()
// callback which returns at least a valid
// address field in the identity struct
//
// return value:
// PEP_STATUS_OK if thread has to terminate successfully or any other
// value on failure
//
// caveat:
// to ensure proper working of this library, a thread has to be started
// with this function immediately after initialization
//
// do_keymanagement() calls retrieve_next_identity(management)
//
// messageToSend can only be null if no transport is application based
// if transport system is not used it must not be NULL
DYNAMIC_API PEP_STATUS do_keymanagement(
retrieve_next_identity_t retrieve_next_identity,
void *management
method key_mistrusted
doc="mark key as being compromised"
@ -183,37 +111,118 @@ DYNAMIC_API PEP_STATUS do_keymanagement(
}
method trust_personal_key
method trust_personal_key
doc="mark a key as trusted for a user"
{
// parms
ident (in) person and key to trust in - this must not be an
// own_identity in which the .me flag is set or
// the user_id is an own user_id.
//
// caveat:
// the fields user_id, address and fpr must be supplied
// own identities will result in a return of PEP_ILLEGAL_VALUE.
// for non-own users, this will 1) set the trust bit on its comm type in the DB,
// 2) set this key as the identity default if the current identity default
// is not trusted, and 3) set this key as the user default if the current
// user default is not trusted.
DYNAMIC_API PEP_STATUS trust_personal_key(
PEP_SESSION session,
pEp_identity *ident
use identity ident
doc="""
person and key to trust in - this must not be an own_identity in which
the .me flag is set or the user_id is an own user_id. The fields user_id,
address and fpr must be supplied own identities will result in a return
of illegal_value.
For non-own users, this will 1) set the trust bit on its comm type in the DB,
2) set this key as the identity default if the current identity default
is not trusted, and 3) set this key as the user default if the current user
default is not trusted.
"""
}
method trust_own_key
doc="""
mark a key as trusted for self, generally used when we need to trust
a public key associated with outselves for issues like manual key import.
"""
{
// parms
use identity ident
doc="""
own ident containing fpr to trust.
If this is a public key only, keep in mind that if the private part of the
keypair is later added, it will not undergo separate trust evaluation. This
is fine - even desired - as long as the semantics of this function are
understood as both trusting the key and verifying it as an own key. This will
NEVER cause replacement of or setting of a default *alone*. However, if a
private key is ever associated with this fpr, please keep in mind that trusting
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!
"""
}
method key_reset_trust
doc="""
reset trust bit or explicitly mistrusted status for an identity and its
accompanying key/user_id pair.
"""
{
// parms
use ientity ident
doc="""
identity for person and key whose trust status is to be reset.
Ident is INPUT ONLY. If you want updated trust on the identity, you'll have
to call update_identity or myself respectively after this.
N.B. If you are calling this on a key that is the identity or user default,
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).
"""
}
method own_key_is_listed
doc="returns true id key is listed as own key"
{
// parms
use hash fpr doc="fingerprint of key to test"
return bool listed doc="flags if key is own"
}
method own_identities_retrieve
doc="retrieve all own identities"
{
// parms
create identity_list own_identities
doc="""
list of own identities.
The ownership of the copy of own_identities goes to the caller.
"""
}
method own_keys_retrieve
doc="retrieve all flagged keypair fingerprints"
{
// parms
create hashlist keylist doc="list of fingerprints"
}
method set_own_key
doc="mark a key as own key"
{
// parms
supply 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.
"""
use hash fpr (in) fingerprint of the key to mark as own key
}
}

39
api/message_api.yml2
Unescape View File

@ -243,27 +243,27 @@ protocol session {
// flags
decrypt_flags {
decrypt_flag_own_private_key 0x1
flags {
flag decrypt_flag_own_private_key 0x1
doc="""
private key was imported for one of our addresses (NOT trusted
or set to be used - handshake/trust is required for that)
""";
decrypt_flag_consume 0x2 doc=’used by sync';
decrypt_flag_ignore 0x4 doc=’used by sync';
decrypt_flag_src_modified 0x8
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.
""";
decrypt_flag_untrusted_server 0x100
flag decrypt_flag_untrusted_server 0x100
doc="""
input flags. Used to signal that decrypt function should engage in behaviour
specified for when the server storing the source is untrusted.
""";
}
}
// exceptions
@ -479,7 +479,7 @@ protocol session {
throws record_not_found
doc="if no trust record for user_id and fpr can be found"
}
}
}
func color_from_rating
@ -493,7 +493,7 @@ func color_from_rating
return color rating_color doc="color representing that rating"
}
func get_binary_path
doc="retrieve path of cryptotech binary if available"
{
@ -508,24 +508,3 @@ func get_binary_path
the library, do not change it!;
"""
}

11
api/pEp.yml2
Unescape View File

@ -38,21 +38,14 @@ decl return @type @name (mode=return) alias parm;
decl throws @except;
decl caveat(mode=caveat) alias doc;
// base types
// string: text
// int: integer number
// blob: Binary Large Object
// size_t: size in memory
// const:
// identity:
// message:
// rating:
// enc_format:
// hash:
// TID:
// bool:
// cryptotech:
// bool: true or false
// collections

Write Preview
Loading…
Cancel
Save