demo(docs): Updated vault/openBao plugin

.github/workflows/checks.yaml

@@ -29,6 +29,8 @@
       checks: write
       contents: read
       pull-requests: read
+    needs:
+      - example-vault
     strategy:
       matrix:
         directory:
@@ -102,6 +104,8 @@
   integration:
     permissions:
       contents: read
+    needs:
+      - go
     name: integration tests
     runs-on: ubuntu-22.04
     env:
@@ -176,9 +180,89 @@
       - name: validate custom entity rego policy
         run: test/rego/custom-entity.bats
 
+  example-vault:
+    permissions:
+      contents: read
+    runs-on: ubuntu-22.04
+    env:
+      TLS_ENABLED: "true"
+      VAULT_ADDR: "https://127.0.0.1:8200"
+    steps:
+      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        with:
+          persist-credentials: false
+      - uses: actions/setup-go@d35c59abb061a4a6fb18e82ac0862c26744d6ab5 # v5.5.0
+        with:
+          go-version-file: "service/go.mod"
+          check-latest: false
+          cache-dependency-path: |
+            service/go.sum
+            examples/go.sum
+            protocol/go/go.sum
+            sdk/go.sum
+      - run: go mod download
+      - run: go mod verify
+      - name: Install mkcert
+        run: |
+          sudo apt-get install -y libnss3-tools
+          curl -JLO "https://dl.filippo.io/mkcert/latest?for=linux/amd64"
+          chmod +x mkcert-v*-linux-amd64
+          sudo cp mkcert-v*-linux-amd64 /usr/local/bin/mkcert
+      - run: |
+          .github/scripts/init-temp-keys.sh
+          mkcert -install
+          mkcert -cert-file ./keys/platform.crt -key-file ./keys/platform-key.pem localhost
+          cp opentdf-dev.yaml opentdf.yaml
+          yq eval '.server.tls.enabled = true' -i opentdf.yaml
+          yq eval '.trace = {"enabled":true}' -i opentdf.yaml
+      - name: Install vault
+       # See https://developer.hashicorp.com/vault/install#linux
+        run: |
+          wget -O - https://apt.releases.hashicorp.com/gpg | sudo gpg --dearmor -o /usr/share/keyrings/hashicorp-archive-keyring.gpg
+          echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] https://apt.releases.hashicorp.com $(grep -oP '(?<=UBUNTU_CODENAME=).*' /etc/os-release || lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/hashicorp.list
+          sudo apt update && sudo apt install vault
+      - uses: JarvusInnovations/background-action@2428e7b970a846423095c79d43f759abf979a635 # v1.0.7
+        name: start vault in background
+        with:
+          run: >
+            vault server -dev -dev-root-token-id root  
+              -dev-tls -dev-tls-cert-dir="keys"
+          wait-on: |
+            tcp:localhost:8200
+          log-output-if: true
+          wait-for: 90s
+      - run: |
+          echo "VAULT_CACERT=$(pwd)/keys/vault-ca.pem" >> "$GITHUB_ENV"
+      - name: Added Trusted Certs
+        run: |
+          sudo chmod -R 777 ./keys
+          sudo apt-get install -y ca-certificates
+          sudo cp "${VAULT_CACERT}" /usr/local/share/ca-certificates || echo unable to find "${VAULT_CACERT}"
+          sudo cp ./keys/localhost.crt /usr/local/share/ca-certificates || echo unable to find ./keys/localhost.crt
+          sudo update-ca-certificates
+      - run: docker compose up -d --wait --wait-timeout 240 || (docker compose logs && exit 1)
+      - run: go run ./service provision keycloak
+      - run: go run ./service provision fixtures
+      - uses: JarvusInnovations/background-action@2428e7b970a846423095c79d43f759abf979a635 # v1.0.7
+        name: start server in background
+        with:
+          run: |
+            . ./examples/ckms/setup-vault-env.sh
+            go run ./examples/ckms
+          wait-on: |
+            tcp:localhost:8080
+          log-output-if: true
+          wait-for: 90s
+      - name: Setup Bats and bats libs
+        uses: bats-core/bats-action@42fcc8700f773c075a16a90eb11674c0318ad507 # 3.0.1
+      - run: ./examples/ckms/trust-sample.bats
+
   benchmark:
     permissions:
       contents: read
+      pull-requests: write
+    needs:
+      - go
     name: benchmark tests
     outputs:
       markdown: ${{ steps.save-benchmark.outputs.BENCHMARK_MARKDOWN }}
@@ -373,6 +457,8 @@
   image:
     permissions:
       contents: read
+    needs:
+      - go
     name: image build
     runs-on: ubuntu-22.04
     steps:
@@ -390,10 +476,12 @@
 
   platform-xtest:
     permissions:
+      checks: write
       contents: read
       packages: read
       pull-requests: write
-      checks: write
+    needs:
+      - go
     uses: opentdf/tests/.github/workflows/xtest.yml@main
     with:
       focus-sdk: go
@@ -462,6 +550,8 @@
   otdfctl-test:
     permissions:
       contents: read
+    needs:
+      - go
     name: otdfctl e2e tests
     runs-on: ubuntu-latest
     steps:
@@ -482,6 +572,8 @@
   buflint:
     permissions:
       contents: read
+    needs:
+      - go
     name: Protocol Buffer Lint and Gencode Up-to-date check
     runs-on: ubuntu-22.04
     steps:

examples/ckms/.gitignore

@@ -0,0 +1,11 @@
+# ignores for CKMS Sample Code
+
+# Generated keydata
+*.crt
+*.key
+*.pem
+
+# Logfiles
+vault-startup.log
+
+

examples/ckms/README.md

@@ -0,0 +1,88 @@
+# Sample Key Management System Integration with OpenBao
+
+This folder includes an example Cryptographic Key Management System (CKMS) extension for OpenTDF.
+It uses Vault or OpenBao to store KAS asymmetric key data,
+provided via a `trust.KeyService` plugin.
+
+## Starting Vault
+
+Start up vault, configured to run in dev mode with local storage.
+
+```sh
+LOCAL_HOSTNAME=$(hostname)
+vault server -dev -dev-root-token-id root -dev-tls -dev-tls-cert-dir=./
+```
+
+Install the generated CA certificate into the system keychain.
+
+```sh
+sudo security add-trusted-cert -d -r trustRoot -k "/Library/Keychains/System.keychain" ./vault-ca.pem
+```
+
+Copy the configuration details somewhere.
+Copy and paste the environment variable configuration into a new shell.
+
+```sh
+export VAULT_ADDR="https://127.0.0.1:8200"
+export VAULT_CACERT="$(pwd)/vault-ca.pem"
+```
+
+Validate vault is running, and log in
+
+```sh
+vault status
+echo root | vault login -
+```
+
+Let's create some roles, policies, and tokens that apply them:
+
+```sh
+vault secrets enable -path=secret kv-v2
+
+vault policy write kas-admin ./vault/policy-admin.hcl
+vault policy write kas-service ./vault/policy-service.hcl
+vault policy write kas-viewer ./vault/policy-viewer.hcl
+
+vault token create -policy="kas-admin" -policy="kas-viewer"
+# Use this token to create and delete KAS keys
+# export KAS_ADMIN_TOKEN=<TOKEN>
+echo ${KAS_ADMIN_TOKEN} | vault login -
+vault kv put secret/kas_keypair/r1 private="$(<../../kas-private.pem | base64)" public="$(<../../kas-cert.pem)" algorithm="rsa:2048""
+```
+
+```sh
+echo root | vault login -
+
+# Create a role to from within KAS
+vault auth enable approle
+vault write auth/approle/role/kas policies="kas-service,kas-viewer"
+vault read auth/approle/role/kas/role-id
+vault write -f auth/approle/role/kas/secret-id
+## Use the role_id and secret_id from the above outputs to create a token with this:
+# export KAS_APPROLE_ROLEID=<ROLE_ID>
+# export KAS_APPROLE_SECRETID=<SECRET_ID>
+vault write auth/approle/login role_id=${KAS_APPROLE_ROLEID} secret_id=${KAS_APPROLE_SECRETID}
+```
+
+Set KAS_SERVICE_TOKEN to the token returned from the above command.
+
+```sh
+echo ${KAS_SERVICE_TOKEN} | vault login -
+vault kv list -mount=secret kas_keypair
+```
+
+
+### Start platform services with sample CKMS plugin
+
+Run the example
+
+```sh
+go run examples/ckms
+```
+
+#### 
+#### Add key based configuration using a new KAS key in the CKMS
+
+
+### Encrypt something
+

examples/ckms/cfg-vault.yaml

@@ -0,0 +1,117 @@
+logger:
+  level: debug
+  type: text
+  output: stdout
+# DB and Server configurations are defaulted for local development
+# db:
+#   host: localhost
+#   port: 5432
+#   user: postgres
+#   password: changeme
+services:
+  entityresolution:
+    log_level: info
+    url: http://localhost:8888/auth
+    clientid: "tdf-entity-resolution"
+    clientsecret: "secret"
+    realm: "opentdf"
+    legacykeycloak: true
+    inferid:
+      from:
+        email: true
+        username: true
+  # policy is enabled by default in mode 'all'
+  # policy:
+  #   enabled: true
+  # list_request_limit_default: 1000
+  # list_request_limit_max: 2500
+server:
+  tls:
+    enabled: false
+    cert: ./keys/platform.crt
+    key: ./keys/platform-key.pem
+  auth:
+    enabled: true
+    enforceDPoP: false
+    public_client_id: "opentdf-public"
+    audience: "http://localhost:8080"
+    issuer: http://localhost:8888/auth/realms/opentdf
+    policy:
+      ## Dot notation is used to access nested claims (i.e. realm_access.roles)
+      # Claim that represents the user (i.e. email)
+      username_claim: # preferred_username
+      # That claim to access groups (i.e. realm_access.roles)
+      groups_claim: # realm_access.roles
+      ## Extends the builtin policy
+      extension: |
+        g, opentdf-admin, role:admin
+        g, opentdf-standard, role:standard
+      ## Custom policy that overrides builtin policy (see examples https://github.com/casbin/casbin/tree/master/examples)
+      csv: #|
+      #  p, role:admin, *, *, allow
+      ## Custom model (see https://casbin.org/docs/syntax-for-models/)
+      model: #|
+      #  [request_definition]
+      #  r = sub, res, act, obj
+      #
+      #  [policy_definition]
+      #  p = sub, res, act, obj, eft
+      #
+      #  [role_definition]
+      #  g = _, _
+      #
+      #  [policy_effect]
+      #  e = some(where (p.eft == allow)) && !some(where (p.eft == deny))
+      #
+      #  [matchers]
+      #  m = g(r.sub, p.sub) && globOrRegexMatch(r.res, p.res) && globOrRegexMatch(r.act, p.act) && globOrRegexMatch(r.obj, p.obj)
+  trace:
+    enabled: false
+    provider:
+      name: file # file | otlp
+      file:
+        path: "./traces/traces.log"
+        prettyPrint: true # Optional, default is compact JSON
+        maxSize: 50    # Optional, default 20MB
+        maxBackups: 5    # Optional, default 10
+        maxAge: 14    # Optional, default 30 days
+        compress: true   # Optional, default false
+      # otlp:
+        # protocol: grpc # Optional, defaults to grpc
+        # endpoint: "localhost:4317"
+        # insecure: true # Set to false if Jaeger requires TLS
+        # headers: {} # Add if authentication is needed
+        # HTTP
+        #        protocol: "http/protobuf"
+        #        endpoint: "http://localhost:4318" # Default OTLP HTTP port
+        #        insecure: true # If collector is just HTTP, not HTTPS
+        # headers: {} # Add if authentication is needed
+  cors:
+    # "*" to allow any origin or a specific domain like "https://yourdomain.com"
+    allowedorigins:
+      - "*"
+    # List of methods. Examples: "GET,POST,PUT"
+    allowedmethods:
+      - GET
+      - POST
+      - PATCH
+      - PUT
+      - DELETE
+      - OPTIONS
+    # List of headers that are allowed in a request
+    allowedheaders:
+      - ACCEPT
+      - Authorization
+      - Content-Type
+      - X-CSRF-Token
+      - X-Request-ID
+    # List of response headers that browsers are allowed to access
+    exposedheaders:
+      - Link
+    # Sets whether credentials are included in the CORS request
+    allowcredentials: true
+    # Sets the maximum age (in seconds) of a specific CORS preflight request
+    maxage: 3600
+  grpc:
+    reflectionEnabled: true # Default is false
+  port: 8080

examples/ckms/docker-compose.yaml

@@ -0,0 +1,18 @@
+version: "3.9"
+services:
+  ckms:
+    image: hashicorp/vault:latest
+    cap_add:
+      - IPC_LOCK
+    command: vault server -config vault/config/local.json
+    environment:
+      VAULT_ADDR: 'https://127.0.0.1:8200'
+      VAULT_LOCAL_CONFIG: '{"listener":[{"tcp":{"address": "0.0.0.0:8200","tls_disable":"1"}}],"ui":true,"storage":[{"file":{"path":"/vault/data"}}]}'
+    healthcheck:
+      retries: 5
+    ports:
+      - 8200:8200
+    restart: always
+    volumes:
+      - ./vault/config:/vault/config
+      - ./vault/data:/vault/data