trust-store: core::trust Namespace Reference

trust-store 2.0.0 Provides a common implementation of a trust store to be used by trusted helpers.

Namespaces | Classes | Typedefs | Functions
core::trust Namespace Reference

Contains functionality for implementing Ubuntu's trust model. More...

## Namespaces
| dbus
| mir
| tag

## Classes
class | Agent
| Abstracts user-prompting functionality. More...
class | CachedAgent
| An agent implementation that uses a trust store instance to cache results. More...
struct | Errors
| All core::trust-specific error/exception types go here. More...
struct | Request
| The Request struct encapsulates information about a trust request answered by the user. More...
struct | RequestParameters
| Summarizes all parameters for processing a trust request. More...
class | Store
| Models read/write/query access to persisted trust requests. More...
struct | TaggedInteger
| Helper structure for tagging integer types with certain semantics. More...
class | Token
| Opaque type describing the exposure of a store instance. More...

## Typedefs
typedef TaggedInteger< tag::Gid, gid_t > | Gid
| Our internal group id type. More...
typedef TaggedInteger< tag::Pid, pid_t > | Pid
| Our internal process id type. More...
typedef TaggedInteger< tag::Uid, uid_t > | Uid
| Our internal user id type. More...
typedef TaggedInteger< tag::Feature, std::uint64_t > | Feature
| Our internal service-feature type. More...

## Functions
CORE_TRUST_DLL_PUBLIC bool | operator== (const Agent::RequestParameters &lhs, const Agent::RequestParameters &rhs)
| Returns true iff lhs and rhs are equal. More...
CORE_TRUST_DLL_PUBLIC std::unique_ptr< Token > | expose_store_to_bus_with_name (const std::shared_ptr< Store > &store, const std::shared_ptr< core::dbus::Bus > &bus, const std::string &name)
| Exposes an existing store instance on the given bus. More...
CORE_TRUST_DLL_PUBLIC std::unique_ptr< Token > | expose_store_to_session_with_name (const std::shared_ptr< Store > &store, const std::string &name)
| Exposes an existing store instance with the current user session. More...
CORE_TRUST_DLL_PUBLIC bool | operator== (const Request &lhs, const Request &rhs)
| operator == compares two Requests for equality. More...
CORE_TRUST_DLL_PUBLIC std::ostream & | operator<< (std::ostream &out, const Request::Answer &a)
| operator << pretty prints answers to the provided output stream. More...
CORE_TRUST_DLL_PUBLIC std::ostream & | operator<< (std::ostream &out, const Request &r)
| operator << pretty prints a request to the provided output stream. More...
CORE_TRUST_DLL_PUBLIC Request::Answer | process_trust_request (const RequestParameters &params)
| Processes an incoming trust-request by an application, tries to lookup a previous reply before issuing a prompt request via the given agent to the user. On return, the given trust-store is up-to-date. More...
CORE_TRUST_DLL_PUBLIC std::shared_ptr< Store > | resolve_store_on_bus_with_name (const std::shared_ptr< core::dbus::Bus > &bus, const std::string &name)
| Resolves an existing store instance within the current user session. More...
CORE_TRUST_DLL_PUBLIC std::shared_ptr< Store > | resolve_store_in_session_with_name (const std::string &name)
| Resolves an existing store instance within the current user session. More...
CORE_TRUST_DLL_PUBLIC std::shared_ptr< Store > | create_default_store (const std::string &service_name)
| Creates an instance for the default store implementation. More...
template<typename Tag , typename Integer >
bool | operator== (const TaggedInteger< Tag, Integer > &lhs, const TaggedInteger< Tag, Integer > &rhs)
| Returns true iff both tagged integer instances are equal. More...
template<typename Tag , typename Integer >
bool | operator!= (const TaggedInteger< Tag, Integer > &lhs, const TaggedInteger< Tag, Integer > &rhs)
| Returns true iff both tagged integer instances are not equal. More...
template<typename Tag , typename Integer >
bool | operator< (const TaggedInteger< Tag, Integer > &lhs, const TaggedInteger< Tag, Integer > &rhs)
| Returns true iff the left-hand-side integer instance is smaller than the right-hand-side. More...
template<typename Tag , typename Integer >
std::ostream & | operator<< (std::ostream &out, const TaggedInteger< Tag, Integer > &ti)
| Pretty prints a tagged integer. More...

## Detailed Description

Contains functionality for implementing Ubuntu's trust model.

Ubuntu's trust model extends upon a strict confinement approach implemented on top of AppArmor. In this approach, applications are not trusted by default, and we assume a very negative view of the app world. That is, we assume that all apps are created with malicious intentions in mind, invading a user's privacy and wasting resources. For that, we severely limit an application's access to the system and provide trusted gates out of the confinement. These trusted gates, also called trusted helpers, ensure that the user is prompted for granting or denying trust to a specific application.

## Typedef Documentation

## ◆ Feature

typedef TaggedInteger<tag::Feature, std::uint64_t> core::trust::Feature

Our internal service-feature type.

Definition at line 106 of file tagged_integer.h.

## ◆ Gid

typedef TaggedInteger<tag::Gid, gid_t> core::trust::Gid

Our internal group id type.

Definition at line 100 of file tagged_integer.h.

## ◆ Pid

typedef TaggedInteger<tag::Pid, pid_t> core::trust::Pid

Our internal process id type.

Definition at line 102 of file tagged_integer.h.

## ◆ Uid

typedef TaggedInteger<tag::Uid, uid_t> core::trust::Uid

Our internal user id type.

Definition at line 104 of file tagged_integer.h.

## Function Documentation

## ◆ create_default_store()

CORE_TRUST_DLL_PUBLIC std::shared_ptr<Store> core::trust::create_default_store | ( | const std::string & | service_name | ) |

Creates an instance for the default store implementation.

Exceptions

  Error::ServiceNameMustNotBeEmpty. |

Parameters

  service_name | [in] The service name, must not be empty.

Returns
  An instance of trust::Store.

## ◆ expose_store_to_bus_with_name()

CORE_TRUST_DLL_PUBLIC std::unique_ptr<Token> core::trust::expose_store_to_bus_with_name | ( | const std::shared_ptr< Store > & | store,
|  | const std::shared_ptr< core::dbus::Bus > & | bus,
|  | const std::string & | name
| ) |  |

Exposes an existing store instance on the given bus.

Exceptions

  Error::ServiceNameMustNotBeEmpty. |

Parameters

  store | The instance to be exposed.
  bus | The bus connection.
  name | The name under which the service can be found within the session.

Returns
  A token that limits the lifetime of the exposure.

## ◆ expose_store_to_session_with_name()

CORE_TRUST_DLL_PUBLIC std::unique_ptr<Token> core::trust::expose_store_to_session_with_name | ( | const std::shared_ptr< Store > & | store,
|  | const std::string & | name
| ) |  |

Exposes an existing store instance with the current user session.

Exceptions

  Error::ServiceNameMustNotBeEmpty. |

Parameters

  store | The instance to be exposed.
  name | The name under which the service can be found within the session.

Returns
  A token that limits the lifetime of the exposure.

## ◆ operator!=()

template<typename Tag , typename Integer >

bool core::trust::operator!= | ( | const TaggedInteger< Tag, Integer > & | lhs,
|  | const TaggedInteger< Tag, Integer > & | rhs
| ) |  |
| inline

Returns true iff both tagged integer instances are not equal.

Definition at line 68 of file tagged_integer.h.

References core::trust::TaggedInteger< Tag, Integer >::value.

## ◆ operator<()

template<typename Tag , typename Integer >

bool core::trust::operator< | ( | const TaggedInteger< Tag, Integer > & | lhs,
|  | const TaggedInteger< Tag, Integer > & | rhs
| ) |  |
| inline

Returns true iff the left-hand-side integer instance is smaller than the right-hand-side.

Definition at line 75 of file tagged_integer.h.

References core::trust::TaggedInteger< Tag, Integer >::value.

## ◆ operator<<() [1/3]

CORE_TRUST_DLL_PUBLIC std::ostream& core::trust::operator<< | ( | std::ostream & | out,
|  | const Request & | r
| ) |  |

operator << pretty prints a request to the provided output stream.

Parameters

  out | [in, out] The stream to print to.
  r | The request to be printed.

Returns
  The output stream.

## ◆ operator<<() [2/3]

CORE_TRUST_DLL_PUBLIC std::ostream& core::trust::operator<< | ( | std::ostream & | out,
|  | const Request::Answer & | a
| ) |  |

operator << pretty prints answers to the provided output stream.

Parameters

  out | [in, out] The stream to print to.
  a | The answer to be printed.

Returns
  The output stream.

## ◆ operator<<() [3/3]

template<typename Tag , typename Integer >

std::ostream& core::trust::operator<< | ( | std::ostream & | out,
|  | const TaggedInteger< Tag, Integer > & | ti
| ) |  |
| inline

Pretty prints a tagged integer.

Definition at line 82 of file tagged_integer.h.

References core::trust::TaggedInteger< Tag, Integer >::value.

## ◆ operator==() [1/3]

CORE_TRUST_DLL_PUBLIC bool core::trust::operator== | ( | const Agent::RequestParameters & | lhs,
|  | const Agent::RequestParameters & | rhs
| ) |  |

Returns true iff lhs and rhs are equal.

## ◆ operator==() [2/3]

CORE_TRUST_DLL_PUBLIC bool core::trust::operator== | ( | const Request & | lhs,
|  | const Request & | rhs
| ) |  |

operator == compares two Requests for equality.

Parameters

  lhs | [in] The left-hand-side of the comparison.
  rhs | [in] The right-hand-side of the comparison.

Returns
  true iff both requests are equal.

## ◆ operator==() [3/3]

template<typename Tag , typename Integer >

bool core::trust::operator== | ( | const TaggedInteger< Tag, Integer > & | lhs,
|  | const TaggedInteger< Tag, Integer > & | rhs
| ) |  |
| inline

Returns true iff both tagged integer instances are equal.

Definition at line 61 of file tagged_integer.h.

References core::trust::TaggedInteger< Tag, Integer >::value.

## ◆ process_trust_request()

CORE_TRUST_DLL_PUBLIC Request::Answer core::trust::process_trust_request | ( | const RequestParameters & | params | ) |

Processes an incoming trust-request by an application, tries to lookup a previous reply before issuing a prompt request via the given agent to the user. On return, the given trust-store is up-to-date.

Exceptions

  std::exception | To indicate that no conclusive answer could be resolved from either the store or the user. In that case, the state of the store instance passed in to the function is not altered.

The following code snippet illustrates how to use the function:

struct Service
{
static constexpr std::uint64_t default_feature = 0;
void on_session_requested(core::trust::Uid app_uid, core::trust::Pid app_pid, std::string const& app_id)
{
core::trust::RequestParameters params
{
trust.agent,
trust.store,
app_uid,
app_pid,
app_id,
core::trust::Feature{default_feature},
"Application " + app_id + " wants to access the example service."
};
switch(process_trust_request(params))
{
case core::trust::Request::Answer::granted:
// Create session and get back to application with session credentials.
break;
case core::trust::Request::Answer::denied:
// Deny session creation and inform application.
break;
}
}
struct
{
// We use Mir's trust session support to request the prompting UI.
std::shared_ptr<core::trust::Agent> agent
{
core::trust::mir::make_agent_for_existing_connection(mir_connection)
};
std::shared_ptr<core::trust::Store> store
{
core::trust::create_default_store("my.example.service");
};
} trust;
};

## ◆ resolve_store_in_session_with_name()

CORE_TRUST_DLL_PUBLIC std::shared_ptr<Store> core::trust::resolve_store_in_session_with_name | ( | const std::string & | name | ) |

Resolves an existing store instance within the current user session.

Exceptions

  Error::ServiceNameMustNotBeEmpty. |

Parameters

  name | The name under which the service can be found within the session.

Returns
  A token that limits the lifetime of the exposure.

## ◆ resolve_store_on_bus_with_name()

CORE_TRUST_DLL_PUBLIC std::shared_ptr<Store> core::trust::resolve_store_on_bus_with_name | ( | const std::shared_ptr< core::dbus::Bus > & | bus,
|  | const std::string & | name
| ) |  |

Resolves an existing store instance within the current user session.

Exceptions

  Error::ServiceNameMustNotBeEmpty. |

Parameters

  bus | The bus connection.
  name | The name under which the service can be found within the session.

Returns
  A token that limits the lifetime of the exposure.

core::trust::RequestParameters::agent
std::shared_ptr< Agent > agent
The Agent implementation to dispatch a request to the user.
Definition: request.h:108
core::trust::TaggedInteger< tag::Uid, uid_t >
core::trust::Request::Answer::granted
@ granted
Yup, I do trust this application.
core::trust::RequestParameters
Summarizes all parameters for processing a trust request.
Definition: request.h:106
core::trust::Request::Answer::denied
@ denied
Nope, I do not trust this application.
core::trust::create_default_store
CORE_TRUST_DLL_PUBLIC std::shared_ptr< Store > create_default_store(const std::string &service_name)
Creates an instance for the default store implementation.
core::trust::process_trust_request
CORE_TRUST_DLL_PUBLIC Request::Answer process_trust_request(const RequestParameters &params)
Processes an incoming trust-request by an application, tries to lookup a previous reply before issuin...