components/openssl: optimize the OpenSSL APIs brief document

1. change document name
2. change function introduction template

components/openssl/OpenSSL-APIs.rst

@@ -0,0 +1,1478 @@
+OpenSSL-APIs 
+======================
+
+Chapter 1. SSL Context Method Create
+Chapter 2. SSL Context Fucntion
+Chapter 3. SSL Fucntion
+Chapter 4. SSL X509 Certification and Private Key Function
+
+======================
+Chapter 1. SSL Context Method Create 
+
+1.1 const SSL_METHOD* SSLv23_client_method(void);
+
+    Arguments : none
+    
+    Return : SSLV2 and 3 version SSL context client method point
+    
+    Description : create the target SSL context method
+    
+    Example :
+    
+        void example(void)
+        {
+            const SSL_METHOD *method = SSLv23_client_method();
+ 
+            ...
+        }
+
+
+1.2 const SSL_METHOD* TLSv1_client_method(void);
+
+    Arguments : none
+    
+    Return : TLSV1.0 version SSL context client method point
+    
+    Description : create the target SSL context method
+    
+    Example :
+    
+        void example(void)
+        {
+            const SSL_METHOD *method = TLSv1_client_method();
+ 
+            ...
+        }
+
+
+1.3 const SSL_METHOD* SSLv3_client_method(void);
+
+    Arguments : none
+    
+    Return : SSLV3.0 version SSL context client method point
+    
+    Description : create the target SSL context method
+    
+    Example :
+    
+        void example(void)
+        {
+            const SSL_METHOD *method = SSLv3_client_method();
+ 
+            ...
+        }
+
+
+1.4 const SSL_METHOD* TLSv1_1_client_method(void);
+
+    Arguments : none
+    
+    Return : TLSV1.1 version SSL context client method point
+    
+    Description : create the target SSL context method
+    
+    Example :
+    
+        void example(void)
+        {
+            const SSL_METHOD *method = TLSv1_1_client_method();
+ 
+            ...
+        }
+
+
+1.5 const SSL_METHOD* TLSv1_2_client_method(void);
+
+    Arguments : none
+    
+    Return : TLSV1.2 version SSL context client method point
+    
+    Description : create the target SSL context method
+    
+    Example :
+    
+        void example(void)
+        {
+            const SSL_METHOD *method = TLSv1_2_client_method();
+ 
+            ...
+        }
+
+
+1.6 const SSL_METHOD* SSLv23_server_method(void);
+
+    Arguments : none
+    
+    Return : SSLV2 and 3 version SSL context server method point
+    
+    Description : create the target SSL context method
+    
+    Example :
+    
+        void example(void)
+        {
+            const SSL_METHOD *method = SSLv23_server_method();
+ 
+            ...
+        }
+
+
+1.7 const SSL_METHOD* TLSv1_1_server_method(void);
+
+    Arguments : none
+    
+    Return : TLSV1.1 version SSL context server method point
+    
+    Description : create the target SSL context method
+    
+    Example :
+    
+        void example(void)
+        {
+            const SSL_METHOD *method = TLSv1_1_server_method();
+ 
+            ...
+        }
+
+
+1.8 const SSL_METHOD* TLSv1_2_server_method(void);
+
+    Arguments : none
+    
+    Return : TLSV1.2 version SSL context server method point
+    
+    Description : create the target SSL context method
+    
+    Example :
+    
+        void example(void)
+        {
+            const SSL_METHOD *method = TLSv1_2_server_method();
+ 
+            ...
+        }
+
+
+1.9 const SSL_METHOD* TLSv1_server_method(void);
+
+    Arguments : none
+    
+    Return : TLSV1.0 version SSL context server method point
+    
+    Description : create the target SSL context method
+    
+    Example :
+    
+        void example(void)
+        {
+            const SSL_METHOD *method = TLSv1_server_method();
+ 
+            ...
+        }
+
+
+1.10 const SSL_METHOD* SSLv3_server_method(void);
+
+    Arguments : none
+    
+    Return : SSLV3.0 version SSL context server method point
+    
+    Description : create the target SSL context method
+    
+    Example :
+    
+        void example(void)
+        {
+            const SSL_METHOD *method = SSLv3_server_method();
+ 
+            ...
+        }
+
+
+======================
+Chapter 2. SSL Context Fucntion
+
+2.1 SSL_CTX* SSL_CTX_new(const SSL_METHOD *method);
+
+    Arguments : method - the SSL context method point
+    
+    Return : context point
+    
+    Description : create a SSL context
+    
+    Example :
+    
+        void example(void)
+        {
+            SSL_CTX *ctx = SSL_CTX_new(SSLv3_server_method());
+ 
+            ...
+        }
+
+
+2.2 void SSL_CTX_free(SSL_CTX *ctx);
+
+    Arguments : ctx - the SSL context point
+    
+    Return : none
+    
+    Description : free a SSL context
+    
+    Example :
+    
+        void example(void)
+        {
+            SSL_CTX *ctx;
+        
+            ... ...
+            
+            SSL_CTX_free(ctx);
+        }
+
+
+2.3 int SSL_CTX_set_ssl_version(SSL_CTX *ctx, const SSL_METHOD *meth);
+
+    Arguments : ctx  - SSL context point
+                meth - SSL method point
+    
+    Return : result
+        1 : OK
+        0 : failed
+    
+    Description : set the SSL context version
+    
+    Example :
+    
+        void example(void)
+        {
+            SSL_CTX *ctx;
+            const SSL_METHOD *meth;
+            
+            ... ...
+            
+            SSL_CTX_set_ssl_version(ctx, meth);    
+        }
+
+
+2.4 const SSL_METHOD *SSL_CTX_get_ssl_method(SSL_CTX *ctx);
+
+    Arguments : ctx - SSL context point
+    
+    Return : SSL context method
+    
+    Description : get the SSL context method
+    
+    Example :
+    
+        void example(void)
+        {
+            const SSL_METHOD *method;
+            SSL_CTX *ctx;
+            
+            ... ...
+                
+            method = SSL_CTX_get_ssl_method(ctx);    
+        }
+
+
+======================
+Chapter 3. SSL Fucntion
+
+3.1 SSL* SSL_new(SSL_CTX *ctx);
+
+    Arguments : ctx - SSL context point
+    
+    Return : SSL method
+    
+    Description : create a SSL
+    
+    Example :
+    
+        void example(void)
+        {
+            SSL *ssl;
+            SSL_CTX *ctx;
+
+            ... ...
+   
+            ssl = SSL_new(ctx);
+        }
+
+
+3.2 void SSL_free(SSL *ssl);
+
+    Arguments : ssl - SSL point
+    
+    Return : none
+    
+    Description : free SSL
+    
+    Example :
+    
+        void example(void)
+        {
+            SSL *ssl;
+            
+            ... ...
+            
+            SSL_free(ssl);
+        }
+        
+
+3.3 int SSL_do_handshake(SSL *ssl);
+
+    Arguments : ssl - SSL point
+    
+    Return : result
+        1 : OK
+        0 : failed, connect is close by remote
+       -1 : a error catch
+    
+    Description : perform the SSL handshake
+    
+    Example :
+    
+        void example(void)
+        {
+            SSL *ssl;
+            int ret;
+            
+            ... ...
+            
+            ret = SSL_do_handshake(ssl);
+        }
+
+
+3.4 int SSL_connect(SSL *ssl);
+
+    Arguments : ssl - SSL point
+    
+    Return : result
+        1 : OK
+        0 : failed, connect is close by remote
+       -1 : a error catch
+    
+    Description : connect to the remote SSL server
+    
+    Example :
+    
+        void example(void)
+        {
+            SSL *ssl;
+            int ret;
+            
+            ... ...
+            
+            ret = SSL_connect(ssl);
+        }
+
+
+3.5 int SSL_accept(SSL *ssl);
+
+    Arguments : ssl - SSL point
+    
+    Return : result
+        1 : OK
+        0 : failed, connect is close by remote
+       -1 : a error catch
+    
+    Description : accept the remote connection
+    
+    Example :
+    
+        void example(void)
+        {
+            SSL *ssl;
+            int ret;
+            
+            ... ...
+            
+            ret = SSL_accept(ssl);
+        }
+
+
+3.6 int SSL_shutdown(SSL *ssl);
+
+    Arguments : ssl - SSL point
+    
+    Return : result
+        1 : OK
+        0 : failed, connect is close by remote
+       -1 : a error catch
+    
+    Description : shutdown the connection
+    
+    Example :
+    
+        void example(void)
+        {
+            SSL *ssl;
+            int ret;
+            
+            ... ...
+            
+            ret = SSL_shutdown(ssl);
+        }
+
+
+3.7 int SSL_clear(SSL *ssl);
+
+    Arguments : ssl - SSL point
+    
+    Return : result
+        1 : OK
+        0 : failed
+        
+    Description : shutdown the connection
+    
+    Example :
+    
+        void example(void)
+        {
+            SSL *ssl;
+            int ret;
+            
+            ... ...
+            
+            ret = SSL_clear(ssl);
+        }
+
+
+3.8 int SSL_read(SSL *ssl, void *buffer, int len);
+
+    Arguments : ssl    - point
+                buffer - data buffer point
+                len    - data length
+    
+    Return : result
+        > 0 : OK, and return received data bytes
+        = 0 : no data received or connection is closed
+        < 0 : an error catch
+        
+    Description : read data from remote
+    
+    Example :
+    
+        void example(void)
+        {
+            SSL *ssl;
+            char *buf;
+            int len;
+            int ret;
+            
+            ... ...
+            
+            ret = SSL_read(ssl, buf, len);
+        }
+
+3.9 int SSL_write(SSL *ssl, const void *buffer, int len);
+
+    Arguments : ssl    - SSL point
+                buffer - data buffer point
+                len    - data length
+    
+    Return : result
+        > 0 : OK, and return received data bytes
+        = 0 : no data sent or connection is closed
+        < 0 : an error catch
+        
+    Description : send the data to remote
+    
+    Example :
+    
+        void example(void)
+        {
+            SSL *ssl;
+            char *buf;
+            int len;
+            int ret;
+            
+            ... ...
+            
+            ret = SSL_write(ssl, buf, len);
+        }
+
+
+3.10 SSL_CTX *SSL_get_SSL_CTX(const SSL *ssl);
+
+    Arguments : ssl - SSL point
+    
+    Return : SSL context
+        
+    Description : get SSL context of the SSL
+    
+    Example :
+    
+        void example(void)
+        {
+            SSL *ssl;
+            SSL_CTX *ctx;
+            
+            ... ...
+            
+            ctx = SSL_get_SSL_CTX(ssl);
+        }
+
+
+3.11 int SSL_get_shutdown(const SSL *ssl);
+
+    Arguments : ssl - SSL point
+    
+    Return : shutdown mode
+        
+    Description : get SSL shutdown mode
+    
+    Example :
+    
+        void example(void)
+        {
+            SSL *ssl;
+            int mode;
+            
+            ... ...
+            
+            mode = SSL_get_SSL_CTX(ssl);
+        }
+
+
+3.12 void SSL_set_shutdown(SSL *ssl, int mode);
+
+    Arguments : ssl - SSL point
+    
+    Return : shutdown mode
+        
+    Description : set SSL shutdown mode
+    
+    Example :
+    
+        void example(void)
+        {
+            SSL *ssl;
+            int mode = 0;
+            
+            ... ...
+            
+            SSL_set_shutdown(ssl, mode);
+        }
+
+
+3.13 const SSL_METHOD *SSL_get_ssl_method(SSL *ssl);
+
+    Arguments : ssl - SSL point
+    
+    Return : SSL method
+        
+    Description : set SSL shutdown mode
+    
+    Example :
+    
+        void example(void)
+        {
+            SSL *ssl;
+            const SSL_METHOD *method;
+            
+            ... ...
+            
+            method = SSL_get_ssl_method(ssl);
+        }
+        
+
+3.14 int SSL_set_ssl_method(SSL *ssl, const SSL_METHOD *method);
+
+    Arguments : ssl  - SSL point
+                meth - SSL method point
+    
+    Return : result
+        1 : OK
+        0 : failed
+        
+    Description : set the SSL method
+    
+    Example :
+    
+        void example(void)
+        {
+            int ret;
+            SSL *ssl;
+            const SSL_METHOD *method;
+            
+            ... ...
+            
+            ret = SSL_set_ssl_method(ssl, method);
+        }
+
+
+3.15 int SSL_pending(const SSL *ssl);
+
+    Arguments : ssl - SSL point
+    
+    Return : data bytes
+        
+    Description : get received data bytes
+    
+    Example :
+    
+        void example(void)
+        {
+            int ret;
+            SSL *ssl;
+            
+            ... ...
+            
+            ret = SSL_pending(ssl);
+        }
+
+
+3.16 int SSL_has_pending(const SSL *ssl);
+
+    Arguments : ssl - SSL point
+    
+    Return : result
+        1 : Yes
+        0 : No
+        
+    Description : check if data is received
+    
+    Example :
+    
+        void example(void)
+        {
+            int ret;
+            SSL *ssl;
+            
+            ... ...
+            
+            ret = SSL_has_pending(ssl);
+        }
+
+
+3.17 int SSL_get_fd(const SSL *ssl);
+
+    Arguments : ssl - SSL point
+    
+    Return : result
+        >= 0 : socket id
+         < 0 : a error catch
+        
+    Description : get the socket of the SSL
+    
+    Example :
+    
+        void example(void)
+        {
+            int ret;
+            SSL *ssl;
+            
+            ... ...
+            
+            ret = SSL_get_fd(ssl);
+        }
+
+
+3.18 int SSL_get_rfd(const SSL *ssl);
+
+    Arguments : ssl - SSL point
+    
+    Return : result
+        >= 0 : socket id
+         < 0 : a error catch
+        
+    Description : get the read only socket of the SSL
+    
+    Example :
+    
+        void example(void)
+        {
+            int ret;
+            SSL *ssl;
+            
+            ... ...
+            
+            ret = SSL_get_rfd(ssl);
+        }
+
+
+3.19 int SSL_get_wfd(const SSL *ssl);
+
+    Arguments : ssl - SSL point
+    
+    Return : result
+        >= 0 : socket id
+         < 0 : a error catch
+        
+    Description : get the write only socket of the SSL
+    
+    Example :
+    
+        void example(void)
+        {
+            int ret;
+            SSL *ssl;
+            
+            ... ...
+            
+            ret = SSL_get_wfd(ssl);
+        }
+
+
+3.20 int SSL_set_fd(SSL *ssl, int fd);
+
+    Arguments : ssl - SSL point
+                fd  - socket id
+    
+    Return : result
+        1 : OK
+        0 : failed
+        
+    Description : set socket to SSL
+    
+    Example :
+    
+        void example(void)
+        {
+            int ret;
+            SSL *ssl;
+            int socket;
+                        
+            ... ...
+            
+            ret = SSL_set_fd(ssl, socket);
+        }
+
+
+3.21 int SSL_set_rfd(SSL *ssl, int fd);
+
+    Arguments : ssl - SSL point
+                fd  - socket id
+    
+    Return : result
+        1 : OK
+        0 : failed
+        
+    Description : set read only socket to SSL
+    
+    Example :
+    
+        void example(void)
+        {
+            int ret;
+            SSL *ssl;
+            int socket;
+                        
+            ... ...
+            
+            ret = SSL_set_rfd(ssl, socket);
+        }
+        
+
+3.22 int SSL_set_wfd(SSL *ssl, int fd);
+
+    Arguments : ssl - SSL point
+                fd  - socket id
+    
+    Return : result
+        1 : OK
+        0 : failed
+        
+    Description : set write only socket to SSL
+    
+    Example :
+    
+        void example(void)
+        {
+            int ret;
+            SSL *ssl;
+            int socket;
+                        
+            ... ...
+            
+            ret = SSL_set_wfd(ssl, socket);
+        }
+        
+
+3.23 int SSL_version(const SSL *ssl);
+
+    Arguments : ssl - SSL point
+    
+    Return : SSL version
+        
+    Description : get SSL version
+    
+    Example :
+    
+        void example(void)
+        {
+            int version;
+            SSL *ssl;
+                        
+            ... ...
+            
+            version = SSL_version(ssl);
+        }
+
+
+3.24 const char *SSL_get_version(const SSL *ssl);
+
+    Arguments : ssl - SSL point
+    
+    Return : SSL version string
+        
+    Description : get the SSL current version string
+    
+    Example :
+    
+        void example(void)
+        {
+            char *version;
+            SSL *ssl;
+                        
+            ... ...
+            
+            version = SSL_get_version(ssl);
+        }
+        
+        
+3.25 OSSL_HANDSHAKE_STATE SSL_get_state(const SSL *ssl);
+
+    Arguments : ssl - SSL point
+    
+    Return : SSL state
+        
+    Description : get the SSL state
+    
+    Example :
+    
+        void example(void)
+        {
+            OSSL_HANDSHAKE_STATE state;
+            SSL *ssl;
+                        
+            ... ...
+            
+            state = SSL_get_state(ssl);
+        }
+
+
+3.26 const char *SSL_alert_desc_string(int value);
+
+    Arguments : value - SSL description
+    
+    Return : alert value string
+        
+    Description : get alert description string
+    
+    Example :
+    
+        void example(void)
+        {
+            int val;
+            char *str;
+                        
+            ... ...
+            
+            str = SSL_alert_desc_string(val);
+        }
+
+
+3.27 const char *SSL_alert_desc_string_long(int value);
+
+    Arguments : value - SSL description
+    
+    Return : alert value long string
+        
+    Description : get alert description long string
+    
+    Example :
+    
+        void example(void)
+        {
+            int val;
+            char *str;
+                        
+            ... ...
+            
+            str = SSL_alert_desc_string_long(val);
+        }
+
+
+3.28 const char *SSL_alert_type_string(int value);
+
+    Arguments : value - SSL type description
+    
+    Return : alert type string
+        
+    Description : get alert type string
+    
+    Example :
+    
+        void example(void)
+        {
+            int val;
+            char *str;
+                        
+            ... ...
+            
+            str = SSL_alert_type_string(val);
+        }
+        
+        
+3.29 const char *SSL_alert_type_string_long(int value);
+
+    Arguments : value - SSL type description
+    
+    Return : alert type long string
+        
+    Description : get alert type long string
+    
+    Example :
+    
+        void example(void)
+        {
+            int val;
+            char *str;
+                        
+            ... ...
+            
+            str = SSL_alert_type_string_long(val);
+        }
+
+3.30 const char *SSL_rstate_string(SSL *ssl);
+
+    Arguments : ssl - SSL point
+    
+    Return : state string
+        
+    Description : get the state string where SSL is reading
+    
+    Example :
+    
+        void example(void)
+        {
+            SSL *ssl;
+            char *str;
+                        
+            ... ...
+            
+            str = SSL_rstate_string(ssl);
+        }
+        
+
+3.31 const char *SSL_rstate_string_long(SSL *ssl);
+
+    Arguments : ssl - SSL point
+    
+    Return : state long string
+        
+    Description : get the state long string where SSL is reading
+    
+    Example :
+    
+        void example(void)
+        {
+            SSL *ssl;
+            char *str;
+                        
+            ... ...
+            
+            str = SSL_rstate_string_long(ssl);
+        }
+
+
+3.32 char *SSL_state_string(const SSL *ssl);
+
+    Arguments : ssl - SSL point
+    
+    Return : state string
+        
+    Description : get the state string
+    
+    Example :
+    
+        void example(void)
+        {
+            SSL *ssl;
+            char *str;
+                        
+            ... ...
+            
+            str = SSL_state_string(ssl);
+        }
+
+
+3.33 char *SSL_state_string_long(const SSL *ssl);
+
+    Arguments : ssl - SSL point
+    
+    Return : state long string
+        
+    Description : get the state long string
+    
+    Example :
+    
+        void example(void)
+        {
+            SSL *ssl;
+            char *str;
+                        
+            ... ...
+            
+            str = SSL_state_string(ssl);
+        }
+
+
+3.34 int SSL_get_error(const SSL *ssl, int ret_code);
+
+    Arguments : ssl      - SSL point
+                ret_code - SSL return code
+    
+    Return : SSL error number
+        
+    Description : get SSL error code
+    
+    Example :
+    
+        void example(void)
+        {
+            SSL *ssl;
+            int ret;
+            int err;
+                        
+            ... ...
+            
+            err = SSL_get_error(ssl, ret);
+        }
+        
+3.35 void SSL_CTX_set_default_read_buffer_len(SSL_CTX *ctx, size_t len);
+
+    Arguments : ctx - SSL context point
+                len - read buffer length
+    
+    Return : none
+        
+    Description : set the SSL context read buffer length
+    
+    Example :
+    
+        void example(void)
+        {
+            SSL_CTX *ctx;
+            size_t len;
+                        
+            ... ...
+            
+            SSL_CTX_set_default_read_buffer_len(ctx, len);
+        }
+        
+
+3.36 void SSL_set_default_read_buffer_len(SSL *ssl, size_t len);
+
+    Arguments : ssl - SSL point
+                len - read buffer length
+    
+    Return : none
+        
+    Description : set the SSL read buffer length
+    
+    Example :
+    
+        void example(void)
+        {
+            SSL *ssl;
+            size_t len;
+                        
+            ... ...
+            
+            SSL_set_default_read_buffer_len(ctx, len);
+        }
+
+
+3.37 int SSL_want(const SSL *ssl);
+
+    Arguments : ssl - SSL point
+    
+    Return : specifical statement
+        
+    Description : get the SSL specifical statement
+    
+    Example :
+    
+        void example(void)
+        {
+            SSL *ssl;
+            int state;
+                        
+            ... ...
+            
+            state = SSL_want(ssl);
+        }
+        
+
+3.38 int SSL_want_nothing(const SSL *ssl);
+
+    Arguments : ssl - SSL point
+    
+    Return : result
+        0 : false
+        1 : true
+        
+    Description : check if SSL want nothing
+    
+    Example :
+    
+        void example(void)
+        {
+            SSL *ssl;
+            int ret;
+                        
+            ... ...
+            
+            ret = SSL_want(ssl);
+        }
+        
+        
+3.39 int SSL_want_read(const SSL *ssl);
+
+    Arguments : ssl - SSL point
+    
+    Return : result
+        0 : false
+        1 : true
+        
+    Description : check if SSL want to read
+    
+    Example :
+    
+        void example(void)
+        {
+            SSL *ssl;
+            int ret;
+                        
+            ... ...
+            
+            ret = SSL_want_read(ssl);
+        }
+
+
+3.40 int SSL_want_write(const SSL *ssl);
+
+    Arguments : ssl - SSL point
+    
+    Return : result
+        0 : false
+        1 : true
+        
+    Description : check if SSL want to write
+    
+    Example :
+    
+        void example(void)
+        {
+            SSL *ssl;
+            int ret;
+                        
+            ... ...
+            
+            ret = SSL_want_write(ssl);
+        }        
+
+======================
+Chapter 4. SSL X509 Certification and Private Key Function
+
+4.1 X509* d2i_X509(X509 **cert, const unsigned char *buffer, long len);
+
+    Arguments : cert   - a point pointed to X509 certification
+                buffer - a point pointed to the certification context memory point
+                length - certification bytes
+    
+    Return : X509 certification object point
+        
+    Description : load a character certification context into system context. If '*cert' is pointed to the
+                  certification, then load certification into it. Or create a new X509 certification object
+    
+    Example :
+    
+        void example(void)
+        {
+            X509 *new;
+            X509 *cert;
+            unsigned char *buffer;
+            long len;            
+            ... ...
+            
+            new = d2i_X509(&cert, buffer, len);
+        }
+
+
+4.2 int SSL_add_client_CA(SSL *ssl, X509 *x);
+
+    Arguments : ssl - SSL point
+                x   - CA certification point
+    
+    Return : result
+        1 : OK
+        0 : failed
+        
+    Description : add CA client certification into the SSL
+    
+    Example :
+    
+        void example(void)
+        {
+            int ret;
+            SSL *ssl;
+            X509 *new;
+                        
+            ... ...
+            
+            ret = SSL_add_client_CA(ssl, new);
+        }
+
+
+4.3 int SSL_CTX_add_client_CA(SSL_CTX *ctx, X509 *x);
+
+    Arguments : ctx - SSL context point
+                x   - CA certification point
+    
+    Return : result
+        1 : OK
+        0 : failed
+        
+    Description : add CA client certification into the SSL context
+    
+    Example :
+    
+        void example(void)
+        {
+            int ret;
+            SSL_CTX *ctx;
+            X509 *new;
+                        
+            ... ...
+            
+            ret = SSL_add_clSSL_CTX_add_client_CAient_CA(ctx, new);
+        }
+
+
+4.4 X509 *SSL_get_certificate(const SSL *ssl);
+
+    Arguments : ssl - SSL point
+    
+    Return : SSL certification point
+        
+    Description : get the SSL certification point
+    
+    Example :
+    
+        void example(void)
+        {
+            SSL *ssl;
+            X509 *cert;
+                        
+            ... ...
+            
+            cert = SSL_get_certificate(ssl);
+        }
+
+
+4.5 long SSL_get_verify_result(const SSL *ssl);
+
+    Arguments : ssl - SSL point
+    
+    Return : the result of verifying
+        
+    Description : get the verifying result of the SSL certification
+    
+    Example :
+    
+        void example(void)
+        {
+            SSL *ssl;
+            long ret;
+                        
+            ... ...
+            
+            ret = SSL_get_verify_result(ssl);
+        }
+
+
+4.6 int SSL_CTX_use_certificate(SSL_CTX *ctx, X509 *x);
+
+    Arguments : ctx  - the SSL context point
+                pkey - certification object point
+    
+    Return : result
+        1 : OK
+        0 : failed
+        
+    Description : load the certification into the SSL_CTX or SSL object
+    
+    Example :
+    
+        void example(void)
+        {
+            int ret;
+            SSL_CTX *ctx
+            X509 *new;
+                        
+            ... ...
+            
+            ret = SSL_CTX_use_certificate(ctx, new);
+        }
+
+
+4.7 int SSL_CTX_use_certificate_ASN1(SSL_CTX *ctx, int len, const unsigned char *d);
+
+    Arguments : ctx - SSL context point
+                len - certification length
+                d   - data point
+    
+    Return : result
+        1 : OK
+        0 : failed
+        
+    Description : load the ASN1 certification into SSL context
+    
+    Example :
+    
+        void example(void)
+        {
+            int ret;
+            SSL_CTX *ctx;
+            const unsigned char *buf;
+            int len;
+                        
+            ... ...
+            
+            ret = SSL_CTX_use_certificate_ASN1(ctx, len, buf);
+        }
+        
+
+4.8 int SSL_CTX_use_PrivateKey(SSL_CTX *ctx, EVP_PKEY *pkey);
+
+    Arguments : ctx - SSL context point
+                pkey - private key object point
+    
+    Return : result
+        1 : OK
+        0 : failed
+        
+    Description : load the private key into the context object
+    
+    Example :
+    
+        void example(void)
+        {
+            int ret;
+            SSL_CTX *ctx;
+            EVP_PKEY *pkey;
+                        
+            ... ...
+            
+            ret = SSL_CTX_use_PrivateKey(ctx, pkey);
+        }
+
+
+4.9 int SSL_CTX_use_PrivateKey_ASN1(int pk, SSL_CTX *ctx, const unsigned char *d,  long len);
+
+    Arguments : ctx - SSL context point
+                d   - data point
+                len - private key length
+    
+    Return : result
+        1 : OK
+        0 : failed
+        
+    Description : load the ASN1 private key into SSL context
+    
+    Example :
+    
+        void example(void)
+        {
+            int ret;
+            int pk;
+            SSL_CTX *ctx;
+            const unsigned char *buf;
+            long len;
+                        
+            ... ...
+            
+            ret = SSL_CTX_use_PrivateKey_ASN1(pk, ctx, buf, len);
+        }
+        
+
+4.10 int SSL_CTX_use_RSAPrivateKey_ASN1(SSL_CTX *ctx, const unsigned char *d, long len);
+
+    Arguments : ctx - SSL context point
+                d   - data point
+                len - private key length
+    
+    Return : result
+        1 : OK
+        0 : failed
+        
+    Description : load the RSA ASN1 private key into SSL context
+    
+    Example :
+    
+        void example(void)
+        {
+            int ret;
+            SSL_CTX *ctx;
+            const unsigned char *buf;
+            long len;
+                        
+            ... ...
+            
+            ret = SSL_CTX_use_RSAPrivateKey_ASN1(ctx, buf, len);
+        }
+
+
+4.11 int SSL_use_certificate_ASN1(SSL *ssl, int len, const unsigned char *d);
+
+    Arguments : ssl - SSL point
+                len - data bytes
+                d   - data point
+    
+    Return : result
+        1 : OK
+        0 : failed
+        
+    Description : load certification into the SSL
+    
+    Example :
+    
+        void example(void)
+        {
+            int ret;
+            SSL *ssl;
+            const unsigned char *buf;
+            long len;
+                        
+            ... ...
+            
+            ret = SSL_use_certificate_ASN1(ssl, len, buf);
+        }
+
+
+4.12 X509 *SSL_get_peer_certificate(const SSL *ssl);
+
+    Arguments : ssl - SSL point
+    
+    Return : peer certification
+        
+    Description : get peer certification
+    
+    Example :
+    
+        void example(void)
+        {
+            SSL *ssl;
+            X509 *peer;
+                        
+            ... ...
+            
+            peer = SSL_get_peer_certificate(ssl);
+        }
+
+======================
+END

components/openssl/OpenSSL_APIs.rst

@@ -1,688 +0,0 @@
-OpenSSL APIs 
-======================
-
-/**
- * @brief create the target SSL context client method
- *
- * @param none
- *
- * @return the SSLV2.3 version SSL context client method
- */
-const SSL_METHOD* SSLv23_client_method(void);
-
-
-/**
- * @brief create the target SSL context client method
- *
- * @param none
- *
- * @return the TLSV1.0 version SSL context client method
- */
-const SSL_METHOD* TLSv1_client_method(void);
-
-
-/**
- * @brief create the target SSL context client method
- *
- * @param none
- *
- * @return the SSLV1.0 version SSL context client method
- */
-const SSL_METHOD* SSLv3_client_method(void);
-
-
-/**
- * @brief create the target SSL context client method
- *
- * @param none
- *
- * @return the TLSV1.1 version SSL context client method
- */
-const SSL_METHOD* TLSv1_1_client_method(void);
-
-
-/**
- * @brief create the target SSL context client method
- *
- * @param none
- *
- * @return the TLSV1.2 version SSL context client method
- */
-const SSL_METHOD* TLSv1_2_client_method(void);
-
-
-/**
- * @brief create the target SSL context server method
- *
- * @param none
- *
- * @return the SSLV2.3 version SSL context server method
- */
-const SSL_METHOD* SSLv23_server_method(void);
-
-/**
- * @brief create the target SSL context server method
- *
- * @param none
- *
- * @return the TLSV1.1 version SSL context server method
- */
-const SSL_METHOD* TLSv1_1_server_method(void);
-
-/**
- * @brief create the target SSL context server method
- *
- * @param none
- *
- * @return the TLSV1.2 version SSL context server method
- */
-const SSL_METHOD* TLSv1_2_server_method(void);
-
-/**
- * @brief create the target SSL context server method
- *
- * @param none
- *
- * @return the TLSV1.0 version SSL context server method
- */
-const SSL_METHOD* TLSv1_server_method(void);
-
-/**
- * @brief create the target SSL context server method
- *
- * @param none
- *
- * @return the SSLV3.0 version SSL context server method
- */
-const SSL_METHOD* SSLv3_server_method(void);
-
-/**
- * @brief create a SSL context
- *
- * @param method - the SSL context method point
- *
- * @return the context point
- */
-SSL_CTX* SSL_CTX_new(const SSL_METHOD *method);
-
-/**
- * @brief free a SSL context
- *
- * @param method - the SSL context point
- *
- * @return none
- */
-void SSL_CTX_free(SSL_CTX *ctx);
-
-/**
- * @brief set  the SSL context version
- *
- * @param ctx  - SSL context point
- * @param meth - SSL method point
- *
- * @return result
- *     1 : OK
- *     0 : failed
- */
-int SSL_CTX_set_ssl_version(SSL_CTX *ctx, const SSL_METHOD *meth);
-
-/**
- * @brief get the SSL context current method
- *
- * @param ctx - SSL context point
- *
- * @return the SSL context current method
- */
-const SSL_METHOD *SSL_CTX_get_ssl_method(SSL_CTX *ctx);
-
-/**
- * @brief create a SSL
- *
- * @param ctx - the SSL context point
- *
- * @return the SSL point
- */
-SSL* SSL_new(SSL_CTX *ctx);
-
-/**
- * @brief free the SSL
- *
- * @param ssl - the SSL point
- *
- * @return none
- */
-void SSL_free(SSL *ssl);
-
-/**
- * @brief perform the SSL handshake
- *
- * @param ssl - SSL point
- *
- * @return result
- *     1 : OK
- *     0 : failed
- *    -1 : a error catch
- */
-int SSL_do_handshake(SSL *ssl);
-
-/**
- * @brief connect to the remote SSL server
- *
- * @param ssl - the SSL point
- *
- * @return result
- *     1 : OK
- *    -1 : failed
- */
-int SSL_connect(SSL *ssl);
-
-/**
- * @brief accept the remote connection
- *
- * @param ssl - the SSL point
- *
- * @return result
- *     1 : OK
- *    -1 : failed
- */
-int SSL_accept(SSL *ssl);
-
-/**
- * @brief shutdown the connection
- *
- * @param ssl - the SSL point
- *
- * @return result
- *     1 : OK
- *     0 : shutdown is not finished
- *    -1 : an error catch
- */
-int SSL_shutdown(SSL *ssl);
-
-/**
- * @brief reset the SSL
- *
- * @param ssl - SSL point
- *
- * @return result
- *     1 : OK
- *     0 : failed
- */
-int SSL_clear(SSL *ssl);
-
-/**
- * @brief read data from to remote
- *
- * @param ssl    - the SSL point which has been connected
- * @param buffer - the received data buffer point
- * @param len    - the received data length
- *
- * @return result
- *     > 0 : OK, and return received data bytes
- *     = 0 : connection is closed
- *     < 0 : an error catch
- */
-int SSL_read(SSL *ssl, void *buffer, int len);
-
-/**
- * @brief send the data to remote
- *
- * @param ssl    - the SSL point which has been connected
- * @param buffer - the send data buffer point
- * @param len    - the send data length
- *
- * @return result
- *     > 0 : OK, and return sent data bytes
- *     = 0 : connection is closed
- *     < 0 : an error catch
- */
-int SSL_write(SSL *ssl, const void *buffer, int len);
-
-/**
- * @brief get SSL context of the SSL
- *
- * @param ssl - SSL point
- *
- * @return SSL context
- */
-SSL_CTX *SSL_get_SSL_CTX(const SSL *ssl);
-
-/**
- * @brief get SSL shutdown mode
- *
- * @param ssl - SSL point
- *
- * @return shutdown mode
- */
-int SSL_get_shutdown(const SSL *ssl);
-
-/**
- * @brief set SSL shutdown mode
- *
- * @param ssl  - SSL point
- * @param mode - shutdown mode
- *
- * @return none
- */
-void SSL_set_shutdown(SSL *ssl, int mode);
-
-/**
- * @brief get the SSL current method
- *
- * @param ssl - SSL point
- *
- * @return the SSL current method
- */
-const SSL_METHOD *SSL_get_ssl_method(SSL *ssl);
-
-/**
- * @brief set the SSL method
- *
- * @param ssl  - SSL point
- * @param meth - SSL method point
- *
- * @return result
- *     1 : OK
- *     0 : failed
- */
-int SSL_set_ssl_method(SSL *ssl, const SSL_METHOD *method);
-
-/**
- * @brief get the bytes numbers which are to be read
- *
- * @param ssl  - SSL point
- *
- * @return bytes number
- */
-int SSL_pending(const SSL *ssl);
-
-/**
- * @brief check if some data can be read
- *
- * @param ssl - SSL point
- *
- * @return
- *     1 : there are bytes to be read
- *     0 : no data
- */
-int SSL_has_pending(const SSL *ssl);
-
-/**
- * @brief get the socket handle of the SSL
- *
- * @param ssl - SSL point
- *
- * @return result
- *     >= 0 : yes, and return socket handle
- *      < 0 : a error catch
- */
-int SSL_get_fd(const SSL *ssl);
-
-/**
- * @brief get the read only socket handle of the SSL
- *
- * @param ssl - SSL point
- *
- * @return result
- *     >= 0 : yes, and return socket handle
- *      < 0 : a error catch
- */
-int SSL_get_rfd(const SSL *ssl);
-
-/**
- * @brief get the write only socket handle of the SSL
- *
- * @param ssl - SSL point
- *
- * @return result
- *     >= 0 : yes, and return socket handle
- *      < 0 : a error catch
- */
-int SSL_get_wfd(const SSL *ssl);
-
-/**
- * @brief bind the socket file description into the SSL
- *
- * @param ssl - the SSL point
- * @param fd  - socket handle
- *
- * @return result
- *     1 : OK
- *     0 : failed
- */
-int SSL_set_fd(SSL *ssl, int fd);
-
-/**
- * @brief bind the read only socket file description into the SSL
- *
- * @param ssl - the SSL point
- * @param fd  - socket handle
- *
- * @return result
- *     1 : OK
- *     0 : failed
- */
-int SSL_set_rfd(SSL *ssl, int fd);
-
-/**
- * @brief bind the write only socket file description into the SSL
- *
- * @param ssl - the SSL point
- * @param fd  - socket handle
- *
- * @return result
- *     1 : OK
- *     0 : failed
- */
-int SSL_set_wfd(SSL *ssl, int fd);
-
-/**
- * @brief get SSL version
- *
- * @param ssl - SSL point
- *
- * @return SSL version
- */
-int SSL_version(const SSL *ssl);
-
-/**
- * @brief get the SSL current version
- *
- * @param ssl - SSL point
- *
- * @return the version string
- */
-const char *SSL_get_version(const SSL *ssl);
-
-/**
- * @brief get the SSL state
- *
- * @param ssl - SSL point
- *
- * @return SSL state
- */
-OSSL_HANDSHAKE_STATE SSL_get_state(const SSL *ssl);
-
-/**
- * @brief get alert description string
- *
- * @param value - alert value
- *
- * @return alert description string
- */
-const char *SSL_alert_desc_string(int value);
-
-/**
- * @brief get alert description long string
- *
- * @param value - alert value
- *
- * @return alert description long string
- */
-const char *SSL_alert_desc_string_long(int value);
-
-/**
- * @brief get alert type string
- *
- * @param value - alert value
- *
- * @return alert type string
- */
-const char *SSL_alert_type_string(int value);
-
-/**
- * @brief get alert type long string
- *
- * @param value - alert value
- *
- * @return alert type long string
- */
-const char *SSL_alert_type_string_long(int value);
-
-/**
- * @brief get the state string where SSL is reading
- *
- * @param ssl - SSL point
- *
- * @return state string
- */
-const char *SSL_rstate_string(SSL *ssl);
-
-/**
- * @brief get the statement long string where SSL is reading
- *
- * @param ssl - SSL point
- *
- * @return statement long string
- */
-const char *SSL_rstate_string_long(SSL *ssl);
-
-/**
- * @brief get SSL statement string
- *
- * @param ssl - SSL point
- *
- * @return SSL statement string
- */
-char *SSL_state_string(const SSL *ssl);
-
-/**
- * @brief get SSL statement long string
- *
- * @param ssl - SSL point
- *
- * @return SSL statement long string
- */
-char *SSL_state_string_long(const SSL *ssl);
-
-/**
- * @brief get SSL error code
- *
- * @param ssl       - SSL point
- * @param ret_code  - SSL return code
- *
- * @return SSL error number
- */
-int SSL_get_error(const SSL *ssl, int ret_code);
-
-/**
- * @brief load a character certification context into system context. If '*cert' is pointed to the
- *        certification, then load certification into it. Or create a new X509 certification object
- *
- * @param cert   - a point pointed to X509 certification
- * @param buffer - a point pointed to the certification context memory point
- * @param length - certification bytes
- *
- * @return X509 certification object point
- */
-X509* d2i_X509(X509 **cert, const unsigned char *buffer, long len);
-
-/**
- * @brief add CA client certification into the SSL
- *
- * @param ssl - SSL point
- * @param x   - CA certification point
- *
- * @return result
- *     1 : OK
- *     0 : failed
- */
-int SSL_add_client_CA(SSL *ssl, X509 *x);
-
-/**
- * @brief add CA client certification into the SSL context
- *
- * @param ctx - SSL context point
- * @param x   - CA certification point
- *
- * @return result
- *     1 : OK
- *     0 : failed
- */
-int SSL_CTX_add_client_CA(SSL_CTX *ctx, X509 *x);
-
-/**
- * @brief get the SSL certification point
- *
- * @param ssl - SSL point
- *
- * @return SSL certification point
- */
-X509 *SSL_get_certificate(const SSL *ssl);
-
-/**
- * @brief get the verifying result of the SSL certification
- *
- * @param ssl - the SSL point
- *
- * @return the result of verifying
- */
-long SSL_get_verify_result(const SSL *ssl);
-
-/**
- * @brief These functions load the certification into the SSL_CTX or SSL object
- *
- * @param ctx  - the SSL context point
- * @param pkey - certification object point
- *
- * @return result
- *     1 : OK
- *     0 : failed
- */
-int SSL_CTX_use_certificate(SSL_CTX *ctx, X509 *x);
-
-/**
- * @brief load the ASN1 certification into SSL context
- *
- * @param ctx - SSL context point
- * @param len - certification length
- * @param d   - data point
- *
- * @return result
- *     1 : OK
- *     0 : failed
- */
-int SSL_CTX_use_certificate_ASN1(SSL_CTX *ctx, int len, const unsigned char *d);
-
-/**
- * @brief These functions load the private key into the SSL_CTX or SSL object
- *
- * @param ctx  - the SSL context point
- * @param pkey - private key object point
- *
- * @return result
- *     1 : OK
- *     0 : failed
- */
-int SSL_CTX_use_PrivateKey(SSL_CTX *ctx, EVP_PKEY *pkey);
-
-/**
- * @brief load the ASN1 private key into SSL context
- *
- * @param ctx - SSL context point
- * @param d   - data point
- * @param len - private key length
- *
- * @return result
- *     1 : OK
- *     0 : failed
- */
-int SSL_CTX_use_PrivateKey_ASN1(int pk, SSL_CTX *ctx, const unsigned char *d,  long len);
-
-/**
- * @brief load the RSA ASN1 private key into SSL context
- *
- * @param ctx - SSL context point
- * @param d   - data point
- * @param len - RSA private key length
- *
- * @return result
- *     1 : OK
- *     0 : failed
- */
-int SSL_CTX_use_RSAPrivateKey_ASN1(SSL_CTX *ctx, const unsigned char *d, long len);
-
-/**
- * @brief load certification into the SSL
- *
- * @param ssl - SSL point
- * @param len - data bytes
- * @param d   - data point
- *
- * @return result
- *     0 : failed
- *     1 : OK
- *
- */
-int SSL_use_certificate_ASN1(SSL *ssl, int len, const unsigned char *d);
-
-/**
- * @brief get peer certification
- *
- * @param ssl - SSL point
- *
- * @return certification
- */
-X509 *SSL_get_peer_certificate(const SSL *ssl);
-
-/**
- * @brief set the SSL context read buffer length
- *
- * @param ctx - SSL context point
- * @param len - read buffer length
- *
- * @return none
- */
-void SSL_CTX_set_default_read_buffer_len(SSL_CTX *ctx, size_t len);
-
-/**
- * @brief set the SSL read buffer length
- *
- * @param ssl - SSL point
- * @param len - read buffer length
- *
- * @return none
- */
-void SSL_set_default_read_buffer_len(SSL *ssl, size_t len);
-
-/**
- * @brief get the SSL specifical statement
- *
- * @param ssl - SSL point
- *
- * @return specifical statement
- */
-int SSL_want(const SSL *ssl);
-
-/**
- * @brief check if SSL want nothing
- *
- * @param ssl - SSL point
- *
- * @return result
- *     0 : false
- *     1 : true
- */
-int SSL_want_nothing(const SSL *ssl);
-
-/**
- * @brief check if SSL want to read
- *
- * @param ssl - SSL point
- *
- * @return result
- *     0 : false
- *     1 : true 
- */
-int SSL_want_read(const SSL *ssl);
-
-/**
- * @brief check if SSL want to write
- *
- * @param ssl - SSL point
- *
- * @return result
- *     0 : false
- *     1 : true 
- */
-int SSL_want_write(const SSL *ssl);