Browse Source

not finished. as far as I got today. for tm

generate_api
nk 4 years ago
parent
commit
c9fe86eae0
2 changed files with 412 additions and 139 deletions
  1. +210
    -0
      api/keymanagement_api.yml2
  2. +202
    -139
      api/message_api.yml2

+ 210
- 0
api/keymanagement_api.yml2 View File

@ -7,3 +7,213 @@
// written by Volker Birk
protocol session {
method update_identity
doc="update identity information"
{
// parms
supply identity identity
doc="""
identity information of communication partner
(identity->fpr is OUT ONLY), and at least
.address must be set.
If .username is set, it will be used to set or patch
the username record for this identity.
at least identity->address must be a non-empty UTF-8 string as input
update_identity() never writes flags; use set_identity_flags() for
writing
this function NEVER reads the incoming fpr, only writes to it.
this function will fail if called on an identity which, with its input
values, *explicitly* indicates it is an own identity (i.e. .me is set
to true on input, or a user_id is given AND it is a known own user_id).
however, it can RETURN an own identity if this is not indicated a
priori, and in fact will do so with prejudice when not faced with a
matching default (i.e. it is forced to search by address only).
if the identity is known to be an own identity (or the caller wishes
to make it one), call myself() on the identity instead.
FIXME: is this next point accurate?
if this function returns PEP_ct_unknown or PEP_ct_key_expired in
identity->comm_type, the caller must insert the identity into the
asynchronous management implementation, so retrieve_next_identity()
will return this identity later
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
"""
}
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"
{
// parms
supply identity identity
doc="""
identity of local user
both .address and .user_id must be set.
if .fpr is set, an attempt will be made to make
that the default key for this identity after key validation
if .fpr is not set, key retrieval is performed.
If .username is set, it will be used to set or patch
the username record for this identity.
If an fpr was entered and is not a valid key, the reason for failure
is immediately returned in the status and, possibly, identity->comm_type
If a default own user_id exists in the database, an alias will
be created for the default for the input user_id. The ENGINE'S default
user_id is always returned in the .user_id field
myself() NEVER elects keys from the keyring; it will only choose keys
which have been set up explicitly via myself(), or which were imported
during a first time DB setup from an OpenPGP keyring (compatibility only)
this function generates a keypair on demand; because it's synchronous
it can need a decent amount of time to return
if you need to do this asynchronous, you need to return an identity
with retrieve_next_identity() where identity.me is true.
"""
}
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"
{
//parms
use identity ident
doc="""
person and key which was compromised
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 ANY identity and user for which
it is the default. Please keep in mind that the undo in undo_last_mistrust
will only undo the current identity's / it's user's default, not any
other identities which may be impacted (this will not affect most use
cases)
"""
}
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

+ 202
- 139
api/message_api.yml2 View File

@ -7,6 +7,70 @@
// written by Volker Birk
enum text_format {
hex text_format_plain 0x0;
hex text_format_html 0x01;
hex text_format_other 0xff;
}
enum msg_direction {
hex dir_incoming 0x0;
hex dir_outgoing 0x01;
}
enum enc_format {
hex enc_none 0x0 doc='message is not encrypted';
hex enc_pieces 0x01 doc='inline PGP + PGP extensions';
hex enc_S_MIME 0x02 doc='RFC5751';
hex enc_PGP_MIME 0x04 doc='RFC3156';
hex enc_PEP 0x08 doc='pEp encryption format';
hex enc_PGP_MIME_Outlook1 0x10 doc='Message B0rken by Outlook type 1';
}
enum message_wrap_type {
message_default doc='typical inner/outer message 2.0';
message_transport doc='e.g. for onion layers';
message_key_reset doc='for wrapped key reset information';
}
struct message {
field msg_direction dir;
field string id doc='UTF-8 string of message ID';
field string shortmsg doc='UTF-8 string of short message';
field string longmsg doc='UTF-8 string of long message'(plain)';
field string longmsg_formatted doc='UTF-8 string of long message (formatted)';
field bloblist_t attachments doc='blobs with attachements';
field char rawmsg_ref doc='reference to raw message data';
field size_t rawmsg_size doc='size of raw message data';
field timestamp sent doc='when the message is sent';
field timestamp recv doc='when the message is received';
field pEp_identity from doc='whom the message is from';
field identity_list to doc='whom the message is to';
field pEp_identity recv_by doc='via which identity the message is received';
field identity_list cc doc='whom a CC is being sent';
field identity_list bcc doc='whom a BCC is being sent';
field identity_list reply_to doc='where a reply should go to';
field string in_reply_to doc='list of UTF-8 strings with MessageIDs of refering messages';
field struct _message refering_msg_ref doc='reference to refering message';
field string references doc='list of UTF-8 strings with references';
field struct _message_ref_list refered_by doc='list of references to messages being refered';
field string keywords doc='list of UTF-8 strings with keywords';
field string char comments doc='UTF-8 string with comments';
field stringpair_list_t opt_fields doc='optional fields';
field enc_format enc_format doc='format of encrypted data';
}
struct message_ref_list {
field message msg_ref doc='reference to message';
field struct _message_ref_list next;
}
protocol session {
method encrypt_message
doc="encrypt message in memory"
@ -26,9 +90,9 @@ protocol session {
doc="""
pointer to new encrypted message or #NV if no encryption could
take place
"""
""";
use enc_format enc_format doc="encrypted format";
use enc_format format doc="encrypted format";
// flags
@ -39,19 +103,18 @@ protocol session {
flag force_no_attached_key 0x4;
flag inner_message 0x8 doc='This is mainly used by pEp clients to send private keys to their own PGP-only device.';
flag force_version_1 0x10 doc='This is mainly used by pEp clients to send private keys to their own PGP-only device';
flag key_reset_only 0x20
flag key_reset_only 0x20;
}
// exceptions
throws key_has_ambig_name
doc="at least one of the receipient keys has an ambiguous name";
throws key_has_ambig_name doc="at least one of the receipient keys has an ambiguous name";
throws unencrypted
doc="""
on demand or no recipients with usable key, is left unencrypted,
and key is attached to it
"""
""";
}
@ -63,12 +126,12 @@ protocol session {
use message src doc="message to encrypt";
create message dst
doc="pointer to new encrypted message or NULL if no encryption could take place";
doc="pointer to new encrypted message or NULL if no encryption could take place";
const char to_fpr
doc="fingerprint of the recipient key to which the private key should be encrypted";
use const char to_fpr
doc="fingerprint of the recipient key to which the private key should be encrypted";
use enc_format enc_format doc="encrypted format";
use enc_format format doc="encrypted format";
// flags
@ -79,19 +142,18 @@ protocol session {
flag force_no_attached_key 0x4;
flag inner_message 0x8 doc='This is mainly used by pEp clients to send private keys to their own PGP-only device.';
flag force_version_1 0x10 doc='This is mainly used by pEp clients to send private keys to their own PGP-only device';
flag key_reset_only 0x20
flag key_reset_only 0x20;
}
// exceptions
throws key_has_ambig_name
doc="at least one of the receipient keys has an ambiguous name";
throws key_has_ambig_name doc="at least one of the receipient keys has an ambiguous name";
throws unencrypted
doc="""
on demand or no recipients with usable key, is left unencrypted,
and key is attached to it
"""
""";
}
@ -105,17 +167,17 @@ protocol session {
use identity target_id
doc="""
self identity this message should be encrypted for. message is NOT encrypted for
identities other than the target_id (and then, only if the target_id refers to self!)
self identity this message should be encrypted for. Message is NOT encrypted for
identities other than the target_id (and then, only if the target_id refers to self!).
""";
use message src doc="message to encrypt";
provide hash_list extra doc="extra keys for encryption";
use hash_list extra doc="extra keys for encryption";
create message dst doc="pointer to new encrypted message or NULL on failure";
use enc_format enc_format? doc="encrypted format";
use enc_format format doc="encrypted format";
// flags
@ -126,59 +188,16 @@ protocol session {
flag force_no_attached_key 0x4;
flag inner_message 0x8 doc='This is mainly used by pEp clients to send private keys to their own PGP-only device.';
flag force_version_1 0x10 doc='This is mainly used by pEp clients to send private keys to their own PGP-only device';
flag key_reset_only 0x20
flag key_reset_only 0x20;
}
// exceptions
// exceptions doc="(FIXME: This may not be correct or complete)"
throws key_not_found
doc="at least one of the receipient keys could not be found";
throws key_not_found doc="at least one of the receipient keys could not be found";
throws key_has_ambig_name
doc="at least one of the receipient keys has an ambiguous name";
throws key_has_ambig_name doc="at least one of the receipient keys has an ambiguous name";
throws get_key_failed
doc="cannot retrieve key"
}
method color_from_rating
doc="calculate color from rating"
{
// parms
provide color_from_rating rating
doc="color representing that rating";
// ratings
ratings {
rating_undefined 0;
rating_cannot_decrypt,
rating_have_no_key,
rating_unencrypted,
rating_unencrypted_for_some doc="don't use this any more",
rating_unreliable,
rating_reliable,
rating_trusted,
rating_trusted_and_anonymized,
rating_fully_anonymous,
rating_mistrust -1;
rating_b0rken -2;
rating_under_attack -3
}
// colors
colors {
color_no_color 0;
color_yellow,
color_green,
color_red -1
}
// return value
doc="color representing that rating"
throws get_key_failed doc="cannot retrieve key";
}
@ -195,8 +214,7 @@ protocol session {
etc) intentionally; when this happens, decrypt_flag_src_modified is set.
""";
create message dst
doc="pointer to new decrypted message or NULL on failure";
create message dst doc="pointer to new decrypted message or NULL on failure";
supply hash_list keylist
doc="""
@ -205,10 +223,11 @@ protocol session {
out: stringlist with keyids used for signing and encryption. first
first key is signer, additional keys are the ones it was encrypted
to. Only signer and whichever of the user's keys was used are reliable.
The ownership of keylist goes to the caller.
If src is unencrypted this function returns unencrypted and sets dst to NULL.
""";
return rating rating
doc="rating for the message";
return rating msg_rating doc="rating for the message";
// flags
@ -217,7 +236,7 @@ protocol session {
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
@ -231,13 +250,12 @@ protocol session {
doc="""
input flags. Used to signal that decrypt function should engage in behaviour
specified for when the server storing the source is untrusted.
"""
""";
}
// exceptions
throws decrypted
doc="if message decrypted but not verified";
throws decrypted doc="if message decrypted but not verified";
throws cannot_reencrypt
doc="""
@ -249,12 +267,19 @@ protocol session {
doc="""
if src is unencrypted this function returns unencrypted and sets
dst to NULL.
"""
""";
throws any doc="error status";
}
method own_message_private_key_details
doc="details on own key in own message"
doc="""
details on own key in own message. Note: In order to obtain details about key
to be possibly imported as a replacement of key currently used as own identity,
application passes message that have been previously flagged by decrypt_message()
as own message containing own key to this function.
"""
{
//parms
@ -264,8 +289,11 @@ protocol session {
can check own signature.
""";
create identity ident
doc="identity containing uid, address and fpr of key"
create identity ident doc="identity containing uid, address and fpr of key";
// exceptions
throws any doc="error status"
}
@ -280,8 +308,11 @@ protocol session {
Dir must be dir_outgoing.
""";
create rating rating
doc="rating for the message"
return rating msg_rating doc="rating for the message";
// exceptions
throws any doc="error status"
}
@ -296,8 +327,11 @@ protocol session {
Dir must be dir_outgoing.
""";
create rating rating
doc="rating preview for the message"
return rating msg_rating doc="rating preview for the message";
// exceptions
throws any doc="error status"
}
@ -306,27 +340,13 @@ protocol session {
{
//parms
use identity ident
doc="identity to get the rating for";
create rating rating
doc="rating for the identity"
}
use identity ident doc="identity to get the rating for";
method get_binary_path
doc="retrieve path of cryptotech binary if available"
{
//parms
return rating identity_rating doc="rating for the identity";
use @type tech
doc="cryptotech to get the binary for";
// exceptions
use @type path
doc="""
path to cryptotech binary or NULL if not available. **path is owned by
the library, do not change it!
"""
throws any doc="error status"
}
@ -335,14 +355,11 @@ protocol session {
{
//parms
provide const identity id1
doc="identity of first party in communication - fpr can't be NULL";
use const identity id1 doc="identity of first party in communication - fpr can't be NULL";
provide const identity id2
doc="identity of second party in communication - fpr can't be NULL";
use const identity id2 doc="identity of second party in communication - fpr can't be NULL";
provide const char lang
doc="C string with ISO 639-1 language code";
use const char lang doc="C string with ISO 639-1 language code";
create char words
doc="""
@ -353,15 +370,14 @@ protocol session {
The caller is responsible to free() it (on Windoze use pEp_free())
""";
create size_t wsize
doc="length of full trustwords string";
create size_t wsize doc="length of full trustwords string";
provide bool full
use bool full
doc="""
if true, generate ALL trustwords for these identities.
else, generate a fixed-size subset. (TODO: fixed-minimum-entropy
subset in next version)
"""
""";
// exceptions
@ -369,7 +385,7 @@ protocol session {
doc="out of memory";
throws trustword_not_found
doc="at least one trustword not found"
doc="at least one trustword not found";
}
@ -378,17 +394,14 @@ protocol session {
{
//parms
provide message msg
doc="message to get sender identity from";
use message msg doc="message to get sender identity from";
provide hash_list keylist
use hash_list keylist
doc="NULL if message to be decrypted, keylist returned by decrypt_message() otherwise.";
provide identity received_by
doc="identity for account receiving message can't be NULL";
use identity received_by doc="identity for account receiving message can't be NULL";
provide const char lang
doc="C string with ISO 639-1 language code";
use string lang doc="C string with ISO 639-1 language code";
create char words
doc="""
@ -398,20 +411,20 @@ protocol session {
The caller is responsible to free() it (on Windoze use pEp_free())
""";
provide bool full
use bool full
doc="""
if true, generate ALL trustwords for these identities.
else, generate a fixed-size subset. (TODO: fixed-minimum-entropy
subset in next version)
"""
""";
// exceptions
throws out_of_memory
doc="out of memory";
throws out_of_memory doc="out of memory";
throws trustword_not_found
doc="at least one trustword not found"
throws trustword_not_found doc="at least one trustword not found";
throws like decrypt_message doc="error status of decrypt_message() if decryption fails"
}
@ -423,14 +436,11 @@ protocol session {
use message msg
doc="message to get the rating for. msg->from must point to a valid pEp_identity";
use hash_list x_keylist
doc="decrypted message recipients keys fpr";
use hash_list x_keylist doc="decrypted message recipients keys fpr";
provide rating x_enc_status
doc="original rating for the decrypted message";
use rating x_enc_status doc="original rating for the decrypted message";
create message rating
doc="rating for the message"
return rating msg_rating doc="rating for the message";
// exceptions
@ -441,8 +451,7 @@ protocol session {
contain X-Keylist optional field and x_keylist is NULL.
""";
throws out_of_memory
doc="if not enough memory could be allocated"
throws out_of_memory doc="if not enough memory could be allocated";
}
@ -451,14 +460,11 @@ protocol session {
{
//parms
provide const char user_id
doc="string with user ID";
use string user_id doc="string with user ID";
provide const char fpr
doc="string with fingerprint";
use string fpr doc="string with fingerprint";
create rating rating
doc="rating of key for this user"
return rating key_rating doc="rating of key for this user";
// exceptions
@ -468,11 +474,37 @@ protocol session {
}
func color_from_rating
doc="calculate color from rating"
{
// parms
provide color_from_rating rating doc="color representing that rating"
// return value
return color rating_color doc="color representing that rating"
}
func get_binary_path
doc="retrieve path of cryptotech binary if available"
{
//parms
use cryptotech tech
doc="cryptotech to get the binary for";
use string path
doc="""
path to cryptotech binary or NULL if not available. **path is owned by
the library, do not change it!;
"""
}
@ -484,6 +516,37 @@ protocol session {
// ratings
ratings {
item rating_undefined 0;
item rating_cannot_decrypt 1;
item rating_have_no_key 2;
item rating_unencrypted 3;
item rating_unencrypted_for_some doc="don't use this any more",
item rating_unreliable 4;
item rating_reliable 5;
item rating_trusted 6;
item rating_trusted_and_anonymized 7;
item rating_fully_anonymous 8;
item rating_mistrust -1;
item rating_b0rken -2;
item rating_under_attack -3;
}
// colors
colors {
item color_no_color 0;
item color_yellow 1;
item color_green 2;
item color_red -1;
}


Loading…
Cancel
Save