###### tags: `documentation` `design`

# Secret Management

What we want and need:
---

- [x] Central lightweight service (on our own servers!) to safely store our secrets - the `secretManager`
- [x] The `secretManager` shall not know our secrets - especially not have them being arbitrarily readable
- [x] Only when knowing the `privateKey` one may request a nodes' secrets
- [x] Only when knowing the `privateKey` one may read a nodes' secrets
- [x] Only when knowing the `privateKey` one may have the authority to manipulate a nodes' secrets
- [x] A node may share any secrets with another node
- [x] A node may decide if it accepts secrets form another node
- [x] The possibility to create a self-destructing temporary node
- [ ] Loggin activities of the keys - accessible only with the `privateKey`
- [x] Authenticates itself using the same mechanism

## Ideas of Further Capabilities
- [ ] Decentralitation/Resilience - reduntant Servers running to ensure availabilty
- [ ] Federation - communication with alien Servers

## Background
What we ultimately want is to have a most simple account management system - however also most flexible. Therefore one certain component is the capability to store/retrieve and share secrets safely. It should be independently from the specific App.

The thought Applications of the future shall not have to deal with "accounts" - having their username passwords etc. stored in their own Database.
The Application simply shall not care about who is requesting what. Who knows the correct secrets has access, who does not has not.
This is thought to make the applications more simple and more safe a we donot have to deal with complex permissions to be checked on the basis of user-roles. This means for the Application that the sole purpose

We want to decouple accounts from applications - as same as UI from Services - all the way.
The broader mor general terms we want This:

- Apps to be crafted as a specific tool for a specific user
- User is in charge
- User choose or build/optimize their own UIs (e.g. simply choose providers they trust)
- Choose or build/optimize your own Services (e.g. simply choose providers they trust)
- Speficy the Services to be used by the UIs
- Using secrets seemlessly across any of those UIs and Services - minimize Data exposure to the Apps
- Proofing auhority once having 100% seemless access without complexity on the App
- Avoid overcomplicated OAuth
- Avoid dependency on monopolistic 3rd parties

It is another step on the move towards an Internet owned, managed and used by self-reliant capable individuals who support eachother to give their best version to the rest of the world.

## Basic Concept and Behaviour

Any PWA(=UI) or Service or other thingy (e.G CLI) in general is regarded simply as a node. For any new node a keypair is generated. The `publicKey` we also call `nodeId` here. (For the sake of simplicity we exclusivly use ed25519-keys - later we will switch completely to one key algorithm which is ready for the quantum computer area)

From the perspective of the secret Manager this `nodeId` has its own unique `secretSpace` where all secrets for this node are stored.
Every secret stored is encrypted by using the nodes' `publicKey` this way only the node may decrypt the secret again. Limiting data exposure to the Secret Manager itself.

- node creation -> (publicKey, privateKey)
- notify secretManager of existence -> send publicKey to secretManager -> creates secretSpace
- store secret -> encrypt(secret) -> send to secretManager -> verify authority -> encrypt(receivedSecret) -> store in relevant secretSpace
- retrieve secret -> request secretManager for secret -> verify authority -> send back encryptedSecret from secreSpace -> decrypt(encryptedSecret)


## The Secret Space
The `secretSpace` is just a JS object. The top structure looks like this:

{
    "meta": {
        ....
    },
    "secrets": {
        ...
    },
    "subSpaces": {
        ...
    }
}

### Meta Data
Thereof `meta` is contains the meta data. This includes a `closureDate` and a `logTo` field

{
    "id": "...",
    "closureDate": "...",
    "owner": "...",
    "communication": "...",
    "notificationHooks": [],
    "serverPub": "...",
    "serverSig": "..."
 }

#### id
The specific corresponding `nodeId`/`publicKey` for the `secretSpace`.

#### closureDae
Certain `secretSpaces` are meant to be temporary and specify a `closureDate`. The date when they would automatically be deleted.
`null` means they are meant to stay forever or until manually deleted.

#### owner
This is specifies another `nodeId` which is the owner of the corresponding `nodeId` for the `secretSpace` - e.g. you have one master key and add new keys via the power of your master key.

#### communcation
This specifies a means of communciation to the human owner of this `secretSpace` - this is for the case when you provide the secret manager as a service to other humans and might want to reach out to them.

#### notificationHooks
This specifies a means to notify external servers of actions related to this `secretSpace`.
A list of the `notificationHookIds`. The state of the `notificationHook` itself is stored somewhereelse.

#### serverPub
the public key of the specific service uses who created the and maintains the `secretSpace`.
This is used for validation in combination with `serverSig` when reading the `secretSpace`.

#### serverSig
The signature of the server. The whole stringified `secretSpace` (without `serverSig`) is signed with by the service who maintains the `secretSpace` when it writes it out.
This is used for validation in combination with `serverPub` when reading the `secretSpace`.

### Secrets
The `secrets` contain a mapping of `secretId`s to a secret object which looks like this:

{
    "allmightySecret": {
        "secret": {referencePoint, encryptedContent}
        "notificationHooks": []
    },
    "otherSecretId": {
        "secret": {referencePoint, encryptedContent},
        "notificationHooks": []
    }
}

Here we have a `secret` object and potential further information like `notificationHooks` (e.g. to send messages on events related to the certain secret).

#### The Secret Object
The secret Object consists of a `referencePoint` and the `encryptedContent`.
This is because encryption works in ElGamal style on ECC.

- base Point G
- Alice' private key is scalar a
- Alice' public key is a * G
- Bobs' private key is scalar b
- Bobs' publicKey is b * G
- throwaway secret is c
- referencePoint is c * G
- Alice generates key to symmetrically encrypt as c * b * G
- Bob may use the reference point then to generate that key for decrypting b * c * G

### The Sub Spaces
The `subSpaces` contain a mapping of `nodeId`s to the specific subSpace. It looks like this:

{
    "9a16ce79c30b3b6b11b9c28e33e64e0d5d270cffebaf12d4c878552ddb2634e5": {
        "meta": {
            "id": "...",
            "closureDate": "...",
            "notificationHooks": []
        },
        "secrets": {
              "sharedSecretId0": {
                "secret": {referencePoint, encryptedContent}
            },
            "sharedSecretId1": {
                "secret": {referencePoint, encryptedContent},
                "notificationHooks": []
            },
            ...
        }
    },
    "9b16ce79c30b3b6b11b9c28e33e64e0d5d270cffebaf12d4c878552ddb2634e6": {
        "meta": {
            ...
        },
        "secrets": {
            ...
        }
    }
}

#### Sub Space Meta
For the `subSpace` meta object some information of the `secretSpace` meta object does not have to be included.
Therefore we have only
- id
- closureDate
- notificationHooks

##### id
This id looks like `nodeId.fromId` where nodeId is the one corresponding to the `secretSpace` and the `fromId` is the id which is allowed to modify this `subSpace`.

##### closureDate
Also on creating the `subSpace` we might want to keep it temporary - it works exactly in the same way as the `closureDate` for the`secretSpace`.

##### notificationHooks
Also the logging/Notification functionality may be individually defined for each `subSpace`.
Note that still all the events happening here in this `subSpace` will also be reported on the `secretSpace`.

### The SecretId
As the `secretId` is not directly subject to any encryption, so it might be advisable to not disclose too much information there and rather use the hash of a human readable identifier for its value.

For now this left to the developer of the specific application if it should be done this way.

## Secret Sharing
For our `secretSpace` labeled with our `nodeId` only we have the authority to write anything.


### Accepting Secrets From Another Node
If we want to allow another node to share secrets to us we first need to create a sub-space labeled as their `nodeId`. This `nodeId` we also call `fromId` in this context.

Now within that sub-space the `fromId` has the authority to store secrets for us. Also those secrets would be asymetrically encrypted using our `publicKey`.

### Writing Shared Secrets
Now the other `nodeId` could decide at any time to write, overwrite and delete any secrets within this sub-space.
Our node would be the only one who could decrypt it using it's own `privateKey`.

### Stop Accepting Secrets
At anytime we could stop accepting secrets from this `nodeId`. Then we would simply delete this sub-space and all secrets therein would be immediately lost.

## DateOfDeath

For some cases we only want a temporary `secretSpace`, know this in beforehand and want to save us the hassle to actively delete the `secretSpace` when we donot need it anymore.

Therefore we specify a `dateOfDeath`. If a nonzero value is specified the `secretSpace` shall be removed and not be reachable ever again after this time.

*Note: if logging of activities happens everything is reproducable*

## Signatures for Request Validation
To verify validity of every request we use ed25519 signatures.
Every request must come from a node with it's `publicKey` which directly defines the full scope of authority. Thus the one signature on the request is the only thing required for authentication.

However there is one nuissance possibility which could potentially push this service to denial of service, or even overwrite a newer secret with older content: **Replay attacks**

To mitigate replay attacks:

- there is a timestamp to limit the timeframe any request will be valid for
- the SCI-endpoint (route) is used with content to be signed
`signature = createSignature(route + stringifiedRequestWithoutSignature, privateKey)`
- the latest valid signatures used must be stored and to recognize duplicate signatures - they must not be processed
storing signatures must last at least for the duration the timestamp is valid, as outside this timeframe the signature will be invalid anyways

---

## Decentralitation/Resilience - reduntant Servers running to ensure availabilty
- Redundancy of Running service
- Load Balancing
- Redundancy of Data Storage

//TODO: research

## Federation - communication with alien Servers
//TODO: research

## Logging activities of the Keys
This is important for breach detection.
Important is to save the logs in a different context in such a way that it is accessible independently of potentially breached keys.

Nice: When having full logs we donot need really any backup as in case of a breach the logs would enable us to reproduce the latest uncorrupted state.

---

## Secret Manager Service
Central part of this is the [secret-manager-service](https://github.com/JhonnyJason/secret-manager-service).
It provides this SCI to savely store these secrets for these nodes.

Anyone is encouraged to check out the code and run their own secretManager. While my first one is also one publicly accessible at https://secrets.extensivlyon.coffee

It is important to notice that this service could be easily DDOSed. As for every request it would at least verify a signature in pure JS.

## Crypto Utils

There is the [secret-manager-crypto-utils](https://www.npmjs.com/package/secret-manager-crypto-utils) package available. This includes all relavant crypto primitives.
If you want to check out the code and the algorithms [this](https://github.com/JhonnyJason/secret-manager-crypto-utils-sources/tree/master/source) would be the place where to start.

## Secret Manager Client

There is the [secret-manager-client](https://www.npmjs.com/package/secret-manager-client) package available which implements the full client-side of the secretManager SCI.

This serves the purpose to be used in the applications if it is in the browser, as a NodeJS service or NodejS CLI which needs the secretManager.
If you are interested in the code go [here](https://github.com/JhonnyJason/secret-manager-client-sources/tree/master/source)

## Secret Cockpit
There is a tool available to analyse secrets of your nodes and manage them in hopefully the most flexible way.

- [Live Tool Online](https://secrets-cockpit.extensivlyon.coffee)
- [Documentation](https://hackmd.io/wPTUeTzwQ3q9uXhuKHf3Cg?view)
- [The Code](https://github.com/JhonnyJason/secret-cockpit)

---

## [From Interface Specification:](https://hackmd.io/EtJSEnxjTVOOvRJdWGJlYw?view)

---

{%hackmd EtJSEnxjTVOOvRJdWGJlYw %}

---

## [From Specification Testing:](https://hackmd.io/vUaiSwD3TRyKRURPEnyQSw?view)

---

{%hackmd vUaiSwD3TRyKRURPEnyQSw %}