Merge pull request #49 from dongbeiouba/improve/doc

Add doc for external API. Refactor sm3 & sm4 API.

.clang-format

@@ -10,7 +10,7 @@ AlignConsecutiveBitFields: AcrossEmptyLines
 AlignConsecutiveDeclarations: None
 AlignEscapedNewlines: Right
 AlignOperands:   Align
-AlignTrailingComments: false
+AlignTrailingComments: true
 AllowAllArgumentsOnNextLine: false
 AllowAllParametersOfDeclarationOnNextLine: false
 AllowShortEnumsOnASingleLine: true
@@ -133,7 +133,7 @@ PenaltyIndentedWhitespace: 0
 PointerAlignment: Right
 PPIndentWidth: 1
 ReferenceAlignment: Pointer
-ReflowComments:  false
+ReflowComments: true
 RemoveBracesLLVM: false
 SeparateDefinitionBlocks: Leave
 ShortNamespaceLines: 1

CMakeLists.txt

@@ -13,11 +13,14 @@ endif()
 set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
 
 if(MSVC)
-    set(TONGSUO_MINI_INSTALL_DIR C:/tongsuo-mini)
+    set(CMAKE_INSTALL_PREFIX C:/tongsuo-mini)
 else()
-    set(TONGSUO_MINI_INSTALL_DIR /opt/tongsuo-mini)
+    set(CMAKE_INSTALL_PREFIX /opt/tongsuo-mini)
 endif()
 
+set(CMAKE_MACOSX_RPATH 1)
+set(CMAKE_INSTALL_RPATH "${CMAKE_INSTALL_PREFIX}/lib")
+
 include_directories(include)
 
 set(libsrc
@@ -197,19 +200,19 @@ message(STATUS "WITH_SM4...................${WITH_SM4}")
 # install
 #
 install(DIRECTORY ${CMAKE_CURRENT_LIST_DIR}/include/tongsuo
-    DESTINATION ${TONGSUO_MINI_INSTALL_DIR}/include/
+    DESTINATION ${CMAKE_INSTALL_PREFIX}/include
     COMPONENT dev)
 
-install(TARGETS tongsuo-mini
-    LIBRARY DESTINATION ${TONGSUO_MINI_INSTALL_DIR}/lib COMPONENT lib
-    ARCHIVE DESTINATION ${TONGSUO_MINI_INSTALL_DIR}/lib COMPONENT lib)
+install(TARGETS tongsuo-mini tongsuo-mini-static
+    LIBRARY DESTINATION ${CMAKE_INSTALL_PREFIX}/lib COMPONENT lib
+    ARCHIVE DESTINATION ${CMAKE_INSTALL_PREFIX}/lib COMPONENT lib)
 
 install(TARGETS minisuo
-    DESTINATION ${TONGSUO_MINI_INSTALL_DIR}/bin
+    DESTINATION ${CMAKE_INSTALL_PREFIX}/bin
     COMPONENT dev)
 
-if(WITH_PERF OR WITH_ALL)
+if(WITH_PERF)
     install(TARGETS minisuo-perf
-        DESTINATION ${TONGSUO_MINI_INSTALL_DIR}/bin
+        DESTINATION ${CMAKE_INSTALL_PREFIX}/bin
         COMPONENT dev)
 endif()

app/minisuo.c

@@ -27,7 +27,7 @@ typedef struct {
 static int sm4_handler(int argc, char **argv)
 {
     int ret = 1, i, mode = TSM_CIPH_MODE_CBC, flags = 0;
-    long len;
+    size_t len;
     size_t outlen;
     size_t nread;
     unsigned char inbuf[1024];
@@ -132,10 +132,14 @@ static int sm4_handler(int argc, char **argv)
         }
     }
 
-    ctx = tsm_sm4_init(mode, key, iv, flags);
+    ctx = tsm_sm4_ctx_new();
     if (ctx == NULL)
         goto end;
 
+    ret = tsm_sm4_init(ctx, mode, key, iv, flags);
+    if (ret != TSM_OK)
+        goto end;
+
     while (1) {
         nread = fread(inbuf, 1, sizeof(inbuf), in);
         if (nread != sizeof(inbuf) && ferror(in)) {
@@ -216,8 +220,8 @@ static int sm3_handler(int argc, char **argv)
 static int ascon_aead_handler(int argc, char **argv)
 {
     int ret = 1, i, scheme, flags = 0, tag_set = 0;
-    long len;
-    int outlen;
+    size_t len;
+    size_t outlen;
     size_t nread;
     unsigned char inbuf[1024];
     unsigned char outbuf[1024 + TSM_MAX_BLOCK_LENGTH];
@@ -356,10 +360,14 @@ static int ascon_aead_handler(int argc, char **argv)
         }
     }
 
-    ctx = tsm_ascon_aead_init(scheme, key, nonce, flags);
+    ctx = tsm_ascon_aead_ctx_new();
     if (ctx == NULL)
         return 1;
 
+    ret = tsm_ascon_aead_init(ctx, scheme, key, nonce, flags);
+    if (ret != TSM_OK)
+        return 1;
+
     if (flags & TSM_CIPH_FLAG_DECRYPT) {
         if (tag_set == 0) {
             fprintf(stderr, "No tag set\n");
@@ -426,7 +434,7 @@ static int ascon_aead_handler(int argc, char **argv)
     if (out != NULL && out != stdout)
         fclose(out);
     if (ctx != NULL)
-        tsm_ascon_aead_clean(ctx);
+        tsm_ascon_aead_ctx_free(ctx);
     return ret;
 }
 

include/internal/sm3.h

@@ -0,0 +1,26 @@
+/*
+ * Copyright 2023 The Tongsuo Project Authors. All Rights Reserved.
+ *
+ * Licensed under the Apache License 2.0 (the "License").  You may not use
+ * this file except in compliance with the License.  You can obtain a copy
+ * in the file LICENSE in the source distribution or at
+ * https://github.com/Tongsuo-Project/tongsuo-mini/blob/main/LICENSE
+ */
+
+#if !defined(TSM_INTERNAL_SM3_H)
+# define TSM_INTERNAL_SM3_H
+# pragma once
+
+# define TSM_SM3_CBLOCK 64
+# define TSM_SM3_LBLOCK 16
+
+# pragma pack(1)
+typedef struct tsm_sm3_ctx_s {
+    unsigned int A, B, C, D, E, F, G, H;
+    unsigned int Nl, Nh;
+    unsigned int data[TSM_SM3_LBLOCK];
+    unsigned int num;
+} TSM_SM3_CTX;
+# pragma pack()
+
+#endif

include/internal/sm4.h

@@ -17,7 +17,7 @@
 # define SM4_KEY_SCHEDULE 32
 
 # pragma pack(1)
-typedef struct tsm_sm4_ctx_st {
+typedef struct tsm_sm4_ctx_s {
     uint32_t rk[SM4_KEY_SCHEDULE];
     unsigned char mode;
     unsigned char flags;
@@ -29,7 +29,6 @@ typedef struct tsm_sm4_ctx_st {
     int final_used;
     unsigned char final[TSM_MAX_BLOCK_LENGTH]; /* possible final block */
 } TSM_SM4_CTX;
-
 # pragma pack()
 
 #endif

include/tongsuo/ascon.h

@@ -15,37 +15,79 @@
 extern "C" {
 # endif
 
-# define TSM_ASCON_AEAD_128     0x1
-# define TSM_ASCON_AEAD_128A    0x2
+# include <stdlib.h>
 
-# define TSM_ASCON_AEAD_TAG_LEN 16
+# define TSM_ASCON_AEAD_128       0x1
+# define TSM_ASCON_AEAD_128A      0x2
 
-# define TSM_ASCON_HASH         0x1
-# define TSM_ASCON_HASHA        0x2
+# define TSM_ASCON_AEAD_TAG_LEN   16
+# define TSM_ASCON_AEAD_KEY_LEN   16
+# define TSM_ASCON_AEAD_NONCE_LEN 16
 
-# define TSM_ASCON_HASH_LEN     32
-# define TSM_ASCON_HMAC_LEN     TSM_ASCON_HASH_LEN
+# define TSM_ASCON_HASH           0x1
+# define TSM_ASCON_HASHA          0x2
 
-void *tsm_ascon_aead_init(int scheme, const unsigned char *key, const unsigned char *nonce,
-                          int flags);
-int tsm_ascon_aead_update(void *ctx, const unsigned char *in, int inl, unsigned char *out,
-                          int *outl);
-int tsm_ascon_aead_final(void *ctx, unsigned char *out, int *outl);
-void tsm_ascon_aead_clean(void *ctx);
+# define TSM_ASCON_HASH_LEN       32
+# define TSM_ASCON_HMAC_LEN       TSM_ASCON_HASH_LEN
 
+/* Create a new context of ascon aead, should be freed by tsm_ascon_aead_ctx_free() after use. */
+void *tsm_ascon_aead_ctx_new(void);
+/* Frees up the context ctx of ascon aead. */
+void tsm_ascon_aead_ctx_free(void *ctx);
+/* Initializes the context ctx with type, key, nonce and flags. type should be TSM_ASCON_AEAD_128 or
+ * TSM_ASCON_AEAD_128A. The length of key and nonce should be 16 bytes. flags may be
+ * TSM_CIPH_FLAG_ENCRYPT or TSM_CIPH_FLAG_DECRYPT. If you want to encrypt data without padding,
+ * flags should be TSM_CIPH_FLAG_ENCRYPT | TSM_CIPH_FLAG_NO_PAD. Returns TSM_OK for success and
+ * others for failure. */
+int tsm_ascon_aead_init(void *ctx, int type, const unsigned char *key, const unsigned char *nonce,
+                        int flags);
+/* Encrypts or decrypts data at in with the length inl, and retrives the result at out. The number
+ * of bytes of result written will be written to the integer at outl. Returns TSM_OK for success and
+ * others for failure. */
+int tsm_ascon_aead_update(void *ctx, const unsigned char *in, size_t inl, unsigned char *out,
+                          size_t *outl);
+/* Encrypts or decrypts the "final" data, that is any data that remains in a partial block. The
+ * encrypted or decrypted final data is written to out which should have sufficient space for one
+ * cipher block, 16 bytes for aead. The number of bytes written is placed in outl. After this
+ * function is called the encryption operation is finished and no further calls to
+ * tsm_ascon_aead_update() should be made. Returns TSM_OK for success and others for failure. */
+int tsm_ascon_aead_final(void *ctx, unsigned char *out, size_t *outl);
+/* Set tag before ascon AEAD decryption. */
 int tsm_ascon_aead_set_tag(void *ctx, const unsigned char *tag);
+/* Get tag after ascon AEAD encryption. */
 int tsm_ascon_aead_get_tag(void *ctx, unsigned char *tag);
-
-int tsm_ascon_aead_oneshot(int scheme, const unsigned char *key, const unsigned char *nonce,
-                           const unsigned char *ad, int adl, const unsigned char *in, int inl,
-                           unsigned char *out, int *outl, int flags);
-void *tsm_ason_hash_ctx_new(void);
+/* Encrypts or decrypts data at in with length inl, and retrives the result at out. The number of
+ * bytes of result written will be written to the integer at outl. The length of key and nonce
+ * should be 16 bytes. type should be TSM_ASCON_AEAD_128 or TSM_ASCON_AEAD_128A. flags may be
+ * TSM_CIPH_FLAG_ENCRYPT or TSM_CIPH_FLAG_DECRYPT. If you want to encrypt data without padding,
+ * flags should be TSM_CIPH_FLAG_ENCRYPT | TSM_CIPH_FLAG_NO_PAD. Returns TSM_OK for success and
+ * others for failure. */
+int tsm_ascon_aead_oneshot(int type, const unsigned char *key, const unsigned char *nonce,
+                           const unsigned char *ad, size_t adl, const unsigned char *in, size_t inl,
+                           unsigned char *out, size_t *outl, int flags);
+/* Create ctx of ascon hash. */
+void *tsm_ascon_hash_ctx_new(void);
+/* Destroy ctx of ascon hash. */
 void tsm_ascon_hash_ctx_free(void *ctx);
+/* Initialize ctx with type. type should be TSM_ASCON_HASH or TSM_ASCON_HASHA. Returns TSM_OK for
+ * success and others for failure. */
 int tsm_ascon_hash_init(void *ctx, int type);
+/* Hashes inl bytes of data at in into the hash context ctx. This function can be called serveral
+ * times on the same ctx to hash more data. Returns TSM_OK for success and others for failure. */
 int tsm_ascon_hash_update(void *ctx, const unsigned char *in, size_t inl);
+/* Retrieves the hash value from ctx and place it in out. The number of bytes of data written will
+ * be written to the integer at outl. If successful, the length of digest should be
+ * TSM_ASCON_HASH_LEN. After calling tsm_ascon_hash_final() no additional calls to
+ * tsm_ascon_hash_update() can be made. Returns TSM_OK for success and others for failure. */
 int tsm_ascon_hash_final(void *ctx, unsigned char *out, size_t *outl);
+/* Hashes inl bytes of data at in, and retrieves the hash value at out. type should be
+ * TSM_ASCON_HASH or TSM_ASCON_HASHA. The number of bytes of data written will be written to the
+ * integer at outl. If successful, the length of digest should be TSM_ASCON_HASH_LEN. Returns TSM_OK
+ * for success and others for failure. */
 int tsm_ascon_hash_oneshot(int type, const unsigned char *in, size_t inl, unsigned char *out,
                            size_t *outl);
+/* Return the method of ascon hash, including create ctx, destroy ctx, etc, maybe used by
+ * tsm_hmac_oneshot(). type should be TSM_ASCON_HASH or TSM_ASCON_HASHA. */
 void *tsm_ascon_hash_meth(int type);
 
 # ifdef __cplusplus

include/tongsuo/hmac.h

@@ -17,15 +17,26 @@ extern "C" {
 
 # include <stdlib.h>
 
+/* Create a new context of HMAC. Should be freed by calling tsm_hmac_ctx_free() after use.  */
 void *tsm_hmac_ctx_new(void);
+/* Frees up the context ctx of HMAC. */
 void tsm_hmac_ctx_free(void *ctx);
-
+/* Initialize the HMAC context with the given key and key length. The meth sets the used hash
+ * methods. For example, if you want to use ascon hash, the meth can be obtained by calling
+ * tsm_ascon_hash_meth(). Returns TSM_OK for success and others for failure. */
 int tsm_hmac_init(void *ctx, const unsigned char *key, size_t keylen, void *meth);
+/* Updates the HMAC context with the given data in and data length inlen. Returns TSM_OK for success
+ * and others for failure. */
 int tsm_hmac_update(void *ctx, const unsigned char *in, size_t inlen);
+/* Finalizes the HMAC context and writes the result to out. The length of the result is written to
+ * outlen. Returns TSM_OK for success and others for failure. */
 int tsm_hmac_final(void *ctx, unsigned char *out, size_t *outlen);
-
-int tsm_hmac(void *meth, const unsigned char *key, size_t keylen, const unsigned char *in,
-             size_t inlen, unsigned char *out, size_t *outl);
+/* Computes the HMAC of the given data in and data length inlen with the given key and key length
+ * keylen. The result is written to out. The length of the result is written to outl. The meth sets
+ * the used hash methods. For example, if you want to use ascon hash, the meth can be obtained by
+ * calling tsm_ascon_hash_meth(). Returns TSM_OK for success and others for failure. */
+int tsm_hmac_oneshot(void *meth, const unsigned char *key, size_t keylen, const unsigned char *in,
+                     size_t inlen, unsigned char *out, size_t *outl);
 
 # ifdef __cplusplus
 }

include/tongsuo/mem.h

@@ -18,25 +18,40 @@ extern "C" {
 # include <stdlib.h>
 
 # pragma pack(1)
-typedef struct {
+typedef struct tsm_str_s {
     size_t length;
     const uint8_t *s;
 } TSM_STR;
 # pragma pack()
 
+/* Create a new TSM_STR object with the given data and length. Should be freed by calling
+ * tsm_str_free() after use. */
 TSM_STR *tsm_str_new(const uint8_t *data, size_t len);
+/* Frees up the TSM_STR object. */
 void tsm_str_free(TSM_STR *buf);
+/* Duplicates the TSM_STR object. Should be freed by calling tsm_str_free() after use. */
 TSM_STR *tsm_str_dup(TSM_STR *buf);
+/* Creates a temp TSM_STR object with the given string. Must not be freed by calling tsm_str_free().
+ */
 TSM_STR *tsm_str(const char *string);
+/* Creates a temp TSM_STR object with the given data and length. Must not be freed by calling
+ * tsm_str_free(). */
 TSM_STR *tsm_str_const(const uint8_t *data, size_t len);
+/* Compares two TSM_STR. Return non-zero means equal, 0 means not equal. */
 int tsm_str_equal(TSM_STR *a, TSM_STR *b);
-
+/* Allocate a new buffer with size length. */
 void *tsm_alloc(size_t size);
+/* Allocate a new buffer with size length and zero it. */
 void *tsm_calloc(size_t size);
+/* Free the buffer. */
 void tsm_free(void *ptr);
+/* Zero the buffer. */
 void tsm_memzero(void *ptr, size_t size);
-
-int tsm_hex2bin(const char *str, unsigned char *buf, long *buflen);
+/* Convert a hex buf with length buflen to binary. Return TSM_OK for success and others for failure.
+ */
+int tsm_hex2bin(const char *str, unsigned char *buf, size_t *buflen);
+/* Convert a hex string with NUL(\0) as ending to buffer. The return pointer shoud be freed by
+ * calling tsm_free() after use. */
 unsigned char *tsm_hex2buf(const char *str);
 
 # ifdef __cplusplus

include/tongsuo/minisuo.h

@@ -22,26 +22,25 @@ extern "C" {
 # define TSM_VERSION_MAJOR     0
 # define TSM_VERSION_MINOR     9
 # define TSM_VERSION_PATCH     0
-/*
- * 0x00, dev
+/* 0x00, dev
  * 0x1~0xfe, pre1~pre254
- * 0xff, release
- */
+ * 0xff, release */
 # define TSM_VERSION_TAG 0
-
 # define TONGSUO_MINI_VERSION                                                                      \
      ((TSM_VERSION_MAJOR << 24) | (TSM_VERSION_MINOR << 16) | (TSM_VERSION_PATCH << 8)             \
       | TSM_VERSION_TAG)
 
-# define TSM_CIPH_MODE_STREAM  0x0
-# define TSM_CIPH_MODE_ECB     0x1
-# define TSM_CIPH_MODE_CBC     0x2
-# define TSM_CIPH_MODE_CFB     0x3
-# define TSM_CIPH_MODE_OFB     0x4
-# define TSM_CIPH_MODE_CTR     0x5
-# define TSM_CIPH_MODE_GCM     0x6
-# define TSM_CIPH_MODE_CCM     0x7
+/* Supported cipher modes. */
+# define TSM_CIPH_MODE_STREAM 0x0
+# define TSM_CIPH_MODE_ECB    0x1
+# define TSM_CIPH_MODE_CBC    0x2
+# define TSM_CIPH_MODE_CFB    0x3
+# define TSM_CIPH_MODE_OFB    0x4
+# define TSM_CIPH_MODE_CTR    0x5
+# define TSM_CIPH_MODE_GCM    0x6
+# define TSM_CIPH_MODE_CCM    0x7
 
+/* Supported cipher flags. */
 # define TSM_CIPH_FLAG_ENCRYPT 0x1
 # define TSM_CIPH_FLAG_DECRYPT 0x2
 # define TSM_CIPH_FLAG_NO_PAD  0x4
@@ -50,8 +49,7 @@ extern "C" {
 # define TSM_MAX_BLOCK_LENGTH  32
 
 /* Return 0 (i.e. TSM_OK) means success, others mean failure whether it is > 0 or < 0.
- * Try to return specific error code if possible.
- */
+ * Try to return specific error code if possible. */
 enum {
     TSM_FAILED = -1,
     TSM_OK = 0,
@@ -81,7 +79,9 @@ enum {
     TSM_ERR_ALGORITHM_NOT_SUPPORTED,
 };
 
+/* Converts error code to error string. */
 const char *tsm_err2str(int err);
+/* Returns version text of tongsuo-mini. */
 const char *tsm_version_text(void);
 
 # ifdef __cplusplus