Browse Source

updates

generate_api
nk 3 years ago
parent
commit
d1f57c9bdf
4 changed files with 383 additions and 363 deletions
  1. +45
    -57
      api/basic_api.yml2
  2. +173
    -181
      api/keymanagement_api.yml2
  3. +158
    -122
      api/message_api.yml2
  4. +7
    -3
      api/pEp.yml2

+ 45
- 57
api/basic_api.yml2 View File

@ -54,7 +54,7 @@ enum comm_type {
hex key_revoked 0x05;
hex key_b0rken 0x06;
hex key_expired_but_confirmed 0x07
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;
@ -110,7 +110,6 @@ enum comm_type {
struct identity {
field string address doc="SMTP address or URI";
field hash fpr doc="fingerprint of key being used as ID";
field string user_id doc="ID for person or entity in M2M case";
@ -134,8 +133,7 @@ flags {
protocol session {
callback messageToSend
doc="a message needs to be delivered by application"
callback messageToSend doc="a message needs to be delivered by application"
{
// parms
@ -147,8 +145,7 @@ protocol session {
}
method config_passive_mode
doc="enable passive mode"
method config_passive_mode doc="enable passive mode"
{
// parms
@ -156,8 +153,7 @@ protocol session {
}
method config_unencrypted_subject
doc="disable subject encryption"
method config_unencrypted_subject doc="disable subject encryption"
{
// parms
@ -165,8 +161,7 @@ protocol session {
}
method config_use_only_own_private_keys
doc="enable passive mode"
method config_use_only_own_private_keys doc="enable passive mode"
{
// parms
@ -174,8 +169,7 @@ protocol session {
}
method config_service_log
doc="log more for service purposes"
method config_service_log doc="log more for service purposes"
{
// parms
@ -183,8 +177,7 @@ protocol session {
}
method config_cipher_suite
doc="cipher suite being used when encrypting"
method config_cipher_suite doc="cipher suite being used when encrypting"
{
// parms
@ -193,19 +186,19 @@ protocol session {
// exceptions
throws cannot_config
doc="""
configuration failed; falling back to default. the default
ciphersuite for a crypt tech implementation is implementation
defined.
""";
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.
"""
doc="""
log a user defined event defined by UTF-8 encoded strings into
management log.
"""
{
// parms
@ -219,8 +212,7 @@ protocol session {
}
method get_default own_userid
doc="get the user_id of the own user"
method get_default own_userid doc="get the user_id of the own user"
{
// parms
@ -228,7 +220,7 @@ protocol session {
doc="""
own user id (if it exists). userid will be NULL if not found; otherwise,
returned string belongs to the caller.
"""
""";
// exceptions
@ -242,21 +234,18 @@ protocol session {
}
method mark_as_compromised
doc="mark key in trust db as compromised"
method mark_as_compromised doc="mark key in trust db as compromised"
{
// parms
use hash fpr doc="fingerprint of key to mark"
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 mark_as_compromized doc="deprecated to fix misspelling. Please move to mark_as_compromised"
method import_key
doc="import key from data"
method import_key doc="import key from data"
{
// parms
@ -272,8 +261,7 @@ protocol session {
}
method export_key
doc="export ascii armored key"
method export_key doc="export ascii armored key"
{
// parms
@ -295,12 +283,11 @@ protocol session {
}
method export_secret_key
doc="export secret key ascii armored"
method export_secret_key doc="export secret key ascii armored"
{
// parms
use hash fpr doc="fingerprint of key, at least 16 hex digits"
use hash fpr doc="fingerprint of key, at least 16 hex digits";
create string key_data
doc="""
@ -321,12 +308,10 @@ protocol session {
}
method export_secrect_key
doc="deprecated misspelled function. Please replace with export_secret_key"
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"
method get_crashdump_log doc="get the last log messages out"
{
// parms
@ -343,8 +328,7 @@ protocol session {
}
method get_languagelist
doc="get the list of languages"
method get_languagelist doc="get the list of languages"
{
//parms
@ -357,8 +341,7 @@ protocol session {
}
method get_phrase
doc="get phrase in a dedicated language through i18n"
method get_phrase doc="get phrase in a dedicated language through i18n"
{
// parms
@ -371,19 +354,24 @@ protocol session {
method get_engine_version
doc="""
returns the current version of pEpEngine (this is different
from the pEp protocol 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"
// parms doc="none"
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*.
"""
// 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


+ 173
- 181
api/keymanagement_api.yml2 View File

@ -4,229 +4,221 @@
// this file is under GNU General Public License 3.0
// see LICENSE.txt
// written by Volker Birk
// written by Nana Karlstetter and 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 myself
doc="ensures that an own identity is complete"
{
// parms
supply identity ident
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 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
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 update_identity doc="update identity information"
{
// parms
lend 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 trust_own_key
method myself doc="ensures that an own identity is complete"
{
// parms
lend identity ident
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.
"""
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 key_mistrusted doc="mark key as being compromised"
{
// parms
//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!
"""
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 key_reset_trust
method trust_personal_key doc="mark a key as trusted for a user"
{
// parms
use identity ident
doc="""
reset trust bit or explicitly mistrusted status for an identity and its
accompanying key/user_id pair.
"""
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
// parms
use ientity ident
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="""
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).
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"
method own_key_is_listed doc="returns true id key is listed as own key"
{
// parms
// parms
use hash fpr doc="fingerprint of key to test"
use hash fpr doc="fingerprint of key to test";
return bool listed doc="flags if key is own"
return bool listed doc="flags if key is own";
}
method own_identities_retrieve
doc="retrieve all own identities"
method own_identities_retrieve doc="retrieve all own identities"
{
// parms
// parms
create identity_list own_identities
doc="""
list of own identities.
The ownership of the copy of own_identities goes to the caller.
"""
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/private keypair fingerprints"
method own_keys_retrieve doc="retrieve all flagged keypair fingerprints/private keypair fingerprints"
{
// parms
// parms
create hashlist keylist
create hashlist keylist
doc="""
list of fingerprints. This function does not return keys without
a private key part.
"""
""";
}
method set_own_key
doc="mark a key as own key"
method set_own_key doc="mark a key as own key"
{
// parms
// 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
lend 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 doc="fingerprint of the key to mark as own key";
}
}

+ 158
- 122
api/message_api.yml2 View File

@ -4,7 +4,7 @@
// this file is under GNU General Public License 3.0
// see LICENSE.txt
// written by Volker Birk
// written by Volker Birk and Nana Karlstetter
enum text_format {
@ -86,12 +86,11 @@ struct message {
protocol session {
method encrypt_message
doc="encrypt message in memory"
method encrypt_message doc="encrypt message in memory"
{
// parms
supply message src
lend message src
doc="""
message to encrypt - usually in-only, but can be in-out for
unencrypted messages; in that case, we may attach the key and
@ -106,7 +105,7 @@ protocol session {
take place
""";
use enc_format format doc="encrypted format";
use enc_format format doc="The desired format this message should be encrypted with";
// flags
@ -117,7 +116,11 @@ 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
doc="""This flag is used to let internal functions know that an encryption call is being
used as part of a reencryption operation
""";
flag encrypt_reencrypt 0x40;
}
// exceptions
@ -133,7 +136,10 @@ protocol session {
method encrypt_message_and_add_priv_key
doc="encrypt message in memory, adding an encrypted private key (encrypted separately and sent within the inner message)"
doc="""
encrypt message in memory, adding an encrypted private key (encrypted separately
and sent within the inner message)
"""
{
// parms
@ -172,10 +178,10 @@ protocol session {
method encrypt_message_for_self
doc="""
encrypt message in memory for user's identity only,
ignoring recipients and other identities from the message
"""
doc="""
encrypt message in memory for user's identity only,
ignoring recipients and other identities from the message
"""
{
// parms
@ -215,12 +221,11 @@ protocol session {
}
method decrypt_message
doc="decrypt message in memory"
method decrypt_message doc="decrypt message in memory"
{
// parms
supply message src
lend message src
doc="""
message to decrypt.
The ownership of src remains with the caller - however, the contents
@ -230,7 +235,7 @@ protocol session {
create message dst doc="pointer to new decrypted message or empty on failure";
supply hash_list keylist
lend hash_list keylist
doc="""
in: stringlist with additional keyids for reencryption if needed
(will be freed and replaced with output keylist)
@ -265,118 +270,114 @@ protocol session {
input flag. Used to signal that decrypt function should engage in behaviour
specified for when the server storing the source is untrusted.
""";
flag decrypt_flag_dont_trigger_sync 0x200
flag decrypt_flag_dont_trigger_sync 0x200;
}
// exceptions
// exceptions
throws decrypted doc="if message decrypted but not verified";
throws decrypted doc="if message decrypted but not verified";
throws cannot_reencrypt
throws cannot_reencrypt
doc="""
if message was decrypted (and possibly verified) but a reencryption
operation is expected by the caller and failed.
""";
throws unencrypted
throws unencrypted
doc="""
if src is unencrypted this function returns unencrypted and sets
dst to empty.
""";
throws any doc="all error status values allowed";
throws any doc="all error status values allowed";
}
method own_message_private_key_details
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.
"""
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
// parms
use message msg
doc="""
message to decrypt. msg MUST be encrypted so that this function
can check own signature.
""";
use message msg
doc="""
message to decrypt. msg MUST be encrypted so that this function
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
// exceptions
throws any doc="error status"
throws any doc="error status";
}
method outgoing_message_rating
doc="get rating for an outgoing message"
method outgoing_message_rating doc="get rating for an outgoing message"
{
//parms
// parms
use message msg
doc="""
message to get the rating for. From must point to a valid pEp_identity.
Dir must be dir_outgoing.
""";
use message msg
doc="""
message to get the rating for. From must point to a valid pEp_identity.
Dir must be dir_outgoing.
""";
return rating msg_rating doc="rating for the message";
return rating msg_rating doc="rating for the message";
// exceptions
// exceptions
throws any doc="error status"
throws any doc="error status";
}
method outgoing_message_rating_preview
doc="get rating preview"
method outgoing_message_rating_preview doc="get rating preview"
{
//parms
// parms
use message msg
doc="""
message to get the rating for. From must point to a valid pEp_identity.
Dir must be dir_outgoing.
""";
use message msg
doc="""
message to get the rating for. From must point to a valid pEp_identity.
Dir must be dir_outgoing.
""";
return rating msg_rating doc="rating preview for the message";
return rating msg_rating doc="rating preview for the message";
// exceptions
// exceptions
throws any doc="error status"
throws any doc="error status";
}
method identity_rating
doc="get rating for a single identity"
method identity_rating doc="get rating for a single identity"
{
//parms
// parms
use identity ident doc="identity to get the rating for";
use identity ident doc="identity to get the rating for";
return rating identity_rating doc="rating for the identity";
return rating identity_rating doc="rating for the identity";
// exceptions
// exceptions
throws any doc="error status"
throws any doc="error status";
}
method get_trustwords
doc="get full trustwords string for a *pair* of identities"
method get_trustwords doc="get full trustwords string for a *pair* of identities"
{
//parms
// parms
use identity id1 doc="identity of first party in communication - fpr can't be empty";
use identity id1 doc="identity of first party in communication - fpr can't be empty";
use identity id2 doc="identity of second party in communication - fpr can't be empty";
use identity id2 doc="identity of second party in communication - fpr can't be empty";
use ISO639_1 lang doc="string with ISO 639-1 language code";
use ISO639_1 lang doc="string with ISO 639-1 language code";
create string words
create string words
doc="""
string with all trustwords, separated
by a blank each. Empty if language is not supported or trustword
@ -385,129 +386,164 @@ protocol session {
The caller is responsible to free() it (on Windoze use pEp_free())
""";
use 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
// 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";
}
method get_message_trustwords
doc="get full trustwords string for message sender and reciever identities"
method get_message_trustwords doc="get full trustwords string for message sender and reciever identities"
{
//parms
// parms
use message msg doc="message to get sender identity from";
use message msg doc="message to get sender identity from";
use hash_list keylist
doc="empty if message to be decrypted, keylist returned by decrypt_message() otherwise.";
use hash_list keylist doc="empty if message to be decrypted, keylist returned by decrypt_message() otherwise.";
use identity received_by doc="identity for account receiving message can't be empty";
use identity received_by doc="identity for account receiving message can't be empty";
use ISO639_1 lang doc="string with ISO 639-1 language code";
use ISO639_1 lang doc="string with ISO 639-1 language code";
create string words
create string words
doc="""
string with all trustwords, separated by a blank each.
Empty if language is not supported or trustword wordlist is damaged or unavailable.
""";
use 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
// 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"
throws like decrypt_message doc="error status of decrypt_message() if decryption fails";
}
method re_evaluate_message_rating
doc="re-evaluate already decrypted message rating"
method get_trustwords_for_fprs doc="get full trustwords string for a pair of fingerprints"
{
//parms
// parms
use message msg
doc="message to get the rating for. msg->from must point to a valid pEp_identity";
use string fpr1 doc="fingerprint 1";
use hash_list x_keylist doc="decrypted message recipients keys fpr";
use string fpr2 doc="fingerprint 2";
use rating x_enc_status doc="original rating for the decrypted message";
use ISO639_1 lang doc="string with ISO 639-1 language code";
return rating msg_rating doc="rating for the message";
create string words
doc="""
pointer to string with all trustwords UTF-8 encoded, separated by a blank each.
NULL if language is not supported or trustword wordlist is damaged or unavailable.
The caller is responsible to free() it (on Windoze use pEp_free()).
""";
// exceptions
return size_t wsize doc="length of full trustwords string";
throws illegal_value
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 trustword_not_found doc="at least one trustword not found";
}
method re_evaluate_message_rating doc="re-evaluate already decrypted message rating"
{
// parms
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 rating x_enc_status doc="original rating for the decrypted message";
return rating msg_rating doc="rating for the message";
// exceptions
throws illegal_value
doc="""
if decrypted message doesn't contain X-EncStatus optional field and
x_enc_status is pEp_rating_udefined or if decrypted message doesn't
contain X-Keylist optional field and x_keylist is empty.
""";
throws out_of_memory doc="if not enough memory could be allocated";
throws out_of_memory doc="if not enough memory could be allocated";
}
method get_key_rating_for_user
doc="get the rating of a certain key for a certain user"
method get_key_rating_for_user doc="get the rating of a certain key for a certain user"
{
//parms
// parms
use string user_id doc="string with user ID";
use string user_id doc="string with user ID";
use string fpr doc="string with fingerprint";
use string fpr doc="string with fingerprint";
return rating key_rating doc="rating of key for this user";
return rating key_rating doc="rating of key for this user";
// exceptions
// exceptions
throws record_not_found doc="if no trust record for user_id and fpr can be found";
}
throws record_not_found
doc="if no trust record for user_id and fpr can be found"
method rating_from_comm_type doc="get the rating for a comm type"
{
// parms
use comm_type ct doc="the comm type to deliver the rating for";
// exceptions
throws any doc="rating value for comm type ct";
}
}
func color_from_rating
doc="calculate color from rating"
func color_from_rating doc="calculate color from rating"
{
// parms
use color_from_rating rating doc="color representing that rating"
use color_from_rating rating doc="color representing that rating";
// return value
return color rating_color doc="color representing that rating"
return color rating_color doc="color representing that rating";
}
func get_binary_path
doc="retrieve path of cryptotech binary if available"
func get_binary_path doc="retrieve path of cryptotech binary if available"
{
//parms
use cryptotech tech
doc="cryptotech to get the binary for";
use cryptotech tech doc="cryptotech to get the binary for";
use string path
doc="""
path to cryptotech binary or empty if not available. **path is owned by
the library, do not change it!;
"""
the library, do not change it!
""";
}

+ 7
- 3
api/pEp.yml2 View File

@ -4,7 +4,7 @@
// this file is under GNU General Public License 3.0
// see LICENSE.txt
// written by Volker Birk
// written by Volker Birk and Nana Karlstetter
decl package @name;
@ -24,7 +24,7 @@ decl construct, new is construct;
// use: readonly in parm, ownership remains with caller
decl use @type @name (mode=use) alias parm;
// supply: inout parm, ownership remains with caller
// lend: inout parm, ownership remains with caller
decl supply @type @name (mode=supply) alias parm;
// create: factory delivers this, ownership goes to caller
@ -42,7 +42,11 @@ decl caveat(mode=caveat) alias doc;
// base types
// string: text
// string: text
doc="""
p≡p engine uses UTF-8 strings which are NFC normalized.
Cf. https://dev.pep.foundation/Engine/Basic%20Concepts%20of%20the%20pEp%20Engine
"""
// int: integer number
// blob: Binary Large Object
// size_t: size in memory


Loading…
Cancel
Save