Documentation
¶
Overview ¶
Package claim holds the logic shared by the claim-initiate and claim-verify Lambdas: the configured variant, MAC normalization, claim-key construction, and the per-caller quota.
The variant and the quota are read at runtime from the claiming configuration document in SSM (ca_bootstrap.ParamConfig), set through the admin config API — not from deploy-time inputs. Deploying the claim stack group stands up the infrastructure; the configuration (plus a minted CA) is what turns claiming on. A configuration with no variant reads as off, and the handlers fail closed.
A claim vends a certificate and assigns a node ID. It confers no permission over the node. Device control comes from the primary user-node mapping, established separately by challenge-response — a proof of physical possession. The reservation is therefore not an authorization record: it exists to make node IDs stable and idempotent, to bound how many a caller can mint, and to stop one caller's claim from disturbing another's device. Anything later scoped to a node's owner must key on the primary mapping, never on this table.
The claim key is what carries that last property. It decides which reservation — and therefore which node ID — a request resolves to, and its shape differs by variant:
- The variant that cannot prove possession (user_authenticated) keys on {mac_addr, caller}. Without the caller dimension, one caller claiming another caller's MAC would resolve to the same node ID and replace the certificate on a device already in service — an unauthenticated denial of service against someone else's hardware.
- The variant that can prove possession (device_attested) keys on mac_addr alone. The caller dimension would buy nothing there and would cost correctness: a device changing hands should keep one identity, not accumulate an orphaned node per previous owner.
See docs/en/specs/assisted-claiming.md.
Index ¶
- Constants
- Variables
- func GenerateNodeID() (string, error)
- func NormalizeMacAddr(macAddr string) (string, error)
- func ProvenanceTags(v Variant, callerID string) []string
- func Quota(ctx context.Context, v Variant) (int, bool)
- func RegisteredAtTag(t time.Time) string
- func ValidateConfiguredMode(mode string) error
- type Key
- type Variant
Constants ¶
const ( TagKeyRegisteredFrom = "registered_from" TagKeyCreatedBy = "created_by" TagKeyRegisteredAt = "registered_at" )
Provenance tag keys. These reuse the keys the admin dashboard already registers as searchable fleet-index fields ("Registered From", "Created By"), so a claimed node is findable by exactly the same filters as one registered through the dashboard. Without them, claimed nodes would be the only nodes in the fleet absent from a `registered_from` search rather than merely untagged.
const DefaultMaxNodesPerClaimant = 20
DefaultMaxNodesPerClaimant bounds how many node IDs one caller can mint.
This is a lifetime cap, not a cap on nodes currently held: reservations are never deleted, so removing a node from an account does not return its slot. That is deliberate — a reclaimable quota would be no bound at all, since a caller could mint, release, and mint again without limit (requirements Req 14).
const NodeIDLength = 36
NodeIDLength is the fixed width of a claimed node ID: the 36 characters of a canonical RFC 4122 UUID (32 hex digits plus four hyphens).
Variables ¶
var ErrUnknownVariant = fmt.Errorf("unknown claiming variant")
ErrUnknownVariant is returned when the configured variant is unrecognized. Callers map it to a 500: an unknown variant means a misconfigured deployment, never a bad request.
Functions ¶
func GenerateNodeID ¶
GenerateNodeID returns a cloud-assigned node ID: a canonical RFC 4122 version-4 UUID in the standard hyphenated lowercase form, e.g. "1b4e28ba-2fa1-4d3b-a3f5-ce6f8a9b0c2d".
This is the same format the DAC and RainMaker pre-provisioning services emit, so a node's ID reads identically whichever path minted it. One value serves as the IoT Thing name, the MQTT client ID and the certificate Common Name.
A claimed node that later joins a Matter fabric has its Matter operational Node ID derived from this value exactly as it is for every other node whose ID is not already 16 hex characters (group.MatterNodeIDFromThingName). The node ID is not itself a Matter Node ID — that identity is fabric-scoped and assigned during association, not at claim time.
func NormalizeMacAddr ¶
NormalizeMacAddr strips separators, upper-cases, and validates that what remains is 12 or 16 hexadecimal characters.
Normalizing is not cosmetic. The MAC is what identifies a device in the reservation key, so "AA:BB:CC:DD:EE:FF", "aa-bb-cc-dd-ee-ff" and "AABBCCDDEEFF" must resolve to one reservation. Storing them verbatim would give the same physical device three node IDs, three certificates, and three quota slots, and would make the idempotence guarantee depend on a client's formatting convention rather than on the device (requirements Req 2.2, 2.3).
func ProvenanceTags ¶
ProvenanceTags returns the "key:value" tags to stamp on a claimed node.
These are set by the server and are deliberately not accepted from the request. The caller is an end user; letting them supply `registered_from` would let them label their node as having come from the dashboard, which is exactly the claim an administrator needs to be able to trust.
callerID is the authenticated user who drove the claim, which is not the same thing as the claim key's claimant. Under device_attested the key is the MAC alone — possession is proven, so a caller dimension in the *key* would be wrong — but a user may still have initiated the claim, and recording who did is worth having for support and audit. Passing the caller rather than the key means that tag appears there too, without the key ever gaining a user.
The sentinel is filtered defensively: it is not a user, and it must never surface in a column labelled "Created By".
func Quota ¶
Quota returns the per-caller reservation limit for the variant and whether a limit applies at all.
device_attested has no user quota, and could not have one: its claim key carries no caller, so there is nothing to count per user. It does not need one either — the device secrets service is the abuse control there, and a stronger one, since it bounds issuance to devices that were actually manufactured rather than to a number someone picked (Req 6.5, 14.4).
func RegisteredAtTag ¶
RegisteredAtTag records when a node first entered the fleet.
Nothing else exposes this to an administrator: reg_ts is written to the node row but the fleet index the console searches reads shadows, not DynamoDB, and iot:DescribeThing carries no creation date at all. As a tag it becomes visible and searchable alongside the other provenance.
RFC 3339 UTC so it sorts lexicographically in a fleet-index range query. The value contains colons, which is fine — tags split on the first one only.
func ValidateConfiguredMode ¶
ValidateConfiguredMode checks an operator-supplied mode before it is stored as the claiming configuration. An empty mode is allowed and means claiming is configured off. A non-empty mode must name a variant that is both recognized and implemented; anything else is rejected so a bad value fails at the config API rather than silently at claim time. This lives here, not in ca_bootstrap, because it needs the Variant type (and ca_bootstrap must not import claim).
Types ¶
type Key ¶
type Key struct {
MacAddr string
// ClaimantID is who the claim is recorded against: the authenticated
// caller's internal user ID, or the device sentinel under
// device_attested. It is not a tenant — this deployment model has no
// tenancy concept.
ClaimantID string
}
Key identifies the reservation a claim resolves to. Its fields map directly onto the reservation table's partition and sort keys.
type Variant ¶
type Variant string
Variant is the claiming mode. Its string values are the ones accepted by the admin config API (validated via ValidateConfiguredMode) and stored as the configuration's Mode.
const ( // VariantUserAuthenticated gates the claim on an authenticated caller. // This is the only variant that vends certificates to users, and it is // what any deployment enabling claiming gets. VariantUserAuthenticated Variant = "user_authenticated" // VariantDeviceAttested gates the claim on the device proving itself // against the secrets service, with no caller dimension. VariantDeviceAttested Variant = "device_attested" )
func CurrentVariant ¶
CurrentVariant reads the configured variant from the claiming configuration document in SSM (cached — this is a hot per-request path). Returns "" when claiming is unconfigured or the configuration cannot be read, so a claim fails closed rather than proceeding on a stale or absent variant.
func (Variant) IsImplemented ¶
IsImplemented reports whether v is not merely recognized but actually built. A known-but-unimplemented variant (device_attested today) must never be accepted as configuration: its entitlement check does not exist yet, so vending under its name would be weaker than the name implies.
func (Variant) RegisteredFrom ¶
RegisteredFrom returns the provenance value recorded for this variant, or "" if the variant is unknown.
func (Variant) RequiresCaller ¶
RequiresCaller reports whether the variant needs an authenticated caller. device_attested authenticates the device, not a user.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package ca_bootstrap mints and publishes the assisted-claiming CA and holds the operator certificate configuration it mints from.
|
Package ca_bootstrap mints and publishes the assisted-claiming CA and holds the operator certificate configuration it mints from. |
|
handlers
|
|
|
claim_admin
command
Claim admin API: admin-only configuration and bootstrap of the claiming CA.
|
Claim admin API: admin-only configuration and bootstrap of the claiming CA. |
|
claim_handler
command
Claim handler lambda: POST /v1/claim/initiate and POST /v1/claim/verify.
|
Claim handler lambda: POST /v1/claim/initiate and POST /v1/claim/verify. |