From 908a2cd7601491195db6c4e6151a601b002c25e0 Mon Sep 17 00:00:00 2001 From: Denis Pynkin Date: Sun, 10 Nov 2019 16:51:23 +0300 Subject: [PATCH] apidoc: add API documentation for signing interface Add the documentation for all public functions. Signed-off-by: Denis Pynkin --- apidoc/ostree-docs.xml | 1 + src/libostree/ostree-sign.c | 355 +++++++++++++++++++++++++++++------- src/libostree/ostree-sign.h | 30 +-- 3 files changed, 298 insertions(+), 88 deletions(-) diff --git a/apidoc/ostree-docs.xml b/apidoc/ostree-docs.xml index 8721ffa8..1ad0de37 100644 --- a/apidoc/ostree-docs.xml +++ b/apidoc/ostree-docs.xml @@ -21,6 +21,7 @@ + diff --git a/src/libostree/ostree-sign.c b/src/libostree/ostree-sign.c index e5d55ef2..95319f67 100644 --- a/src/libostree/ostree-sign.c +++ b/src/libostree/ostree-sign.c @@ -22,6 +22,15 @@ * */ +/** + * SECTION:ostree-sign + * @title: Signature management + * @short_description: Sign and verify commits + * + * An #OstreeSign interface allows to select and use any available engine + * for signing or verifying the commit object or summary file. + */ + #include "config.h" #include @@ -71,7 +80,20 @@ ostree_sign_default_init (OstreeSignInterface *iface) g_debug ("OstreeSign initialization"); } -const gchar * ostree_sign_metadata_key (OstreeSign *self) +/** + * ostree_sign_metadata_key: + * @self: an #OstreeSign object + * + * Return the pointer to the name of the key used in (detached) metadata for + * current signing engine. + * + * Returns: (transfer none): pointer to the metadata key name, + * @NULL in case of error (unlikely). + * + * Since: 2020.2 + */ +const gchar * +ostree_sign_metadata_key (OstreeSign *self) { g_debug ("%s enter", __FUNCTION__); @@ -79,7 +101,20 @@ const gchar * ostree_sign_metadata_key (OstreeSign *self) return OSTREE_SIGN_GET_IFACE (self)->metadata_key (self); } -const gchar * ostree_sign_metadata_format (OstreeSign *self) +/** + * ostree_sign_metadata_format: + * @self: an #OstreeSign object + * + * Return the pointer to the string with format used in (detached) metadata for + * current signing engine. + * + * Returns: (transfer none): pointer to the metadata format, + * @NULL in case of error (unlikely). + * + * Since: 2020.2 + */ +const gchar * +ostree_sign_metadata_format (OstreeSign *self) { g_debug ("%s enter", __FUNCTION__); @@ -87,8 +122,20 @@ const gchar * ostree_sign_metadata_format (OstreeSign *self) return OSTREE_SIGN_GET_IFACE (self)->metadata_format (self); } -gboolean ostree_sign_clear_keys (OstreeSign *self, - GError **error) +/** + * ostree_sign_clear_keys: + * @self: an #OstreeSign object + * @error: a #GError + * + * Clear all previously preloaded secret and public keys. + * + * Returns: @TRUE in case if no errors, @FALSE in case of error + * + * Since: 2020.2 + */ +gboolean +ostree_sign_clear_keys (OstreeSign *self, + GError **error) { g_debug ("%s enter", __FUNCTION__); @@ -98,9 +145,25 @@ gboolean ostree_sign_clear_keys (OstreeSign *self, return OSTREE_SIGN_GET_IFACE (self)->clear_keys (self, error); } -gboolean ostree_sign_set_sk (OstreeSign *self, - GVariant *secret_key, - GError **error) +/** + * ostree_sign_set_sk: + * @self: an #OstreeSign object + * @secret_key: secret key to be added + * @error: a #GError + * + * Set the secret key to be used for signing data, commits and summary. + * + * The @secret_key argument depends of the particular engine implementation. + * + * Returns: @TRUE in case if the key could be set successfully, + * @FALSE in case of error (@error will contain the reason). + * + * Since: 2020.2 + */ +gboolean +ostree_sign_set_sk (OstreeSign *self, + GVariant *secret_key, + GError **error) { g_debug ("%s enter", __FUNCTION__); @@ -110,9 +173,26 @@ gboolean ostree_sign_set_sk (OstreeSign *self, return OSTREE_SIGN_GET_IFACE (self)->set_sk (self, secret_key, error); } -gboolean ostree_sign_set_pk (OstreeSign *self, - GVariant *public_key, - GError **error) +/** + * ostree_sign_set_pk: + * @self: an #OstreeSign object + * @public_key: single public key to be added + * @error: a #GError + * + * Set the public key for verification. It is expected what all + * previously pre-loaded public keys will be dropped. + * + * The @public_key argument depends of the particular engine implementation. + * + * Returns: @TRUE in case if the key could be set successfully, + * @FALSE in case of error (@error will contain the reason). + * + * Since: 2020.2 + */ +gboolean +ostree_sign_set_pk (OstreeSign *self, + GVariant *public_key, + GError **error) { g_debug ("%s enter", __FUNCTION__); @@ -122,9 +202,26 @@ gboolean ostree_sign_set_pk (OstreeSign *self, return OSTREE_SIGN_GET_IFACE (self)->set_pk (self, public_key, error); } -gboolean ostree_sign_add_pk (OstreeSign *self, - GVariant *public_key, - GError **error) +/** + * ostree_sign_add_pk: + * @self: an #OstreeSign object + * @public_key: single public key to be added + * @error: a #GError + * + * Add the public key for verification. Could be called multiple times for + * adding all needed keys to be used for verification. + * + * The @public_key argument depends of the particular engine implementation. + * + * Returns: @TRUE in case if the key could be added successfully, + * @FALSE in case of error (@error will contain the reason). + * + * Since: 2020.2 + */ +gboolean +ostree_sign_add_pk (OstreeSign *self, + GVariant *public_key, + GError **error) { g_debug ("%s enter", __FUNCTION__); @@ -134,9 +231,33 @@ gboolean ostree_sign_add_pk (OstreeSign *self, return OSTREE_SIGN_GET_IFACE (self)->add_pk (self, public_key, error); } -/* Load private keys for verification from anywhere. - * No need to have the same function for secret keys -- the signing SW must do it in it's own way - * */ +/** + * ostree_sign_load_pk: + * @self: an #OstreeSign object + * @options: any options + * @error: a #GError + * + * Load public keys for verification from anywhere. + * It is expected that all keys would be added to already pre-loaded keys. + * + * The @options argument depends of the particular engine implementation. + * + * For example, @ed25515 engine could use following string-formatted options: + * - @filename -- single file to use to load keys from + * - @basedir -- directory containing subdirectories + * 'trusted.ed25519.d' and 'revoked.ed25519.d' with appropriate + * public keys. Used for testing and re-definition of system-wide + * directories if defaults are not suitable for any reason. + * + * Returns: @TRUE in case if at least one key could be load successfully, + * @FALSE in case of error (@error will contain the reason). + * + * Since: 2020.2 + */ +/* + * No need to have similar function for secret keys load -- it is expected + * what the signing software will load the secret key in it's own way. + */ gboolean ostree_sign_load_pk (OstreeSign *self, GVariant *options, @@ -150,11 +271,30 @@ ostree_sign_load_pk (OstreeSign *self, return OSTREE_SIGN_GET_IFACE (self)->load_pk (self, options, error); } -gboolean ostree_sign_data (OstreeSign *self, - GBytes *data, - GBytes **signature, - GCancellable *cancellable, - GError **error) +/** + * ostree_sign_data: + * @self: an #OstreeSign object + * @data: the raw data to be signed with pre-loaded secret key + * @signature: in case of success will contain signature + * @cancellable: A #GCancellable + * @error: a #GError + * + * Sign the given @data with pre-loaded secret key. + * + * Depending of the signing engine used you will need to load + * the secret key with #ostree_sign_set_sk. + * + * Returns: @TRUE if @data has been signed successfully, + * @FALSE in case of error (@error will contain the reason). + * + * Since: 2020.2 + */ +gboolean +ostree_sign_data (OstreeSign *self, + GBytes *data, + GBytes **signature, + GCancellable *cancellable, + GError **error) { g_debug ("%s enter", __FUNCTION__); @@ -164,11 +304,29 @@ gboolean ostree_sign_data (OstreeSign *self, return OSTREE_SIGN_GET_IFACE (self)->data (self, data, signature, cancellable, error); } +/** + * ostree_sign_data_verify: + * @self: an #OstreeSign object + * @data: the raw data to check + * @signatures: the signatures to be checked + * @error: a #GError + * + * Verify given data against signatures with pre-loaded public keys. + * + * Depending of the signing engine used you will need to load + * the public key(s) with #ostree_sign_set_pk, #ostree_sign_add_pk + * or #ostree_sign_load_pk. + * + * Returns: @TRUE if @data has been signed at least with any single valid key, + * @FALSE in case of error or no valid keys are available (@error will contain the reason). + * + * Since: 2020.2 + */ gboolean ostree_sign_data_verify (OstreeSign *self, - GBytes *data, - GVariant *signatures, - GError **error) + GBytes *data, + GVariant *signatures, + GError **error) { g_debug ("%s enter", __FUNCTION__); g_return_val_if_fail (OSTREE_IS_SIGN (self), FALSE); @@ -213,6 +371,25 @@ _sign_detached_metadata_append (OstreeSign *self, return g_variant_dict_end (&metadata_dict); } +/** + * ostree_sign_commit_verify: + * @self: an #OstreeSign object + * @repo: an #OsreeRepo object + * @commit_checksum: SHA256 of given commit to verify + * @cancellable: A #GCancellable + * @error: a #GError + * + * Verify if commit is signed with known key. + * + * Depending of the signing engine used you will need to load + * the public key(s) for verification with #ostree_sign_set_pk, + * #ostree_sign_add_pk and/or #ostree_sign_load_pk. + * + * Returns: @TRUE if commit has been verified successfully, + * @FALSE in case of error or no valid keys are available (@error will contain the reason). + * + * Since: 2020.2 + */ gboolean ostree_sign_commit_verify (OstreeSign *self, OstreeRepo *repo, @@ -254,60 +431,51 @@ ostree_sign_commit_verify (OstreeSign *self, return ostree_sign_data_verify (self, - signed_data, - signatures, - error); + signed_data, + signatures, + error); } -const gchar * ostree_sign_get_name (OstreeSign *self) +/** + * ostree_sign_get_name: + * @self: an #OstreeSign object + * + * Return the pointer to the name of currently used/selected signing engine. + * + * The list of available engines could be acquired with #ostree_sign_list_names. + * + * Returns: (transfer none): pointer to the name + * @NULL in case of error (unlikely). + * + * Since: 2020.2 + */ +const gchar * +ostree_sign_get_name (OstreeSign *self) { g_debug ("%s enter", __FUNCTION__); - g_return_val_if_fail (OSTREE_IS_SIGN (self), FALSE); - g_return_val_if_fail (OSTREE_SIGN_GET_IFACE (self)->get_name != NULL, FALSE); + g_return_val_if_fail (OSTREE_IS_SIGN (self), NULL); + g_return_val_if_fail (OSTREE_SIGN_GET_IFACE (self)->get_name != NULL, NULL); return OSTREE_SIGN_GET_IFACE (self)->get_name (self); } -OstreeSign * ostree_sign_get_by_name (const gchar *name, GError **error) -{ - g_debug ("%s enter", __FUNCTION__); - - OstreeSign *sign = NULL; - - /* Get types if not initialized yet */ -#if defined(HAVE_LIBSODIUM) - if (sign_types[SIGN_ED25519].type == 0) - sign_types[SIGN_ED25519].type = OSTREE_TYPE_SIGN_ED25519; -#endif - if (sign_types[SIGN_DUMMY].type == 0) - sign_types[SIGN_DUMMY].type = OSTREE_TYPE_SIGN_DUMMY; - - for (gint i=0; i < G_N_ELEMENTS(sign_types); i++) - { - if (g_strcmp0 (name, sign_types[i].name) == 0) - { - g_debug ("Found '%s' signing module", sign_types[i].name); - sign = g_object_new (sign_types[i].type, NULL); - break; - } - } - - if (sign == NULL) - g_set_error_literal (error, G_IO_ERROR, G_IO_ERROR_FAILED, - "Requested signature type is not implemented"); - - return sign; -} - - /** * ostree_sign_commit: - * @self: Self + * @self: an #OstreeSign object + * @repo: an #OsreeRepo object * @commit_checksum: SHA256 of given commit to sign * @cancellable: A #GCancellable * @error: a #GError * - * Add a GPG signature to a commit. + * Add a signature to a commit. + * + * Depending of the signing engine used you will need to load + * the secret key with #ostree_sign_set_sk. + * + * Returns: @TRUE if commit has been signed successfully, + * @FALSE in case of error (@error will contain the reason). + * + * Since: 2020.2 */ gboolean ostree_sign_commit (OstreeSign *self, @@ -354,7 +522,17 @@ ostree_sign_commit (OstreeSign *self, return TRUE; } -GStrv ostree_sign_list_names(void) +/** + * ostree_sign_list_names: + * + * Return an array with all available sign engines names. + * + * Returns: (transfer full): an array of strings, free when you used it + * + * Since: 2020.2 + */ +GStrv +ostree_sign_list_names(void) { g_debug ("%s enter", __FUNCTION__); @@ -364,8 +542,53 @@ GStrv ostree_sign_list_names(void) for (i=0; i < G_N_ELEMENTS(sign_types); i++) { names[i] = g_strdup(sign_types[i].name); - g_debug ("Found '%s' signing module", names[i]); + g_debug ("Found '%s' signing engine", names[i]); } return names; } + +/** + * ostree_sign_get_by_name: + * @name: the name of desired signature engine + * @error: return location for a #GError + * + * Tries to find and return proper signing engine by it's name. + * + * The list of available engines could be acquired with #ostree_sign_list_names. + * + * Returns: (transfer full): a constant, free when you used it + * + * Since: 2020.2 + */ +OstreeSign * +ostree_sign_get_by_name (const gchar *name, GError **error) +{ + g_debug ("%s enter", __FUNCTION__); + + OstreeSign *sign = NULL; + + /* Get types if not initialized yet */ +#if defined(HAVE_LIBSODIUM) + if (sign_types[SIGN_ED25519].type == 0) + sign_types[SIGN_ED25519].type = OSTREE_TYPE_SIGN_ED25519; +#endif + if (sign_types[SIGN_DUMMY].type == 0) + sign_types[SIGN_DUMMY].type = OSTREE_TYPE_SIGN_DUMMY; + + for (gint i=0; i < G_N_ELEMENTS(sign_types); i++) + { + if (g_strcmp0 (name, sign_types[i].name) == 0) + { + g_debug ("Using '%s' signing engine", sign_types[i].name); + sign = g_object_new (sign_types[i].type, NULL); + break; + } + } + + if (sign == NULL) + g_set_error_literal (error, G_IO_ERROR, G_IO_ERROR_FAILED, + "Requested signature type is not implemented"); + + return sign; +} diff --git a/src/libostree/ostree-sign.h b/src/libostree/ostree-sign.h index 9add0450..87ed25ce 100644 --- a/src/libostree/ostree-sign.h +++ b/src/libostree/ostree-sign.h @@ -55,7 +55,7 @@ struct _OstreeSignInterface GError **error); gboolean (* data_verify) (OstreeSign *self, GBytes *data, - GVariant *metadata, + GVariant *signatures, GError **error); const gchar *(* metadata_key) (OstreeSign *self); const gchar *(* metadata_format) (OstreeSign *self); @@ -80,16 +80,16 @@ const gchar * ostree_sign_get_name (OstreeSign *self); _OSTREE_PUBLIC gboolean ostree_sign_data (OstreeSign *self, - GBytes *data, - GBytes **signature, - GCancellable *cancellable, - GError **error); + GBytes *data, + GBytes **signature, + GCancellable *cancellable, + GError **error); _OSTREE_PUBLIC gboolean ostree_sign_data_verify (OstreeSign *self, - GBytes *data, - GVariant *signatures, - GError **error); + GBytes *data, + GVariant *signatures, + GError **error); _OSTREE_PUBLIC const gchar * ostree_sign_metadata_key (OstreeSign *self); @@ -136,23 +136,9 @@ gboolean ostree_sign_load_pk (OstreeSign *self, GError **error); -/** - * ostree_sign_list_names: - * - * Return the array with all available sign modules names. - * - * Returns: (transfer full): an array of strings, free when you used it - */ _OSTREE_PUBLIC GStrv ostree_sign_list_names(void); -/** - * ostree_sign_get_by_name: - * - * Tries to find and return proper signing engine by it's name. - * - * Returns: (transfer full): a constant, free when you used it - */ _OSTREE_PUBLIC OstreeSign * ostree_sign_get_by_name (const gchar *name, GError **error);