/* * Copyright (C) 2011 Colin Walters * * SPDX-License-Identifier: LGPL-2.0+ * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation; either * version 2 of the License, or (at your option) any later version. * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public * License along with this library; if not, write to the * Free Software Foundation, Inc., 59 Temple Place - Suite 330, * Boston, MA 02111-1307, USA. * * Author: Colin Walters */ #pragma once #include #include #include G_BEGIN_DECLS /** * OSTREE_MAX_METADATA_SIZE: * * Default limit for maximum permitted size in bytes of metadata objects fetched * over HTTP (including repo/config files, refs, and commit/dirtree/dirmeta * objects). This is an arbitrary number intended to mitigate disk space * exhaustion attacks. */ #define OSTREE_MAX_METADATA_SIZE (10 * 1024 * 1024) /** * OSTREE_MAX_METADATA_WARN_SIZE: * * This variable is no longer meaningful, it is kept only for compatibility. */ #define OSTREE_MAX_METADATA_WARN_SIZE (7 * 1024 * 1024) /** * OSTREE_SHA256_DIGEST_LEN: * * Length of a sha256 digest when expressed as raw bytes */ #define OSTREE_SHA256_DIGEST_LEN (32) /** * OSTREE_SHA256_STRING_LEN: * * Length of a sha256 digest when expressed as a hexadecimal string */ #define OSTREE_SHA256_STRING_LEN (64) /** * OstreeObjectType: * @OSTREE_OBJECT_TYPE_FILE: Content; regular file, symbolic link * @OSTREE_OBJECT_TYPE_DIR_TREE: List of children (trees or files), and metadata * @OSTREE_OBJECT_TYPE_DIR_META: Directory metadata * @OSTREE_OBJECT_TYPE_COMMIT: Toplevel object, refers to tree and dirmeta for root * @OSTREE_OBJECT_TYPE_TOMBSTONE_COMMIT: Toplevel object, refers to a deleted commit * @OSTREE_OBJECT_TYPE_COMMIT_META: Detached metadata for a commit * @OSTREE_OBJECT_TYPE_PAYLOAD_LINK: Symlink to a .file given its checksum on the payload only. * * Enumeration for core object types; %OSTREE_OBJECT_TYPE_FILE is for * content, the other types are metadata. */ typedef enum { OSTREE_OBJECT_TYPE_FILE = 1, /* .file */ OSTREE_OBJECT_TYPE_DIR_TREE = 2, /* .dirtree */ OSTREE_OBJECT_TYPE_DIR_META = 3, /* .dirmeta */ OSTREE_OBJECT_TYPE_COMMIT = 4, /* .commit */ OSTREE_OBJECT_TYPE_TOMBSTONE_COMMIT = 5, /* .commit-tombstone */ OSTREE_OBJECT_TYPE_COMMIT_META = 6, /* .commitmeta */ OSTREE_OBJECT_TYPE_PAYLOAD_LINK = 7, /* .payload-link */ } OstreeObjectType; /** * OSTREE_OBJECT_TYPE_IS_META: * @t: An #OstreeObjectType * * Returns: %TRUE if object type is metadata */ #define OSTREE_OBJECT_TYPE_IS_META(t) (t >= 2 && t <= 6) /** * OSTREE_OBJECT_TYPE_LAST: * * Last valid object type; use this to validate ranges. */ #define OSTREE_OBJECT_TYPE_LAST OSTREE_OBJECT_TYPE_PAYLOAD_LINK /** * OSTREE_DIRMETA_GVARIANT_FORMAT: * * - u - uid (big-endian) * - u - gid (big-endian) * - u - mode (big-endian) * - a(ayay) - xattrs */ #define OSTREE_DIRMETA_GVARIANT_STRING "(uuua(ayay))" #define OSTREE_DIRMETA_GVARIANT_FORMAT G_VARIANT_TYPE (OSTREE_DIRMETA_GVARIANT_STRING) /** * OSTREE_FILEMETA_GVARIANT_FORMAT: * * This is not a regular object type, but used as an xattr on a .file object * in bare-user repositories. This allows us to store metadata information that we * can't store in the real filesystem but we can still use a regular .file object * that we can hardlink to in the case of a user-mode checkout. * * - u - uid (big-endian) * - u - gid (big-endian) * - u - mode (big-endian) * - a(ayay) - xattrs */ #define OSTREE_FILEMETA_GVARIANT_STRING "(uuua(ayay))" #define OSTREE_FILEMETA_GVARIANT_FORMAT G_VARIANT_TYPE (OSTREE_FILEMETA_GVARIANT_STRING) /** * OSTREE_TREE_GVARIANT_FORMAT: * * - a(say) - array of (filename, checksum) for files * - a(sayay) - array of (dirname, tree_checksum, meta_checksum) for directories */ #define OSTREE_TREE_GVARIANT_STRING "(a(say)a(sayay))" #define OSTREE_TREE_GVARIANT_FORMAT G_VARIANT_TYPE (OSTREE_TREE_GVARIANT_STRING) /** * OSTREE_COMMIT_GVARIANT_FORMAT: * * - a{sv} - Metadata * - ay - parent checksum (empty string for initial) * - a(say) - Related objects * - s - subject * - s - body * - t - Timestamp in seconds since the epoch (UTC, big-endian) * - ay - Root tree contents * - ay - Root tree metadata */ #define OSTREE_COMMIT_GVARIANT_STRING "(a{sv}aya(say)sstayay)" #define OSTREE_COMMIT_GVARIANT_FORMAT G_VARIANT_TYPE (OSTREE_COMMIT_GVARIANT_STRING) /** * OSTREE_SUMMARY_GVARIANT_FORMAT: * * - a(s(taya{sv})) - Map of ref name -> (latest commit size, latest commit checksum, additional metadata), sorted by ref name * - a{sv} - Additional metadata, at the current time the following are defined: * - key: "ostree.static-deltas", value: a{sv}, static delta name -> 32 bytes of checksum * - key: "ostree.summary.last-modified", value: t, timestamp (seconds since * the Unix epoch in UTC, big-endian) when the summary was last regenerated * (similar to the HTTP `Last-Modified` header) * - key: "ostree.summary.expires", value: t, timestamp (seconds since the * Unix epoch in UTC, big-endian) after which the summary is considered * stale and should be re-downloaded if possible (similar to the HTTP * `Expires` header) * * The currently defined keys for the `a{sv}` of additional metadata for each commit are: * - key: `ostree.commit.timestamp`, value: `t`, timestamp (seconds since the * Unix epoch in UTC, big-endian) when the commit was committed */ #define OSTREE_SUMMARY_GVARIANT_STRING "(a(s(taya{sv}))a{sv})" #define OSTREE_SUMMARY_GVARIANT_FORMAT G_VARIANT_TYPE (OSTREE_SUMMARY_GVARIANT_STRING) #define OSTREE_SUMMARY_SIG_GVARIANT_STRING "a{sv}" #define OSTREE_SUMMARY_SIG_GVARIANT_FORMAT G_VARIANT_TYPE (OSTREE_SUMMARY_SIG_GVARIANT_STRING) /** * OSTREE_TIMESTAMP: * * The mtime used for stored files. This was originally 0, changed to 1 for * a few releases, then was reverted due to regressions it introduced from * users who had been using zero before. */ #define OSTREE_TIMESTAMP (0) /** * OstreeRepoMode: * @OSTREE_REPO_MODE_BARE: Files are stored as themselves; checkouts are hardlinks; can only be written as root * @OSTREE_REPO_MODE_ARCHIVE: Files are compressed, should be owned by non-root. Can be served via HTTP. Since: 2017.12 * @OSTREE_REPO_MODE_ARCHIVE_Z2: Legacy alias for `OSTREE_REPO_MODE_ARCHIVE` * @OSTREE_REPO_MODE_BARE_USER: Files are stored as themselves, except ownership; can be written by user. Hardlinks work only in user checkouts. * @OSTREE_REPO_MODE_BARE_USER_ONLY: Same as BARE_USER, but all metadata is not stored, so it can only be used for user checkouts. Does not need xattrs. * * See the documentation of #OstreeRepo for more information about the * possible modes. */ typedef enum { OSTREE_REPO_MODE_BARE, OSTREE_REPO_MODE_ARCHIVE, OSTREE_REPO_MODE_ARCHIVE_Z2 = OSTREE_REPO_MODE_ARCHIVE, OSTREE_REPO_MODE_BARE_USER, OSTREE_REPO_MODE_BARE_USER_ONLY, } OstreeRepoMode; /** * OSTREE_COMMIT_META_KEY_VERSION: * * GVariant type `s`. This metadata key is used for version numbers. A freeform * string; the intention is that systems using ostree do not interpret this * semantically as traditional package managers do. * * This is the only ostree-defined metadata key that does not start with `ostree.`. * Since: 2014.9 */ #define OSTREE_COMMIT_META_KEY_VERSION "version" /** * OSTREE_COMMIT_META_KEY_ARCHITECTURE: * * GVariant type `s`. Intended to describe the CPU architecture. This is a freeform string, and some distributions * which have existing package managers might want to match that schema. If you * don't have a prior schema, it's recommended to use `uname -m` by default (i.e. the Linux kernel schema). In the future * ostree might include a builtin function to compare architectures. * * Since: 2020.4 */ #define OSTREE_COMMIT_META_KEY_ARCHITECTURE "ostree.architecture" /** * OSTREE_COMMIT_META_KEY_ENDOFLIFE_REBASE: * * GVariant type `s`. Should contain a refspec defining a new target branch; * `ostree admin upgrade` and `OstreeSysrootUpgrader` will automatically initiate * a rebase upon encountering this metadata key. * * Since: 2017.7 */ #define OSTREE_COMMIT_META_KEY_ENDOFLIFE_REBASE "ostree.endoflife-rebase" /** * OSTREE_COMMIT_META_KEY_ENDOFLIFE: * * GVariant type `s`. This metadata key is used to display vendor's message * when an update stream for a particular branch ends. It usually provides * update instructions for the users. * * Since: 2017.7 */ #define OSTREE_COMMIT_META_KEY_ENDOFLIFE "ostree.endoflife" /** * OSTREE_COMMIT_META_KEY_SOURCE_TITLE: * * GVariant type `s`. This should hold a relatively short single line value * containing a human-readable "source" for a commit, intended to be displayed * near the origin ref. This is particularly useful for systems that inject * content into an OSTree commit from elsewhere - for example, generating from * an OCI or qcow2 image. Or if generating from packages, the enabled repository * names and their versions. * * Try to keep this key short (e.g. < 80 characters) and human-readable; if you * desire machine readable data, consider injecting separate metadata keys. * * Since: 2017.13 */ #define OSTREE_COMMIT_META_KEY_SOURCE_TITLE "ostree.source-title" /** * OSTREE_COMMIT_META_KEY_REF_BINDING: * * GVariant type `as`; each element is a branch name. If this is added to a * commit, `ostree_repo_pull()` will enforce that the commit was retrieved from * one of the branch names in this array. This prevents "sidegrade" attacks. * The rationale for having this support multiple branch names is that it helps * support a "promotion" model of taking a commit and moving it between development * and production branches. * * Since: 2017.9 */ #define OSTREE_COMMIT_META_KEY_REF_BINDING "ostree.ref-binding" /** * OSTREE_COMMIT_META_KEY_COLLECTION_BINDING: * * GVariant type `s`. If this is added to a commit, `ostree_repo_pull()` * will enforce that the commit was retrieved from a repository which has * the same collection ID. See `ostree_repo_set_collection_id()`. * This is most useful in concert with `OSTREE_COMMIT_META_KEY_REF_BINDING`, * as it more strongly binds the commit to the repository and branch. * * Since: 2018.6 */ #define OSTREE_COMMIT_META_KEY_COLLECTION_BINDING "ostree.collection-binding" _OSTREE_PUBLIC const GVariantType *ostree_metadata_variant_type (OstreeObjectType objtype); _OSTREE_PUBLIC gboolean ostree_validate_checksum_string (const char *sha256, GError **error); _OSTREE_PUBLIC guchar *ostree_checksum_to_bytes (const char *checksum); _OSTREE_PUBLIC GVariant *ostree_checksum_to_bytes_v (const char *checksum); _OSTREE_PUBLIC guchar *ostree_checksum_b64_to_bytes (const char *checksum); _OSTREE_PUBLIC void ostree_checksum_b64_inplace_to_bytes (const char *checksum, guint8 *buf); _OSTREE_PUBLIC char * ostree_checksum_from_bytes (const guchar *csum); _OSTREE_PUBLIC char * ostree_checksum_from_bytes_v (GVariant *csum_v); _OSTREE_PUBLIC char * ostree_checksum_b64_from_bytes (const guchar *csum); _OSTREE_PUBLIC void ostree_checksum_inplace_from_bytes (const guchar *csum, char *buf); _OSTREE_PUBLIC void ostree_checksum_b64_inplace_from_bytes (const guchar *csum, char *buf); _OSTREE_PUBLIC void ostree_checksum_inplace_to_bytes (const char *checksum, guchar *buf); _OSTREE_PUBLIC const guchar *ostree_checksum_bytes_peek (GVariant *bytes); _OSTREE_PUBLIC const guchar *ostree_checksum_bytes_peek_validate (GVariant *bytes, GError **error); _OSTREE_PUBLIC int ostree_cmp_checksum_bytes (const guchar *a, const guchar *b); _OSTREE_PUBLIC gboolean ostree_validate_rev (const char *rev, GError **error); _OSTREE_PUBLIC gboolean ostree_validate_collection_id (const char *collection_id, GError **error); _OSTREE_PUBLIC gboolean ostree_validate_remote_name (const char *remote_name, GError **error); _OSTREE_PUBLIC gboolean ostree_parse_refspec (const char *refspec, char **out_remote, char **out_ref, GError **error); _OSTREE_PUBLIC const char * ostree_object_type_to_string (OstreeObjectType objtype); _OSTREE_PUBLIC OstreeObjectType ostree_object_type_from_string (const char *str); _OSTREE_PUBLIC guint ostree_hash_object_name (gconstpointer a); _OSTREE_PUBLIC GVariant *ostree_object_name_serialize (const char *checksum, OstreeObjectType objtype); _OSTREE_PUBLIC void ostree_object_name_deserialize (GVariant *variant, const char **out_checksum, OstreeObjectType *out_objtype); _OSTREE_PUBLIC char * ostree_object_to_string (const char *checksum, OstreeObjectType objtype); _OSTREE_PUBLIC void ostree_object_from_string (const char *str, gchar **out_checksum, OstreeObjectType *out_objtype); _OSTREE_PUBLIC gboolean ostree_content_stream_parse (gboolean compressed, GInputStream *input, guint64 input_length, gboolean trusted, GInputStream **out_input, GFileInfo **out_file_info, GVariant **out_xattrs, GCancellable *cancellable, GError **error); _OSTREE_PUBLIC gboolean ostree_content_file_parse (gboolean compressed, GFile *content_path, gboolean trusted, GInputStream **out_input, GFileInfo **out_file_info, GVariant **out_xattrs, GCancellable *cancellable, GError **error); _OSTREE_PUBLIC gboolean ostree_content_file_parse_at (gboolean compressed, int parent_dfd, const char *path, gboolean trusted, GInputStream **out_input, GFileInfo **out_file_info, GVariant **out_xattrs, GCancellable *cancellable, GError **error); _OSTREE_PUBLIC gboolean ostree_raw_file_to_archive_z2_stream (GInputStream *input, GFileInfo *file_info, GVariant *xattrs, GInputStream **out_input, GCancellable *cancellable, GError **error); _OSTREE_PUBLIC gboolean ostree_raw_file_to_archive_z2_stream_with_options (GInputStream *input, GFileInfo *file_info, GVariant *xattrs, GVariant *options, GInputStream **out_input, GCancellable *cancellable, GError **error); _OSTREE_PUBLIC gboolean ostree_raw_file_to_content_stream (GInputStream *input, GFileInfo *file_info, GVariant *xattrs, GInputStream **out_input, guint64 *out_length, GCancellable *cancellable, GError **error); _OSTREE_PUBLIC gboolean ostree_checksum_file_from_input (GFileInfo *file_info, GVariant *xattrs, GInputStream *in, OstreeObjectType objtype, guchar **out_csum, GCancellable *cancellable, GError **error); _OSTREE_PUBLIC gboolean ostree_checksum_file (GFile *f, OstreeObjectType objtype, guchar **out_csum, GCancellable *cancellable, GError **error); _OSTREE_PUBLIC gboolean ostree_break_hardlink (int dfd, const char *path, gboolean skip_xattrs, GCancellable *cancellable, GError **error); /** * OstreeChecksumFlags: * @OSTREE_CHECKSUM_FLAGS_NONE: Default checksumming without tweaks. * (Since: 2017.13.) * @OSTREE_CHECKSUM_FLAGS_IGNORE_XATTRS: Ignore xattrs when checksumming. * (Since: 2017.13.) * @OSTREE_CHECKSUM_FLAGS_CANONICAL_PERMISSIONS: Use canonical uid/gid/mode * values, for bare-user-only mode. (Since: 2021.4.) * * Flags influencing checksumming logic. * * Since: 2017.13 */ typedef enum { OSTREE_CHECKSUM_FLAGS_NONE = 0, OSTREE_CHECKSUM_FLAGS_IGNORE_XATTRS = (1 << 0), OSTREE_CHECKSUM_FLAGS_CANONICAL_PERMISSIONS = (1 << 1), } OstreeChecksumFlags; _OSTREE_PUBLIC gboolean ostree_checksum_file_at (int dfd, const char *path, struct stat *stbuf, OstreeObjectType objtype, OstreeChecksumFlags flags, char **out_checksum, GCancellable *cancellable, GError **error); _OSTREE_PUBLIC void ostree_checksum_file_async (GFile *f, OstreeObjectType objtype, int io_priority, GCancellable *cancellable, GAsyncReadyCallback callback, gpointer user_data); _OSTREE_PUBLIC gboolean ostree_checksum_file_async_finish (GFile *f, GAsyncResult *result, guchar **out_csum, GError **error); _OSTREE_PUBLIC GVariant *ostree_create_directory_metadata (GFileInfo *dir_info, GVariant *xattrs); /* VALIDATION */ _OSTREE_PUBLIC gboolean ostree_validate_structureof_objtype (guchar objtype, GError **error); _OSTREE_PUBLIC gboolean ostree_validate_structureof_csum_v (GVariant *checksum, GError **error); _OSTREE_PUBLIC gboolean ostree_validate_structureof_checksum_string (const char *checksum, GError **error); _OSTREE_PUBLIC gboolean ostree_validate_structureof_file_mode (guint32 mode, GError **error); _OSTREE_PUBLIC gboolean ostree_validate_structureof_commit (GVariant *commit, GError **error); _OSTREE_PUBLIC gboolean ostree_validate_structureof_dirtree (GVariant *dirtree, GError **error); _OSTREE_PUBLIC gboolean ostree_validate_structureof_dirmeta (GVariant *dirmeta, GError **error); _OSTREE_PUBLIC gchar * ostree_commit_get_parent (GVariant *commit_variant); _OSTREE_PUBLIC guint64 ostree_commit_get_timestamp (GVariant *commit_variant); _OSTREE_PUBLIC gchar * ostree_commit_get_content_checksum (GVariant *commit_variant); /** * OstreeCommitSizesEntry: * @checksum: (not nullable): object checksum * @objtype: object type * @unpacked: unpacked object size * @archived: compressed object size * * Structure representing an entry in the "ostree.sizes" commit metadata. Each * entry corresponds to an object in the associated commit. * * Since: 2020.1 */ typedef struct { gchar *checksum; OstreeObjectType objtype; guint64 unpacked; guint64 archived; } OstreeCommitSizesEntry; _OSTREE_PUBLIC GType ostree_commit_sizes_entry_get_type (void); _OSTREE_PUBLIC OstreeCommitSizesEntry *ostree_commit_sizes_entry_new (const gchar *checksum, OstreeObjectType objtype, guint64 unpacked, guint64 archived); _OSTREE_PUBLIC OstreeCommitSizesEntry *ostree_commit_sizes_entry_copy (const OstreeCommitSizesEntry *entry); _OSTREE_PUBLIC void ostree_commit_sizes_entry_free (OstreeCommitSizesEntry *entry); _OSTREE_PUBLIC gboolean ostree_commit_get_object_sizes (GVariant *commit_variant, GPtrArray **out_sizes_entries, GError **error); _OSTREE_PUBLIC gboolean ostree_check_version (guint required_year, guint required_release); G_END_DECLS