Skip to content

Commit

Permalink
Update docs for identityd
Browse files Browse the repository at this point in the history
muhamadazmy authored and zaibon committed Oct 17, 2019
1 parent 58b9940 commit 911e0b0
Showing 5 changed files with 118 additions and 175 deletions.
105 changes: 105 additions & 0 deletions docs/identity/identity.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,105 @@
# Identity Module

## ZBus

Identity module is available on zbus over the following channel

| module | object | version |
|--------|--------|---------|
| identity|[manager](#interface)| 0.0.1|

## Home Directory

identity keeps some data in the following locations

| directory | path|
|----|---|
| root| `/var/cache/modules/identity`|

## Introduction

Identity manager is responsible for node identification on the grid. The manager make sure the node has one valid ID during the entire lifetime of the node, and that node id is registered on the grid.

On first boot, the identity manager will generate an ID and then persist this ID for life. The node registration happens to the BCDB once the network is reachable, and after that the node will be available for reservations.

Since the identity daemon is the only one that can access the node private key, it provides an interface to sign, verify and encrypt data. This methods are available for other modules on the local node to use.

## On Node Booting

- Check if node already has a seed generated
- If yes, load the node identity
- If not, generate a new ID
- Once identity is loaded, register the node to bcdb, this will keep running in the background until successful.
- Start the zbus daemon.

## ID generation

At this time of development the ID generated by identityd is the base58 encoded public key of a ed25519 key pair.

The key pair itself is generated from a random seed of 32 bytes. It is this seed that is actually saved on the node. And during boot the key pair is re-generated from this seed if it exists.

There is an open issue to make this all ID generation compatible with the rest of the Threefold ecosystem: https://github.com/threefoldtech/zos/issues/161

## Cryptography

The signing and encryption capabilities of the identity module rely on this ed25519 key pair.

For signing, it directly used the key pair.
For public key encryption, the ed25519 key pair is converted to its cure25519 equivalent and then use use to encrypt the data.

### zinit unit

The zinit unit file of the module specify the command line, test command, and the order where the services need to be booted.

`identityd` require `storaged` to make sure the seed is persisted over reboots, to make sure node has the same ID during the full life time of the node.
The identityd daemon is only considered running if the seed file exists.

```yaml
exec: /bin/identityd
test: test -e /var/cache/modules/identity/seed.txt
after:
- storaged
```
## Interface
```go
package pkg

// Identifier is the interface that defines
// how an object can be used as an identity
type Identifier interface {
Identity() string
}

// StrIdentifier is a helper type that implement the Identifier interface
// on top of simple string
type StrIdentifier string

// Identity implements the Identifier interface
func (s StrIdentifier) Identity() string {
return string(s)
}

// IdentityManager interface.
type IdentityManager interface {
// NodeID returns the node id (public key)
NodeID() StrIdentifier

// FarmID return the farm id this node is part of. this is usually a configuration
// that the node is booted with. An error is returned if the farmer id is not configured
FarmID() (StrIdentifier, error)

// Sign signs the message with privateKey and returns a signature.
Sign(message []byte) ([]byte, error)

// Verify reports whether sig is a valid signature of message by publicKey.
Verify(message, sig []byte) error

// Encrypt encrypts message with the public key of the node
Encrypt(message []byte) ([]byte, error)

// Decrypt decrypts message with the private of the node
Decrypt(message []byte) ([]byte, error)
}
```
103 changes: 3 additions & 100 deletions docs/identity/readme.md
Original file line number Diff line number Diff line change
@@ -1,105 +1,8 @@
# Identity Module

## ZBus

Storage module is available on zbus over the following channel

| module | object | version |
|--------|--------|---------|
| identity|[manager](#interface)| 0.0.1|

## Home Directory
identity keeps some data in the following locations

| directory | path|
|----|---|
| root| `/var/cache/modules/identity`|


## Introduction

Identity manager is responsible for node identification on the grid. The manager make sure the node has one valid ID during the entire lifetime of the node, and that node id is registered on the grid.

On first boot, the identity manager will generate an ID and then persist this ID for life. The node registration happens to the BCDB once the network is reachable, and after that the node will be available for reservations.

Since the identity daemon is the only one that can access the node private key, it provides an interface to sign, verify and encrypt data. This methods are available for other modules on the local node to use.

## On Node Booting

- Check if node already has a seed generated
- If yes, load the node identity
- If not, generate a new ID
- Once identity is loaded, register the node to bcdb, this will keep running in the background until successful.
- Start the zbus daemon.

## ID generation

At this time of development the ID generated by identityd is the base58 encoded public key of a ed25519 key pair.

The key pair itself is generated from a random seed of 32 bytes. It is this seed that is actually saved on the node. And during boot the key pair is re-generated from this seed if it exists.

There is an open issue to make this all ID generation compatible with the rest of the Threefold ecosystem: https://github.com/threefoldtech/zos/issues/161

## Cryptography

The signing and encryption capabilities of the identity module rely on this ed25519 key pair.

For signing, it directly used the key pair.
For public key encryption, the ed25519 key pair is converted to its cure25519 equivalent and then use use to encrypt the data.

### zinit unit

The zinit unit file of the module specify the command line, test command, and the order where the services need to be booted.

`identityd` require `storaged` to make sure the seed is persisted over reboots, to make sure node has the same ID during the full life time of the node.
The identityd daemon is only considered running if the seed file exists.

```yaml
exec: /bin/identityd
test: test -e /var/cache/modules/identity/seed.txt
after:
- storaged
```
## Interface
```go
package pkg

// Identifier is the interface that defines
// how an object can be used as an identity
type Identifier interface {
Identity() string
}

// StrIdentifier is a helper type that implement the Identifier interface
// on top of simple string
type StrIdentifier string

// Identity implements the Identifier interface
func (s StrIdentifier) Identity() string {
return string(s)
}

// IdentityManager interface.
type IdentityManager interface {
// NodeID returns the node id (public key)
NodeID() StrIdentifier

// FarmID return the farm id this node is part of. this is usually a configuration
// that the node is booted with. An error is returned if the farmer id is not configured
FarmID() (StrIdentifier, error)

// Sign signs the message with privateKey and returns a signature.
Sign(message []byte) ([]byte, error)

// Verify reports whether sig is a valid signature of message by publicKey.
Verify(message, sig []byte) error

// Encrypt encrypts message with the public key of the node
Encrypt(message []byte) ([]byte, error)
Identity daemon is responsible for major two operations that is crucial for the node operation

// Decrypt decrypts message with the private of the node
Decrypt(message []byte) ([]byte, error)
}
```
- [Node ID generation and registration on the grid](identity.md)
- [Node live software update](upgrade.md)
46 changes: 9 additions & 37 deletions docs/upgrade/readme.md → docs/identity/upgrade.md
Original file line number Diff line number Diff line change
@@ -1,33 +1,5 @@
# Upgrade module

## Zbus

Upgrade module is available on zbus over the following channel

| module | object | version |
|--------|--------|---------|
|upgrade |[upgrade](#public-interface)| 0.0.1

## Public interface [![GoDoc](https://godoc.org/github.com/threefoldtech/zos/pkg/flist?status.svg)](https://godoc.org/github.com/threefoldtech/zos/pkg/upgrade#Upgrader.Version)

```go
type UpgradeModule interface {
// version return the current version 0-OS is running
Version() (semver.Version, error)
}
```


## Home Directory
Upgraded does not have a home directory, although it can keep track of some files under /tmp. The reason that those files
are kept in a tmpfs filesystem, and not persisted on disk is that they are only needed during the runtime. On reboot new
files will be written. More on that later

## zinit unit

Upgrade module depends on network and flist module. This is because is requires network connection to check for new update and the flist module to download the upgrade flist on the node.


## Philosophy

0-OS is meant to be a black box no one can access. While this provide some nice security features it also makes it harder to manage. Specially when it comes to update/upgrade.
@@ -40,10 +12,11 @@ The run mode defines which flist the node is going to use to boot. Run mode can
- test: Mostly stable features that need to be tested at scale, allow preview and test of new features. Always the latest and greatest. This network can be reset sometimes, but should be relatively stable.
- prod: Released of stable version. Used to run the real grid with real money. Cannot be reset ever. Only stable and battle tested feature reach this level.


## Booting a new node

The base image for zos contains a very small subset of tools, plus the boot program. Standing alone, the image is not really useful. On boot and
after initial start of the system, the boot program kicks in and it does the following:

- Detect the boot flist that the node must use to fully start. The default is hard-coded into the image, but this can be overridden by the `flist=` kernel param. The `flist=` kernel param can get deprecated without a warning, since it's a development flag.
- The bootstrap, will then mount this flist using 0-fs, this of course requires a working connection to the internet. Hence bootstrap is configured to wait for the `internet` service.
- The flist information (name, and version) is saved under `/tmp/flist.name` and `/tmp/flist.info`.
@@ -53,16 +26,17 @@ after initial start of the system, the boot program kicks in and it does the fol
- Boot process continues.

## Runtime upgrade of a node
Once the node is up and running, upgraded takes over and it does the following:

Once the node is up and running, identityd takes over and it does the following:

- It loads the boot info files `/tmp/flist.name` and `/tmp/flist.info`
- If the `flist.name` file does **not** exist, `upgraded` will assume the node is booted with other means than an flist (for example overlay). In that case, upgraded will log this, and disable live upgrade of the node.
- If the `flist.name` file does **not** exist, `identityd` will assume the node is booted with other means than an flist (for example overlay). In that case, identityd will log this, and disable live upgrade of the node.
- If the `flist.name` file exists, the flist will be monitored on the `https://hub.grid.tf` for changes. Any change in the version will initiate a life upgrade routine.
- Once the flist change is detected, upgraded will mount the flist, make sure upgraded is running the latest version. If not, upgraded will update itself first before continuing.
- Once the flist change is detected, identityd will mount the flist, make sure identityd is running the latest version. If not, identityd will update itself first before continuing.
- services that will need update will be gracefully stopped.
- `upgraded` will then make sure to update all services from the flist, and config files. and restart the services properly.
- `identityd` will then make sure to update all services from the flist, and config files. and restart the services properly.
- services are started again after all binaries has been copied


## Technical

0-OS is designed to provide maximum uptime for its workload, rebooting a node should never be required to upgrade any of its component (except when we push a kernel upgrade).
@@ -90,7 +64,6 @@ Example:
/etc/zinit/flistd.yaml
/etc/zinit/readme.md
/etc/zinit/internet.yaml
/etc/zinit/upgraded.yaml
/etc/zinit/containerd.yaml
/etc/zinit/boot.yaml
/etc/zinit/provisiond.yaml
@@ -100,9 +73,8 @@ Example:
/bin/zlf
/bin/provisiond
/bin/flistd
/bin/upgraded
/bin/contd
/bin/identityd
/bin/contd
/bin/capacityd
/bin/storaged
/bin/networkd
3 changes: 1 addition & 2 deletions docs/readme.md
Original file line number Diff line number Diff line change
@@ -9,8 +9,7 @@
- [Network](network/readme.md)
- [Provision](provision/readme.md)
- [Storage](storage/readme.md)
- [Upgrade](upgrade/readme.md)


- Developer tools
- [development environment](../qemu)
- [tfuser](tfuser/readme.md)
36 changes: 0 additions & 36 deletions docs/upgrade/upgrade_flow.pu

This file was deleted.

0 comments on commit 911e0b0

Please sign in to comment.