nodeattestor.proto

syntax = "proto3";
package spire.plugin.server.nodeattestor.v1;
option go_package = "github.com/spiffe/spire-plugin-sdk/proto/spire/plugin/server/nodeattestor/v1;nodeattestorv1";

service NodeAttestor {
    // Attest attests attestation payload received from the agent and
    // optionally participates in challenge/response attestation mechanics.
    //
    // The attestation flow is as follows:
    // 1. SPIRE Server opens up a stream to the plugin via Attest.
    // 2. SPIRE Server sends a request containing the attestation payload
    //    received from the agent.
    // 3. Optionally, the plugin responds with a challenge:
    //    3a. SPIRE Server sends the challenge to the agent.
    //    3b. SPIRE Agent responds with the challenge response.
    //    3c. SPIRE Server sends the challenge response to the plugin.
    //    3d. Step 3 is repeated until the plugin is satisfied and does
    //        not respond with an additional challenge.
    // 4. The plugin returns the attestation results to SPIRE Server and closes
    //    the stream.
    rpc Attest(stream AttestRequest) returns (stream AttestResponse);
}

message AttestRequest {
    oneof request {
        // Required in the first request. The attestation payload. See the
        // Attest RPC for details.
        bytes payload = 1;

        // Required in subsequent requests. The response to a plugin issued
        // challenge. See the Attest RPC for details.
        bytes challenge_response = 2;
    }
}

message AttestResponse {
    oneof response {
        // Required in all but the last response. The challenge to issue the
        // agent. See the Attest RPC for details.
        bytes challenge = 1;

        // Required as the last response. The agent attributes resulting from
        // the attestation. See the Attest RPC for details.
        AgentAttributes agent_attributes = 2;
    }
}

message AgentAttributes {
    // The ID to assign to the agent. Each agent in SPIRE must have a unique ID.
    // The convention for agent IDs is as follows:
    //
    // spiffe://<trust-domain>/spire/agent/<plugin-name>/<unique-suffix>
    //
    // with:
    // <trust-domain>  = the trust domain that the server belongs to
    // <plugin-name>   = the name of the plugin which attested the agent
    // <unique-suffix> = a unique suffix for this agent
    //
    // As of SPIRE 1.2.1, a warning is emitted when plugins return agent IDs
    // that do not follow the convention. Future SPIRE releases will enforce
    // the convention (see SPIRE issue #2712).
    string spiffe_id = 1;

    // Optional. Selectors values to ascribe to the agent. The type of the
    // selectors will be inferred from the plugin name.
    repeated string selector_values = 2;

    // Optional. If can_reattest is true, then this attestation method
    // allows an agent to attest multiple times with the same
    // attestation payload without operator intervention.
    // This also allows the server to clear out old entries automatically
    // since they can be easily recreated.
    bool can_reattest = 3;
}