Updates header files (#332)

Co-authored-by: bjornvolcker <bjornvolcker@users.noreply.github.com>

Author: bjornvolcker

lib/src/includes/signed_video_common.h

@@ -133,7 +133,7 @@ int
 signed_video_compare_versions(const char* version1, const char* version2);
 
 /**
- * @brief Checks if a NALU/OBU is a golden SEI/OBU Metadata
+ * @brief Checks if a Bitstream Unit is a golden SEI/OBU Metadata
  *
  * A golden SEI/OBU Metadata is a self-signed SEI/OBU Metadata that includes all information only
  * needed once such as the Public key. Usually a golden SEI/OBU Metadata is sent only once in the
@@ -143,7 +143,7 @@ signed_video_compare_versions(const char* version1, const char* version2);
  * For the signing side it can help out to verify that a pre-generated golden SEI/OBU Metadata
  * actually is a golden SEI/OBU Metadata before adding it to the stream.
  *
- * @param nalu A pointer to the NALU/OBU data
+ * @param nalu A pointer to the Bitstream Unit data
  * @param nalu_size Size of the |nalu|
  *
  * @returns True if |nalu| is a golden SEI/OBU Metadata

lib/src/includes/signed_video_openssl.h

@@ -93,11 +93,11 @@ typedef struct _pem_pkey_t {
  *
  * @param sign_data A pointer to the struct that holds all necessary information for signing.
  *
- * @returns SV_OK Successfully generated |signature|,
- *          SV_INVALID_PARAMETER Errors in |sign_data|,
- *          SV_NOT_SUPPORTED No private key present,
- *          SV_MEMORY Not enough memory allocated for the |signature|,
- *          SV_EXTERNAL_ERROR Failure in OpenSSL.
+ * @return SV_OK Successfully generated |signature|,
+ *         SV_INVALID_PARAMETER Errors in |sign_data|,
+ *         SV_NOT_SUPPORTED No private key present,
+ *         SV_MEMORY Not enough memory allocated for the |signature|,
+ *         SV_EXTERNAL_ERROR Failure in OpenSSL.
  */
 SignedVideoReturnCode
 openssl_sign_hash(sign_or_verify_data_t *sign_data);
@@ -114,10 +114,10 @@ openssl_sign_hash(sign_or_verify_data_t *sign_data);
  * @param private_key The content of the private key PEM file.
  * @param private_key_size The size of the |private_key|.
  *
- * @returns SV_OK Successfully generated |signature|,
- *          SV_INVALID_PARAMETER Missing inputs,
- *          SV_MEMORY Failed allocating memory for the |signature|,
- *          SV_EXTERNAL_ERROR Failure in OpenSSL.
+ * @return SV_OK Successfully generated |signature|,
+ *         SV_INVALID_PARAMETER Missing inputs,
+ *         SV_MEMORY Failed allocating memory for the |signature|,
+ *         SV_EXTERNAL_ERROR Failure in OpenSSL.
  */
 SignedVideoReturnCode
 openssl_private_key_malloc(sign_or_verify_data_t *sign_data,
@@ -152,10 +152,10 @@ openssl_free_key(void *key);
  *   Ownership is transferred.
  * @param private_key_size If not NULL outputs the size of the |private_key|.
  *
- * @returns SV_OK Valid algorithm and successfully written PEM-file,
- *          SV_NOT_SUPPORTED Algorithm is not supported,
- *          SV_INVALID_PARAMETER Invalid input parameter,
- *          SV_EXTERNAL_ERROR PEM-file could not be written.
+ * @return SV_OK Valid algorithm and successfully written PEM-file,
+ *         SV_NOT_SUPPORTED Algorithm is not supported,
+ *         SV_INVALID_PARAMETER Invalid input parameter,
+ *         SV_EXTERNAL_ERROR PEM-file could not be written.
  */
 SignedVideoReturnCode
 signed_video_generate_ecdsa_private_key(const char *dir_to_key,
@@ -185,10 +185,10 @@ signed_video_generate_rsa_private_key(const char *dir_to_key,
  *   Ownership is transferred.
  * @param private_key_size If not NULL outputs the size of the |private_key|.
  *
- * @returns SV_OK Valid algorithm and successfully written PEM-file,
- *          SV_NOT_SUPPORTED Algorithm is not supported,
- *          SV_INVALID_PARAMETER Invalid input parameter,
- *          SV_EXTERNAL_ERROR PEM-file could not be written.
+ * @return SV_OK Valid algorithm and successfully written PEM-file,
+ *         SV_NOT_SUPPORTED Algorithm is not supported,
+ *         SV_INVALID_PARAMETER Invalid input parameter,
+ *         SV_EXTERNAL_ERROR PEM-file could not be written.
  */
 SignedVideoReturnCode
 signed_video_generate_private_key(sign_algo_t algo,

lib/src/includes/signed_video_sign.h

@@ -34,22 +34,23 @@ typedef struct _legacy_sv_t legacy_sv_t;
 /**
  * @brief Creates a legacy signed video session.
  *
- * Creates a legacy_sv_t object which the user should keep across the entire streaming session.
- * The returned struct can be used for validating the authenticity of a legacy video.
+ * Creates a legacy_sv_t object which the user should keep across the entire streaming
+ * session. The returned struct can be used for validating the authenticity of a legacy
+ * video.
  *
  * @param parent The parent session, i.e., a signed_video_t object.
  *
- * @returns A pointer to legacy_sv_t struct, allocated and initialized. A null pointer is
- *          returned if memory could not be allocated.
+ * @return A pointer to legacy_sv_t struct, allocated and initialized. A null pointer is
+ *         returned if memory could not be allocated.
  */
 legacy_sv_t *
 legacy_sv_create(signed_video_t *parent);
 
 /**
  * @brief Frees the memory of the legacy_sv_t object.
  *
- * All memory allocated to and by the legacy_sv_t object will be freed. This will affectivly end
- * the signed video session.
+ * All memory allocated to and by the legacy_sv_t object will be freed. This will
+ * affectivly end the signed video session.
  *
  * @param self Pointer to the object which memory to free.
  */
@@ -59,64 +60,66 @@ legacy_sv_free(legacy_sv_t *self);
 /**
  * @brief Resets the legacy session to allow for, e.g., scrubbing signed video
  *
- * Resets the session and puts it in a pre-stream state, that is, waiting for a new GOP. Once a new
- * GOP is found the operations start over.
+ * Resets the session and puts it in a pre-stream state, that is, waiting for a new GOP.
+ * Once a new GOP is found the operations start over.
  *
  * For the signing part, this means starting to produce the required SEIs needed for
- * authentication. For the authentication part, this should be used when scrubbing the video.
- * Otherwise the lib will fail authentication due to skipped NALUs.
+ * authentication. For the authentication part, this should be used when scrubbing the
+ * video. Otherwise the lib will fail authentication due to skipped Bitstream Units.
  *
  * @param self Signed Video session in use
  *
- * @returns A svrc_t
+ * @return A svrc_t
  */
 svrc_t
 legacy_sv_reset(legacy_sv_t *self);
 
 /**
- * @brief Add NALU data to the session and get an authentication report
+ * @brief Add Bitstream Unit data to the session and get an authentication report
  *
- * This function should be called for each H26x NALU the user receives. It is assumed that
- * |nalu_data| consists of one single NALU including Start Code and NALU, so that NALU type can be
- * parsed. That is, the format should look like this:
+ * This function should be called for each Bitstream Unit the user receives. It is assumed
+ * that |nalu_data| consists of one single Bitstream Unit including Start Code and
+ * Bitstream Unit, so that Bitstream Unit type can be parsed. That is, the format should
+ * look like this:
  *
  * |------------|------|
  * | Start Code | NALU |
  * |------------|------|
  *  3 or 4 bytes       ^
  *                     Including stop bit
  *
- * NOTE: NALUs sent into the API cannot be in packetized format (access units)!
- * The access unit has to be split into NALUs if so.
+ * @note: Bitstream Units sent into the API cannot be in packetized format (access units)!
+ * The access unit has to be split into Bitstream Units if so.
  *
- * The input |nalu_data| is not changed by this call. Note that it is assumed that ALL H26x NALUs
- * are passed to this function. Otherwise, they will be treated as missing/lost packets which may
- * affect the validation.
+ * The input |nalu_data| is not changed by this call. Note that it is assumed that ALL
+ * Bitstream Units are passed to this function. Otherwise, they will be treated as
+ * missing/lost packets which may affect the validation.
  *
- * Signatures are sent on regular basis. Currently this is done at the end of each GOP (Group Of
- * Pictures). For every input |nalu_data| with a signature, or when a signature is expected,
- * validation is performed and a copy of the |authenticity| result is provided. If a NALU does not
- * trigger a validation, |authenticity| is a NULL pointer. If one NALU is lost or tampered with
- * within a GOP, the whole GOP is marked as NOT OK, even if the other NALUs are correct.
+ * Signatures are sent on regular basis. Currently this is done at the end of each GOP
+ * (Group Of Pictures). For every input |nalu_data| with a signature, or when a signature
+ * is expected, validation is performed and a copy of the |authenticity| result is
+ * provided. If a Bitstream Unit does not trigger a validation, |authenticity| is a NULL
+ * pointer. If one NALU is lost or tampered with within a GOP, the whole GOP is marked as
+ * NOT OK, even if the other NALUs are correct.
  *
  * The user should continuously check the return value for errors and upon success check
  * |authenticity| for a new report.
  * Two typical use cases are; 1) live monitoring which could be screening the video until
- * authenticity can no longer be validated OK, and 2) screening a recording and get a full report at
- * the end. In the first case further operations can simply be aborted as soon as a validation
- * fails, whereas in the latter case all the NALUs need to be screened.
- * NOTE: Only the live monitoring use case is currently supported.
+ * authenticity can no longer be validated OK, and 2) screening a recording and get a full
+ * report at the end. In the first case further operations can simply be aborted as soon
+ * as a validation fails, whereas in the latter case all the NALUs need to be screened.
+ * @note: Only the live monitoring use case is currently supported.
  *
  * Example code of usage; See example code above.
  *
  * @param self Pointer to the legacy_sv_t object to update
- * @param nalu_data Pointer to the H26x NALU data to be added
+ * @param nalu_data Pointer to the Bitstream Unit data to be added
  * @param nalu_data_size Size of the nalu_data
- * @param authenticity Pointer to the autenticity report. Passing in a NULL pointer will not provide
- *     latest validation results. The user is then responsible to get a report using
- *     signed_video_get_authenticity_report(...).
+ * @param authenticity Pointer to the autenticity report. Passing in a NULL pointer will
+ *     not provide latest validation results. The user is then responsible to get a report
+ *     using signed_video_get_authenticity_report(...).
  *
- * @returns A svrc_t
+ * @return A svrc_t
  */
 svrc_t
 legacy_sv_add_nalu_and_authenticate(legacy_sv_t *self,
@@ -125,14 +128,14 @@ legacy_sv_add_nalu_and_authenticate(legacy_sv_t *self,
     signed_video_authenticity_t **authenticity);
 
 /**
- * @brief Gets the size of the NAL Unit list
+ * @brief Gets the size of the Bitstream Unit list
  *
  * This function is necessary to update the authenticity report from the parent Signed
  * Video session.
  *
  * @param self Pointer to the legacy_sv_t object
  *
- * @return Number of NAL Units (items) in the nalu_list
+ * @return Number of Bitstream Units (items) in the nalu_list
  */
 int
 legacy_get_nalu_list_items(legacy_sv_t *self);

lib/src/legacy_validation.h

@@ -18,8 +18,8 @@
  * 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_AUTHENTICITY_H__
-#define __SIGNED_VIDEO_AUTHENTICITY_H__
+#ifndef __SV_AUTHENTICITY_H__
+#define __SV_AUTHENTICITY_H__
 
 #include "includes/signed_video_auth.h"  // signed_video_product_info_t
 #include "sv_defines.h"  // svrc_t
@@ -31,7 +31,7 @@
  * @param dst The signed_video_product_info_t struct of which to write to
  * @param src The signed_video_product_info_t struct of which to read from
  *
- * @returns A Signed Video Return Code
+ * @return A Signed Video Return Code
  */
 svrc_t
 transfer_product_info(signed_video_product_info_t *dst, const signed_video_product_info_t *src);
@@ -64,7 +64,7 @@ accumulated_validation_init(signed_video_accumulated_validation_t *self);
  *
  * @param self The current Signed Video session
  *
- * @returns A Signed Video Return Code
+ * @return A Signed Video Return Code
  */
 svrc_t
 create_local_authenticity_report_if_needed(signed_video_t *self);
@@ -78,7 +78,7 @@ create_local_authenticity_report_if_needed(signed_video_t *self);
  * @param dst_str A pointer holding a pointer to the copied string. Memory is allocated if needed.
  * @param src_str The null-terminated string to copy. A NULL pointer copies "".
  *
- * @returns A Signed Video Return Code
+ * @return A Signed Video Return Code
  */
 svrc_t
 allocate_memory_and_copy_string(char **dst_str, const char *src_str);
@@ -98,4 +98,4 @@ void
 update_accumulated_validation(const signed_video_latest_validation_t *latest,
     signed_video_accumulated_validation_t *accumulated);
 
-#endif  // __SIGNED_VIDEO_AUTHENTICITY_H__
+#endif  // __SV_AUTHENTICITY_H__

lib/src/sv_authenticity.h

@@ -18,8 +18,8 @@
  * 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_DEFINES__
-#define __SIGNED_VIDEO_DEFINES__
+#ifndef __SV_DEFINES__
+#define __SV_DEFINES__
 
 #include <stdbool.h>  // bool
 
@@ -148,12 +148,12 @@ typedef SignedVideoReturnCode svrc_t;
 /**
  * Definition of available TLV tags.
  *
- * Vendor specific TLV tags start from UNDEFINED_VENDOR_TAG. Both sub-lists begin and end with
- * invalid tags (UNDEFINED_TAG and NUMBER_OF_TLV_TAGS) resp. (UNDEFINED_VENDOR_TAG and
- * NUMBER_OF_VENDOR_TLV_TAGS).
+ * Vendor specific TLV tags start from UNDEFINED_VENDOR_TAG. Both sub-lists begin and end
+ * with invalid tags (UNDEFINED_TAG and NUMBER_OF_TLV_TAGS) resp. (UNDEFINED_VENDOR_TAG
+ * and NUMBER_OF_VENDOR_TLV_TAGS).
  *
- * NOTE: When a new tag is added simply append the sub-list of valid tags. Changing the number of
- * existing tags will break backwards compatibility!
+ * @note: When a new tag is added simply append the sub-list of valid tags. Changing the
+ * number of existing tags will break backwards compatibility!
  */
 typedef enum {
   UNDEFINED_TAG = 0,  // Should always be zero

lib/src/sv_defines.h

@@ -18,8 +18,8 @@
  * 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_INTERNAL_H__
-#define __SIGNED_VIDEO_INTERNAL_H__
+#ifndef __SV_INTERNAL_H__
+#define __SV_INTERNAL_H__
 
 #include <stdbool.h>  // bool
 #include <stdint.h>  // uint8_t
@@ -274,4 +274,4 @@ void
 sv_print_hex_data(const uint8_t *data, size_t data_size, const char *fmt, ...);
 #endif
 
-#endif  // __SIGNED_VIDEO_INTERNAL_H__
+#endif  // __SV_INTERNAL_H__