p≡p engine fork for my own dirty testing of stuff
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.
 
 
 
 

289 lines
10 KiB

// p≡p Keymanagement API version 0.1
// 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
protocol session {
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 any doc="any other value on error";
}
method myself doc="ensures that an own identity is complete"
{
// parms
lend 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.
""";
// exceptions
throws illegal_value doc="illegal parameter values";
throws out_of_memory doc="out of memory";
throws any doc="any other value on error";
}
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.
""";
// exceptions
throws key_unsuitable;
throws illegal_value doc="illegal parameter values";
throws out_of_memory doc="out of memory";
throws any doc="any other value on error";
}
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!
""";
// exceptions
throws key_unsuitable;
throws illegal_value doc="illegal parameter values";
throws out_of_memory doc="out of memory";
throws any doc="any other value on error";
}
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).
""";
// exceptions
throws illegal_value doc="illegal parameter values";
throws out_of_memory doc="out of memory";
throws any doc="any other value on error";
}
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";
// exceptions
throws illegal_value doc="illegal parameter values";
throws any doc="any other value on error";
}
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.
""";
// exceptions
throws illegal_value doc="illegal parameter values";
throws out_of_memory doc="out of memory";
throws any doc="any other value on error";
}
method own_keys_retrieve doc="retrieve all flagged keypair fingerprints/private keypair fingerprints"
{
// parms
create hashlist keylist
doc="""
list of fingerprints. This function does not return keys without
a private key part.
""";
// exceptions
throws illegal_value doc="illegal parameter values";
throws out_of_memory doc="out of memory";
throws any doc="any other value on error";
}
method set_own_key doc="mark a key as own key"
{
// parms
lend identity me
doc="""
own identity this key is used for.
The key has to be in the key ring already identity->address must be set to valid
data update_identity() is called by this function and will create a TOFU user_id +
new entry if none is indicated and heuristic fails to match extant identity identity-
>fpr will NOT be updated with the set identity fpr; it is only in,out because
update_identity() is called before setting it.
""";
use hash fpr doc="fingerprint of the key to mark as own key";
// exceptions
throws key_unsuitable;
throws illegal_value
doc="""
illegal parameter values, including if update_identity determines this is an own
identity""";
throws out_of_memory doc="out of memory";
throws any doc="any other value on error";
}
}