esp-idf/components/openssl/OpenSSL-APIs.rst

1861 lines
31 KiB
ReStructuredText

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);
}