This is a guide for building and deploying the KBS components locally (without containers) on Ubuntu 22.04. The guide also covers configuration and testing. If you're looking for something even quicker, you might want to deploy the KBS components with docker compose or the KBS operator.
Install Rust tooling:
curl https://sh.rustup.rs -sSf | sh
source "$HOME/.cargo/env"Install dependencies:
curl -L "https://download.01.org/intel-sgx/sgx_repo/ubuntu/intel-sgx-deb.key" | sudo gpg --dearmor --output /usr/share/keyrings/intel-sgx.gpg
echo "deb [arch=amd64 signed-by=/usr/share/keyrings/intel-sgx.gpg] https://download.01.org/intel-sgx/sgx_repo/ubuntu jammy main" \
| sudo tee /etc/apt/sources.list.d/intel-sgx.list
sudo apt-get update
sudo apt-get install -y \
build-essential \
clang \
libsgx-dcap-quote-verify-dev \
libsgx-dcap-quote-verify \
libtss2-dev \
openssl \
pkg-config \
protobuf-compilerGenerate User authentication key pair and admin token:
openssl genpkey -algorithm ed25519 > config/private.key
openssl pkey -in config/private.key -pubout -out config/public.pub
b64url() { openssl base64 -A | tr '+/' '-_' | tr -d '='; }
header='{"alg":"EdDSA","typ":"JWT"}'
iat=$(date +%s); exp=$((iat + 315360000))
payload="{\"issuer\":\"admin\",\"subject\":\"admin\",\"audiences\":[],\"iat\":${iat},\"exp\":${exp}}"
h64=$(printf '%s' "$header" | b64url)
p64=$(printf '%s' "$payload" | b64url)
sig=$(printf '%s' "${h64}.${p64}" | openssl pkeyutl -sign -inkey config/private.key -rawin | b64url)
printf '%s.%s.%s\n' "$h64" "$p64" "$sig" > config/admin-tokenIf you want connect KBS with HTTPS, you should generate a server-side certificate for KBS using a trusted CA and pass it to the KBS server through startup parameters.
Build KBS in Background Check mode:
make background-check-kbs
sudo make install-kbsBuild and install the kbs-client:
make cli
sudo make install-cliStart KBS with HTTP server:
sudo kbs --config-file config/kbs-config.toml &If you want start KBS with HTTPS server, use --private-key and --certificate
to provide file path of server-side HTTPS key and certificate (both in PEM format).
Generate a dummy resource data file:
cat > test/dummy_data << EOF
1234567890abcde
EOFUse kbs-client to upload resource data to KBS storage:
kbs-client --url http://127.0.0.1:8080 config --admin-token-file config/admin-token set-resource --resource-file test/dummy_data --path default/test/dummyHere we assigned a custom path for this resource: default/test/dummy.
Run following command to get resource data from KBS:
kbs-client --url http://127.0.0.1:8080 get-resource --path default/test/dummyIf you run the client outside of a TEE, the sample attester will be used. By default the KBS rejects all sample evidence. To test the KBS with sample evidence, you'll need to update the resource policy to something more permissive. This can be done with a command such as
kbs-client --url http://127.0.0.1:8080 config --admin-token-file config/admin-token set-resource-policy --policy-file sample_policies/allow_all.regoBuild and start KBS for token distribution:
make passport-issuer-kbs
make install-issuer-kbs
issuer-kbs --socket 127.0.0.1:50001 --insecure-http --auth-public-key config/public.pubBuild and start KBS for resource distribution:
make passport-resource-kbs
make install-resource-kbs
resource-kbs --socket 127.0.0.1:50002 --insecure-http --auth-public-key config/public.pubIf you want start KBS with HTTPS server, use --private-key and --certificate to set server-side HTTPS key and certificate.
Generate a dummy resource data file:
cat > test/dummy_data << EOF
1234567890abcde
EOFUse kbs-client to upload resource data to KBS storage:
kbs-client --url http://127.0.0.1:50002 config --admin-token-file config/admin-token set-resource --resource-file test/dummy_data --path default/test/dummyHere we assigned a custom path for this resource: default/test/dummy.
Generate a TEE key pair (RSA):
openssl genrsa -traditional -out test/tee_key.pem 2048
openssl rsa -in test/tee_key.pem -pubout -out test/tee_pubkey.pemFirst, use kbs-client to get Attestation Token from KBS which is responsible for issuing token:
kbs-client --url http://127.0.0.1:50001 attest --tee-key-file test/tee_key.pem > test/attestation_tokenThe public part of TEE key is included in the Attestation Token claims to identify the TEE.
Then get resource from KBS with the attestation_token:
kbs-client --url http://127.0.0.1:50002 get-resource --attestation-token test/attestation_token --tee-key-file test/tee_key.pem --path default/test/dummyUse kbs-client to set a custom attestation policy to KBS in background check mode:
kbs-client --url http://127.0.0.1:50001 config --admin-token-file config/admin-token set-attestation-policy --policy-file /path/to/policyWhere /path/to/policy should be replaced by the real path to your policy file.
Attestation policies need to be specified using the rego syntax defined by Open Policy Agent.
For example, you can use the following policy to verify the value of TCB SVN and firmware measurement of TDX:
package my_policy
import future.keywords.if
default allow = false
# The allowed reference values for the specific field in the quote
reference_tdx_tcb_svn = [ "03000500000000000000000000000000" ]
reference_tdx_mr_td = [ "abcd1234", "1234abcd", "a1b2c3d4" ]
allow if {
input["tdx.quote.body.tcb_svn"] == reference_tdx_tcb_svn[_]
input["tdx.quote.body.mr_td"] == reference_tdx_mrtd[_]
}
Refer to Attestation-Service for filed names.
Use kbs-client to set custom resource policy to KBS:
kbs-client --url http://127.0.0.1:50002 config --admin-token-file config/admin-token set-attestation-policy --policy-file /path/to/policyWhere /path/to/policy should be replaced by the real path to your policy file.
Resource policy also needs to be the rego syntax defined by Open Policy Agent.
You can read the notes of default resource policy file for more details of resource policy.
You can configure certificate of the signing key of Attestation Token (JWT) by config files.
Adding the following content to the config file of Issuer KBS to specify token signing key and its certificate chain, which both should be PEM format.
Adding the following content to TOML config file of KBS itself:
[as_config.attestation_token_broker.signer]
key_path = "/path/to/token-key.pem"
cert_path = "/path/to/token-cert-chain.pem"See Attestation Token Verification for how AS signing material maps to KBS trust anchors. Refer to config.md for the configuration reference.
Adding the following content to JSON config file of gRPC AS:
{
...
"attestation_token_broker": {
"duration_min": 5,
"signer": {
"key_path": "/path/to/token-key.pem",
"cert_path": "/path/to/token-cert-chain.pem"
}
}
}Attestation Tokens are now all in JWT format.
Adding the following content to the config file of Resource KBS to specify trusted root certificate (PEM format) or JWK set which are used to verify the trustworthy of the Attestation Token:
[attestation_token]
# Trust anchors (PEM) used to validate the `x5c` chain on a header-embedded `jwk`
# when `insecure_header_jwk` is false.
trusted_certs_paths = ["/path/to/trusted_cacert.pem"]
# Trusted JWK set (`file://` or `https://`) used when the JWT header carries `kid`
# instead of an embedded `jwk`.
trusted_jwk_sets = ["/url/to/trusted_jwk_set"]
# When false, header `jwk` keys must be endorsed via `x5c` and `trusted_certs_paths`.
# When true, the header `jwk` is trusted without endorsement checks (testing only).
insecure_header_jwk = falseWhen insecure_header_jwk is false and the token header contains a jwk, you must configure
trusted_certs_paths; otherwise verification fails. Tokens that use kid rely on
trusted_jwk_sets instead and are not affected by insecure_header_jwk.
Refer to Attestation Token Verification for trust-chain setup and config.md for the configuration reference.