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:: 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:: 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:: 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:: 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:: 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:: 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:: > 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:: > 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:: 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:: 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:: >= 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:: >= 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:: >= 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:: 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:: 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:: 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 const 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; const 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:: 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:: 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:: 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:: 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:: 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:: 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:: 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:: 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:: 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:: 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:: 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); }