diff --git a/components/openssl/OpenSSL-APIs.rst b/components/openssl/OpenSSL-APIs.rst index ff91d2ebb7..5a44794cd2 100644 --- a/components/openssl/OpenSSL-APIs.rst +++ b/components/openssl/OpenSSL-APIs.rst @@ -1,1478 +1,1487 @@ -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 \ No newline at end of file +OpenSSL-APIs +============ + +All original source code in this repository is Copyright (C) 2015-2016 +Espressif Systems. This source code is licensed under the Apache +License 2.0 as described in the file LICENSE. + +Chapter Introduction +==================== + +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); + } +