Query auth tag size in soter_sym_aead_encrypt_final() (#493)

Documentation for soter_sym_aead_encrypt_final() states that it is
possible to query buffer size for authentication tag by passing NULL.
However, currently we do not allow NULL values for auth_tag.

Replace SOTER_CHECK with proper validation and return buffer size with
proper error code when auth_tag == NULL.

Add a test to verify this behavior. Update documentation to improve
readability, fix typos, grammar, etc.

src/soter/boringssl/soter_sym.c

@@ -369,8 +369,10 @@ soter_status_t soter_sym_aead_encrypt_aad(soter_sym_ctx_t* ctx,
 
 soter_status_t soter_sym_aead_encrypt_final(soter_sym_ctx_t* ctx, void* auth_tag, size_t* auth_tag_length)
 {
-    SOTER_CHECK_PARAM(auth_tag != NULL);
-    if ((*auth_tag_length) < SOTER_AES_GCM_AUTH_TAG_LENGTH) {
+    if (!auth_tag_length) {
+        return SOTER_INVALID_PARAMETER;
+    }
+    if (!auth_tag || (*auth_tag_length) < SOTER_AES_GCM_AUTH_TAG_LENGTH) {
         (*auth_tag_length) = SOTER_AES_GCM_AUTH_TAG_LENGTH;
         return SOTER_BUFFER_TOO_SMALL;
     }

src/soter/openssl/soter_sym.c

@@ -367,8 +367,10 @@ soter_status_t soter_sym_aead_encrypt_aad(soter_sym_ctx_t* ctx,
 
 soter_status_t soter_sym_aead_encrypt_final(soter_sym_ctx_t* ctx, void* auth_tag, size_t* auth_tag_length)
 {
-    SOTER_CHECK_PARAM(auth_tag != NULL);
-    if ((*auth_tag_length) < SOTER_AES_GCM_AUTH_TAG_LENGTH) {
+    if (!auth_tag_length) {
+        return SOTER_INVALID_PARAMETER;
+    }
+    if (!auth_tag || (*auth_tag_length) < SOTER_AES_GCM_AUTH_TAG_LENGTH) {
         (*auth_tag_length) = SOTER_AES_GCM_AUTH_TAG_LENGTH;
         return SOTER_BUFFER_TOO_SMALL;
     }

src/soter/soter_sym.h

@@ -323,16 +323,19 @@ soter_status_t soter_sym_aead_encrypt_update(soter_sym_ctx_t* ctx,
                                              size_t* cipher_data_length);
 
 /**
- * @brief final symmetric encryption context
- * @param [in] ctx pointer to symmetric encryption context prerviosly created by
- * soter_sym_encrypt_create
- * @param [out] auth_tag pointer to buffer for auth tag store, may be set to NULL for auth tag
- * length determination
- * @param [in, out] auth_tag_length length of auth_tag
+ * Finalize symmetric encryption context.
+ *
+ * @param [in]  ctx       pointer to symmetric encryption context previously
+ *                        created by soter_sym_encrypt_create
+ * @param [out] auth_tag  pointer to buffer for auth tag store,
+ *                        may be set to NULL to query auth tag length
+ * @param [in, out] auth_tag_length  length of auth_tag
+ *
  * @return result of operation, @ref SOTER_SUCCESS on success and @ref SOTER_FAIL on failure.
- * @note If auth_tag==NULL or auth_tag_length less then need to store auth tag, @ref
- * SOTER_BUFFER_TOO_SMALL will return and auth_tag_length will contain length of buffer thet need to
- * store auth_tag.
+ *
+ * @note If auth_tag is NULL or auth_tag_length is not big enough to store an auth tag,
+ *       @ref SOTER_BUFFER_TOO_SMALL is returned and auth_tag_length will contain suitable
+ *       size for the buffer that is required to store auth_tag.
  */
 SOTER_API
 soter_status_t soter_sym_aead_encrypt_final(soter_sym_ctx_t* ctx, void* auth_tag, size_t* auth_tag_length);

tests/soter/soter_sym_test.c

@@ -458,6 +458,12 @@ static void test_auth_tag(void)
         return;
     }
 
+    res = soter_sym_aead_encrypt_final(ctx, NULL, NULL);
+    testsuite_fail_if(res != SOTER_INVALID_PARAMETER, "soter_sym_aead_encrypt_final: NULL length");
+
+    res = soter_sym_aead_encrypt_final(ctx, NULL, &tag_length);
+    testsuite_fail_if(res != SOTER_BUFFER_TOO_SMALL, "soter_sym_aead_encrypt_final: query size");
+
     res = soter_sym_aead_encrypt_final(ctx, tag, &tag_length);
     if (SOTER_SUCCESS != res) {
         testsuite_fail_if(res, "soter_sym_aead_encrypt_final");