From 63f7b06b78de41dca2026103a496ead0a0189229 Mon Sep 17 00:00:00 2001
From: Gorachya <heyifei1998@sina.com>
Date: Tue, 12 Mar 2019 23:50:42 -0700
Subject: [PATCH] add-docs

---
 doc/crypto/SM9_MASTER_KEY_new.pod | 26 ++++++++++++++++++++++++++
 doc/crypto/SM9_setup.pod          | 30 ++++++++++++++++++++++++++++++
 doc/crypto/ZUC_set_key.pod        | 31 +++++++++++++------------------
 3 files changed, 69 insertions(+), 18 deletions(-)

diff --git a/doc/crypto/SM9_MASTER_KEY_new.pod b/doc/crypto/SM9_MASTER_KEY_new.pod
index 676fdafe7..e416487ba 100644
--- a/doc/crypto/SM9_MASTER_KEY_new.pod
+++ b/doc/crypto/SM9_MASTER_KEY_new.pod
@@ -18,9 +18,35 @@ SM9_MASTER_KEY_new, SM9_MASTER_KEY_free, SM9_KEY_new, SM9_KEY_free - SM9 Algorit
 
 =head1 DESCRIPTION
 
+SM9_MASTER_KEY_new() allocates an empty B<SM9_MASTER_KEY> structure.
+
+SM9_MASTER_KEY_new()分配一个新的B<SM9_MASTER_KEY>结构。
+
+SM9_MASTER_KEY_free() frees the given B<SM9_MASTER_KEY> structure.
+
+SM9_MASTER_KEY_free()将给定的B<SM9_MASTER_KEY>结构释放。
+
+SM9_KEY_new() allocates an empty B<SM9_KEY> structure.
+
+SM9_KEY_new()分配一个新的B<SM9_KEY>结构。
+
+SM9_KEY_free() frees the given B<SM9_KEY> structure.
+
+SM9_KEY_free()将给定的B<SM9_KEY>结构释放。
 
 =head1 RETURN VALUES
 
+SM9_MASTER_KEY_new() returns a pointer to an allocated B<SM9_MASTER_KEY> structure or NULL on error.
+
+SM9_MASTER_KEY_new()返回一个指向已分配的B<SM9_MASTER_KEY>结构的指针。如果发生错误则返回NULL。
+
+SM9_KEY_new() returns a pointer to an allocated B<SM9_KEY> structure or NULL on error.
+
+SM9_KEY_new()返回一个指向已分配的B<SM9_KEY>结构的指针。如果发生错误则返回NULL。
+
+SM9_MASTER_KEY_free() and SM9_KEY_free() have no return value.
+
+SM9_MASTER_KEY_free()和SM9_KEY_free()无返回值。
 
 =head1 CONFORMING TO
 
diff --git a/doc/crypto/SM9_setup.pod b/doc/crypto/SM9_setup.pod
index cdd4434b7..98bb44367 100644
--- a/doc/crypto/SM9_setup.pod
+++ b/doc/crypto/SM9_setup.pod
@@ -25,9 +25,39 @@ SM9_extract_private_key, SM9_extract_public_key - SM9 Algorithm
 
 =head1 DESCRIPTION
 
+SM9_setup() calls SM9_generate_master_secret() and SM9_extract_public_parameters() to set up public parameters and master key for a later usage of SM9 system.
+
+SM9_setup()通过调用SM9_generate_master_secret()和SM9_extract_public_parameters()来设置SM9系统的公共参数和主密钥，以备之后使用。
+
+SM9_generate_master_secret() generates a new B<SM9MasterSecret> structure and set its parameters including pairing type, helper functions, master secret value and master public point.
+
+SM9_generate_master_secret()产生一个新的B<SM9MasterSecret>结构，并为它设置双线性对类型、主密钥等参数值。
+
+SM9_extract_public_parameters() allocates an empty B<SM9PublicParameters> structure and copies some parameters from the given B<SM9MasterSecret> structure.
+
+SM9_extract_public_parameters()分配一个空的B<SM9PublicParameters>结构，并从给定的B<SM9MasterSecret>结构中拷贝部分变量值。
+
+SM9_extract_private_key() and SM9_extract_public_key() both call SM9_MASTER_KEY_extract_key() (but using a different identifier) to generate public or private key for SM9.
+
+SM9_extract_private_key()和SM9_extract_public_key()都调用SM9_MASTER_KEY_extract_key()生成一个B<SM9_KEY>结构，但通过一个标识位区别生成的是公钥还是私钥。
 
 =head1 RETURN VALUES
 
+SM9_setup() returns 1 on success or 0 on failure.
+
+SM9_setup()如果执行成功则返回1，失败返回0。
+
+SM9_generate_master_secret() returns a pointer to an allocated B<SM9MasterSecret> structure or NULL on error.
+
+SM9_generate_master_secret()返回一个指向已分配的B<SM9MasterSecret>结构的指针。如果发生错误则返回NULL。
+
+SM9_extract_public_parameters() returns a pointer to an allocated B<SM9PublicParameters> structure or NULL on error.
+
+SM9_extract_public_parameters()返回一个指向已分配的B<SM9PublicParameters>结构的指针。如果发生错误则返回NULL。
+
+SM9_extract_private_key() and SM9_extract_public_key() return a pointer to an allocated B<SM9_KEY> structure or NULL on error.
+
+SM9_extract_private_key()和SM9_extract_public_key()返回一个指向已分配的B<SM9_KEY>结构的指针。如果发生错误则返回NULL。
 
 =head1 CONFORMING TO
 
diff --git a/doc/crypto/ZUC_set_key.pod b/doc/crypto/ZUC_set_key.pod
index d80f5eb54..157c1176e 100644
--- a/doc/crypto/ZUC_set_key.pod
+++ b/doc/crypto/ZUC_set_key.pod
@@ -16,32 +16,27 @@ ZUC_set_key, ZUC_generate_keystream, ZUC_generate_keyword - ZUC Stream Cipher
 
 =head1 DESCRIPTION
 
-Applications should use the higher level functions
-L<EVP_DigestInit(3)> etc. instead of calling the hash
-functions directly.
+ZUC_set_key() sets up the B<ZUC_KEY> key using the B<user_key> and initial vector B<iv>.
 
-SM3 (ShangMi#3 Hash Algorithm) is a cryptographic hash function with a
-256 bit output.
+ZUC_set_key()通过用户的密钥B<user_key>以及初始向量B<iv>来设置密钥结构B<ZUC_KEY>。
 
-sm3() computes the SM3 message digest of the B<n>
-bytes at B<d> and places it in B<md> (which must have space for
-SHA_DIGEST_LENGTH == 20 bytes of output). If B<md> is NULL, the digest
-is placed in a static array. Note: setting B<md> to NULL is B<not thread safe>.
+ZUC_generate_keystream() computes 32-bit keywords for B<nwords> times by a B<ZUC_KEY> structure, and stores them in the given B<words> array(pointer).
 
-The following functions may be used if the message is not completely
-stored in memory:
+ZUC_generate_keystream()通过函数参数中的B<ZUC_KEY>结构计算B<nwords>个32-bit的密钥字，并装入给定的B<words>数组中。
 
-sm3_nit() initializes a B<sm3_ctx_t> structure.
+ZUC_generate_keyword() is simliar to ZUC_generate_keystream(), but computes keyword only once and return this value.
 
-sm3_update() can be called repeatedly with chunks of the message to
-be hashed (B<len> bytes at B<data>).
-
-sm3_final() places the message digest in B<md>, which must have space
-for SM3_DIGEST_LENGTH == 32 bytes of output, and erases the B<sm3_ctx_t>.
+ZUC_generate_keyword()与ZUC_generate_keystream()相似，但只计算一次并直接返回该密钥字的值。
 
 =head1 RETURN VALUES
 
-sm3_init(), sm3_update(), sm3_final(), sm3_compress() and sm3() return void.
+ZUC_set_key() and ZUC_generate_keystream() have no return value.
+
+ZUC_set_key()和ZUC_generate_keystream()无返回值。
+
+ZUC_generate_keyword() returns a 32-bit unsigned integer.
+
+ZUC_generate_keyword()返回一个32位无符号整数。
 
 =head1 CONFORMING TO