mirror of
https://github.com/ostreedev/ostree.git
synced 2024-12-22 17:35:55 +03:00
apidoc: add API documentation for signing interface
Add the documentation for all public functions. Signed-off-by: Denis Pynkin <denis.pynkin@collabora.com>
This commit is contained in:
Denis Pynkin
parent
e9b1ebfc11
commit
908a2cd760
@ -21,6 +21,7 @@
|
||||
<xi:include href="xml/ostree-sepolicy.xml"/>
|
||||
<xi:include href="xml/ostree-sysroot-upgrader.xml"/>
|
||||
<xi:include href="xml/ostree-gpg-verify-result.xml"/>
|
||||
<xi:include href="xml/ostree-sign.xml"/>
|
||||
<xi:include href="xml/ostree-bootconfig-parser.xml"/>
|
||||
<xi:include href="xml/ostree-chain-input-stream.xml"/>
|
||||
<xi:include href="xml/ostree-checksum-input-stream.xml"/>
|
||||
|
||||
@ -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 <unistd.h>
|
||||
@ -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;
|
||||
}
|
||||
|
||||
@ -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);
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user