Adapter/MessageToSendPassphrase

Passphrase support for messageToSend() in the adapter

There is a complete implementation of this protocol in libpEpAdapter

Usage:

  1. return pEp::PassphraseCache::config_next_passphrase() in your messageToSend() implementation if the call is on Sync thread and parameter msg is nullptr
  2. call pEp::PassphraseCache::config_next_passphrase(true) in you messageToSend() implementation if the call is on Sync thread and msg is not nullptr

Sample implementation

// these lines must appear at the beginning of adapter's messageToSend

if (on_sync_thread() && !msg)
    return pEp::PassphraseCache::config_next_passphrase();

if (on_sync_thread())
    pEp::PassphraseCache::config_next_passphrase(true);

API calls, which MAY use messageToSend() callbacks as part of their implementation, do not need extra implementation

API calls MUST behave all the same regarding passphrases. First an empty passphrase and then all passphrases from the passphrase cache have to be probed. When no passphrase works they return PEP_PASSPHRASE_REQUIRED or PEP_WRONG_PASSPHRASE. messageToSend() is only be used with a valid struct _message.

This does not differ from any other API calls, so there is no need for a different implementation.

Using messageToSend() as part of a network protocol implementation executing asynchronously (i.e. p≡p Sync)

When a protocol implementation of the p≡p engine using messageToSend() cannot sign or encrypt with an empty passphrase and not with the configured passphrase it is calling messageToSend() with a NULL instead of a struct _message object.

In this case the handler for messageToSend() in the p≡p adapter MUST configure the next passphrase in passphrase cache to the PEP_SESSION used for the protocol and return PEP_STATUS_OK. The protocol implementation will retry with the now configured passphrase.

When the handler has no passphrase (left) in the passphrase cache it signals the app that it needs a passphrase by returning PEP_PASSPHRASE_REQUIRED for an empty cache and PEP_WRONG_PASSPHRASE for a non-empty cache. Then the protocol implementation signals the missing passphrase using notifyHandshake(from, NULL, SYNC_PASSPHRASE_REQUIRED) and retries.

When the user decides not to deliver a passphrase and shuts down p≡p Sync instead the Adapter MUST return PEP_SYNC_NO_CHANNEL.

Before retrying the Sync implementation MUST block until passphrase_cache.add() was being called. libpEpAdapter is offering the Semaphore class for implementing the block.

See also