mirror of
https://github.com/espressif/esp-idf.git
synced 2025-10-31 15:11:40 +01:00
1800 lines
30 KiB
ReStructuredText
1800 lines
30 KiB
ReStructuredText
OpenSSL-APIs
|
|
------------
|
|
|
|
The code of this API (located in :component:`openssl` directory), does not contain OpenSSL itself but is intended 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 Function
|
|
- Chapter 3. SSL Function
|
|
- Chapter 4. SSL X509 Certification and Private Key Function
|
|
|
|
|
|
Chapter 1. SSL Context Method Create
|
|
====================================
|
|
|
|
.. highlight:: none
|
|
|
|
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 Function
|
|
===============================
|
|
|
|
|
|
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 Function
|
|
=======================
|
|
|
|
|
|
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);
|
|
}
|
|
|