SPIRE SPIFFE Exchange - Public Keysets 1.0.0

1
# Copyright 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2
# SPDX-License-Identifier: Apache-2.0
3
4
asyncapi: 3.1.0
5
info:
6
  title: SPIRE SPIFFE Exchange - Public Keysets
7
  version: 1.0.0
8
  description: |
9
    AsyncAPI specification for publishing JWK (JSON Web Key) public keys on the
10
    SPIFFE/SPIRE exchange topic. One JWK per message. Used to distribute public
11
    keys for a given tenant and key identifier so consumers can verify JWS or
12
    use keys for encryption.
13
14
    **Topic format:** `spiffe-exchange/v1/pub-keysets/tenant/{tenant_domain}/kid/{kid}`
15
16
    Payloads conform to RFC 7517 (JSON Web Key). Only public key material is
17
    published on this channel.
18
19
servers:
20
  production:
21
    host: broker.example.com
22
    protocol: mqtt
23
    description: MQTT broker for SPIFFE exchange public key distribution
24
25
channels:
26
  pubKeysets:
27
    address: "spiffe-exchange/v1/pub-keysets/tenant/{tenant_domain}/kid/{kid}"
28
    parameters:
29
      tenant_domain:
30
        description: Tenant domain identifier (e.g. tenant namespace or domain name).
31
      kid:
32
        description: Key ID (kid) for this key; aligns with JWS/JWE header kid.
33
    messages:
34
      jwk:
35
        $ref: "#/components/messages/JwkMessage"
36
37
operations:
38
  publishPubKeyset:
39
    action: send
40
    channel:
41
      $ref: "#/channels/pubKeysets"
42
    messages:
43
      - $ref: "#/channels/pubKeysets/messages/jwk"
44
    description: >
45
      Publish one JWK for the given tenant and kid. Publishers (e.g. SPIRE)
46
      use this to advertise a public key for verification or encryption.
47
48
  subscribePubKeyset:
49
    action: receive
50
    channel:
51
      $ref: "#/channels/pubKeysets"
52
    messages:
53
      - $ref: "#/channels/pubKeysets/messages/jwk"
54
    description: >
55
      Subscribe to public key updates for a tenant and kid. Each message
56
      carries one JWK. Consumers use the key to verify signatures or encrypt.
57
58
components:
59
  messages:
60
    JwkMessage:
61
      name: JwkMessage
62
      title: JWK (RFC 7517)
63
      contentType: application/json
64
      payload:
65
        $ref: "#/components/schemas/Jwk"
66
67
  schemas:
68
    Jwk:
69
      type: object
70
      required:
71
        - kty
72
      description: >
73
        Single JSON Web Key per RFC 7517. Only public key parameters are included
74
        on this channel. Key type (kty) determines which additional members are present.
75
      properties:
76
        kty:
77
          type: string
78
          description: Key type (e.g. RSA, EC, OKP).
79
          enum:
80
            - RSA
81
            - EC
82
            - OKP
83
        use:
84
          type: string
85
          description: Public key use (sig, enc, or omitted).
86
          enum:
87
            - sig
88
            - enc
89
        key_ops:
90
          type: array
91
          items:
92
            type: string
93
          description: Key operations (e.g. verify, encrypt).
94
        alg:
95
          type: string
96
          description: Algorithm (e.g. ES256, RS256, EdDSA).
97
        kid:
98
          type: string
99
          description: Key ID; should match the topic kid when present.
100
        # RSA public key parameters (when kty is RSA)
101
        n:
102
          type: string
103
          description: RSA modulus (Base64url).
104
        e:
105
          type: string
106
          description: RSA public exponent (Base64url).
107
        # EC public key parameters (when kty is EC)
108
        crv:
109
          type: string
110
          description: Elliptic curve (e.g. P-256, P-384).
111
        x:
112
          type: string
113
          description: EC x coordinate (Base64url).
114
        y:
115
          type: string
116
          description: EC y coordinate (Base64url).
117
        # OKP (e.g. Ed25519): public key is in 'x'. Private key (d) MUST NOT be published here.