CODEX_APSS::StateInfo Class Reference

This is a singleton class that holds all of the state information that different parts of the APSS protocol need to share. More...

#include <StateInfo.h>

Collaboration diagram for CODEX_APSS::StateInfo:

[legend]List of all members.

Public Types
typedef map< unsigned int, SecretManagement >	SecretManagementMap
	Shorthand for a mapping between identifiers of secrets and the SecretManagement objects maintaining them.
Public Member Functions
void	configure (const CONF *conf, const char *sec, const string &fname)
	Configure the APSS from an OpenSSL CONF-format file.
void	setDomain (unsigned char d)
	Set the 1-byte domain identifier for this module.
unsigned char	domain () const
	The 1-byte domain identifier for this module.
void	setMessageDeliverer (MessageDeliverer *deliverer)
	Set the MessageDeliverer.
unsigned int	refreshInterval () const
	The interval, in seconds, between successive APSS runs.
void	addSharing (LSType *sharing)
	Add a new labeled sharing.
const LSType &	sharing (const LSType::LabelType &label, unsigned int server) const
	Get the sharing with a particular label.
const WitnessType &	witness (unsigned int num) const
	Get the witness for a secret.
const ShareSetType &	subsharing (const SublabelType &sublabel, unsigned int server) const
	Get the subsharing with a particular label.
void	addSubsharing (const SublabelType &sublabel, const ShareType &subsharing)
	Add a splitting of a share with a given label.
void	recover (const SublabelType &sublabel)
	Recover the subsharings corresponding to a label from the other servers in the system.
void	markRecovered (const SublabelType &sublabel)
	Mark a subsharing label as recovered.
SubshareList &	splittings (const LabelType &label)
	Retrieve the splittings for all shares corresponding to a label.
const CODEX_VSS::Range &	subshareRange (unsigned int num) const
	The CODEX_VSS::Range in which to generate subshares for a secret.
void	updateExpired ()
	Initiate the APSS protocol for expired secrets.
void	updateAll ()
	Initiate the APSS protocol for all secrets, regardless of the time since the last refresh.
bool	addInitMsg (const SignedInitMsg &im)
	Add a SignedInitMsg to the log.
bool	addEstablishMsg (const SignedEstablishMsg &em)
	Add a SignedEstablishMsg to the log.
bool	addComputeMsg (const SignedComputeMsg &cm)
	Add a SignedComputeMsg to the log.
bool	addFinishedMsg (const SignedFinishedMsg &fm)
	Add a SignedFinishedMsg to the log.
bool	addInitResponse (const SignedContributeMsg &cm)
	Add a SignedContributeMsg to the log.
bool	addEstablishResponse (const SignedEstablishedMsg &em)
	Add a SignedEstablishedMsg to the log.
bool	addComputeResponse (const SignedComputedMsg &cm)
	Add a SignedComputedMsg to the log.
void	clearEstablishMsgs (unsigned int num)
	Remove cached EstablishMsg%s for a secret.
void	clearEstablishMsgs (unsigned int num, unsigned int establisher)
	Removed cached EstablishMsg%s for a secret that were sent by a particular server.
unsigned long	version (unsigned int num) const
	The current version (epoch) number for a secret.
const InitRecord &	initRecord (unsigned int num, unsigned int i) const
	Retrieve the InitRecord for a secret and a coordinator.
const EstablishRecord &	establishRecord (unsigned int num, unsigned int establisher, unsigned int shareNum, const LabelType &label) const
	Retrieve the EstablishRecord for a secret, an establishing server, and a specific share.
const ComputeRecord &	computeRecord (unsigned int num, unsigned int i) const
	Retrieve the ComputeRecord for a secret and a coordinator.
const SignedFinishedMsg &	finishedMsg (unsigned int num, unsigned int i) const
	Retrieve the SignedFinishedMsg for a secret and a coordinator.
void	sendFinished (unsigned int num, unsigned int server) const
	Send a SignedFinishedMsg to a server.
void	sendFinished (unsigned int num, unsigned int coord, unsigned int server) const
	Send a SignedFinishedMsg to a server.
void	sendTo (unsigned int server, const CODEX_Quorum::Message &message)
	Send a message to a server.
void	broadcast (const CODEX_Quorum::Message &message, CODEX_Quorum::ResponseCallback *cb)
	Broadcast a message to all servers.
Static Public Member Functions
static StateInfo *	instance ()
	Static method to fetch the unique instance.
static void	destroy ()
	Destroys the unique instance.
Static Public Attributes
static const unsigned int	NumShares = LabelType::NumShares
	Shorthand for the number of shares into which a secret is split.
static const unsigned int	NumServers
	Shorthand for the number of servers in the system.
Protected Member Functions
	StateInfo ()
	Protected constructor, prevents multiple instances.
virtual	~StateInfo ()
	Protected virtual destructor.
void	checkSecretNum (unsigned int num) const
	Test a secret ID for validity.
Static Protected Attributes
static StateInfo *	m_instance = 0
	Unique instance of this class.

---

Detailed Description

This is a singleton class that holds all of the state information that different parts of the APSS protocol need to share.

Implementing the state this way allows us not to have to pass pointers and references to the state everywhere. There is, of course, the danger that something that really shouldn't be accessing the state will be able to, but since the server code has to be trusted on that server in any event, this shouldn't matter.

Definition at line 51 of file CODEX_APSS/StateInfo.h.

---

Member Function Documentation

bool StateInfo::addComputeMsg (  const SignedComputeMsg &  cm  )

Add a SignedComputeMsg to the log. Parameters: cm  The request to add. Returns: Whether the message was added successfully. Exceptions: BadSecretNumberException  if the message does not correspond to a known secret. Definition at line 358 of file CODEX_APSS/StateInfo.cc. References checkSecretNum(). Referenced by CODEX_APSS::MessageVerifier::handler().

bool StateInfo::addComputeResponse (  const SignedComputedMsg &  cm  )

Add a SignedComputedMsg to the log. This will be matched with the corresponding ComputeMsg. Parameters: cm  The response to add. Returns: Whether the message was added successfully. Exceptions: BadSecretNumberException  if the message does not correspond to a known secret. Definition at line 393 of file CODEX_APSS/StateInfo.cc. References checkSecretNum(). Referenced by CODEX_APSS::MessageProcessor::handler().

bool StateInfo::addEstablishMsg (  const SignedEstablishMsg &  em  )

Add a SignedEstablishMsg to the log. Parameters: em  The request to add. Returns: Whether the message was added successfully. Exceptions: BadSecretNumberException  if the message does not correspond to a known secret. Definition at line 350 of file CODEX_APSS/StateInfo.cc. References checkSecretNum(). Referenced by CODEX_APSS::MessageVerifier::handler().

bool StateInfo::addEstablishResponse (  const SignedEstablishedMsg &  em  )

Add a SignedEstablishedMsg to the log. This will be matched with the corresponding EstablishMsg. Parameters: em  The response to add. Returns: Whether the message was added successfully. Exceptions: BadSecretNumberException  if the message does not correspond to a known secret. Definition at line 385 of file CODEX_APSS/StateInfo.cc. References checkSecretNum(), and CODEX_VSS::SubshareLabel< _ShareLabel >::label(). Referenced by CODEX_APSS::MessageProcessor::handler().

bool StateInfo::addFinishedMsg (  const SignedFinishedMsg &  fm  )

Add a SignedFinishedMsg to the log. If this is the first SignedFinishedMsg for a secret with a new version, cleanup will be initiated. See also: SecretManagement::addFinishedMsg() Parameters: fm  The request to add. Returns: Whether the message was added successfully. Exceptions: BadSecretNumberException  if the message does not correspond to a known secret. Definition at line 366 of file CODEX_APSS/StateInfo.cc. References checkSecretNum(). Referenced by CODEX_APSS::MessageVerifier::handler().

bool StateInfo::addInitMsg (  const SignedInitMsg &  im  )

Add a SignedInitMsg to the log. Parameters: im  The request to add. Returns: Whether the message was added successfully. Exceptions: BadSecretNumberException  if the message does not correspond to a known secret. Definition at line 342 of file CODEX_APSS/StateInfo.cc. References checkSecretNum(). Referenced by CODEX_APSS::MessageVerifier::handler().

bool StateInfo::addInitResponse (  const SignedContributeMsg &  cm  )

Add a SignedContributeMsg to the log. This will be matched with the corresponding InitMsg. Parameters: cm  The response to add. Returns: Whether the message was added successfully. Exceptions: BadSecretNumberException  if the message does not correspond to a known secret. Definition at line 376 of file CODEX_APSS/StateInfo.cc. References checkSecretNum(), CODEX_VSS::SubshareLabel< _ShareLabel >::label(), CODEX_APSS::SignedMessage< MT, ST >::message(), and CODEX_APSS::EstablishedMsg::sublabel(). Referenced by CODEX_APSS::InitActivity::addEvidence().

void StateInfo::addSubsharing (  const SublabelType &  sublabel, const ShareType &  subsharing )

Add a splitting of a share with a given label. The label must be consistent with the sharing. Parameters: sublabel  The labelling for the set of subshares. subsharing  The splitting of a share. Definition at line 191 of file CODEX_APSS/StateInfo.cc. References checkSecretNum(), and subsharing().

void StateInfo::broadcast (  const CODEX_Quorum::Message &  message, CODEX_Quorum::ResponseCallback *  cb )

Broadcast a message to all servers. This passes the arguments to a special CODEX_Events::Activity that only exists to emit events and collect the acknowledgements. This is useful for those methods needing to generate messages but not themselves members of a CODEX_Events::Activity. Parameters: message  The message to send. cb  The callback to handle responses. Definition at line 480 of file CODEX_APSS/StateInfo.cc. References CODEX_APSS::MessageDeliverer::broadcast(). Referenced by CODEX_APSS::SecretManagement::beginRun(), and recover().

void StateInfo::clearEstablishMsgs (  unsigned int  num, unsigned int  establisher )

Removed cached EstablishMsg%s for a secret that were sent by a particular server. Parameters: num  The identifier for a secret. establisher  The server from which the messages originated. Exceptions: BadSecretNumberException  if the identifier does not correspond to a known secret. Definition at line 408 of file CODEX_APSS/StateInfo.cc. References checkSecretNum().

void StateInfo::clearEstablishMsgs (  unsigned int  num  )

Remove cached EstablishMsg%s for a secret. Parameters: num  The identifier for a secret. Exceptions: BadSecretNumberException  if the identifier does not correspond to a known secret. Definition at line 401 of file CODEX_APSS/StateInfo.cc. References checkSecretNum().

const ComputeRecord & StateInfo::computeRecord (  unsigned int  num, unsigned int  i )  const

Retrieve the ComputeRecord for a secret and a coordinator. Parameters: num  The identifier for a secret. i  The coordinator initiating an instance of the APSS protocol for the secret. Returns: An object containing the most recent ComputeMsg for the secret sent by the specified coordinator, as well as any cached response. Exceptions: BadSecretNumberException  if the identifier does not correspond to a known secret. Definition at line 441 of file CODEX_APSS/StateInfo.cc. References checkSecretNum(). Referenced by CODEX_APSS::MessageVerifier::handler().

const EstablishRecord & StateInfo::establishRecord (  unsigned int  num, unsigned int  establisher, unsigned int  shareNum, const LabelType &  label )  const

Retrieve the EstablishRecord for a secret, an establishing server, and a specific share. Parameters: num  The identifier for a secret. establisher  The server propagating a subsharing for a share of the secret. shareNum  The index of the share split by the server. label  The label for a sharing of a secret from which the split share is drawn. Returns: An object containing the EstablishMsg for the specified subsharing, as well as any cached response. Exceptions: BadSecretNumberException  if the identifier does not correspond to a known secret. Definition at line 429 of file CODEX_APSS/StateInfo.cc. References checkSecretNum(). Referenced by CODEX_APSS::MessageVerifier::handler().

const SignedFinishedMsg & StateInfo::finishedMsg (  unsigned int  num, unsigned int  i )  const

Retrieve the SignedFinishedMsg for a secret and a coordinator. Parameters: num  The identifier for a secret. i  The coordinator initiating an instance of the APSS protocol for the secret. Returns: A signed FinishedMsg indicating the successful termination of the APSS protocol, which is uninitialized if there is no currently-valid sharing established by this coordinator. Exceptions: BadSecretNumberException  if the identifier does not correspond to a known secret. Definition at line 448 of file CODEX_APSS/StateInfo.cc. References checkSecretNum(). Referenced by CODEX_APSS::MessageVerifier::handler().

const InitRecord & StateInfo::initRecord (  unsigned int  num, unsigned int  i )  const

Retrieve the InitRecord for a secret and a coordinator. Parameters: num  The identifier for a secret. i  The coordinator initiating an instance of the APSS protocol for the secret. Returns: An object containing the most recent InitMsg for the secret sent by the specified coordinator, as well as any cached response. Exceptions: BadSecretNumberException  if the identifier does not correspond to a known secret. Definition at line 422 of file CODEX_APSS/StateInfo.cc. References checkSecretNum(). Referenced by CODEX_APSS::MessageVerifier::handler().

void StateInfo::markRecovered (  const SublabelType &  sublabel  )

Mark a subsharing label as recovered. This should be called when recovery is complete, or when recovery is terminated for other reasons. If the label is not in the list, no error is reported. Parameters: sublabel  The label to remove from the recovery list Definition at line 281 of file CODEX_APSS/StateInfo.cc. Referenced by CODEX_APSS::RecoverCallback::~RecoverCallback().

void StateInfo::recover (  const SublabelType &  sublabel  )

Recover the subsharings corresponding to a label from the other servers in the system. Parameters: sublabel  The label to be recovered Definition at line 200 of file CODEX_APSS/StateInfo.cc. References broadcast(), domain(), CODEX_Quorum::Message::fill(), CODEX_Server::ServerState::hashFunc(), CODEX_Server::ServerState::hostNum(), instance(), CODEX_Server::ServerState::instance(), CODEX_APSS::SignedMessage< MT, ST >::marshal(), CODEX_Server::ServerState::newSequenceNumber(), CODEX_Server::ServerState::privateKey(), CODEX_Ciphers::RSAPrivateKey::sign(), CODEX_APSS::SignatureMask, and version(). Referenced by CODEX_APSS::MessageProcessor::handler().

void StateInfo::sendFinished (  unsigned int  num, unsigned int  coord, unsigned int  server )  const

Send a SignedFinishedMsg to a server. Parameters: num  The number of the secret coord  The coordinator establishing the sharing server  The server to which the message should be sent Definition at line 462 of file CODEX_APSS/StateInfo.cc. References checkSecretNum().

void StateInfo::sendFinished (  unsigned int  num, unsigned int  server )  const

Send a SignedFinishedMsg to a server. This method will use the message corresponding to the default label for the secret. Parameters: num  The number of the secret server  The server to which the message should be sent Definition at line 455 of file CODEX_APSS/StateInfo.cc. References checkSecretNum(). Referenced by CODEX_APSS::MessageVerifier::handler().

void StateInfo::sendTo (  unsigned int  server, const CODEX_Quorum::Message &  message )

Send a message to a server. This passes the arguments to a special CODEX_Events::Activity that only exists to emit events and collect the acknowledgements. This is useful for those methods needing to generate messages but not themselves members of a CODEX_Events::Activity. Parameters: server  The server to contact. message  The message to send. Definition at line 471 of file CODEX_APSS/StateInfo.cc. References CODEX_APSS::MessageDeliverer::sendTo(). Referenced by CODEX_APSS::SecretManagement::sendFinished().

void CODEX_APSS::StateInfo::setMessageDeliverer (  MessageDeliverer *  deliverer  )  [inline]

Set the MessageDeliverer. This is used by objects that are not CODEX_Events::Activitys but need to send messages to servers. Definition at line 110 of file CODEX_APSS/StateInfo.h.

const LSType & StateInfo::sharing (  const LSType::LabelType &  label, unsigned int  server )  const

Get the sharing with a particular label. If the label is not present locally share recovery will be triggered, but only if the version number in the label is greater than the current local version number or they are equal and no sharing was established at this server by the specified coordinator. Parameters: label  The label requested. server  The requesting server. This is needed in order to send finished messages in response to out-of-date labels. Returns: The sharing, if present Exceptions: CODEX_Server::KeySharesNotFoundException  if the label does not exist at this server. Definition at line 167 of file CODEX_APSS/StateInfo.cc. References checkSecretNum(). Referenced by addSharing(), CODEX_APSS::MessageProcessor::handler(), and CODEX_APSS::APSSShareCallback::operator()().

SubshareList & StateInfo::splittings (  const LabelType &  label  )

Retrieve the splittings for all shares corresponding to a label. Parameters: label  The label of the sharing. Returns: The splittings of the shares held with the label. See also: SecretManagement::splittings() Definition at line 287 of file CODEX_APSS/StateInfo.cc. References checkSecretNum(). Referenced by CODEX_APSS::MessageProcessor::handler().

const CODEX_VSS::Range & StateInfo::subshareRange (  unsigned int  num  )  const

The CODEX_VSS::Range in which to generate subshares for a secret. Parameters: num  The identifier for a secret. Returns: The range in which to generate subshares. Definition at line 295 of file CODEX_APSS/StateInfo.cc. References checkSecretNum(). Referenced by CODEX_APSS::MessageProcessor::handler().

const ShareSetType & StateInfo::subsharing (  const SublabelType &  sublabel, unsigned int  server )  const

Get the subsharing with a particular label. If the label is not present locally an exception will be thrown. Parameters: sublabel  The label requested. server  The requesting server. This is needed in order to send finished messages in response to out-of-date labels. Returns: The subsharing, if present Exceptions: CODEX_Server::KeySharesNotFoundException  if the label does not exist at this server. Definition at line 182 of file CODEX_APSS/StateInfo.cc. References checkSecretNum(). Referenced by addSubsharing(), and CODEX_APSS::MessageProcessor::handler().

void StateInfo::updateAll (   )

Initiate the APSS protocol for all secrets, regardless of the time since the last refresh. This method is suitable for cron-like refreshing of secrets, where APSS is triggered at a specified time, rather than according to a secret-by-secret interval. Definition at line 331 of file CODEX_APSS/StateInfo.cc.

void StateInfo::updateExpired (   )

Initiate the APSS protocol for expired secrets. For each secret maintained by this module, check its time since establishment against the configured refresh interval. If the refresh interval has been exceeded, call SecretManagement::beginRun() for the secret. This method is suitable for a continuously-queued CODEX_Events::Event that enforces periodic refreshing of secrets. Definition at line 302 of file CODEX_APSS/StateInfo.cc. Referenced by CODEX_APSS::TriggerActivity::handler().

unsigned long StateInfo::version (  unsigned int  num  )  const

The current version (epoch) number for a secret. Parameters: num  The identifier for a secret. Returns: The current epoch for that secret at this server. Exceptions: BadSecretNumberException  if the identifier does not correspond to a known secret. Definition at line 415 of file CODEX_APSS/StateInfo.cc. References checkSecretNum(). Referenced by recover().

const WitnessType & StateInfo::witness (  unsigned int  num  )  const

Get the witness for a secret. Parameters: num  The number of the secret Returns: The witness for the secret, used to test the validity of a label. Definition at line 175 of file CODEX_APSS/StateInfo.cc. References checkSecretNum(), and CODEX_VSS::SecretWitness< _ShareType, _OneWay >::witness(). Referenced by CODEX_APSS::MessageVerifier::handler(), and CODEX_APSS::MessageProcessor::handler().

---

Member Data Documentation

const unsigned int CODEX_APSS::StateInfo::NumServers [static]

Initial value: CODEX_Server::ServerState::nServers Shorthand for the number of servers in the system. Definition at line 75 of file CODEX_APSS/StateInfo.h.

---

The documentation for this class was generated from the following files:

• CODEX_APSS/StateInfo.h
• CODEX_APSS/StateInfo.cc
• CODEX_KeyService/StateInfo.cc

---