pw_software_update/tuf.proto - pigweed/pigweed - Git at Google

 // Copyright 2021 The Pigweed Authors
 //
 // Licensed under the Apache License, Version 2.0 (the "License"); you may not
 // use this file except in compliance with the License. You may obtain a copy of
 // the License at
 //
 //     https://www.apache.org/licenses/LICENSE-2.0
 //
 // Unless required by applicable law or agreed to in writing, software
 // distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 // WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 // License for the specific language governing permissions and limitations under
 // the License.
 //
 // Implementation of metadata formats specified in TUF Specification.
 // See https://theupdateframework.github.io/specification/latest/

 syntax = "proto3";

 package pw.software_update;

 import "google/protobuf/timestamp.proto";

 // Metadata for a particular TUF role (e.g. targets metadata).
 // Was TufMetadata
 message SignedRootMetadata {
   // Serialized RootMetadata message that is the data portion of the metadata.
   bytes serialized_root_metadata = 1;

   // Signature of the canonical form of the role's serialized metadata
   // (serialized_root_metadata).
   repeated Signature signatures = 2;
 }

 message SignedTimestampMetadata {
   // Serialized TimestampMetadata message that is the data portion of the
   // metadata.
   bytes serialized_timestamp_metadata = 1;

   // Signature of the canonical form of the role's serialized metadata
   // (serialized_timestamp_metadata).
   repeated Signature signatures = 2;
 }

 message SignedSnapshotMetadata {
   // Serialized SnapshotMetadata message that is the data portion of the
   // metadata.
   bytes serialized_snapshot_metadata = 1;

   // Signature of the canonical form of the role's serialized metadata
   // (serialized_snapshot_metadata).
   repeated Signature signatures = 2;
 }

 message SignedTargetsMetadata {
   // Serialized TargetsMetadata message that is the data portion of the
   // metadata.
   bytes serialized_targets_metadata = 1;

   // Signature of the canonical form of the role's serialized metadata
   // (serialized_targets_metadata).
   repeated Signature signatures = 2;
 }

 message CommonMetadata {
   // Version number of the TUF Specification.
   // Follows the Semantic Versioning 2.0.0 (semver) format. Metadata is
   // written according to this version, and clients MUST verify that
   // "spec_version" matches the expected version number.
   // E.g. "1.0.0".
   string spec_version = 1;

   // Metadata file version.
   // Clients MUST NOT replace a metadata file with a version number less than
   // the one currently trusted.
   uint32 version = 2;

   // Expiration time for the metadata.
   // Indicates when this metadata should be considered expired and no longer
   // trusted by clients. Notice the TUF Specification defines this as a JSON
   // string following the ISO 8601 standard. The expected format of the date and
   // time string is "YYYY-MM-DDTHH:MM:SSZ". Time is always in UTC, and the "Z"
   // time zone designator is attached to indicate a zero UTC offset.
   // E.g. "2030-08-26T16:48:27Z".
   optional google.protobuf.Timestamp expires = 3;

   // Role type for the metadata.
   // Indicates the type of the metadata. Valid values are 'root', 'targets',
   // 'snapshot' and 'timestamp' as defined in the TUF spec, though we don't
   // plan to support 'mirrors'.
   //
   // This field serves as a "magic code" that identifies a particular type of
   // a metadata. During verification, the client is expected to check this
   // field against the expected role type immediately after verifying the
   // signatures of a metadata. This can be considered a "confidence booster"
   // in the absence of canonical protobuf -- i.e. it makes the various
   // `serialized_x_metadata` fields more tamper resistant.
   optional string role = 4;
 }

 // This content is signed.
 message RootMetadata {
   CommonMetadata common_metadata = 1;

   // Whether the repo supports consistent snapshots. If the repo has frequent
   // updates, you should set this to true.
   bool consistent_snapshot = 2;

   // Map from Keyid to Key.
   // Keyid is a unique identifier that identifies a cryptographic key.
   // Contains all of cryptographic keys used by this repository.
   repeated KeyMapping keys = 3;

   // KeyConfig is the list of keys use for a particular role and the threshold.
   // Threshold is number of keys of that role whose signatures are required in
   // order to consider a file as being properly signed by that role.
   SignatureRequirement root_signature_requirement = 4;
   SignatureRequirement timestamp_signature_requirement = 5;
   SignatureRequirement snapshot_signature_requirement = 6;
   SignatureRequirement targets_signature_requirement = 7;

   // This is NOT a part of the TUF Specification.
   reserved 8 to 31;  // Reserved for TUF Specification changes.

   reserved 32 to 64;  // Reserved for future Pigweed usage.

   reserved 65 to 255;  // Reserved for project-specific usage.
 }

 // The timestamp role is used for freshness check of the snapshot. Any
 // project-specific update metadata should go in the top-level targets_metadata
 // or with the TargetFile information
 message TimestampMetadata {
   CommonMetadata common_metadata = 1;

   // Only one snapshot_metadata is used per timestamp.
   MetadataFile snapshot_metadata = 2;

   // This is NOT a part of the TUF Specification.
   reserved 3 to 31;  // Reserved for TUF Specification changes.

   reserved 32 to 64;  // Reserved for future Pigweed usage.

   reserved 65 to 255;  // Reserved for project-specific usage.
 }

 // The snapshot role is used to ensure that the collection of targets_metadata
 // files is securely consistent (no target metadata mix and match). Any
 // project-specific update metadata should go in the top-level targets_metadata
 // or with the TargetFile information
 message SnapshotMetadata {
   CommonMetadata common_metadata = 1;

   // Map from Target metadata file name to MetadataFile.
   // File name can be an arbitrary name or a full file name with relative path.
   // This map should contain an entry for the top level targets role and all
   // delegated roles.
   repeated MetadataFile targets_metadata = 2;

   // This is NOT a part of the TUF Specification.
   reserved 3 to 31;  // Reserved for TUF Specification changes.

   reserved 32 to 64;  // Reserved for future Pigweed usage.

   reserved 65 to 255;  // Reserved for project-specific usage.
 }

 // The targets role describes the target files that comprise the software
 // update. Targets metadata is organized in to a top-level targets metadata file
 // and optional multiple deligated targets metadata files
 //
 // The top-level targets metatdata is the correct place to put any
 // project-specific build version information, including build ID, hardware rev,
 // etc.
 message TargetsMetadata {
   CommonMetadata common_metadata = 1;

   // Collection of target file information
   repeated TargetFile target_files = 2;
   // Target file name can be an arbitrary name or a path that describes where
   // the file lives relative to the base directory of the repository, e.g.
   // "path/to/amber_tools/0".

   // TODO: When it is time to support delegation, add delegation information
   // here.

   // This is NOT a part of the TUF Specification.
   reserved 9 to 31;  // Reserved for TUF Specification changes.

   reserved 32 to 64;  // Reserved for future Pigweed usage.

   reserved 65 to 255;  // Reserved for project-specific usage.
 }

 message Signature {
   // Identifier of the key, which is bytes of the SHA-256 hash of the
   // canonical form of the key.
   bytes key_id = 1;

   // The signature of the canonical form of the role's serialized metadata
   // (serialized_{root,timestamp,snapshot,targets}_metadata).
   bytes sig = 2;
 }

 message KeyMapping {
   // Identifier of the key, which is bytes of the SHA-256 hash of the
   // canonical form of the key.
   bytes key_id = 1;

   // Cryptographic key
   Key key = 2;
 }

 // Identifies an asymmetric cryptographic key.
 message Key {
   // Denotes a public key signature system, such as RSA or ECDSA.
   KeyType key_type = 1;

   // Denotes the signature scheme corresponding to the key type. For example:
   // "rsassa-pss-sha256" or "ecdsa-sha2-nistp256".
   KeyScheme scheme = 2;

   // Stores the serialized public key for this cryptographic algorithm.
   bytes keyval = 3;
 }

 // The set of cryptographic keys used by a specific role. For example, list of
 // key_ids used by the top level role "root".
 message SignatureRequirement {
   // Set of Keyid's.
   // Keyid is a unique identifier that identifies a cryptographic key.
   // E.g. "f2d5020d08aea06a0a9192eb6a4f549e17032ebefa1aa9ac167c1e3e727930d6".
   repeated bytes key_ids = 1;

   // Threshold of signatures required to trust given file.
   // In other words; the number of keys of that role whose signatures are
   // required in order to consider a file as being properly signed by that role.
   uint32 threshold = 2;
 }

 enum HashFunction {
   // Never use this in any TUF metadata.
   UNKNOWN_HASH_FUNCTION = 0;

   SHA256 = 1;
 }

 message Hash {
   HashFunction function = 1;
   // Digest of the cryptographic hash function computed on the target file.
   bytes hash = 2;
 }

 // Descriptor for a file stored in this repository. Linked to from target
 // metadata.
 message TargetFile {
   // Target file name can be an arbitrary name or a path that describes where
   // the file lives relative to the base directory of the repository, e.g.
   // "path/to/amber_tools/0".
   string file_name = 1;

   // Size of the target file (element payload) in bytes. This the size as stored
   // in the bundle. The final applied size can be different due to optional
   // compression.
   uint64 length = 2;

   // Map from algorithm name to Hash.
   // Algorithm name is the name of a cryptographic hash function. E.g. "sha256".
   // The Hash string is the hex digest of the cryptographic function computed on
   // the target file. E.g.
   // "65b8c67f51c993d898250f40aa57a317d854900b3a04895464313e48785440da".
   repeated Hash hashes = 3;

   // This is NOT a part of the TUF Specification.
   reserved 4 to 15;  // Reserved for TUF Specification changes.

   reserved 16 to 31;  // Reserved for future Pigweed usage.

   reserved 32 to 255;  // Reserved for future project-specific usage.
 }

 message MetadataFile {
   // Target file name can be an arbitrary name or a path that describes where
   // the file lives relative to the base directory of the repository, e.g.
   // "path/to/target/0".
   optional string file_name = 1;

   // Metadata file version. E.g. 3.
   uint32 version = 2;

   // Size of the target file in bytes.
   optional uint64 length = 3;

   // Map from algorithm name to Hash.
   // Algorithm name is the name of a cryptographic hash function. E.g. "sha256".
   // The Hash is the hex digest of the cryptographic function computed on the
   // target file. E.g.
   // "65b8c67f51c993d898250f40aa57a317d854900b3a04895464313e48785440da".
   repeated Hash hashes = 4;
 }

 enum KeyType {
   // Never use this in any TUF metadata.
   UNKNOWN_KEY_TYPE = 0;

   RSA = 1;

   ED25519 = 2;

   ECDSA_SHA2_NISTP256 = 3;
 }

 enum KeyScheme {
   // Never use this in any TUF metadata.
   UNKNOWN_KEY_SCHEME = 0;

   // RSA Probabilistic signature scheme with appendix.
   // The underlying hash function is SHA256.
   // In TUF Specification, this is referred to as "rsassa-pss-sha256".
   RSASSA_PSS_SHA256_SCHEME = 1;

   // Elliptic Curve digital signature algorithm based on Twisted Edwards curves.
   // See https://ed25519.cr.yp.to/.
   // In TUF Specification, it is referred to as "ed25519".
   ED25519_SCHEME = 2;

   // Elliptic Curve Digital Signature Algorithm with NIST P-256 curve signing
   // and SHA-256 hashing. See
   // https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm In
   // TUF Specification, it is referred to as "ecdsa-sha2-nistp256".
   ECDSA_SHA2_NISTP256_SCHEME = 3;
 }
	// Copyright 2021 The Pigweed Authors
	//
	// Licensed under the Apache License, Version 2.0 (the "License"); you may not
	// use this file except in compliance with the License. You may obtain a copy of
	// the License at
	//
	// https://www.apache.org/licenses/LICENSE-2.0
	//
	// Unless required by applicable law or agreed to in writing, software
	// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
	// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
	// License for the specific language governing permissions and limitations under
	// the License.
	//
	// Implementation of metadata formats specified in TUF Specification.
	// See https://theupdateframework.github.io/specification/latest/

	syntax = "proto3";

	package pw.software_update;

	import "google/protobuf/timestamp.proto";

	// Metadata for a particular TUF role (e.g. targets metadata).
	// Was TufMetadata
	message SignedRootMetadata {
	// Serialized RootMetadata message that is the data portion of the metadata.
	bytes serialized_root_metadata = 1;

	// Signature of the canonical form of the role's serialized metadata
	// (serialized_root_metadata).
	repeated Signature signatures = 2;
	}

	message SignedTimestampMetadata {
	// Serialized TimestampMetadata message that is the data portion of the
	// metadata.
	bytes serialized_timestamp_metadata = 1;

	// Signature of the canonical form of the role's serialized metadata
	// (serialized_timestamp_metadata).
	repeated Signature signatures = 2;
	}

	message SignedSnapshotMetadata {
	// Serialized SnapshotMetadata message that is the data portion of the
	// metadata.
	bytes serialized_snapshot_metadata = 1;

	// Signature of the canonical form of the role's serialized metadata
	// (serialized_snapshot_metadata).
	repeated Signature signatures = 2;
	}

	message SignedTargetsMetadata {
	// Serialized TargetsMetadata message that is the data portion of the
	// metadata.
	bytes serialized_targets_metadata = 1;

	// Signature of the canonical form of the role's serialized metadata
	// (serialized_targets_metadata).
	repeated Signature signatures = 2;
	}

	message CommonMetadata {
	// Version number of the TUF Specification.
	// Follows the Semantic Versioning 2.0.0 (semver) format. Metadata is
	// written according to this version, and clients MUST verify that
	// "spec_version" matches the expected version number.
	// E.g. "1.0.0".
	string spec_version = 1;

	// Metadata file version.
	// Clients MUST NOT replace a metadata file with a version number less than
	// the one currently trusted.
	uint32 version = 2;

	// Expiration time for the metadata.
	// Indicates when this metadata should be considered expired and no longer
	// trusted by clients. Notice the TUF Specification defines this as a JSON
	// string following the ISO 8601 standard. The expected format of the date and
	// time string is "YYYY-MM-DDTHH:MM:SSZ". Time is always in UTC, and the "Z"
	// time zone designator is attached to indicate a zero UTC offset.
	// E.g. "2030-08-26T16:48:27Z".
	optional google.protobuf.Timestamp expires = 3;

	// Role type for the metadata.
	// Indicates the type of the metadata. Valid values are 'root', 'targets',
	// 'snapshot' and 'timestamp' as defined in the TUF spec, though we don't
	// plan to support 'mirrors'.
	//
	// This field serves as a "magic code" that identifies a particular type of
	// a metadata. During verification, the client is expected to check this
	// field against the expected role type immediately after verifying the
	// signatures of a metadata. This can be considered a "confidence booster"
	// in the absence of canonical protobuf -- i.e. it makes the various
	// `serialized_x_metadata` fields more tamper resistant.
	optional string role = 4;
	}

	// This content is signed.
	message RootMetadata {
	CommonMetadata common_metadata = 1;

	// Whether the repo supports consistent snapshots. If the repo has frequent
	// updates, you should set this to true.
	bool consistent_snapshot = 2;

	// Map from Keyid to Key.
	// Keyid is a unique identifier that identifies a cryptographic key.
	// Contains all of cryptographic keys used by this repository.
	repeated KeyMapping keys = 3;

	// KeyConfig is the list of keys use for a particular role and the threshold.
	// Threshold is number of keys of that role whose signatures are required in
	// order to consider a file as being properly signed by that role.
	SignatureRequirement root_signature_requirement = 4;
	SignatureRequirement timestamp_signature_requirement = 5;
	SignatureRequirement snapshot_signature_requirement = 6;
	SignatureRequirement targets_signature_requirement = 7;

	// This is NOT a part of the TUF Specification.
	reserved 8 to 31; // Reserved for TUF Specification changes.

	reserved 32 to 64; // Reserved for future Pigweed usage.

	reserved 65 to 255; // Reserved for project-specific usage.
	}

	// The timestamp role is used for freshness check of the snapshot. Any
	// project-specific update metadata should go in the top-level targets_metadata
	// or with the TargetFile information
	message TimestampMetadata {
	CommonMetadata common_metadata = 1;

	// Only one snapshot_metadata is used per timestamp.
	MetadataFile snapshot_metadata = 2;

	// This is NOT a part of the TUF Specification.
	reserved 3 to 31; // Reserved for TUF Specification changes.

	reserved 32 to 64; // Reserved for future Pigweed usage.

	reserved 65 to 255; // Reserved for project-specific usage.
	}

	// The snapshot role is used to ensure that the collection of targets_metadata
	// files is securely consistent (no target metadata mix and match). Any
	// project-specific update metadata should go in the top-level targets_metadata
	// or with the TargetFile information
	message SnapshotMetadata {
	CommonMetadata common_metadata = 1;

	// Map from Target metadata file name to MetadataFile.
	// File name can be an arbitrary name or a full file name with relative path.
	// This map should contain an entry for the top level targets role and all
	// delegated roles.
	repeated MetadataFile targets_metadata = 2;

	// This is NOT a part of the TUF Specification.
	reserved 3 to 31; // Reserved for TUF Specification changes.

	reserved 32 to 64; // Reserved for future Pigweed usage.

	reserved 65 to 255; // Reserved for project-specific usage.
	}

	// The targets role describes the target files that comprise the software
	// update. Targets metadata is organized in to a top-level targets metadata file
	// and optional multiple deligated targets metadata files
	//
	// The top-level targets metatdata is the correct place to put any
	// project-specific build version information, including build ID, hardware rev,
	// etc.
	message TargetsMetadata {
	CommonMetadata common_metadata = 1;

	// Collection of target file information
	repeated TargetFile target_files = 2;
	// Target file name can be an arbitrary name or a path that describes where
	// the file lives relative to the base directory of the repository, e.g.
	// "path/to/amber_tools/0".

	// TODO: When it is time to support delegation, add delegation information
	// here.

	// This is NOT a part of the TUF Specification.
	reserved 9 to 31; // Reserved for TUF Specification changes.

	reserved 32 to 64; // Reserved for future Pigweed usage.

	reserved 65 to 255; // Reserved for project-specific usage.
	}

	message Signature {
	// Identifier of the key, which is bytes of the SHA-256 hash of the
	// canonical form of the key.
	bytes key_id = 1;

	// The signature of the canonical form of the role's serialized metadata
	// (serialized_{root,timestamp,snapshot,targets}_metadata).
	bytes sig = 2;
	}

	message KeyMapping {
	// Identifier of the key, which is bytes of the SHA-256 hash of the
	// canonical form of the key.
	bytes key_id = 1;

	// Cryptographic key
	Key key = 2;
	}

	// Identifies an asymmetric cryptographic key.
	message Key {
	// Denotes a public key signature system, such as RSA or ECDSA.
	KeyType key_type = 1;

	// Denotes the signature scheme corresponding to the key type. For example:
	// "rsassa-pss-sha256" or "ecdsa-sha2-nistp256".
	KeyScheme scheme = 2;

	// Stores the serialized public key for this cryptographic algorithm.
	bytes keyval = 3;
	}

	// The set of cryptographic keys used by a specific role. For example, list of
	// key_ids used by the top level role "root".
	message SignatureRequirement {
	// Set of Keyid's.
	// Keyid is a unique identifier that identifies a cryptographic key.
	// E.g. "f2d5020d08aea06a0a9192eb6a4f549e17032ebefa1aa9ac167c1e3e727930d6".
	repeated bytes key_ids = 1;

	// Threshold of signatures required to trust given file.
	// In other words; the number of keys of that role whose signatures are
	// required in order to consider a file as being properly signed by that role.
	uint32 threshold = 2;
	}

	enum HashFunction {
	// Never use this in any TUF metadata.
	UNKNOWN_HASH_FUNCTION = 0;

	SHA256 = 1;
	}

	message Hash {
	HashFunction function = 1;
	// Digest of the cryptographic hash function computed on the target file.
	bytes hash = 2;
	}

	// Descriptor for a file stored in this repository. Linked to from target
	// metadata.
	message TargetFile {
	// Target file name can be an arbitrary name or a path that describes where
	// the file lives relative to the base directory of the repository, e.g.
	// "path/to/amber_tools/0".
	string file_name = 1;

	// Size of the target file (element payload) in bytes. This the size as stored
	// in the bundle. The final applied size can be different due to optional
	// compression.
	uint64 length = 2;

	// Map from algorithm name to Hash.
	// Algorithm name is the name of a cryptographic hash function. E.g. "sha256".
	// The Hash string is the hex digest of the cryptographic function computed on
	// the target file. E.g.
	// "65b8c67f51c993d898250f40aa57a317d854900b3a04895464313e48785440da".
	repeated Hash hashes = 3;

	// This is NOT a part of the TUF Specification.
	reserved 4 to 15; // Reserved for TUF Specification changes.

	reserved 16 to 31; // Reserved for future Pigweed usage.

	reserved 32 to 255; // Reserved for future project-specific usage.
	}

	message MetadataFile {
	// Target file name can be an arbitrary name or a path that describes where
	// the file lives relative to the base directory of the repository, e.g.
	// "path/to/target/0".
	optional string file_name = 1;

	// Metadata file version. E.g. 3.
	uint32 version = 2;

	// Size of the target file in bytes.
	optional uint64 length = 3;

	// Map from algorithm name to Hash.
	// Algorithm name is the name of a cryptographic hash function. E.g. "sha256".
	// The Hash is the hex digest of the cryptographic function computed on the
	// target file. E.g.
	// "65b8c67f51c993d898250f40aa57a317d854900b3a04895464313e48785440da".
	repeated Hash hashes = 4;
	}

	enum KeyType {
	// Never use this in any TUF metadata.
	UNKNOWN_KEY_TYPE = 0;

	RSA = 1;

	ED25519 = 2;

	ECDSA_SHA2_NISTP256 = 3;
	}

	enum KeyScheme {
	// Never use this in any TUF metadata.
	UNKNOWN_KEY_SCHEME = 0;

	// RSA Probabilistic signature scheme with appendix.
	// The underlying hash function is SHA256.
	// In TUF Specification, this is referred to as "rsassa-pss-sha256".
	RSASSA_PSS_SHA256_SCHEME = 1;

	// Elliptic Curve digital signature algorithm based on Twisted Edwards curves.
	// See https://ed25519.cr.yp.to/.
	// In TUF Specification, it is referred to as "ed25519".
	ED25519_SCHEME = 2;

	// Elliptic Curve Digital Signature Algorithm with NIST P-256 curve signing
	// and SHA-256 hashing. See
	// https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm In
	// TUF Specification, it is referred to as "ecdsa-sha2-nistp256".
	ECDSA_SHA2_NISTP256_SCHEME = 3;
	}