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_id
s. user_id
s 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_id
s, the pEp Engine will create aTOFU_
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 aTOFU_
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.