Engine/GroupEncryption

p≡p Group Encryption Protocol family

Front matter

Title: Managed Group Encryption Specification
Author: Volker Birk
Team: Engine Team
Reviewer(s): TBD
Created: 2020-11-13
Last updated: 2020-11-13
Ticket reference: ENGINE-822

Introduction

p≡p is securing message based communication. This can be bilateral or multilateral communication. The p≡p Group Encryption Protocol family defines how to protect multilateral communication between a group of people (or machines in M2M case). There will be different protocols for managed groups (which are created and dissolved by a Group Manager) and unmanaged groups, which will be created and dissolved momentarily.

Goals

This document describes the Managed Group Encryption Protocol and the API for the Application Programmers. It will be later extended by description of the Unmanaged Group Encryption Protocol.

Glossary

  • Personal Identity: An Identity, which is used exclusively by one User. The Address of a Personal Identity is called Personal Address.
  • Group: Set of Personal Identities.
  • Group Manager: Identity, who manages a Group.
  • Managed Group: Group with a Group Manager.
  • Group Identity: An Identity, which is used by a Group. In email this can be a mailing list address. In pEp the Address of a Group Identity is Called Group Address.
  • Group Member: Personal Identity, which is element of the Group. A Group Member has a rating of PEP_rating_reliable or better. Identities with other ratings cannot be Group Member.
  • Group Key: Secret Key. Default Key for the Group Identity.
  • Group Rating: the Group Rating is the Minimum Rating of the Ratings of all Group Members and the straight Rating of the Group Identity.
  • Group Message: Message to the Group Identity from a Group Member with a Rating of at least PEP_rating_reliable.
  • Group Management Message: Message with Management data for a Managed Group.

Background

The Managed Group Encryption Protocol is derived from encrypting Mailing Lists. It is a generalization of that problem. A Mailing list can be encrypted by creating a list key and providing this secret key to all list members. Then list members can use that key to encrypt messages to the list, which can be read by all list members.

Abstract

Analogously to mailing list encryption in Managed Group Encryption Protocol there is a Group Key. It is generated by the p≡p engine of the Group Manager and sent to all Group Members. When a Group Identity (the identity of a new member) is added by the Group Manager then the Group Key is sent to this new member, too. When a Group Member is excluded from the Group by the Group Manager then a Key Reset is being executed for the Group Key. This Group Key Reset is part of p≡p Key Reset Protocol. When the Group is dissolved the management data is being deleted. No further action happens to the Group Key in this case.

The Managed Group Encryption Protocol may be supported by p≡p Applications by adding User Interface for the managment tasks for creating a group, inviting communication partners, excluding communication partners and dissolving a group. This will enable this user for becoming a Group Manager. The p≡p engine implements the protocol and provides an API as part of p≡p API for the management tasks, so application programmers can use it for connecting the UI.

Use cases

This specification defines the design of the Managed Group Encryption Protocol. The following use cases illustrate the reasons why this design was chosen.

Use case: User defines a closed group of people who need to communicate in a secure way, becoming Group Manager

The user wants to name people who form a closed group. Inside this group confidentiality must be preserved. The user is defining a Group Identity for addressing the Group.

The user needs a way to name people as communication partners. In p≡p this is done by listing identites, each person being represented by one identity in the list.

To keep group communication confidential the communication in this group must be protected. It must be protected differently than the communication between the user and a single person from this group, so communication with one single person cannot be accessed by other group members, while communication with the group can.

All Group Members must be informed about their membership.

Sample:

Alice wants to create the group dev@pep-project.org and inviting Bob and Claire. Therefore, she is using her identity Alice Cooper alice@pep.null for being Group Manager. She’s listing Bob with Bob Hope bob@pep.null and Claire Robinson claire@pep.null.

Use case: Group Manager adds a person to the group, who is becoming Group Member

The user needs a way to extend the group by adding an identity to the list. When a person is added then access to the group communication must be granted to this person.

When a Group Member is added the Group Member must be informed about the membership.

Sample:

Alice is adding Devon Parker devon@pep.null to the Group.

Use case: Group Manager removes a Group Member from the group

The user needs a way to remove a person from the group by removing the person’s identity from the list. When a person is removed then a Key Reset is to be executed to guarantee that the removed person cannot access further communication.

When a Group Member is removed the Group Member must be informed about losing membership status.

Sample:

Alice is removing Bob Hope bob@pep.null from the group.

Use case: Membership in a Managed Group granted

This information must be managed by p≡p. There is no user notification.

Use case: Membership revoked

This information must be managed by p≡p. There is no user notification.

Technical Requirements

Key Reset

The Managed Group Encryption Protocol is dependent on the implementation of the Group Key Reset protocol as part of the Key Reset protocol. See the specification of Key Reset.

Group management storage for the Group Manager

The Group Manager needs to store the list of identities representing the Group Members.

Group management storage per Group Member

A Group Member needs to store her own status in the group for each group where she is member of.

Solution

Status quo

The current implementation of p≡p does not support Group Encryption. But because of Key Election still being in place it supports Unmanaged Group Encryption implicitely when importing the right Keys. With the removal of Key Election this property will be lost. Therefore, an explicit implementation for Group Encryption is necessary.

Design

Overview

The p≡p management DB will be used to hold management data for Groups. Group Identities, the identities of communication partners who are Group members, will be stored in the p≡p engine of the Group Manager. By executing API calls for creating a Group, adding Members, excluding Members and dissolving a Group the Group Manager is triggering corresponding transactions into the management DB, and sending membership information and Keys to the Group Members. When membership information arrives then a Group Member’s p≡p engine is storing the membership in their management DB, creating a Group Identity and assigning the incoming Group Key. By doing so distributed knowledge about the Group is being available to the Group Members and the Group Manager.

Dependencies

  • Group Key Reset
  • implementation of Group Management API in the p≡p adapters

Pros and Cons

The Managed Group Encryption Protocol is covering the case of an explicitely managed group completely. It cannot be used for multilateral communication, which defines a group of recipientes instantanously by message like using multiple communication partners in To: and/or CC:

API

For the API see in branch ENGINE-822 pEpEngine/src/group.h

// This file is under GNU General Public License 3.0
// see LICENSE.txt

#pragma once

#include "message_api.h"

#ifdef __cplusplus
extern "C" {
#endif


// struct for holding group data in memory
// groups are persistant, therefore they're living in management.db

typedef struct _pEp_member {
    pEp_identity *ident;
    bool adopted;
} pEp_member;

pEp_member *new_member(pEp_identity *ident);
void free_member(pEp_member *member);

typedef struct _member_list {
    pEp_member *member;
    struct _member_list *next;
} member_list;

member_list *new_memberlist(pEp_member *member);
void free_memberlist(member_list *list);
member_list *memberlist_add(member_list *list, pEp_member *member);

typedef struct _pEp_group {
    pEp_identity *group_identity;
    pEp_identity *manager;
    member_list *members;
    bool active;
} pEp_group;


// new_group() - allocate pEp_group struct. This function does not create a
// group.
//
//  params:
//      group_identity (in)
//      manager (in, optional)
//      memberlist (in, optional)
//
//  caveat:
//      the ownership of all parameters groes to the struct; data is not copied

pEp_group *new_group(
        pEp_identity *group_identity,
        pEp_identity *manager,
        member_list *memberlist
    );


// free_group() - free pEp_group struct. This function does not dissolve a
// group.

void free_group(pEp_group *group);


// group_create() - create group as group manager and marks it as being active
//
//  params:
//      group_identity (in)
//      manager (in)            own identity

PEP_STATUS group_create(
        PEP_SESSION session,
        pEp_identity *group_identity,
        pEp_identity *manager,
        member_list *memberlist,
        pEp_group **group
    );


// group_adopt() - adopt group as member
//
//  params:
//      group_identity (in)
//      as_member (in)          own identity

PEP_STATUS group_adopt(
        PEP_SESSION session,
        pEp_identity *group_identity,
        pEp_identity *as_member
    );


// group_dissolve() - dissolve a group and marks it as being inactive

PEP_STATUS group_dissolve(
        PEP_SESSION session,
        pEp_identity *group_identity,
        pEp_identity *manager
    );


// group_add_member() - add group member

PEP_STATUS group_add_member(
        PEP_SESSION session,
        pEp_identity *group_identity,
        pEp_identity *group_member,
        pEp_identity *manager
    );


// group_remove_member() - remove a member from the group

PEP_STATUS group_remove_member(
        PEP_SESSION session,
        pEp_identity *group_identity,
        pEp_identity *group_member,
        pEp_identity *manager
    );


// group_rating() - returns the group rating as manager or the straight rating
// otherwise

PEP_STATUS group_rating(
        PEP_SESSION session,
        pEp_identity *group_identity,
        pEp_identity *manager,
        PEP_rating *rating
    );


#ifdef __cplusplus
}
#endif

Actions

Creating a Group

  1. The Group Manager creates the Group by defining a Group Identity and a set of Personal Identities as initial Group Members.
  2. The Group Identity is stored.
  3. A Group Key is generated.
  4. A Create Group Message is sent to all Members. The Message contains the Group Key.
  5. The Group is being marked as active.

Adopting a Group

  1. CreateGroup is Received by a Member, which is not the Group Manager.
  2. The Group is being Adopted by calling group_adopt().
  3. GroupAdopted is being sent to the Group Manager
  4. The Group is being marked as active.

Adding a Group Member

The Group Manager can add Members.

  1. The Group Manager calls group_add_member()
  2. CreateGroup is being sent to the new Member

Removing a Group Member

  1. The Group Manager calls group_remove_member()
  2. The former Member is being removed from the Member List
  3. A Key Reset is being executed on the Group Identity

Dissolving a Group

  1. The Group Manager calls group_dissolve()
  2. GroupDissolve is being sent to all Group Members
  3. Group is being marked as inactive

Calculation of a Rating for a Group Identity

  • If a User is Group Manager then the Rating of the Group Identity is the Group Rating.
  • If a User is not Group Manager then the Rating of the Group Identity is the straight Rating of this Identity.

Storage in management DB

The following information must be stored:

  • group flag for identity for marking group identites
  • the list of groups
  • for each group a flag if it is active
  • for a Member, for each group if it is adopted
  • for a Manager, for each group the Members list
  • for a Manager, for each group for each Member if he/she has adopted the Group

Protocol

The definition of all p≡p protocols is in the FSM Y-language defined in pEpEngine/sync/fsm.yml2

p≡p network protocols are mapped into ASN.1. Hence, the documentation of actual message data is in ASN.1. See pEpEngine/asn.1/managedgroup.asn1

For the protocol overview See in branch ENGINE-822 pEpEngine/sync/distribution.fsm

fsm ManagedGroup 2 {
    version 1, 0;

    message GroupCreate 2 {
        field Identity groupIdentity;
        field Identity manager;
    }

    message GroupAdopted 3 {
        field Identity groupIdentity;
        field Identity member;
    }

    message GroupDissolve 4 {
        field Identity groupIdentity;
        field Identity manager;
    }
}

GroupCreate

Sent from the Group Manager to the Group

The message must contain:

  • Group Identity
  • Group Mananger sending the message
Sample
GroupCreate {
    groupIdentity {
        address     "dev@pep-project.org",
        fpr         "E41DDCF6AFB12E6AD9869469D0A556A8D12F1002"
        user-id     "pEp_own_userId",
        username    "p≡p development",
        comm-type   255,
        lang        "en"
    }

    manager {
        address     "vb@pep-project.org",
        fpr         "AAB978A882B9A6E793960B071ADFC82AC3586C14"
        user-id     "pEp_own_userId",
        username    "Volker Birk",
        comm-type   255,
        lang        "en"
    }
}
Sending
  • The Group Manager sends GroupCreate when creating a Group.
  • The Group Manger sends GroupCreate to all Group Members, which did not yet adopt the group when receiving a Group Message.

If a Group Member is not reachable on a channel, which is at least yellow then the GroupDissolve message is not sent to this Group Member.

Receiving

When receiving a GroupCreate from a Group Manager it must be answered with GroupAdopted.

If the message is not coming from a channel, which is at least yellow then the message is ignored.

If the Sender Key is not a Key from the Group Manager the message is ignored.

GroupAdopted

Sent from each Group Member to the Group Manager

The message must contain:

  • Group Identity
  • Group Member sending the message

Sample

GroupAdopted {
    groupIdentity {
        address     "dev@pep-project.org",
        fpr         "E41DDCF6AFB12E6AD9869469D0A556A8D12F1002"
        user-id     "23",
        username    "p≡p development",
        comm-type   127,
        lang        "en"
    }

    member {
        address     "alice@pep.foundation",
        fpr         "AABFB526AAB9A63437ECBB071555582AC3336BC2"
        user-id     "pEp_own_userId",
        username    "Alice Marquez",
        comm-type   255,
        lang        "es"
    }
}
Sending

If the Group Manager is not reachable on a channel, which is at least yellow then the GroupAdopted message is not sent.

Receiving

When the Group Manager receives GroupAdopted then it marks the Group Member as having adopted the Group.

If the Group does not exist or is inactive the GroupAdopted message is ignored.

If the message is not coming from a Group Member then the message is ignored.

If the message is not coming from a channel, which is at least yellow then the message is ignored.

If the Sender Key is not a Key of the Group Member then the message is ignored.

GroupDissolve

Sent from the Group Manager to the Group

The message must contain:

  • Group Identity
  • Group Manager sending the message

Sample

GroupDissolve {
    groupIdentity {
        address     "dev@pep-project.org",
        fpr         "E41DDCF6AFB12E6AD9869469D0A556A8D12F1002"
        user-id     "pEp_own_userId",
        username    "p≡p development",
        comm-type   255,
        lang        "en"
    }

    manager {
        address     "vb@pep-project.org",
        fpr         "AAB978A882B9A6E793960B071ADFC82AC3586C14"
        user-id     "pEp_own_userId",
        username    "Volker Birk",
        comm-type   255,
        lang        "en"
    }
}

Sending

The Group Manager sends this message to all Group Members when the User decides to dissolve the Group.

If a Group Member is not reachable or the channel is not at least yellow then the GroupDissolve message is not sent to this Group Member.

Receiving

A Group Member receiving this message is marking the Group as being inactive.

Inactive Groups are not supported by the Managed Group Encryption implementation and will be furthermore ignored like they would not exist.

If the message is not coming from a channel, which is at least yellow then the message is ignored.

If the message is not coming from the Group Manager then the message is ignored.

If the Sender Key is not a Key from the Group Manager the message is ignored.

Group Message from inactive Group

When receiving a Group Message from a Member of an inactive Group the Group Mananger sends GroupDissolve to the Sender.

Security considerations

  • The Sender of all GroupCreate and GroupDissolve must be the Group Manager
  • Only the GroupManager reacts on GroupAdopted
  • A Group Message must be encrypted with a Key of the Sender.

Service requirements

Service tooling

Service must have tooling to decode messages of this protocol. This may be part of Enterprise Toolkit (see there).

Logging

There must be switchable Service Log information for:

  1. Group Identity
  2. Manager / Member data
  3. Actions
  4. Message Content

Enterprise Toolkit

The Enterprise Toolkit must contain tools for:

  1. Display Groups
  2. Search Groups by Group Identity
  3. Provision Groups
  4. Manage Groups while runtime

Affected Teams

  • Implementation: Engine team

Additionally:

  • All p≡p for E-Mail Application teams for implementing UI
  • All p≡p Adapter developers for implementing the extension to the p≡p API
  • The p≡p Enterprise Toolkit developers
  • The p≡p Service & QA team

See also

Distribution.ManagedGroup