Google Git
Sign in
coral / mcuxpresso_sdk / 20602c8dd7e6c22a33e76e7325f487e6858506c3 / . / rtos / freertos / doc / lib / https.txt
blob: 6da136d0f09d0e878fb4bec2623af4890c88ed01 [file] [log] [blame]
/**
@mainpage
@anchor https
@brief HTTPS Client v1.0.0 library.
- HTTPS Client Main page text.
> The Hypertext Transfer Protocol (HTTP) is a stateless application-level protocol for distributed, collaborative, hypertext information systems.
<span style="float:right;margin-right:4em"> &mdash; <i>Official description of HTTP from [RFC 7231](https://tools.ietf.org/html/rfc7231)</i></span><br>
This HTTP library implements a subset of the HTTP/1.1 standard for compatibility with the [AWS IoT HTTP Server](https://docs.aws.amazon.com/iot/latest/developerguide/http.html) and the [AWS S3 HTTP Server](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTObjectOps.html). It is also compatible with other HTTP servers. Feature of this library include:
- Both fully asynchronous and synchronous (blocking) API functions.
- Application managed memory for internal context and HTTP formatted headers.
- Thread-aware and parallelized connections.
@dependencies_section{https}
@dependencies_brief{HTTPS Client library}
@dot "HTTPS Client direct dependencies"
digraph https_dependencies
{
node[shape=box, fontname=Helvetica, fontsize=10, style=filled];
edge[fontname=Helvetica, fontsize=10];
subgraph
{
https[label="HTTPS", fillcolor="#cc00ccff"];
}
subgraph
{
node[fillcolor="#aed8a9ff"];
rank = same;
linear_containers[label="List/Queue", URL="@ref linear_containers"];
logging[label="Logging", URL="@ref logging"];
}
subgraph
{
rank = same;
platform_threads[label="Thread management", fillcolor="#e89025ff", URL="@ref platform_threads"];
platform_clock[label="Clock", fillcolor="#e89025ff", URL="@ref platform_clock"];
platform_network[label="Network", fillcolor="#e89025ff", URL="@ref platform_network"];
}
https -> linear_containers;
https -> logging [label=" if logging enabled", style="dashed"];
https -> platform_threads;
https -> platform_clock;
https -> platform_network;
logging -> platform_clock;
}
@enddot
Currently, the HTTPS Client library has the following dependencies:
- The queue library for maintaining of list of pending requests and responses on the connection.
- The logging library may be used if @ref IOT_LOG_LEVEL_HTTPS is not @ref IOT_LOG_NONE.
- The platform layer provides an interface to the operating system for thread management, clock functions, networking, etc.
In addition to the components above, the HTTPS Client library also depends on C standard library headers.
*/
/**
@page https_design Design
@brief Architecture behind the HTTPS library.
The HTTPS Client library will invoke a task pool worker to send a request. It will then receive the response during the network receive callback context. If there are more requests in the connection's request queue, it will schedule another task pool worker to send that request.
@section Synchronous_Design Synchronous Design
@image html https_client_sync_workflow.png width=100%
@section Asynchronous_Design Asynchronous Design
@image html https_client_async_workflow.png width=100%
@section Asynchronous_Callback_Order Asynchronous Callbacks Ordering
@image html https_client_async_callback_order.png width=100%
*/
/**
@page https_demo Demos
@brief The HTTPS Client demos demonstrates usage of the HTTPS Client library.
These demos show downloading a file from S3 and uploading a file to S3 using a pre-signed URL using the FreeRTOS HTTP Client library. The HTTPS Client library is a generic HTTP/1.1 client library that be used to download files from other web servers as well.
See @subpage https_download_demo_usage for information on how to get the download demo up and running.
See @subpage https_upload_demo_usage for information on how to get the upload demo up and running.
The main HTTPS Client demo files contain platform-independent code. See @ref building_demo for instructions on building the HTTPS Client demo.
<h1> Demo files </h1>
<h2>[iot_demo_https_s3_download_sync.c](https://github.com/aws/amazon-freertos/tree/master/demos/https/iot_demo_https_s3_download_sync.c)</h2>
@brief Synchronously download a file from an S3 bucket using a pre-signed URL.
This demo will use @ref https_client_function_sendsync to download the file specified in the S3 bucket.
<h2>[iot_demo_https_s3_download_async.c](https://github.com/aws/amazon-freertos/tree/master/demos/https/iot_demo_https_s3_download_async.c)</h2>
@brief Asynchronously download a file from an S3 bucket using a pre-signed URL.
This demo will use @ref https_client_function_sendasync to download the file specified in the S3 bucket.
<h2>[iot_demo_https_s3_upload_sync.c](https://github.com/aws/amazon-freertos/tree/master/demos/https/iot_demo_https_s3_upload_sync.c)</h2>
@brief Synchronously upload a file to an S3 bucket using a pre-signed URL.
This demo will use @ref https_client_function_sendsync to upload a file to S3 bucket.
<h2>[iot_demo_https_s3_upload_async.c](https://github.com/aws/amazon-freertos/tree/master/demos/https/iot_demo_https_s3_upload_async.c)</h2>
@brief Asynchronously upload a file to an S3 bucket using a pre-signed URL.
This demo will use @ref https_client_function_sendasync to upload a file to the S3 bucket.
See @subpage https_demo_config for configuration settings that change the behavior of the demo.
@page https_download_demo_usage Download Demo Usage Instructions
<ol>
<li>
Ensure that you have permissions in your AWS account to access S3.
For information on AWS S3 please see: https://docs.aws.amazon.com/AmazonS3/latest/dev/Welcome.html
</li>
<li>
In an existing bucket or creating a new bucket upload the following file:
<a href='gettysburg.txt'>gettysburg.txt</a>
</li>
<li>
Install and configured the AWS CLI.
For AWS CLI installation information please see: https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html
For AWS CLI configuration information please see: https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html
</li>
<li>
Run [demos/https/presigned_url_gen.py](https://github.com/aws/amazon-freertos/tree/master/demos/https/presigned_urls_gen.py) with your s3 **bucket-name** and s3 object key **object-key**.
\code
python presigned_url_gen.py --bucket my-bucket --key object-key
\endcode
Please see [demos/https/README.md](https://github.com/aws/amazon-freertos/tree/master/demos/https/README.md) for information on the required Python version and Python package dependencies.
Example output:
\code
#define IOT_DEMO_HTTPS_PRESIGNED_GET_URL https://my-bucket.s3.amazonaws.com/object-key.txt?AWSAccessKeyId=AAAAAAAAAAAAAAAAAAAA&Expires=1560555644&Signature=SomeHash12345UrlABcdEFgfIjK%3D
#define IOT_DEMO_HTTPS_PRESIGNED_PUT_URL https://my-bucket.s3.amazonaws.com/object-key.txt?AWSAccessKeyId=ABABABABABABABABABAB&Expires=1560555644&Signature=SomeHash12345UrlLMnmOPqrStUvW
\endcode
Paste this output to iot_config.h.
<br>
<br>
Note:
If your bucket is less than 24 hours old, then you will need to append the region the bucket was created in to the pre-signed URL:
\code
https://my-bucket.s3-<region>.amazonaws.com/object-key.txt?AWSAccessKeyId=AAAAAAAAAAAAAAAAAAAA&Expires=1560555644&Signature=SomeHash12345UrlABcdEFgfIjK%3D
\endcode
Example:
\code
https://my-bucket.s3-us-west-2.amazonaws.com/object-key.txt?AWSAccessKeyId=AAAAAAAAAAAAAAAAAAAA&Expires=1560555644&Signature=SomeHash12345UrlABcdEFgfIjK%3D
\endcode
Please see https://aws.amazon.com/premiumsupport/knowledge-center/s3-http-307-response/ for more information.
</li>
<li>
Paste your RSA-2048 or ECC-P256 keys into [aws_clientcredential_keys.h](https://github.com/aws/amazon-freertos/blob/master/demos/include/aws_clientcredential_keys.h). This is needed to for the TLS handshake with the AWS S3 HTTP Server.
</li>
<li>
Enable the <b>Synchronous download demo</b> by defining @ref CONFIG_HTTPS_SYNC_DOWNLOAD_DEMO_ENABLED in aws_demo_config.h:
\code
/* To run a particular demo you need to define one of these.
* Only one demo can be configured at a time
*
* CONFIG_MQTT_DEMO_ENABLED
* CONFIG_SHADOW_DEMO_ENABLED
* CONFIG_GREENGRASS_DISCOVERY_DEMO_ENABLED
* CONFIG_TCP_ECHO_CLIENT_DEMO_ENABLED
* CONFIG_DEFENDER_DEMO_ENABLED
* CONFIG_POSIX_DEMO_ENABLED
* CONFIG_OTA_UPDATE_DEMO_ENABLED
* CONFIG_HTTPS_SYNC_DOWNLOAD_DEMO_ENABLED
* CONFIG_HTTPS_ASYNC_DOWNLOAD_DEMO_ENABLED
* CONFIG_HTTPS_SYNC_UPLOAD_DEMO_ENABLED
* CONFIG_HTTPS_ASYNC_UPLOAD_DEMO_ENABLED
*
* These defines are used in iot_demo_runner.h for demo selection */
#define CONFIG_HTTPS_SYNC_DOWNLOAD_DEMO_ENABLED
\endcode
</li>
<li>
See @ref building_demo for instructions on building the demo.
A successful output looks like this:
\code
10 618 [iot_thread] [INFO ][INIT][618] SDK successfully initialized.
11 618 [iot_thread] [INFO ][DEMO][618] Successfully initialized the demo. Network type for the demo: 4
12 618 [iot_thread] [INFO ][DEMO][618] HTTPS Client Synchronous S3 download demo using pre-signed URL: https://sarem-public.s3.amazonaws.com/gettysburg.txt?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=3600&X-Amz-Credential=AKIAIYLZ53PYH6JY77YQ%2F20190830%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-SignedHeaders=host&X-Amz-Date=20190830T171845Z&X-Amz-Signature=2b185273a920fe10b0bbf5a391c9af8af7caf0d76170eade4fd99f28d3a68a00
13 902 [iot_thread] [INFO ][DEMO][902] Now requesting Range: bytes=0-511.
14 942 [iot_thread] [INFO ][DEMO][942] Response return code: 206
15 942 [iot_thread] [INFO ][DEMO][942] Response Body:
Four score and seven years ago our fathers brought forth on this continent, a new nation, conceived in Liberty, and dedicated to the proposition that all men are created equal.
Now we are engaged in a great civil war, testing whether that nation, or any nation so conceived and so dedicated, can long endure. We are met on a great battle-field of that war. We have come to dedicate a portion of that field, as a final resting place for those who here gave their lives that that nation might live. It is altoge
16 942 [iot_thread] [INFO ][DEMO][942] Downloaded 512/1517
17 942 [iot_thread] [INFO ][DEMO][942] Now requesting Range: bytes=512-1023.
18 1003 [iot_thread] [INFO ][DEMO][1003] Response return code: 206
19 1003 [iot_thread] [INFO ][DEMO][1003] Response Body:
ther fitting and proper that we should do this.
But, in a larger sense, we can not dedicate -- we can not consecrate -- we can not hallow -- this ground. The brave men, living and dead, who struggled here, have consecrated it, far above our poor power to add or detract. The world will little note, nor long remember what we say here, but it can never forget what they did here. It is for us the living, rather, to be dedicated here to the unfinished work which they who fought here have thus far so nobly adv
20 1003 [iot_thread] [INFO ][DEMO][1003] Downloaded 1024/1517
21 1003 [iot_thread] [INFO ][DEMO][1003] Now requesting Range: bytes=1024-1516.
22 1063 [iot_thread] [INFO ][DEMO][1063] Response return code: 206
23 1063 [iot_thread] [INFO ][DEMO][1063] Response Body:
anced. It is rather for us to be here dedicated to the great task remaining before us -- that from these honored dead we take increased devotion to that cause for which they gave the last full measure of devotion -- that we here highly resolve that these dead shall not have died in vain -- that this nation, under God, shall have a new birth of freedom -- and that government of the people, by the people, for the people, shall not perish from the earth.
Abraham Lincoln
November 19, 1863
24 1063 [iot_thread] [INFO ][DEMO][1063] Downloaded 1517/1517
25 1102 [iot_thread] [INFO ][DEMO][1102] Demo completed successfully.
26 1105 [iot_thread] [INFO ][INIT][1105] SDK cleanup done.
\endcode
</li>
<li>
Enable the <b>Asynchronous download demo</b> by defining either @ref CONFIG_HTTPS_ASYNC_DOWNLOAD_DEMO_ENABLED in aws_demo_config.h:
\code
/* To run a particular demo you need to define one of these.
* Only one demo can be configured at a time
*
* CONFIG_MQTT_DEMO_ENABLED
* CONFIG_SHADOW_DEMO_ENABLED
* CONFIG_GREENGRASS_DISCOVERY_DEMO_ENABLED
* CONFIG_TCP_ECHO_CLIENT_DEMO_ENABLED
* CONFIG_DEFENDER_DEMO_ENABLED
* CONFIG_POSIX_DEMO_ENABLED
* CONFIG_OTA_UPDATE_DEMO_ENABLED
* CONFIG_HTTPS_SYNC_DOWNLOAD_DEMO_ENABLED
* CONFIG_HTTPS_ASYNC_DOWNLOAD_DEMO_ENABLED
* CONFIG_HTTPS_SYNC_UPLOAD_DEMO_ENABLED
* CONFIG_HTTPS_ASYNC_UPLOAD_DEMO_ENABLED
*
* These defines are used in iot_demo_runner.h for demo selection */
#define CONFIG_HTTPS_ASYNC_DOWNLOAD_DEMO_ENABLED
\endcode
</li>
<li>
See @ref building_demo for instructions on building the demo.
A successful output looks like this:
\code
10 632 [iot_thread] [INFO ][INIT][632] SDK successfully initialized.
11 632 [iot_thread] [INFO ][DEMO][632] Successfully initialized the demo. Network type for the demo: 4
12 632 [iot_thread] [INFO ][DEMO][632] HTTPS Client Asynchronous S3 download demo using pre-signed URL: https://sarem-public.s3.amazonaws.com/gettysburg.txt?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=3600&X-Amz-Credential=AKIAIYLZ53PYH6JY77YQ%2F20190830%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-SignedHeaders=host&X-Amz-Date=20190830T171845Z&X-Amz-Signature=2b185273a920fe10b0bbf5a391c9af8af7caf0d76170eade4fd99f28d3a68a00
13 915 [iot_thread] [INFO ][DEMO][915] Inside of the append header callback for part bytes=0-511
14 954 [NetRecv] [INFO ][DEMO][954] Inside of the read ready callback for part bytes=0-511 with network return code: 0
15 954 [NetRecv] [INFO ][DEMO][954] Response return code: 206 for bytes=0-511
16 954 [NetRecv] [INFO ][DEMO][954] Response Body for bytes=0-511:
Four score and seven years ago our fathers brought forth on this continent, a new nation, conceived in Liberty, and dedicated to the proposition that all men are created equal.
Now we are engaged in a great civil war, testing whether that nation, or any nation so conceived and so dedicated, can long endure. We are met on a great battle-field of that war. We have come to dedicate a portion of that field, as a final resting place for those who here gave their lives that that nation might live. It is altoge
17 954 [iot_thread] [INFO ][DEMO][954] Inside of the append header callback for part bytes=512-1023
18 954 [NetRecv] [INFO ][DEMO][954] Part bytes=0-511 has been fully processed.
19 954 [NetRecv] [INFO ][DEMO][954] Downloaded: 512/1517
20 1014 [NetRecv] [INFO ][DEMO][1014] Inside of the read ready callback for part bytes=512-1023 with network return code: 0
21 1014 [NetRecv] [INFO ][DEMO][1014] Response return code: 206 for bytes=512-1023
22 1014 [NetRecv] [INFO ][DEMO][1014] Response Body for bytes=512-1023:
ther fitting and proper that we should do this.
But, in a larger sense, we can not dedicate -- we can not consecrate -- we can not hallow -- this ground. The brave men, living and dead, who struggled here, have consecrated it, far above our poor power to add or detract. The world will little note, nor long remember what we say here, but it can never forget what they did here. It is for us the living, rather, to be dedicated here to the unfinished work which they who fought here have thus far so nobly adv
23 1014 [iot_thread] [INFO ][DEMO][1014] Inside of the append header callback for part bytes=1024-1516
24 1014 [NetRecv] [INFO ][DEMO][1014] Part bytes=512-1023 has been fully processed.
25 1014 [NetRecv] [INFO ][DEMO][1014] Downloaded: 1024/1517
26 1074 [NetRecv] [INFO ][DEMO][1074] Inside of the read ready callback for part bytes=1024-1516 with network return code: 0
27 1074 [NetRecv] [INFO ][DEMO][1074] Response return code: 206 for bytes=1024-1516
28 1074 [NetRecv] [INFO ][DEMO][1074] Response Body for bytes=1024-1516:
anced. It is rather for us to be here dedicated to the great task remaining before us -- that from these honored dead we take increased devotion to that cause for which they gave the last full measure of devotion -- that we here highly resolve that these dead shall not have died in vain -- that this nation, under God, shall have a new birth of freedom -- and that government of the people, by the people, for the people, shall not perish from the earth.
Abraham Lincoln
November 19, 1863
29 1074 [NetRecv] [INFO ][DEMO][1074] Part bytes=1024-1516 has been fully processed.
30 1074 [NetRecv] [INFO ][DEMO][1074] Downloaded: 1517/1517
31 1114 [iot_thread] [INFO ][DEMO][1114] Demo completed successfully.
32 1116 [iot_thread] [INFO ][INIT][1116] SDK cleanup done.
\endcode
</li>
</ol>
Notes:
Please note that the buffer for printing may be smaller than 512 characters and the printed received response body may be truncated.<br><br>
"[NetRecv] [WARN ][NET][2977] Receive requested 768 bytes, but 400 bytes received instead." is OK because the library requests from the network interface the full size of the header buffer or body buffer.<br><br>
S3 will close the connection after 100 requests on the same connection.
@page https_upload_demo_usage Upload Demo Usage Instructions
<ol>
<li>
Ensure that you have permissions in your AWS account to access S3.
For information on AWS S3 please see: https://docs.aws.amazon.com/AmazonS3/latest/dev/Welcome.html
</li>
<li>
Install and configured the AWS CLI.
For AWS CLI installation information please see: https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html
For AWS CLI configuration information please see: https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html
</li>
<li>
Run [demos/https/presigned_url_gen.py](https://github.com/aws/amazon-freertos/tree/master/demos/https/presigned_urls_gen.py) with your s3 **bucket-name** and s3 object key **object-key**.
\code
python presigned_url_gen.py --bucket my-bucket --key object-key
\endcode
Please see [demos/https/README.md](https://github.com/aws/amazon-freertos/tree/master/demos/https/README.md) for information on the required Python version and Python package dependencies.
Example output:
\code
#define IOT_DEMO_HTTPS_PRESIGNED_GET_URL https://my-bucket.s3.amazonaws.com/object-key.txt?AWSAccessKeyId=AAAAAAAAAAAAAAAAAAAA&Expires=1560555644&Signature=SomeHash12345UrlABcdEFgfIjK%3D
#define IOT_DEMO_HTTPS_PRESIGNED_PUT_URL https://my-bucket.s3.amazonaws.com/object-key.txt?AWSAccessKeyId=ABABABABABABABABABAB&Expires=1560555644&Signature=SomeHash12345UrlLMnmOPqrStUvW
\endcode
Paste this output to iot_config.h.
<br>
<br>
Note:
If your bucket is less than 24 hours old, then you will need to append the region the bucket was created in to the pre-signed URL:
\code
https://my-bucket.s3-<region>.amazonaws.com/object-key.txt?AWSAccessKeyId=AAAAAAAAAAAAAAAAAAAA&Expires=1560555644&Signature=SomeHash12345UrlABcdEFgfIjK%3D
\endcode
Example:
\code
https://my-bucket.s3-us-west-2.amazonaws.com/object-key.txt?AWSAccessKeyId=AAAAAAAAAAAAAAAAAAAA&Expires=1560555644&Signature=SomeHash12345UrlABcdEFgfIjK%3D
\endcode
Please see https://aws.amazon.com/premiumsupport/knowledge-center/s3-http-307-response/ for more information.
</li>
<li>
Paste your RSA-2048 or ECC-P256 keys into [aws_clientcredential_keys.h](https://github.com/aws/amazon-freertos/blob/master/demos/include/aws_clientcredential_keys.h). This is needed to for the TLS handshake with the AWS S3 HTTP Server.
</li>
<li>
Enable the <b>Synchronous upload demo</b> by defining @ref CONFIG_HTTPS_SYNC_UPLOAD_DEMO_ENABLED in aws_demo_config.h:
\code
/* To run a particular demo you need to define one of these.
* Only one demo can be configured at a time
*
* CONFIG_MQTT_DEMO_ENABLED
* CONFIG_SHADOW_DEMO_ENABLED
* CONFIG_GREENGRASS_DISCOVERY_DEMO_ENABLED
* CONFIG_TCP_ECHO_CLIENT_DEMO_ENABLED
* CONFIG_DEFENDER_DEMO_ENABLED
* CONFIG_POSIX_DEMO_ENABLED
* CONFIG_OTA_UPDATE_DEMO_ENABLED
* CONFIG_HTTPS_SYNC_DOWNLOAD_DEMO_ENABLED
* CONFIG_HTTPS_ASYNC_DOWNLOAD_DEMO_ENABLED
* CONFIG_HTTPS_SYNC_UPLOAD_DEMO_ENABLED
* CONFIG_HTTPS_ASYNC_UPLOAD_DEMO_ENABLED
*
* These defines are used in iot_demo_runner.h for demo selection */
#define CONFIG_HTTPS_SYNC_UPLOAD_DEMO_ENABLED
\endcode
</li>
<li>
See @ref building_demo for instructions on building the demo.
A successful output looks like this:
\code
10 621 [iot_thread] [INFO ][INIT][621] SDK successfully initialized.
11 621 [iot_thread] [INFO ][DEMO][621] Successfully initialized the demo. Network type for the demo: 4
12 621 [iot_thread] [INFO ][DEMO][621] HTTPS Client Synchronous S3 upload demo using pre-signed URL: https://sarem-public.s3.amazonaws.com/helloworld5.txt?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=3600&X-Amz-Credential=AKIAIYLZ53PYH6JY77YQ%2F201908313 971 [iot_thread] [INFO ][DEMO][970] File was successfully uploaded.
14 971 [iot_thread] [INFO ][DEMO][971] Now checking sarem-public.s3.amazonaws.com for the file uploaded...
15 1010 [iot_thread] [INFO ][DEMO][1010] Verified file size on S3 is 12. File size specified to upload is 12.
16 1070 [iot_thread] [INFO ][DEMO][1070] Demo completed successfully.
17 1073 [iot_thread] [INFO ][INIT][1073] SDK cleanup done.
\endcode
</li>
<li>
Enable the <b>Asynchronous upload demo</b> by defining either @ref CONFIG_HTTPS_ASYNC_UPLOAD_DEMO_ENABLED in aws_demo_config.h:
\code
/* To run a particular demo you need to define one of these.
* Only one demo can be configured at a time
*
* CONFIG_MQTT_DEMO_ENABLED
* CONFIG_SHADOW_DEMO_ENABLED
* CONFIG_GREENGRASS_DISCOVERY_DEMO_ENABLED
* CONFIG_TCP_ECHO_CLIENT_DEMO_ENABLED
* CONFIG_DEFENDER_DEMO_ENABLED
* CONFIG_POSIX_DEMO_ENABLED
* CONFIG_OTA_UPDATE_DEMO_ENABLED
* CONFIG_HTTPS_SYNC_DOWNLOAD_DEMO_ENABLED
* CONFIG_HTTPS_ASYNC_DOWNLOAD_DEMO_ENABLED
* CONFIG_HTTPS_SYNC_UPLOAD_DEMO_ENABLED
* CONFIG_HTTPS_ASYNC_UPLOAD_DEMO_ENABLED
*
* These defines are used in iot_demo_runner.h for demo selection */
#define CONFIG_HTTPS_ASYNC_UPLOAD_DEMO_ENABLED
\endcode
</li>
<li>
See @ref building_demo for instructions on building the demo.
A successful output looks like this:
\code
10 610 [iot_thread] [INFO ][INIT][610] SDK successfully initialized.
11 610 [iot_thread] [INFO ][DEMO][610] Successfully initialized the demo. Network type for the demo: 4
12 610 [iot_thread] [INFO ][DEMO][610] HTTPS Client Asynchronous S3 upload demo using pre-signed URL: https://sarem-public.s3.amazonaws.com/helloworld5.txt?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=3600&X-Amz-Credential=AKIAIYLZ53PYH6JY77YQ%2F20190813 900 [iot_thread] [INFO ][DEMO][900] Now checking sarem-public.s3.amazonaws.com for the file uploaded...
14 940 [iot_thread] [INFO ][DEMO][940] Verified file size on S3 is 12. File size specified to upload is 12.
15 1000 [iot_thread] [INFO ][DEMO][1000] Demo completed successfully.
16 1002 [iot_thread] [INFO ][INIT][1002] SDK cleanup done.
\endcode
</li>
</ol>
Notes:
Please note that the buffer for printing may be smaller than 512 characters and the printed received response body may be truncated.<br>
*/
/**
@config_page{https_demo,Demo}
@config_brief{https_demo,HTTP Client demo,demos}
@section IOT_DEMO_HTTPS_PRESIGNED_GET_URL
@brief Presigned URL for AWS S3 GET Object access.
This is generated using the script demos/https/presigned_url_gen.py. demos/https/README.md explains how to use the script.
@configpossible Presigned URL of the form: `https://my-bucket.s3.amazonaws.com/object-key.txt?AWSAccessKeyId=AAAAAAAAAAAAAAAAAAAA&Expires=1560555644&Signature=SomeHash12345UrlABcdEFgfIjK%3D`. <br>
@configdefault `"Please configure a presigned GET URL in iot_config.h."`
@section IOT_DEMO_HTTPS_PORT
@brief The port number for the TLS connection to AWS S3's HTTP server.
@configpossible Any positive integer up to 2^16. <br>
@configdefault `443`
@section IOT_DEMO_HTTPS_TRUSTED_ROOT_CA
@brief The trusted root CA needed to connected to AWS S3's HTTP server.
@configpossible A valid PEM encoded certificate string. <br>
@configdefault The Baltimore Cybertrust root CA.
@section IOT_DEMO_HTTPS_CONN_BUFFER_SIZE
@brief The size of the static user buffer to store the HTTP Client connection context.
Size in bytes of the User Buffer used to store the internal connection context. The size presented here accounts for
storage of the internal connection context. The minimum size can be found in @ref connectionUserBufferMinimumSize.
@configpossible Any positive integer. <br>
@configdefault `400`
@section IOT_DEMO_HTTPS_REQ_USER_BUFFER_SIZE
@brief The size of the static user buffer to store the HTTP Client request context and HTTP formatted request headers.
Size in bytes of the user buffer used to store the internal request context and HTTP request header lines.
The size presented here accounts for the storage of the internal context, the first Request-Line in the HTTP
formatted header and extra headers. The minimum size can be found in @ref requestUserBufferMinimumSize. Keep in mind that this @ref requestUserBufferMinimumSize does not include the size of the
path in the Request-Line. The path could be well over 100 characters long as it includes not only the object key name
in S3, but also the query following. The query following has the AWSAccessKeyId, the expiration time, and the
AWS Signature Version 4 signature.
@configpossible Any positive integer. <br>
@configdefault `512`
@section IOT_DEMO_HTTPS_RESP_USER_BUFFER_SIZE
@brief The size of the static user buffer to store the HTTP Client response context and HTTP formatted response headers.
Size in bytes of the user buffer used to store the internal response context and the HTTP response header lines.
The size presented here accounts for the storage of the internal context, the first Request-Line in the HTTP
formatted header and extra headers. The minimum can be found in @ref requestUserBufferMinimumSize.
Keep in mind that if the headers from the response do not all fit into this buffer, then the rest of the headers
will be discarded. The minimum size can be found in @ref responseUserBufferMinimumSize.
@configpossible Any positive integer. <br>
@configdefault `1024`
@section IOT_DEMO_HTTPS_RESP_BODY_BUFFER_SIZE
@brief The size of the static buffer to store an increment of the response body.
Size in bytes of the buffer used to store the response body (parts of it). This should be less than or equal to
the size of the file we want to download
@configpossible Any positive integer. <br>
@configdefault `512`
@section IOT_DEMO_HTTPS_UPLOAD_DATA
@brief Pointer to the data to upload to S3.
This can be a pointer to a memory location or a string literal.
@configpossible Any readable address location or string. <br>
@configdefault `"Hello World!"
@section IOT_DEMO_HTTPS_UPLOAD_DATA_SIZE
@brief The size of the data pointed to by @ref IOT_DEMO_HTTPS_UPLOAD_DATA.
@configpossible Any positive integer. <br>
@configdefault `( sizeof( IOT_DEMO_HTTPS_UPLOAD_DATA ) - 1 )`
@section IOT_DEMO_HTTPS_CONNECTION_RETRY_WAIT_MS
@brief Time to wait in milliseconds before retrying the HTTPS Connection.
A connection is only attempted again if @ref IOT_HTTPS_CONNECTION_ERROR is returned from IotHttpsClient_Connect(). This
indicates an error in the network layer. To view network errors update @ref IOT_LOG_LEVEL_NETWORK to @ref IOT_LOG_ERROR
in iot_config.h.
@configpossible Any positive integer.
@configdefault `3000`
@section IOT_DEMO_HTTPS_CONNECTION_NUM_RETRY
@brief Number of times to retry the HTTPS connection.
A connection is only attempted again if @ref IOT_HTTPS_CONNECTION_ERROR is returned from IotHttpsClient_Connect(). This
indicates an error in the network layer. To view network errors update @ref IOT_LOG_LEVEL_NETWORK to @ref IOT_LOG_ERROR
in iot_config.h.
@configpossible Any positive integer.
@configdefault `3`
@section IOT_HTTPS_DEMO_SYNC_TIMEOUT_MS
@brief Timeout in milliseconds to wait for a response to to a synchronous request.
This timeout is applied to function @ref https_client_function_sendsync.
This configuration applies to [iot_demo_https_s3_download_sync.c](https://github.com/aws/amazon-freertos/tree/master/demos/https/iot_demo_https_s3_download_sync.c) and [iot_demo_https_s3_upload_sync.c](https://github.com/aws/amazon-freertos/tree/master/demos/https/iot_demo_https_s3_upload_sync.c)
@configpossible Any positive integer. <br>
@configdefault `60000`
@section IOT_HTTPS_DEMO_MAX_ASYNC_REQUESTS
@brief The maximum number of inflight asynchronous requests.
This configuration applies only to [iot_demo_https_s3_download_async.c](https://github.com/aws/amazon-freertos/tree/master/demos/https/iot_demo_https_s3_download_async.c).
This configures the total number of requests in the pool of HTTPS Client library configurations and handles. In order to send
a request asynchronously the memory for both the request buffers and the response buffers must not be shared between
other asynchronous requests on the same connection. You can reuse the buffer only after the request/response process
has been finished. It is finished when the responseCompleteCallback() is invoked. We create a pool of memory so that
all available requests in the pool can be scheduled right away without over-writing each other.
@configpossible Any positive integer. <br>
@configdefault `3`
@section IOT_HTTPS_DEMO_ASYNC_TIMEOUT_MS
@brief Timeout in milliseconds to wait for all asynchronous requests to finish.
This configuration applies to [iot_demo_https_s3_download_async.c](https://github.com/aws/amazon-freertos/tree/master/demos/https/iot_demo_https_s3_download_async.c) and [iot_demo_https_s3_upload_async.c](https://github.com/aws/amazon-freertos/tree/master/demos/https/iot_demo_https_s3_upload_async.c)
For [iot_demo_https_s3_download_async.c](https://github.com/aws/amazon-freertos/tree/master/demos/https/iot_demo_https_s3_download_async.c) this timeout starts when the last @ref IOT_HTTPS_DEMO_MAX_ASYNC_REQUESTS sent have been scheduled.
@configpossible Any positive integer. <br>
@configdefault `300000`
*/
/**
@page https_tests Tests
@brief Tests written for the HTTPS Client library.
The HTTPS Client tests reside in the `tests` directory. They are divided into the following subdirectories:
- `access`: Helper files that allow access to internal variables and functions of the HTTPS Client library.
- `system`: HTTPS Client integration testing. These tests require a network connection.
- `unit`: HTTPS Client unit tests. These tests do not require a network connection.
See @subpage https_tests_config for configuration settings that change the behavior of the tests.
The current HTTPS Client tests use the [Unity test framework](http://www.throwtheswitch.org/unity/). See @ref building_tests for a guide on running the tests.
*/
/**
@config_page{https_tests,Test}
@config_brief{https_tests,HTTPS Client tests,tests}
@section IOT_TEST_HTTPS_SERVER_HOST_NAME
@brief The HTTP server used for this test.
This server needs to accept methods HEAD, GET, POST, and PUT. This server needs to send some data on a GET request. It can be a simple HTTP echo server.
@configpossible Any server host name string. This host name must not include "https://" or "http://" in the name. <br>
@configdefault `"httpbin.org"`
@section IOT_TEST_HTTPS_PORT
@brief The socket port number of the server to connect to.
@configpossible Any positive integer up to 2^16. <br>
@configdefault `443`
@section IOT_TEST_HTTPS_ALPN_PROTOCOLS
@brief APLN protocol string if necessary to connect to a secure testing server configured in @ref IOT_TEST_HTTPS_SERVER_HOST_NAME.
This is a comma separated list of protocol. Please see [Transport Layer Security (TLS) Application-Layer Protocol Negotiation Extension](https://tools.ietf.org/html/rfc7301) for more information.
@configpossible A comma separated string of ALPN protocol names or NULL. An empty string is not allowed. <br>
@configdefault `NULL`
@section IOT_TEST_HTTPS_ROOT_CA
@brief Root certificate authority to verify the server that the HTTPS_Client_System tests are connecting to.
@configpossible A valid PEM encoded certificate string. <br>
@configdefault `NULL`
@section IOT_TEST_HTTPS_CLIENT_CERTIFICATE
@brief The client certificate used in TLS negotiation with the test HTTP server configured in @ref IOT_TEST_HTTPS_SERVER_HOST_NAME.
With PKCS #11 provisioning of the keys these parameters are deprecated.
@configpossible A valid RSA-2048 or ECC-P256 PEM encoded certificate string. <br>
@configdefault The system provisioned client certificate.
@section IOT_TEST_HTTPS_CLIENT_PRIVATE_KEY
@brief The client private key used in TLS negotiation with the test HTTP server configured in @ref IOT_TEST_HTTPS_SERVER_HOST_NAME.
With PKCS #11 provisioning of the keys these parameters are deprecated.
@configpossible A valid RSA-2048 or ECC-P256 PEM encoded private key string. <br>
@configdefault The system provisioned client private key.
@section IOT_TEST_HTTPS_SYNC_TIMEOUT_MS
@brief Timeout in milliseconds for tests that synchronously send HTTP requests.
This timeout encompasses the waiting time for the both sending of the request and receiving the response.
@configpossible Any positive integer. <br>
@configdefault `60000`
@section IOT_TEST_HTTPS_ASYNC_TIMEOUT_MS
@brief Timeout in milliseconds for tests asynchronously send HTTP requests.
This timeout encompasses the waiting time for the both sending of the request and receiving the response.
@configpossible Any positive integer. <br>
@configdefault `60000`
@section IOT_TEST_HTTPS_INITIAL_CONNECTION_RETRY_DELAY
@brief The initial delay in milliseconds that is doubled each retry of server connection.
@configpossible Any positive integer. <br>
@configdefault `300`
@section IOT_TEST_HTTPS_CONNECTION_NUM_RETRIES
@brief The amount of times to retry the server connection if it fails.
@configpossible Any positive integer. <br>
@configdefault `3`
*/
/**
@config_page{https}
@config_brief{HTTPS Client library}
@section AWS_IOT_HTTPS_ENABLE_METRICS
@brief Set this to `1` to enable anonymous metrics reporting to AWS IoT.
Metrics allow AWS IoT to prioritize engineering resources based on SDK usage. SDK name and version are reported; no personal or identifying information is reported.
@configpossible `0` (metrics reporting disabled) or `1` (metrics reporting enabled)<br>
@configrecommended `1`<br>
@configdefault `1`
@section IOT_HTTPS_USER_AGENT
@brief The name of the application type, operating system, software vendor, or software version of the requesting software agent.
This configuration will dictate the header value written to required header field "User-Agent". This value is written when the request is initialized with @ref https_client_function_initializerequest.
@configpossible Any string. <br>
@configdefault `"amazon-freertos"`
@section IOT_LOG_LEVEL_HTTPS
@brief Set the log level of the HTTPS Client library.
Log messages from the HTTPS Client library at or below this setting will be printed.
@configpossible One of the @ref logging_constants_levels.<br>
@configdefault @ref IOT_LOG_LEVEL_GLOBAL; if that is undefined, then @ref IOT_LOG_NONE.
@section IOT_HTTPS_MAX_FLUSH_BUFFER_SIZE
@brief The size of a buffer instantiated in stack to flush the socket of the rest of possible unread response.
@configpossible Any positive integer.<br>
@configdefault `1024`
@section IOT_HTTPS_RESPONSE_WAIT_MS
@brief The time in milliseconds to wait for a response from the network before timing out.
@configpossible Any positive integer.<br>
@configdefault `1000`
@section IOT_HTTPS_MAX_HOST_NAME_LENGTH
@brief The maximum length of the DNS resolvable host name string allowed to be configured in #IotHttpsConnectionInfo_t.pAddress.
An array of this length is allocated on stack during @ref https_client_function_connect.
@configpossible Any positive integer. <br>
@configrecommended It is recommended that this be less or equal to 255. 255 is the maximum host length according to FQDN. <br>
@configdefault `255`
@section IOT_HTTPS_MAX_ALPN_PROTOCOLS_LENGTH
@brief The maximum length of the ALPN protocols names string allowed to be configured in #IotHttpsConnectionInfo_t.pAlpnProtocols.
An array of this length is allocated on stack during @ref https_client_function_connect.
@configpossible Any positive integer. <br>
@configdefault `255`
*/