packaging
/
ostree
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

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 2019-11-10 16:51:23 +03:00
parent e9b1ebfc11
commit 908a2cd760
3 changed files with 298 additions and 88 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
apidoc/ostree-docs.xml
View File

@ -21,6 +21,7 @@
<xi:include href="xml/ostree-sepolicy.xml"/> <xi:include href="xml/ostree-sepolicy.xml"/>
<xi:include href="xml/ostree-sysroot-upgrader.xml"/> <xi:include href="xml/ostree-sysroot-upgrader.xml"/>
<xi:include href="xml/ostree-gpg-verify-result.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-bootconfig-parser.xml"/>
<xi:include href="xml/ostree-chain-input-stream.xml"/> <xi:include href="xml/ostree-chain-input-stream.xml"/>
<xi:include href="xml/ostree-checksum-input-stream.xml"/> <xi:include href="xml/ostree-checksum-input-stream.xml"/>

355
src/libostree/ostree-sign.c
View File

@ -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 "config.h"
#include <unistd.h> #include <unistd.h>
@ -71,7 +80,20 @@ ostree_sign_default_init (OstreeSignInterface *iface)
g_debug ("OstreeSign initialization"); 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__); 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); 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__); 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); 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__); 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); return OSTREE_SIGN_GET_IFACE (self)->clear_keys (self, error);
} }
gboolean ostree_sign_set_sk (OstreeSign *self, /**
GVariant *secret_key, * ostree_sign_set_sk:
GError **error) * @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__); 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); return OSTREE_SIGN_GET_IFACE (self)->set_sk (self, secret_key, error);
} }
gboolean ostree_sign_set_pk (OstreeSign *self, /**
GVariant *public_key, * ostree_sign_set_pk:
GError **error) * @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__); 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); return OSTREE_SIGN_GET_IFACE (self)->set_pk (self, public_key, error);
} }
gboolean ostree_sign_add_pk (OstreeSign *self, /**
GVariant *public_key, * ostree_sign_add_pk:
GError **error) * @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__); 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); 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 gboolean
ostree_sign_load_pk (OstreeSign *self, ostree_sign_load_pk (OstreeSign *self,
GVariant *options, GVariant *options,
@ -150,11 +271,30 @@ ostree_sign_load_pk (OstreeSign *self,
return OSTREE_SIGN_GET_IFACE (self)->load_pk (self, options, error); return OSTREE_SIGN_GET_IFACE (self)->load_pk (self, options, error);
} }
gboolean ostree_sign_data (OstreeSign *self, /**
GBytes *data, * ostree_sign_data:
GBytes **signature, * @self: an #OstreeSign object
GCancellable *cancellable, * @data: the raw data to be signed with pre-loaded secret key
GError **error) * @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__); 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); 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 gboolean
ostree_sign_data_verify (OstreeSign *self, ostree_sign_data_verify (OstreeSign *self,
GBytes *data, GBytes *data,
GVariant *signatures, GVariant *signatures,
GError **error) GError **error)
{ {
g_debug ("%s enter", __FUNCTION__); g_debug ("%s enter", __FUNCTION__);
g_return_val_if_fail (OSTREE_IS_SIGN (self), FALSE); 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); 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 gboolean
ostree_sign_commit_verify (OstreeSign *self, ostree_sign_commit_verify (OstreeSign *self,
OstreeRepo *repo, OstreeRepo *repo,
@ -254,60 +431,51 @@ ostree_sign_commit_verify (OstreeSign *self,
return ostree_sign_data_verify (self, return ostree_sign_data_verify (self,
signed_data, signed_data,
signatures, signatures,
error); 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_debug ("%s enter", __FUNCTION__);
g_return_val_if_fail (OSTREE_IS_SIGN (self), FALSE); g_return_val_if_fail (OSTREE_IS_SIGN (self), NULL);
g_return_val_if_fail (OSTREE_SIGN_GET_IFACE (self)->get_name != NULL, FALSE); g_return_val_if_fail (OSTREE_SIGN_GET_IFACE (self)->get_name != NULL, NULL);
return OSTREE_SIGN_GET_IFACE (self)->get_name (self); 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: * ostree_sign_commit:
* @self: Self * @self: an #OstreeSign object
* @repo: an #OsreeRepo object
* @commit_checksum: SHA256 of given commit to sign * @commit_checksum: SHA256 of given commit to sign
* @cancellable: A #GCancellable * @cancellable: A #GCancellable
* @error: a #GError * @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 gboolean
ostree_sign_commit (OstreeSign *self, ostree_sign_commit (OstreeSign *self,
@ -354,7 +522,17 @@ ostree_sign_commit (OstreeSign *self,
return TRUE; 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__); 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++) for (i=0; i < G_N_ELEMENTS(sign_types); i++)
{ {
names[i] = g_strdup(sign_types[i].name); 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; 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;
}

30
src/libostree/ostree-sign.h
View File

@ -55,7 +55,7 @@ struct _OstreeSignInterface
GError **error); GError **error);
gboolean (* data_verify) (OstreeSign *self, gboolean (* data_verify) (OstreeSign *self,
GBytes *data, GBytes *data,
GVariant *metadata, GVariant *signatures,
GError **error); GError **error);
const gchar *(* metadata_key) (OstreeSign *self); const gchar *(* metadata_key) (OstreeSign *self);
const gchar *(* metadata_format) (OstreeSign *self); const gchar *(* metadata_format) (OstreeSign *self);
@ -80,16 +80,16 @@ const gchar * ostree_sign_get_name (OstreeSign *self);
_OSTREE_PUBLIC _OSTREE_PUBLIC
gboolean ostree_sign_data (OstreeSign *self, gboolean ostree_sign_data (OstreeSign *self,
GBytes *data, GBytes *data,
GBytes **signature, GBytes **signature,
GCancellable *cancellable, GCancellable *cancellable,
GError **error); GError **error);
_OSTREE_PUBLIC _OSTREE_PUBLIC
gboolean ostree_sign_data_verify (OstreeSign *self, gboolean ostree_sign_data_verify (OstreeSign *self,
GBytes *data, GBytes *data,
GVariant *signatures, GVariant *signatures,
GError **error); GError **error);
_OSTREE_PUBLIC _OSTREE_PUBLIC
const gchar * ostree_sign_metadata_key (OstreeSign *self); const gchar * ostree_sign_metadata_key (OstreeSign *self);
@ -136,23 +136,9 @@ gboolean ostree_sign_load_pk (OstreeSign *self,
GError **error); 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 _OSTREE_PUBLIC
GStrv ostree_sign_list_names(void); 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 _OSTREE_PUBLIC
OstreeSign * ostree_sign_get_by_name (const gchar *name, GError **error); OstreeSign * ostree_sign_get_by_name (const gchar *name, GError **error);