signed_video_signing_plugin.h

/**
 * MIT License
 *
 * Copyright (c) 2021 Axis Communications AB
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
 * associated documentation files (the "Software"), to deal in the Software without restriction,
 * including without limitation the rights to use, copy, modify, merge, publish, distribute,
 * sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice (including the next paragraph) shall be
 * included in all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT
 * NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
 * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 */

#ifndef __SIGNED_VIDEO_SIGNING_PLUGIN_H__
#define __SIGNED_VIDEO_SIGNING_PLUGIN_H__

#include <stdbool.h>  // bool
#include <stdint.h>  // uint8_t
#include <string.h>  // size_t

#include "signed_video_common.h"  // SignedVideoReturnCode

#ifdef __cplusplus
extern "C" {
#endif

/**
 * Cryptography library calling interface APIs are declared here.
 */

/**
 * @brief Signs a hash with a private key
 *
 * This function takes |hash| data and adds it for signing using the |private_key|
 * provided through sv_signing_plugin_session_setup(). The Signed Video library will
 * call this function when signing a hash.
 *
 * @param handle    A pointer to the handle for the plugin, generated by
 *                  sv_signing_plugin_session_setup().
 * @param hash      A pointer to the hash data to be signed.
 * @param hash_size The size of the |hash| to be signed.
 *
 * @returns SV_OK upon success and an adequate value upon failure.
 */
SignedVideoReturnCode
sv_signing_plugin_sign(void *handle, const uint8_t *hash, size_t hash_size);

/**
 * @brief Gets the signature
 *
 * This function writes the, by the private key, signed hash to |signature| if a new signature
 * is available, and returns True if the output has been updated. It is called by the Signed Video
 * library repeatedly to collect all available signatures.
 *
 * @param handle A pointer to the handle for the plugin, generated by
 *   sv_signing_plugin_session_setup().
 * @param signature The memory slot to which the signature is copied if present. It is assumed that
 *   enough memory has been allocated by the user.
 * @param max_signature_size The maximum amount of data that can be written to |signature|. If the
 *   plugin cannot write all the data to |signature|, no data is written and
 *   |written_signature_size| is set to 0.
 * @param written_signature_size The actual size of the data written to |signature|.
 * @param error Pointer to catch an error that occured when signing. A NULL pointer is
 *   allowed to skip collecting an error.
 *
 * @returns True if signature is updated, else False
 */
bool
sv_signing_plugin_get_signature(void *handle,
    uint8_t *signature,
    size_t max_signature_size,
    size_t *written_signature_size,
    SignedVideoReturnCode *error);

/**
 * @brief Sets up the signing plugin
 *
 * This function is called when the Signed Video session is created. For example, useful to initiate
 * member variables of the plugin.
 *
 * @param private_key A pointer to the private key data.
 * @param private_key_size The size of the private key data.
 *
 * @returns A plugin handle needed for further operations and NULL if invalid input parameters or
 *   memory could not be allocated.
 */
void *
sv_signing_plugin_session_setup(const void *private_key, size_t private_key_size);

/**
 * @brief Tears down the signing plugin
 *
 * This function is called when the Signed Video session is terminated.
 *
 * @param handle A pointer to the handle for the plugin, generated by
 *   sv_signing_plugin_session_setup().
 */
void
sv_signing_plugin_session_teardown(void *handle);

/**
 * @brief Plugin initialization
 *
 * This function can/should be called to initialize the signing plugin. Compared to
 * sv_signing_plugin_session_setup() this function is not called by the library when creating a
 * session. Therefore, it can be used to handle session independent operations, like setting up a
 * thread, before any session has been created.
 *
 * @param user_data Generic data to provide if needed.
 *
 * @returns 0 upon success
 */
int
sv_signing_plugin_init(void *user_data);
/* Temporary function for backwards compatibility while re-interpreting |user_data|. */
int
sv_signing_plugin_init_new(void *user_data);

/**
 * @brief Plugin termination
 *
 * This function can/should be called when terminating the plugin. Compared to
 * sv_interface_teardown() this function is not called by the library when closing a session.
 * Therefore, it can be used to handle session independent operations, like terminating a thread,
 * after all sessions have been closed.
 *
 * @param user_data Generic data to provide if needed.
 */
void
sv_signing_plugin_exit(void *user_data);

#ifdef __cplusplus
}
#endif

#endif  // __SIGNED_VIDEO_SIGNING_PLUGIN_H__