Identities

In pEp the term User refers to a real person (or system) using the p≡p installation. An Identity denotes a digital identity, this is: How the person appears in the network.

Each Identity is a mapping between a User and an address. This mapping is represented by the tuple (user_id, address).

Each User can have several addresses and thus identities, e.g. one e-mail address based in the full name, another on based on initials, a telephone number, as well as a XMPP address. Also a User can use different names, e.g. his/her real name and a nickname. For associating these information with the respective User, pEp uses the user_id. This user_id is a unique ID for a User.

The identity database in the p≡p Engine (management.db) uniquely identifies Identities by user_id and address. and a reference to each Identity’s Default Key.

The Identity Management itself is done completely by the p≡p Engine. The User management is up to the application, though.

Identifying Users will become more important with p≡p Sync evolving to include contacts and calendars.

Note: When dealing with a pEp application representing a system, instead of a person, everything is on the lines of what is written here. Just think about the system being the person and any system ID will be used as user_id.

Own Identities

Own Identities are part of the application’s configuration. The “Own” person is the one using the application, specified in the application by configuration settings like real name and e-mail address.

As user_id the application shall use an unique identifier. If no such value is available, the application shall use the PEP_OWN_USERID pre-processor define.

Some examples for reasonable unique values are

  • the ID of the user’s own address-book entry (macOS, Exchange, vCard),
  • the user’s User SID (Windows without Exchange),
  • the administrative ID (Management tools, e.g. Tivoli), and
  • the Distinguished Name (DN) (LDAP).

For Unix you must not use the Unix uid, as it is not unique, esp. on stand-alone systems. PEP_OWN_USERID shall be used instead.

Communication Partner’s Identities

For communication partner’s, the application shall look up the partner in the address-book and use the address-book entry’s unique ID as user_id.

If the application does not use an address-book, or there is no entry for her/him, the user_id shall be left off and the pEp Engine will create a TOFU_ ID for this entry. The application can easily change a TOFU_ ID into a unique ID later (see below).

Addresses

An address has to be encoded as URI. Using URIs is a conceptual specification, currently not enforced by the Engine.

These URIs MUST NOT start with TOFU_, as this is reserved by the Engine (see above).

Examples:

  • mailto:bear@pep-project.org for e-mail,
  • jabber:rachael@pep-project.org for Jabber/XMPP,
  • payto://bic/SOGEDEFFXXX (or other target types) for payments,
  • https://api.pep-project.org/v2 for a REST API.

For historical reasons, addresses without scheme are expected to be e-mail addresses. These MUST NOT start with TOFU_, either.

Using Identities in Applications

Following are some example on how to use Identities in your application.

Rule of thumb: The application shall provide as much information about the Identity as it has.

Please note: The pEp Engine does not provide an interface for querying e.g. user_ids. user_ids are always managed by the application and the application must keep track of them.

Own Identities

  • If the application has some unique ID for the owning user, pass this, when instantiating the Own Identity:

    # a vCard UID:
me = Identity("mailto:ana@pep-project.org", "Dr. Ana Stelline",
              "UID:urn:uuid:79d49066-5600-4b93-a33e-72f9db218b11")

  • If the application has no unique ID available for the own user, use PEP_OWN_USERID:

    me = Identity("mailto:tyrell@pep-project.org", "Dr. Eldon Tyrell",
              PEP_OWN_USERID)

  • If the application has no “real name” consider using the address instead:

    python
me = Identity("https://api.pep-project.org/v2",
              "https://api.pep-project.org/v2",
              PEP_OWN_USERID)

Communication Partner’s Identities

  • If the communication partner is in the application’s address book:

    p = Identity("mailto:bear@pep-project.org", "Bear",
             "UID:urn:uuid:6b3b79a1-6887-49c1-b9d4-64f66dabdd35")

  • If the application’s address book doesn’t contain an entry for the communication partner, or the application does not manage user_ids, the pEp Engine will create a TOFU_ ID based on the address:

    p = Identity("mailto:sebastian@pep-project.org", "J.F. Sebastian")

  • If the communication partner has no “real name” consider using the address instead:

    p = Identity("https://api.pep-project.org/v2",
             "https://api.pep-project.org/v2")

  • Setting a user_id for a TOFU_ Identity:

    p = Identity("mailto:sebastian@pep-project.org", "J.F. Sebastian",
             "UID:urn:uuid:b07c8fca-0726-493c-bf82-413d801b68e1")
p.update()

Please note: This only works for Identities whose user_id is a TOFU_ one.