trust-store  1.0.0
Provides a common implementation of a trust store to be used by trusted helpers.
core::trust Namespace Reference

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

Namespaces

 mir
 

Classes

class  Agent
 Abstracts user-prompting functionality. 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...
 
class  Token
 Opaque type describing the exposure of a store instance. More...
 

Functions

CORE_TRUST_DLL_PUBLIC
std::unique_ptr< Token
expose_store_to_bus_with_name (const std::shared_ptr< Store > &store, const std::shared_ptr< 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...
 

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.

Function Documentation

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.
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< dbus::Bus > &  bus,
const std::string &  name 
)

Exposes an existing store instance on the given bus.

Exceptions
Error::ServiceNameMustNotBeEmpty.
Parameters
storeThe instance to be exposed.
nameThe name under which the service can be found within the session.
Returns
A token that limits the lifetime of the exposure.
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
storeThe instance to be exposed.
nameThe name under which the service can be found within the session.
Returns
A token that limits the lifetime of the exposure.
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.
aThe answer to be printed.
Returns
The output stream.
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.
rThe request to be printed.
Returns
The output stream.
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.
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::exceptionTo 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(pid_t app_pid, const std::string& app_id)
{
{
trust.agent,
trust.store,
app_pid,
app_id,
default_feature,
"Application " + app_id + " wants to access the example service."
};
switch(process_trust_request(params))
{
// Create session and get back to application with session credentials.
break;
// 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;
};
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
nameThe name under which the service can be found within the session.
Returns
A token that limits the lifetime of the exposure.
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
nameThe name under which the service can be found within the session.
Returns
A token that limits the lifetime of the exposure.