Password/Pin protection

[sosthene-nitrokey]

The idea of adding PIN support has already been raised. I'm trying to draft what such an API would look like.

We could either create a new PinClient trait, or add it as part of the CryptoClient. This functionality would allow creation of PIN-Protected keys.

The way I see it, the API would add a couple methods:

/// Protect an existing key with a PIN
/// This operation deletes the non-protected key, making it accessible only via `unlock_pin`
fn create_pin(&mut self, key: KeyId, attempts_limit: u16, pin: &[u8])
    -> ClientResult<'_, reply::CreatePin, Self>
 
/// Generate a new random Key, protected by a PIN
///
///  Setting attempts_limit at 0 allows infinite attempts.
fn generate_pin(&mut self, mechanism: Mechanism, attempts_limit: u16, pin: &[u8])
    -> ClientResult<'_, reply::CreatePin, Self>

/// Get the number of remaining attempts at unlocking the pin
fn pin_retries(&mut self, pin: PinId)
    -> ClientResult<'_, reply::PinRetries, Self>

/// Tries to unlock the pin, if successful, reset the retry counter
fn unlock_pin(&mut self, pin: PinId, value: &[u8])
    -> ClientResult<'_, reply::UnlockPin, Self>

/// Lock the pin, making the key it protects inaccessible, even if the corresponding `KeyId` is used
fn lock_pin(&mut self, pin: PinId)
    -> ClientResult<'_, reply::LockPin, Self>

with the reply structures:

/// Id of the generated PIN
pub struct CreatePin {
    pin: PinId,
    key; KeyId,
}

/// Number of possible retries
pub struct PinRetries {
    retries: u16,
}

/// Result of unlocking the PIN
pub struct UnlockPin {
    /// None if the PIN validation failed
    key: Option<KeyId>
}

pub struct LockPin {}

This makes the resulting API easy to use. Multiple keys can be protected using (un)wrap_key with a pin-protected key. It also allows more complex setups with "user" and "admin" PIN where the admin can reset the counter of the user PIN. (This would be done by creating a new pin, unwrapping the key with the admin pin, and re-wrapping the key with the key of the newly generated user pin).

[sosthene-nitrokey]

It might be interesting to have a way to support protecting more than a single key with a pin, for example unlock_pin could return a "token" that could be then passed to other crypto methods. Keys that are protected by the PIN would error if the token is incorrect or for a closed session.

[daringer]

Summarizing the current state of this concept here. This replaces the concept above and also extends the whole concept with some implementation details, while also extending the scope of this towards an Abstract Authentication Mechanism.

The service backends changeset is strictly needed and used within this approach. In particular there will be an secondary software backend, which will implement (and therefore overwrite) multiple API calls in a way that the authentication context will be verified automatically by trussed and the client will be enabled to maintain these contexts. This will also ensure a proper backwards compatibility. The current fido-authenticator can stay as it is, while in parallel there can be other clients implementing authentication through this mechanism by setting the proper backend-service order like: software_v2, software instead of just software

Requirements / Goals

• Top priority: keep backwards compatibility for the fido-authenticator client
  (means it should build with trussed w/o any changes)
• Trussed should provide an abstract mechanism to:
  • allow clients to define a user-context (e.g., user, admin, authorized)
  • associate objects (keys, certs, ...) with a user-context and set-of-policies
• Trussed should introduce and handle the following policies:
  • read, write, delete, gen, import, encrypt, decrypt, sign, verify, all .... (tbd)
• A client should have the possibility to ensure that certain operations are only allowed to be executed under a (client-defined) policy, e.g.:
  • Sign with KeyID == "abc" is only allowed, if the client has set a proper user context a.k.a. PIN
  • Deletion of KeyID == "abc" is only allowed within the admin context

API extensions:

• set_pin_context(contextId: &[u8], pin: &[u8])
  • contextId might be a simple string here, or we enforce a u8 derived from a client-side-enum
  • it would make sense to properly return if the context can be acquired using this pin, the client can use this to do operations which are not necessarily (directly) bound to data-objects but still require authentication (reset?)
• set_policy_context() ...
  • provide a given set of policies to be used for the next creation/generation of an object
• create_context(contextId: &[u8], pin: &[u8]) (likely only possible, if context was not created yet)
• change_context(contextId: &[u8], pin: &[u8]) (once the context was created)

Software v2 API

Using the "service backends" approach we can easily allow a client to define in which order service backends can be asked to handle a given syscall. Each service backend also needs to implement its own KeyStore, CertStore, CounterStore.

Eventually, a software-v2 service backend must be implemented, which will enforce the permissions for the policies and user-contexts defined by the client.

Authentication Representation in Storage

• PinContextEntry
  • Keeps the (hashed) pin for a client-defined context
  • Members:
    • secret
    • contextId
  • Example: {secret: "78gh23f...7r83gf", contextID: "admin"}
• AccessControlEntry
  • Keeps the access control information for a specific object
  • Members:
    • objectID (keyId, CertId, BlobId, CounterId)
      [might not be needed, as we could place this simply next to the object, e.g., /path/to/my/key.acl]
    • <contextID_1>: {"<policy_1>", ... , "<policy_N>"}
    • <contextID_X>: {"<policy_1>", ... , "<policy_M>"}
  • Example:{objectID: "abc", admin: {"write", "modify"}, user: {"use"}, noauth: {}

This is to be seen as an early draft of a "spec"/TIP for an abstract authentication mechanism, overall this will grow and mature during the implementation. Thanks to especially @sosthene-nitrokey & @jnordholz for the fruitful discussions leading to this draft...

ToDos / Open Questions

• contextId is kind of ugly, creating an enum inside the client would need a conversion back to str or u8, so maybe define a enum inside trussed ? (how many different contexts can there be?)
• set_policy_context() tbd
• currently there this mapping: (user-context) x (policies) => (objectId) this allows only the application of policies for existing objects, how can trussed enforce that only a specific user-context (e.g., admin-context for OpenPGPCard) can generate/create a new key? One option would be to use the response of set_pin_context(), so the client could enforce this by himself, but this would be somehow an inconsistency within this concept...

This content as a file for easier editing: AbstractAuthenticationMechanism.md

[sosthene-nitrokey]

Maybe the policy for keys could be passed as a field of StorageAttributes? It's taken as an argument for most key persistence operations.