Skip to content

Latest commit

 

History

History
328 lines (272 loc) · 13.2 KB

secure_manager.md

File metadata and controls

328 lines (272 loc) · 13.2 KB
Raw

Secure Manager

Contents

  1. Introduction
  2. Verifier
    2.1 Description
    2.2 Workflow
    2.3 Verifier Management
    2.4 Usage Edge-Orchestration with Verifier
  3. Authenticator
    3.1 Description
    3.2 Workflow
    3.3 JWT generation
    3.4 JWT usage
  4. Authorizer
    4.1 Description
    4.2 Workflow
    4.3 JWT generation with user’s name for authorization
  5. TLS
    5.1 Description
    5.2 Workflow
    5.3 Generation key infrastructure

1. Introduction

The Secure Manager is designed to control security components. Currently it is in an initial state of development and includes the following components:

  1. Verifier
  2. Authenticator
  3. Authorizer (RBAC)
  4. TLS

In order for the Secure Manager to be allowed, it is necessary to run the Edge-Orchestration with the -e SECURE=true option.

Unfortunately the datastorage is temporarily not supported in secure mode.

2. Verifier

2.1 Description

The verifier ensures that only allowed containers (images) are launched; a list of allowed containers (their sha256 hashes) is stored in a /var/edge-orchestration/data/cwl/containerwhitelist.txt file.

2.2 Workflow

TBD

2.3 Verifier Management

There are two ways to change the container white list:

  1. Using REST API
  2. Editing the containerwhitelist.txt file (root rights required)

2.3.1 REST API

REST API supports the next functions for contaner white list management:

  • addHashCWL - adds container image hash to the container white list
  • delHashCWL - deletes container image hash from the container white list
  • delAllHashCWL - deletes all container image hashes from container white list
  • printAllHashCWL - displays all hashes (from the container white list) in the log.

To send commands it is necessary to use a JSON Web Token (see 3. Authenticator).

Examples of using these commands are given below:

  • POST
  • IP:56001/api/v1/orchestration/securemgr
  • BODY (depends on the command):

addHashCWL
JSON:

    {
        "SecureMgr": "Verifier",
        "CmdType": "addHashCWL",
        "Desc": [
        {
            "ContainerHash": "fc6a51919cfeb2e6763f62b6d9e8815acbf7cd2e476ea353743570610737b752"
        },
        {
            "ContainerHash": "fc6a51919cfeb2e6763f62b6d9e8815acbf7cd2e476ea353743570610737b751"
        }]
    }

Curl:

curl -X POST "127.0.0.1:56001/api/v1/orchestration/securemgr" -H "accept: application/json" -H "Content-Type: application/json" -H "Authorization: $EDGE_ORCHESTRATION_TOKEN" -d "{ \"SecureMgr\": \"Verifier\", \"CmdType\": \"addHashCWL\", \"Desc\": [{ \"ContainerHash\": \"fc6a51919cfeb2e6763f62b6d9e8815acbf7cd2e476ea353743570610737b752\"}, { \"ContainerHash\": \"fc6a51919cfeb2e6763f62b6d9e8815acbf7cd2e476ea353743570610737b751\"}]}"

delHashCWL
JSON:

    {
        "SecureMgr": "Verifier",
        "CmdType": "delHashCWL",
        "Desc": [
        {
            "ContainerHash": "fc6a51919cfeb2e6763f62b6d9e8815acbf7cd2e476ea353743570610737b752"
        }]
    }

Curl:

curl -X POST "127.0.0.1:56001/api/v1/orchestration/securemgr" -H "accept: application/json" -H "Content-Type: application/json" -H "Authorization: $EDGE_ORCHESTRATION_TOKEN" -d "{ \"SecureMgr\": \"Verifier\", \"CmdType\": \"delHashCWL\", \"Desc\": [{ \"ContainerHash\": \"fc6a51919cfeb2e6763f62b6d9e8815acbf7cd2e476ea353743570610737b752\"}]}"

delAllHashCWL
JSON:

    {
        "SecureMgr": "Verifier",
        "CmdType": "delAllHashCWL"
    }

Curl:

curl -X POST "127.0.0.1:56001/api/v1/orchestration/securemgr" -H "accept: application/json" -H "Content-Type: application/json" -H "Authorization: $EDGE_ORCHESTRATION_TOKEN" -d "{ \"SecureMgr\": \"Verifier\", \"CmdType\": \"delAllHashCWL\"}"

printAllHashCWL
JSON:

    {
        "SecureMgr": "Verifier",
        "CmdType": "printAllHashCWL"
    }

Curl:

curl -X POST "127.0.0.1:56001/api/v1/orchestration/securemgr" -H "accept: application/json" -H "Content-Type: application/json" -H "Authorization: $EDGE_ORCHESTRATION_TOKEN" -d "{ \"SecureMgr\": \"Verifier\", \"CmdType\": \"printAllHashCWL\"}"

2.3.2 Editing the container white list by other tools.

The /var/edge-orchestration/data/cwl/containerwhitelist.txt file consists of records that include: container's image sha256 hash (64-ASCII symbols) + '\n' Therefore, it can be edited with any editor or from the command line. Example: how to add hash by command line

# echo "fc6a51919cfeb2e6763f62b6d9e8815acbf7cd2e476ea353743570610737b752" >> /var/edge-orchestration/data/cwl/containerwhitelist.txt

2.4 Usage Edge-Orchestration with Verifier

To run Edge Orchestration container you need to add a digest (sha256) to the last parameter. For example: "hello-world@sha256:fc6a51919cfeb2e6763f62b6d9e8815acbf7cd2e476ea353743570610737b752"

curl -X POST "127.0.0.1:56001/api/v1/orchestration/services" -H "accept: application/json" -H "Content-Type: application/json" -H "Authorization: $EDGE_ORCHESTRATION_TOKEN" -d "{ \"ServiceName\": \"hello-world\", \"ServiceInfo\": [{ \"ExecutionType\": \"container\", \"ExecCmd\": [ \"docker\", \"run\", \"-v\", \"/var/run:/var/run:rw\", \"hello-world@sha256:fc6a51919cfeb2e6763f62b6d9e8815acbf7cd2e476ea353743570610737b752\"]}]}"

If the "fc6a51919cfeb2e6763f62b6d9e8815acbf7cd2e476ea353743570610737b752" hash is written to the /var/edge-orchestration/data/cwl/containerwhitelist.txt file, the container will be launched successfully.

3. Authenticator

3.1 Description

The Authenticator provides access to resources only for authenticated users (services). The current implementation is based on the use of JSON Web Tokens (JWT). The Authenticator uses the HMAC or RSA256 algorithms to generate the JWTs. The key phrase (secret) is stored in /var/edge-orchestration/data/jwt/passPhraseJWT.txt file for HMAC and the pubkey is stored in /var/edge-orchestration/data/jwt/app_rsa.pub for RSA256.

The distribution of the key phrase is not yet in the field of implementation and should be done manually (especially considering the fact that external REST API requests can only be from the localhost or 127.0.0.1).

3.2 Workflow

To view the Workflow, you need to install a plantuml extension for your browser.

@startuml

top to bottom direction

actor User

node "Home Edge Node #1" {
  User --> [f1] : 1. Generate & store ''secret''
  [HOM1] --> [f1] : 4. Get ''secret''
  [HOM1] --> [HOM1] : 5. Check JWT, if success handle request
  [CA1] --> [f1] : 2. Get ''secret'' & generate JWT 
  [CA1] -->[HOM1] : 3. Send Request & JWT
  rectangle "/var/edge-orchestration/data/jwt/passPhraseJWT.txt" as f1 {
  }
  rectangle "App" as CA1 {
  }
  rectangle "Home Edge Orchestrator" as HOM1 {
  }
}

@enduml

3.3 JWT generation

To create a JWT, you can use the script tools/jwt_gen.sh by running it as shown below: For HMAC

. tools/jwt_gen.sh HS256 Admin

or for RSA256

. tools/jwt_gen.sh RS256 Admin

The generated token is exported to the shell environment variable: EDGE_ORCHESTRATION_TOKEN. Enter the following command to display the token:

echo $EDGE_ORCHESTRATION_TOKEN

If you want to use the RSA256 algorithm, you need to generate keys using the commands:

cd /var/edge-orchestration/data/jwt
openssl genrsa -out app_rsa.key keysize
openssl rsa -in app_rsa.key -pubout > app_rsa.pub

3.4 JWT usage

To use a JWT, you must include it in the header of the request: Authorization: {token}. Example below:

curl -X POST "127.0.0.1:56001/api/v1/orchestration/securemgr" -H "accept: applicationnt-Type: application/json" -H "Authorization: $EDGE_ORCHESTRATION_TOKEN" -d "{ \"SecureMgr\": \"Verifier\", \"CmdType\": \"printAllHashCWL\"}"

4. Authorizer (RBAC)

4.1 Description

The Authorizer provides Role Based Access Control (RBAC). Its an approach to restricting system access to authorized users by using a set of permissions and grants. In Edge-Orchestration project was used the open-source access control library casbin. "In Casbin, an access control model is abstracted into a CONF file based on the PERM metamodel (Policy, Effect, Request, Matchers). So switching or upgrading the authorization mechanism for a project is just as simple as modifying a configuration" (description from the official site). The system is currently configured in the simplest configuration with two roles: admin and member. The table below demonstrates access to external api for these roles.

Resource\Role admin member
/api/v1/orchestration/services Allow Allow
/api/v1/orchestration/securemgr Allow Deny
/api/v1/orchestration/cloudsyncmgr/publish Allow Allow

To change the access model and policy, you need to edit the files:
/var/edge-orchestration/data/rbac/auth_model.conf

[request_definition]
r = sub, obj, act

[policy_definition]
p = sub, obj, act

[policy_effect]
e = some(where (p.eft == allow))

[matchers]
m = r.sub == p.sub && keyMatch(r.obj, p.obj) && (r.act == p.act || p.act == "*")

and /var/edge-orchestration/data/rbac/policy.csv

p, admin, /*, *
p, member, /api/v1/orchestration/services, *
p, member, /api/v1/orchestration/cloudsyncmgr/publish, *

4.2 Workflow

To view the Workflow, you need to install a plantuml extension for your browser.

TBD

4.3 JWT generation with user's name for authorization

To create a JWT, you can use the script tools/jwt_gen.sh by running it as shown below: common rules

. tools/jwt_gen.sh [Algo] [User]

where: Algo {}; User {Admin, Member}. Examples: For HMAC and Admin

. tools/jwt_gen.sh HS256 Admin

or for RSA256 and Member

. tools/jwt_gen.sh RS256 Member

It should be noted that the user's name and role are currently hardcoded in authorizer.go, but this will change when the ability to register users in the system is added.

users = append(users, User{Name: "Admin", Role: "admin"})
users = append(users, User{Name: "Member", Role: "member"})

5. TLS

5.1 Description

The Transport Layer Security (TLS) is a cryptographic protocol designed to provide communications security over a computer network. The Edge-orchestration project uses a standard package crypto/tls. The product uses an authentication mechanism with a center authority, realizing a certificate chain of trust and data encryption based on a session key.

5.2 Workflow

To view the Workflow, you need to install a plantuml extension for your browser.

@startuml
  autonumber
  CA->>CA: Generate CA Root Certificate ca-crt.pem ca-key.pem
  "Node (192.168.0.100)"->>"Node (192.168.0.100)": Generate private key hen-key.pem, request hen.csr
  "Node (192.168.0.100)"->>CA: Send hen.csr to CA
  CA-->>"Node (192.168.0.100)": Send ca-crt.pem and hen-crt.pem to Node
  Note right of CA: For each Node, must be executed items 2-4
@enduml

5.3 Generation key infrastructure

Before starting work the Home Edge Network, need to create a key infrastructure (for a certification authority and for each node separately).

There are two scripts:

  • tools/gen_ca_cert.sh for generation of CA Root Certificate, that consists of a private key ca-key.pem and a self-signed root certificate ca-crt.pem
  • tools/gen_hen_cert.sh for generation of Home Edge Node (HEN) Certificate, that consists of a private key hen-key.pem and a signature HEN certificate: hen-crt.pem

CA Root Certificate

Generating a CA Root Certificate only needs to be done once for Home Edge Network by running command:

tools/gen_ca_cert.sh

As a result, we get the private key certs/ca-key.pem and self-signed root certificate certs/ca-crt.pem. The certificate must be saved on all nodes in the /var/edge-orchestration/certs/ folder.

Home Edge Node (HEN) Certificate

Generate HEN Certificate private key : hen-key.pem

For each node, need to create a private key hen-key.pem and a certificate hen-crt.pem. To do this, need to start the script and specify the node IP address.

tools/gen_hen_cert.sh 192.168.0.100

As a result, the key and certificate will be created in the certs/<IP>/. They must be copied into the /var/edge-orchestration/certs/ folder on a node with the specified IP address