Engine/KeyReset

Cut and pasted for Volker from the pad - I have not looked at this in some time, so I do not know if it is up-to-date - Krista

FYI: currently being changed while some functionality is dealt with. Not canonical atm.

Key Reset

Key Reset is

  • a function, which is used in the pEp protocols
  • a use case, which means manually triggering this function

Key reset is what is needed, if a key gets compromised in any way.

At the API level, key_reset is broken into two external functions

  • key_reset_user(user_id)
  • key_reset_identity(identity, fpr)

Internal only:

  • key_reset_own_identity(address, fpr)

This is on top of the key_reset functionality, which may be removed from the accessible API. Both of the above calls are calls to the main key_reset function which restrict its external functionality.

The functionality is as follows:

key_reset_user(user_id):

    if user_id is not NULL and not the own user_id:
       reset all trust for all keys for user_id
       remove all default keys for all identities associated with user_id
    else:
       for each *identity* associated with the own user_id:
           call key_reset_own_identity(identity->address, identity->fpr)


key_reset_identity(identity, fpr):

    non-own_identity:

        if fpr is NULL:
            set fpr to default for this identity

        remove fpr from all identities
        remove fpr from all users
        delete key from key ring 

    own_identity:

        call key_reset_own_identity(identity->address, identity->fpr)

// ?? This is not what you call from an application. But it IS what gets called for own identities
//      internally.

key_reset_own_identity(address, fpr):

    if there's an input fpr, user that. Otherwise, use the stored default fpr for this identity. Then:

    Create revocation
    add to revocation list
    mistrust fpr from trust
    Remove fpr from ALL identities
    Remove fpr from ALL users
    generate new key
    for all active communication partners:
        active_send revocation

Key reset functionality

How do we get revocations through?

  1. We communicate them immediately to frequent comm partners (“active”)

  2. We communicate them on demand to non-frequent comm parterns (“passive”)

  3. If a revoked key is used when decrypt_message() is called, we answer with the revocation immediately

  4. We communicate them immediately to frequent comm partners (“active”)

  5. We communicate them on demand to non-frequent comm parterns (“passive”)

  6. If a revoked key is used when decrypt_message() is called, we answer with the revocation immediately

The idea for trust is that with sending out we’re using a key, which is not revoked yet, if we have one. This is:

  1. own key for identity of recipient, if this key is not revoked
  2. own key for own user, if this key is not revoked
  3. first known good key if this key is not revoked

If a key reset message arrives, trust is copied on demand.

Social graph is to be stored with encrypt_message():

own identity => user (comm partner)

Algorithm for the internal key reset function, which provides the functionality to the API functions above:

Key Reset trigger; either manually or in another protocol, parameter key (optional)

    if identity given:
        key reset for one identity
    else:
        For identity in own identities:
            key reset for one identitiy

Key Reset for identity:

    if own identity:
        Create revocation

        add to revocation list
        mistrust fpr from trust
        Remove fpr from ALL identities
        Remove fpr from ALL users
        generate new key

        for all active communication partners:
            active_send revocation

    else:
        remove fpr from all identities
        remove fpr from all users
        delete key from key ring

In encrypt_message() (later, too, in transport’s send):

attach new revocations regarding the from; this has to work like adding a key

In decrypt_message() (later, too, in transport’s receive):

if key used is in revocation list:
    if pEp user:
        send message with revocation

That makes two database tables:

revocation_list:

id (sequence), fpr, timestamp

social_graph:

own_identity, user_id

Applications:

  1. manually:

Message API:

key_reset_user(user_id)

key_reset_identity(identity, fpr)
  1. automatically