OpenSSL-APIs ------------ This directory does not contain OpenSSL itself, but the code here can be used as a wrapper for applications using the OpenSSL API. It uses mbedTLS to do the actual work, so anyone compiling openssl code needs the mbedtls library and header file. OpenSSL APIs not mentioned in this article are not open to public for the time, also do not have the corresponding function. If user calls it directly, it will always return an error or may show cannot link at compiling time. 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* ``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.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* ``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.4 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.5 const SSL_METHOD* ``TLS_client_method`` (void) Arguments:: none Return:: TLSV1.2 version SSL context client method point Description:: create the default SSL context method, it's always to be TLSV1.2 Example:: void example(void) { const SSL_METHOD *method = TLSv1_2_client_method(); ... } 1.6 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(); ... } 1.7 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.8 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.9 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.10 const SSL_METHOD* ``TLS_server_method`` (void) Arguments:: none Return:: TLSV1.2 version SSL context server method point Description:: create the default SSL context method, it's always to be TLSV1.2 Example:: void example(void) { const SSL_METHOD *method = TLSv1_2_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 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.36 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.37 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.38 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); }