path: root/src/libostree/ostree-core.h

/*
 * Copyright (C) 2011 Colin Walters <walters@verbum.org>
 *
 * 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 <walters@verbum.org>
 */

#pragma once

#include <sys/stat.h>
#include <gio/gio.h>
#include <ostree-types.h>

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