<pre>
FTN8.3: FutoIn Security Concept - Master Secret Authentication
Version: 0.4DV
Date: 2018-05-18
Copyright: 2014-2018 FutoIn Project (http://futoin.org)
Authors: Andrey Galkin
</pre>

# CHANGES

* v0.3 - 2018-05-18 - Andrey Galkin
    - CHANGED: revised with implementation
* v0.2 - 2017-12-30 - Andrey Galkin
    - CHANGED: heavily revised & split into sub-specs
* v0.1 - 2014-06-03 - Andrey Galkin
    - Initial draft

# 1. Intro

This sub-specification of [FTN8](./ftn8_security_concept.md) covers
more secure Master Secret Authentication with dynamically updated shared secrets.

Service is assumed to be a B2B software or equal - high number of
unattended requests.

# 2. Concept

## 2.1. Overall idea

1. Strong symmetric master key is assumed under "Secret".
2. Use approach to exchange keys based on temporary asymmetric key generated by Service.
    - RSA 2048/4096-bit with ephemeral key as safe default.
    - X25519 with [ECIES][] for key encryption
    - X448 with [ECIES][] for key encryption
3. Ensure asymmetric key authenticity based transport security and/or
    existing shared Secret signing.
4. Ensure temporary key and new Secret quality by AuthService.
5. Use one of supported key derivation strategies:
    - do not lock on one method,
    - allow tradeoff between performance and extra security at use time.
6. Secret exchange interval solely depends on Invoker, but AuthService
    may deactivate too old or too used keys (defined by configuration).

## 2.2. Secure Master Secret exchange

1. Service makes initial call:
    - generates a temporary asymmetric key,
    - requests a new Master Secret from AuthService providing:
        - the temporary public key for response encryption,
        - current active Master Secret ID as part of MAC.
2. AuthService processes the request:
    - ensures request is authentic based on Master MAC signature,
    - ensures that primary Master Key (not scoped) is used,
    - generates a new Secret,
    - cleans up old secrets ensuring current active Master Secret ID remains
      per required scope,
    - sends back the new Master Secret encrypted by the temporary public key.
3. Service processes response:
    - decrypts the payload using the temporary private key,
    - injects the new Master Secret as primary.
4. Service gradually starts using the new Secret.
5. Both the new Secret and the previous Secret are active.

Goals met:

* Forward secrecy even if any secret gets compromised.
* Works over unencrypted/untrusted channels, but it is discouraged.
* Ensure rolling Secret updates without communication interruptions.
* AuthService controls Secret quality.
* Resource-heavy asymmetric key generation is responsibility of Service to
  protect AuthService of heavy load.
* Initiating Service (acting as Invoker) is responsible for periodic
  Master Secret exchange.
    - It may not do that at all to reduce complexity, if static key is acceptable.
    - It avoids overcomplicated design with AuthService-to-Service callbacks.

## 2.3 "sec" field structured format

`Schema(futoin-sec-master-mac){`

    {
        "title" : "FutoIn 'sec' field - Master MAC",
        "type" : "object",
        "additionalProperties" : false,
        "required" : [ "msid", "algo", "kds", "sig" ],
        "properties" : {
            "msid" : {
                "type" : "string",
                "description" : "Unique Master Secret ID"
            },
            "algo" : {
                "type" : "string",
                "description" : "MAC algo name as defined in FTN8"
            },
            "kds" : {
                "type" : "string",
                "description" : "Key Derivation Strategy"
            },
            "prm" : {
                "type" : "string",
                "description" : "KDS parameter, if applicable"
            },
            "sig" : {
                "type" : "string",
                "description" : "Base64 encoded MAC"
            }
        }
    }

`}Schema`

## 2.4 "sec" field string format

```
    "-mmac:{msid}:{algo}:{dks}:{prm}:{sig}"
```

## 2.5. Master MAC response "sec" field

Response must be authenticated by the same Secret and the same hash algorithm
as used for request signing. Only signature has to be sent.


## 2.6. Master MAC security level

`ExceptionalOps` security level must be assigned.

## 2.7. Optional Master Secret Scope

User/Service is in control of its own privacy vs. simplicity. There is an optional,
`scope` parameter for new Master Secret generation.

Peer Service must not be able to get derived key for particular Master Secret directly.
It must be possible only if invoking Service signs any message with particular derived key -
implicit approval to provide Derived Key to particular Service.

Only Master Secret with empty or matching `scope` must be accepted for new Secret
exchange to mitigate unauthorized access with Master Secret recovered from scoped
derived key. So, Master Secret with empty `scope` is seen as "main".

There are various options:

1. Use one global Master Secret with high risk of its recovery through derived key.
2. Use several Master Secrets per peer service vendor.
3. Use a separate Master Secret per each peer.

## 2.8. Events

* `MSTR_NEW` - new master secret
    * `user` - LocalUserID
    * `key_id` - MasterSecretID
    * `scope` - key scope
* `MSTR_DEL` - master secret delete
    * `key_id` - LocalUserID
    * `id` - MasterSecretID

# 3. Interface

## 3.1. Message authentication

Provide Master Secret based authentication to Executor.

It is designed the way when MAC secret is always kept inside AuthService to
minimize risk of exposure.

`Iface{`

    {
        "iface" : "futoin.auth.master",
        "version" : "{ver}",
        "ftn3rev" : "1.9",
        "imports" : [
            "futoin.ping:1.0",
            "futoin.auth.types:{ver}"
        ],
        "types" : {
            "KDSParam" : {
                "type" : "string",
                "regex" : "^[a-zA-Z0-9._/+-]{1,32}$"
            },
            "MACSecField" : {
                "type" : "map",
                "fields" : {
                    "msid" : "MasterSecretID",
                    "algo" : "MACAlgo",
                    "kds" : "KeyDerivationStrategy",
                    "prm" : {
                        "type" : "KDSParam",
                        "optional" : true
                    },
                    "sig" : "MACValue"
                }
            },
            "CipherType" : {
                "type" : "GenericIdentifier",
                "minlen" : 1,
                "maxlen" : 32
            },
            "CipherMode" : {
                "type" : "string",
                "regex" : "^[A-Z0-9][A-Z0-9_]{1,14}[A-Z0-9]$",
                "desc" : "CBC, CTR, GCM, CFB and others"
            }
        },
        "funcs" : {
            "checkMAC" : {
                "params" : {
                    "base" : "MACBase",
                    "sec" : "MACSecField",
                    "source" : "ClientFingerprints"
                },
                "result" : "AuthInfo",
                "throws" : [
                    "SecurityError"
                ],
                "seclvl" : "PrivilegedOps"
            },
            "genMAC" : {
                "params" : {
                    "base" : "MACBase",
                    "reqsec" : "MACSecField"
                },
                "result" : "MACValue",
                "throws" : [
                    "SecurityError"
                ],
                "seclvl" : "PrivilegedOps"
            },
            "exposeDerivedKey" : {
                "params" : {
                    "base" : "MACBase",
                    "sec" : "MACSecField",
                    "source" : "ClientFingerprints"
                },
                "result" : {
                    "auth" : "AuthInfo",
                    "prm" : "KDSParam",
                    "etype" : "CipherType",
                    "emode" : "CipherMode",
                    "ekey" : "EncryptedKey"
                },
                "throws" : [
                    "SecurityError"
                ],
                "desc" : "Feature to support local key cache",
                "seclvl" : "ExceptionalOps"
            },
            "getNewEncryptedSecret" : {
                "params" : {
                    "type" : "ExchangeKeyType",
                    "pubkey" : "ExchangeKey",
                    "scope" : {
                        "type" : "MasterScope",
                        "default" : null
                    }
                },
                "result" : {
                    "id" : "MasterSecretID",
                    "esecret" : "EncryptedMasterSecret"
                },
                "throws" : [
                    "SecurityError",
                    "NotSupportedKeyType"
                ],
                "seclvl" : "ExceptionalOps"
            }
        },
        "requires" : [
            "SecureChannel",
            "MessageSignature",
            "BinaryData"
        ]
    }

`}Iface`

## 3.2. Auto registration

This interface allow anonymous access and should be disabled by default
configuration.

TBD.

`Iface{`

    {
        "iface" : "futoin.auth.master.register",
        "version" : "{ver}",
        "ftn3rev" : "1.9",
        "imports" : [
            "futoin.ping:1.0",
            "futoin.auth.types:{ver}"
        ],
        "funcs" : {
        },
        "requires" : [
            "SecureChannel",
            "AllowAnonymous"
        ]
    }

`}Iface`

## 3.3. Management

This one is complementary to "futoin.auth.manage" iface.

`Iface{`

    {
        "iface" : "futoin.auth.master.manage",
        "version" : "{ver}",
        "ftn3rev" : "1.9",
        "imports" : [
            "futoin.ping:1.0",
            "futoin.auth.types:{ver}"
        ],
        "funcs" : {
            "getNewPlainSecret" : {
                "params" : {
                    "user" : "LocalUserID"
                },
                "result" : {
                    "id" : "MasterSecretID",
                    "secret" : "Base64"
                },
                "throws" : [
                    "UnknownUser",
                    "NotSet"
                ],
                "seclvl" : "System"
            }
        },
        "requires" : [
            "SecureChannel",
            "MessageSignature"
        ]
    }

`}Iface`

[HKDF]: https://tools.ietf.org/html/rfc5869
[ECIES]: https://en.wikipedia.org/wiki/Integrated_Encryption_Scheme

=END OF SPEC=