lib/src/main/java/io/v/v23/security/BlessingStore.java

// Copyright 2015 The Vanadium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.

package io.v.v23.security;

import java.security.interfaces.ECPublicKey;
import java.util.List;
import java.util.Map;

import io.v.v23.verror.VException;

/**
 * The interface for storing blessings bound to a principal and managing the subset of blessings to
 * be presented to particular peers.
 */
public interface BlessingStore {
    /**
     * Marks the set of blessings to be shared with peers.
     * <p>
     * {@code set(b, pattern)} marks the intention to reveal {@code b} to peers who
     * present blessings that match the given {@code pattern}.
     * <p>
     * If multiple calls to {@link #set set} are made with the same pattern, the last call prevails.
     * <p>
     * {@code set(null, pattern)} can be used to remove the blessings previously associated with
     * the pattern (by a prior call to {@link #set set}).
     * <p>
     * It is an error to call {@link #set set} with blessings whose public key does not match the
     * public key of the principal for which this store hosts blessings.
     *
     * @param  blessings       blessings to be revealed to the specified peers
     * @param  forPeers        a peer to whom the blessings should be revealed
     * @return                 blessings previously associated with the specified pattern
     * @throws VException      if there was an error making the association
     */
    Blessings set(Blessings blessings, BlessingPattern forPeers) throws VException;

    /**
     * Returns the set of blessings that have been previously added to the store with an intent of
     * being shared with peers that have at least one of the provided blessings.
     * <p>
     * If no peer blessings are provided then blessings marked for all peers (i.e., those added
     * with the {@link Constants#ALL_PRINCIPALS} pattern) is returned.
     * <p>
     * Returns {@code null} if there are no matching blessings in the store.
     *
     * @param  peerBlessings human-readable peer blessings we're retrieving blessings for
     * @return               the set of blessings that have been previously added to the store with
     *                       an intent of being shared with peers that have at least one of the
     *                       provided (human-readable) blessings
     */
    Blessings forPeer(String... peerBlessings);

    /**
     * Sets up the blessings made available on a subsequent call to
     * {@link #defaultBlessings defaultBlessing}.
     * <p>
     * It is an error to call {@link #setDefaultBlessings setDefaultBlessings} with blessings whose
     * public key does not match the public key of the principal for which this store hosts
     * blessings.
     *
     * @param  blessings       blessings made available on a subsequent call to
     *                         {@link #defaultBlessings defaultBlessings}
     * @throws VException      if there was an error setting the default blessings
     */
    void setDefaultBlessings(Blessings blessings) throws VException;

    /**
     * Returns the blessings to be shared with peers for which no other information is
     * available in order to select blessings from the store.
     * <p>
     * For example, {@link #defaultBlessings defaultBlessings} can be used by servers to identify
     * themselves to clients before the client has identified itself.
     * <p>
     * This method returns the blessings provided to the last call to
     * {@link #setDefaultBlessings setDefaultBlessings}, or if no such call was made it is
     * equivalent to {@link #forPeer forPeer} with no arguments.
     *
     * @return blessings to be shared with peers for which no other information is available
     */
    Blessings defaultBlessings();

    /**
     * Returns the public key of the principal for which this store hosts blessings.
     */
    ECPublicKey publicKey();

    /**
     * Returns all the blessings that the store currently holds for various peers.  Never returns
     * {@code null}.
     */
    Map<BlessingPattern, Blessings> peerBlessings();

    /**
     * Inserts the discharge for the provided impetus and caveat into the cache.
     */
    void cacheDischarge(Discharge discharge, Caveat caveat, DischargeImpetus impetus);

    /**
     * Clears the input discharges from the BlessingStore's discharge cache.
     */
    void clearDischarges(List<Discharge> discharges);

    /**
     * Takes a caveat and DischargeImpetus and returns a cached discharge, returning a {@link
     * WireDischarge#zeroValue zero value} if no corresponding cached discharge can be found.
     */
    Discharge discharge(Caveat caveat, DischargeImpetus impetus);

    /**
     * Return a human-readable string description of the store.  This description is detailed and
     * lists out the contents of the store.  Use {@link Object#toString} for a more succinct
     * description.
     */
    String debugString();
}