Skip to content

Commit d843ac2

Browse files
gowthamsk-armgowthamsk-arm
authored
Merge branch 'main' into bump-sdnotify
2 parents b58377e + 0de9b61 commit d843ac2

11 files changed

+505
-136
lines changed

‎.dockerignore

+17
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
quickstart/quickstart.Dockerfile
2+
quickstart/package.sh
3+
quickstart/*.tar.gz
4+
.idea/
5+
6+
# Copied from .gitignore
7+
/target
8+
*.psa_its
9+
*.swp
10+
tags
11+
*DS_Store
12+
*vscode
13+
*.patch
14+
mappings/
15+
kim-mappings/
16+
NVChip
17+
.devcontainer

‎.gitignore

+6
Original file line numberDiff line numberDiff line change
@@ -26,3 +26,9 @@ kim-mappings/
2626
# TPM simulator state file
2727
NVChip
2828
.devcontainer
29+
30+
# Quickstart tarball
31+
quickstart/*.tar.gz
32+
33+
# IDE settings files
34+
.idea

‎config.toml

+10-1
Original file line numberDiff line numberDiff line change
@@ -189,7 +189,16 @@ key_info_manager = "sqlite-manager"
189189
# (Required) TPM TCTI device to use with this provider. The string can include configuration values - if no
190190
# configuration value is given, the defaults are used. Options are:
191191
# - "device": uses a TPM device available as a file node; path can be given as a configuration string,
192-
# e.g "device:/path/to/tpm"; the default path is /dev/tpm0
192+
# e.g "device:/path/to/tpm". The default path is /dev/tpm0, but this default is only suitable in deployments
193+
# where Parsec would have exclusive usage of the device, and where Parsec is executing at a sufficiently high
194+
# privilege for such access. It is more common for the TPM device to be managed by an Access Broker / Resource
195+
# Manager (ABRM) component, either within the kernel or via a userspace daemon (the TABRMD). Trying to
196+
# use /dev/tpm0 directly in such cases will lead to "device busy" errors on service start-up. Instead, Parsec should
197+
# normally be configured to access the TPM via the suitable ABRM. To use the in-kernel ABRM, the "device"
198+
# setting should be configured to use the managed TPM device path, typically /dev/tpmrm0. Permissions on this
199+
# device are normally less restrictive. In most Linux distributions, this device can be accessed by any user
200+
# within the "tss" group, so whatever user the Parsec service is running as should be made a member of this group.
201+
# To use the userspace ABRMD, adopt the "tabrmd" setting below, instead of "device".
193202
# - "mssim": uses the TPM simulator server with the socket; server path and/or port can be given as configuration values,
194203
# e.g. "mssim:host=168.0.1.1,port=1234"; "host" can be set to IPv4, IPv6 or a hostname; default values are
195204
# "localhost" for "host" and 2321 for "port"

‎packaging_assets/package.sh

-131
This file was deleted.

‎packaging_assets/quickstart_README.md

-4
This file was deleted.

‎packaging_assets/quickstart_config.toml ‎quickstart/config.toml

File renamed without changes.

‎quickstart/construct-build-details.sh

+31
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
#!/bin/bash
2+
3+
# Copyright 2023 Contributors to the Parsec project.
4+
# SPDX-License-Identifier: Apache-2.0
5+
6+
cat << EOF
7+
----------------------------------------
8+
-- Parsec Quickstart Build Details
9+
----------------------------------------
10+
OS: $(cat /build-env/os)
11+
Architecture: $(cat /build-env/arch)
12+
Rust: $(cat /build-env/rustc-version)
13+
Cargo: $(cat /build-env/cargo-version)
14+
15+
----------------------------------------
16+
-- Parsec Service
17+
----------------------------------------
18+
Version: $(cat /build-env/parsec-version)
19+
Commit Hash: $(cat /build-env/parsec-commit)
20+
Dependencies:
21+
$(cat /build-env/parsec-dependencies)
22+
23+
----------------------------------------
24+
-- Parsec Tool
25+
----------------------------------------
26+
Version: $(cat /build-env/parsec-tool-version)
27+
Commit Hash: $(cat /build-env/parsec-tool-commit)
28+
Dependencies:
29+
$(cat /build-env/parsec-tool-dependencies)
30+
31+
EOF

‎quickstart/docker_README.md

+133
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
# Parsec Quickstart - Docker
2+
3+
This Docker container is constructed specifically as an introductory quickstart for the Parsec service and client tool. It is not intended for use in any production system.
4+
5+
The container is started with the following command. This assumes that your Docker system is configured to pull images from ghcr.io. If that's not the case, or if you'd like to build a local image, see section [Building Quickstart Image](#building-quickstart-image).
6+
7+
```bash
8+
$> docker run --rm --name parsec -it parallaxsecond/parsec-quickstart bash
9+
qs@319b139eb85e:/parsec/quickstart$
10+
```
11+
12+
## Directory Layout & Environment Settings
13+
14+
```
15+
parsec
16+
├── bin
17+
│ ├── parsec # The parsec binary
18+
│ └── parsec-tool # The parsec client tool
19+
└── quickstart
20+
├── README.md # This README
21+
├── build.txt # Information about the Parsec build environment
22+
├── config.toml # The config file used by parsec
23+
└── parsec-cli-tests.sh # Standard parsec-tool tests
24+
```
25+
26+
```
27+
PWD=/parsec/quickstart
28+
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/parsec/bin
29+
PARSEC_SERVICE_ENDPOINT=unix:/parsec/quickstart/parsec.sock
30+
```
31+
32+
## Usage
33+
34+
The following describe standard quickstart usage examples.
35+
36+
### Start the PARSEC service
37+
38+
```bash
39+
# This will execute the parsec binary found in /parsec/bin using the config file
40+
# found at /parsec/quickstart/config.toml.
41+
# The socket path will be placed at /parsec/quickstart/parsec.sock
42+
qs@319b139eb85e:/parsec/quickstart$ parsec &
43+
[INFO parsec] Parsec started. Configuring the service...
44+
[INFO parsec_service::key_info_managers::sqlite_manager] SQLiteKeyInfoManager - Found 0 key info mapping records
45+
[INFO parsec_service::utils::service_builder] Creating a Mbed Crypto Provider.
46+
[INFO parsec] Parsec is ready.
47+
48+
qs@319b139eb85e:/parsec/quickstart$
49+
```
50+
51+
### Ping Parsec
52+
53+
```bash
54+
# This will execute a ping command using the parsec-tool binary.
55+
# The container has already configured the environment variable
56+
# PARSEC_SERVICE_ENDPOINT=unix:/parsec/quickstart/parsec.sock
57+
# which will allow all parsec-tool commands to successfully find
58+
# the necessary socket.
59+
qs@319b139eb85e:/parsec/quickstart$ parsec-tool ping
60+
[INFO ] Service wire protocol version
61+
1.0
62+
```
63+
64+
### Parsec Tool Examples
65+
66+
```bash
67+
# List Providers
68+
qs@319b139eb85e:/parsec/quickstart$ parsec-tool list-providers
69+
[INFO ] Available providers:
70+
ID: 0x01 (Mbed Crypto provider)
71+
Description: User space software provider, based on Mbed Crypto - the reference implementation of the PSA crypto API
72+
Version: 0.1.0
73+
Vendor: Arm
74+
UUID: 1c1139dc-ad7c-47dc-ad6b-db6fdb466552
75+
76+
ID: 0x00 (Core provider)
77+
Description: Software provider that implements only administrative (i.e. no cryptographic) operations
78+
Version: 1.1.0
79+
Vendor: Unspecified
80+
UUID: 47049873-2a43-4845-9d72-831eab668784
81+
82+
# Create RSA Key
83+
qs@319b139eb85e:/parsec/quickstart$ parsec-tool create-rsa-key --key-name demo1
84+
[INFO ] Creating RSA encryption key...
85+
[INFO ] Key "demo1" created.
86+
87+
# Encrypt data using the RSA Key
88+
qs@319b139eb85e:/parsec/quickstart$ parsec-tool encrypt --key-name demo1 "Super secret data"
89+
[INFO ] Encrypting data with RsaPkcs1v15Crypt...
90+
RuPgZld6....brHqQd7xJg==
91+
92+
# Decrypt ciphertext using the RSA Key
93+
qs@319b139eb85e:/parsec/quickstart$ parsec-tool decrypt --key-name demo1 RuPgZld6....brHqQd7xJg==
94+
[INFO ] Decrypting data with RsaPkcs1v15Crypt...
95+
Super secret data
96+
```
97+
98+
### Run the Test Script
99+
100+
```bash
101+
qs@319b139eb85e:/parsec/quickstart$ ./parsec-cli-tests.sh
102+
Checking Parsec service...
103+
[INFO ] Service wire protocol version
104+
1.0
105+
106+
Testing Mbed Crypto provider
107+
108+
- Test random number generation
109+
[INFO ] Generating 10 random bytes...
110+
[INFO ] Random bytes:
111+
24 A1 19 DB 3F 3C A0 82 FE 63
112+
....
113+
```
114+
115+
## Building Quickstart Image
116+
117+
Building the Quickstart image locally can be accomplished by executing the `package.sh` script located in the `quickstart` directory. Running `package.sh` will also generate the Quickstart tarball and place it in the current directory.
118+
119+
```bash
120+
$ quickstart > ./package.sh
121+
Packaging started...
122+
...
123+
Finalizing packages
124+
```
125+
126+
Alternatively, you can execute the Docker build command directly
127+
128+
```bash
129+
# We use .. at the end so the entire parsec directory is available in the docker build context
130+
$ quickstart > docker build --target runnable_image --tag parallaxsecond/parsec-quickstart -f quickstart.Dockerfile ..
131+
```
132+
133+
Image construction requires cloning of https://github.com/parallaxsecond/parsec-tool in order to include the `parsec-tool` binary in the built image. This will be done automatically as part of the image construction process, but it does necessitate your system having access to Github.

0 commit comments

Comments
 (0)