blob: 74cfe3be48c2c5a792ba4f47a390e44604c4ef2b [file] [log] [blame]
// 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;
}