diff --git a/java-spiffe-core/src/main/proto/workload.proto b/java-spiffe-core/src/main/proto/workload.proto index 07c6776..5df8d2e 100644 --- a/java-spiffe-core/src/main/proto/workload.proto +++ b/java-spiffe-core/src/main/proto/workload.proto @@ -4,100 +4,152 @@ option java_package = "io.spiffe.workloadapi.grpc"; import "google/protobuf/struct.proto"; +service SpiffeWorkloadAPI { + ///////////////////////////////////////////////////////////////////////// + // X509-SVID Profile + ///////////////////////////////////////////////////////////////////////// + + // Fetch X.509-SVIDs for all SPIFFE identities the workload is entitled to, + // as well as related information like trust bundles and CRLs. As this + // information changes, subsequent messages will be streamed from the + // server. + rpc FetchX509SVID(X509SVIDRequest) returns (stream X509SVIDResponse); + + // Fetch trust bundles and CRLs. Useful for clients that only need to + // validate SVIDs without obtaining an SVID for themself. As this + // information changes, subsequent messages will be streamed from the + // server. + rpc FetchX509Bundles(X509BundlesRequest) returns (stream X509BundlesResponse); + + ///////////////////////////////////////////////////////////////////////// + // JWT-SVID Profile + ///////////////////////////////////////////////////////////////////////// + + // Fetch JWT-SVIDs for all SPIFFE identities the workload is entitled to, + // for the requested audience. If an optional SPIFFE ID is requested, only + // the JWT-SVID for that SPIFFE ID is returned. + rpc FetchJWTSVID(JWTSVIDRequest) returns (JWTSVIDResponse); + + // Fetches the JWT bundles, formatted as JWKS documents, keyed by the + // SPIFFE ID of the trust domain. As this information changes, subsequent + // messages will be streamed from the server. + rpc FetchJWTBundles(JWTBundlesRequest) returns (stream JWTBundlesResponse); + + // Validates a JWT-SVID against the requested audience. Returns the SPIFFE + // ID of the JWT-SVID and JWT claims. + rpc ValidateJWTSVID(ValidateJWTSVIDRequest) returns (ValidateJWTSVIDResponse); +} + +// The X509SVIDRequest message conveys parameters for requesting an X.509-SVID. +// There are currently no request parameters. message X509SVIDRequest { } -// The X509SVIDResponse message carries a set of X.509 SVIDs and their -// associated information. It also carries a set of global CRLs, and a -// TTL to inform the workload when it should check back next. +// The X509SVIDResponse message carries X.509-SVIDs and related information, +// including a set of global CRLs and a list of bundles the workload may use +// for federating with foreign trust domains. message X509SVIDResponse { - // A list of X509SVID messages, each of which includes a single - // SPIFFE Verifiable Identity Document, along with its private key - // and bundle. + // Required. A list of X509SVID messages, each of which includes a single + // X.509-SVID, its private key, and the bundle for the trust domain. repeated X509SVID svids = 1; - // ASN.1 DER encoded + // Optional. ASN.1 DER encoded certificate revocation lists. repeated bytes crl = 2; - // CA certificate bundles belonging to foreign Trust Domains that the - // workload should trust, keyed by the SPIFFE ID of the foreign + // Optional. CA certificate bundles belonging to foreign trust domains that + // the workload should trust, keyed by the SPIFFE ID of the foreign trust // domain. Bundles are ASN.1 DER encoded. map federated_bundles = 3; } -// The X509SVID message carries a single SVID and all associated -// information, including CA bundles. +// The X509SVID message carries a single SVID and all associated information, +// including the X.509 bundle for the trust domain. message X509SVID { - // The SPIFFE ID of the SVID in this entry + // Required. The SPIFFE ID of the SVID in this entry string spiffe_id = 1; - // ASN.1 DER encoded certificate chain. MAY include intermediates, - // the leaf certificate (or SVID itself) MUST come first. + // Required. ASN.1 DER encoded certificate chain. MAY include + // intermediates, the leaf certificate (or SVID itself) MUST come first. bytes x509_svid = 2; - // ASN.1 DER encoded PKCS#8 private key. MUST be unencrypted. + // Required. ASN.1 DER encoded PKCS#8 private key. MUST be unencrypted. bytes x509_svid_key = 3; - // CA certificates belonging to the Trust Domain - // ASN.1 DER encoded + // Required. ASN.1 DER encoded X.509 bundle for the trust domain. bytes bundle = 4; } -message X509BundlesRequest {} - -message X509BundlesResponse { - // x509 certificates, keyed by trust domain URI - map bundles = 1; +// The X509BundlesRequest message conveys parameters for requesting X.509 +// bundles. There are currently no such parameters. +message X509BundlesRequest { } -message JWTSVID { - string spiffe_id = 1; +// The X509BundlesResponse message carries a set of global CRLs and a map of +// trust bundles the workload should trust. +message X509BundlesResponse { + // Optional. ASN.1 DER encoded certificate revocation lists. + repeated bytes crl = 1; - // Encoded using JWS Compact Serialization - string svid = 2; + // Required. CA certificate bundles belonging to trust domains that the + // workload should trust, keyed by the SPIFFE ID of the trust domain. + // Bundles are ASN.1 DER encoded. + map bundles = 2; } message JWTSVIDRequest { + // Required. The audience(s) the workload intends to authenticate against. repeated string audience = 1; - // SPIFFE ID of the JWT being requested - // If not set, all IDs will be returned + // Optional. The requested SPIFFE ID for the JWT-SVID. If unset, all + // JWT-SVIDs to which the workload is entitled are requested. string spiffe_id = 2; } +// The JWTSVIDResponse message conveys JWT-SVIDs. message JWTSVIDResponse { + // Required. The list of returned JWT-SVIDs. repeated JWTSVID svids = 1; } -message JWTBundlesRequest { } +// The JWTSVID message carries the JWT-SVID token and associated metadata. +message JWTSVID { + // Required. The SPIFFE ID of the JWT-SVID. + string spiffe_id = 1; -message JWTBundlesResponse { - // JWK sets, keyed by trust domain URI - map bundles = 1; -} - -message ValidateJWTSVIDRequest { - string audience = 1; - - // Encoded using JWS Compact Serialization + // Required. Encoded JWT using JWS Compact Serialization. string svid = 2; } +// The JWTBundlesRequest message conveys parameters for requesting JWT bundles. +// There are currently no such parameters. +message JWTBundlesRequest { } + +// The JWTBundlesReponse conveys JWT bundles. +message JWTBundlesResponse { + // Required. JWK encoded JWT bundles, keyed by the SPIFFE ID of the trust + // domain. + map bundles = 1; +} + +// The ValidateJWTSVIDRequest message conveys request parameters for +// JWT-SVID validation. +message ValidateJWTSVIDRequest { + // Required. The audience of the validating party. The JWT-SVID must + // contain an audience claim which contains this value in order to + // succesfully validate. + string audience = 1; + + // Required. The JWT-SVID to validate, encoded using JWS Compact + // Serialization. + string svid = 2; +} + +// The ValidateJWTSVIDReponse message conveys the JWT-SVID validation results. message ValidateJWTSVIDResponse { + // Required. The SPIFFE ID of the validated JWT-SVID. string spiffe_id = 1; + + // Optional. Arbitrary claims contained within the payload of the validated + // JWT-SVID. google.protobuf.Struct claims = 2; } -service SpiffeWorkloadAPI { - // JWT-SVID Profile - rpc FetchJWTSVID(JWTSVIDRequest) returns (JWTSVIDResponse); - rpc FetchJWTBundles(JWTBundlesRequest) returns (stream JWTBundlesResponse); - rpc ValidateJWTSVID(ValidateJWTSVIDRequest) returns (ValidateJWTSVIDResponse); - - // X.509-SVID Profile - // Fetch all SPIFFE identities the workload is entitled to, as - // well as related information like trust bundles and CRLs. As - // this information changes, subsequent messages will be sent. - rpc FetchX509SVID(X509SVIDRequest) returns (stream X509SVIDResponse); - rpc FetchX509Bundles(X509BundlesRequest) returns (stream X509BundlesResponse); -} -