1## AWS Crt Cpp 2 3C++ wrapper around the aws-c-* libraries. Provides Cross-Platform Transport Protocols and SSL/TLS implementations for C++. 4 5### Documentation 6 7https://awslabs.github.io/aws-crt-cpp/ 8 9### Currently Included: 10 11* aws-c-common: Cross-platform primitives and data structures. 12* aws-c-io: Cross-platform event-loops, non-blocking I/O, and TLS implementations. 13* aws-c-mqtt: MQTT client. 14* aws-c-auth: Auth signers such as Aws-auth sigv4 15* aws-c-http: HTTP 1.1 client, and websockets (H2 coming soon) 16* aws-checksums: Cross-Platform HW accelerated CRC32c and CRC32 with fallback to efficient SW implementations. 17* aws-c-event-stream: C99 implementation of the vnd.amazon.event-stream content-type. 18 19More protocols and utilities are coming soon, so stay tuned. 20 21## Building 22 23The C99 libraries are already included for your convenience as submodules. 24You should perform a recursive clone `git clone --recursive` or initialize the submodules via 25`git submodule update --init`. These dependencies are compiled by CMake as part of the build process. 26 27If you want to manage these dependencies manually (e.g. you're using them in other projects), configure CMake with 28`-DBUILD_DEPS=OFF` and `-DCMAKE_PREFIX_PATH=<install>` pointing to the absolute path where you have them installed. 29 30### MSVC 31If you want to use a statically linked MSVCRT (/MT, /MTd), you can add `-DSTATIC_CRT=ON` to your cmake configuration. 32 33## Dependencies? 34 35There are no non-OS dependencies that AWS does not own, maintain, and ship. 36 37## Common Usage 38 39To do anything with IO, you'll need to create a few objects that will be used by the rest of the library. 40 41For example: 42 43```` 44 Aws::Crt::LoadErrorStrings(); 45```` 46 47Will load error strings for debugging purposes. Since the C libraries use error codes, this will allow you to print the corresponding 48error string for each error code. 49 50```` 51 Aws::Crt::ApiHandle apiHandle; 52```` 53This performs one-time static initialization of the library. You'll need it to do anything, so don't forget to create one. 54 55```` 56 Aws::Crt::Io::EventLoopGroup eventLoopGroup(<number of threads you want>); 57```` 58To use any of our APIs that perform IO you'll need at least one event-loop. An event-loop group is a collection of event-loops that 59protocol implementations will load balance across. If you won't have very many connections (say, more than 100 or so), then you 60most likely only want 1 thread. In this case, you want to pass a single instance of this to every client or server implementation of a protocol 61you use in your application. In some advanced use cases, you may want to reserve a thread for different types of IO tasks. In that case, you can have an 62instance of this class for each reservation. 63 64```` 65 Aws::Crt::Io::TlsContextOptions tlsCtxOptions = 66 Aws::Crt::Io::TlsContextOptions::InitClientWithMtls(certificatePath.c_str(), keyPath.c_str()); 67 /* 68 * If we have a custom CA, set that up here. 69 */ 70 if (!caFile.empty()) 71 { 72 tlsCtxOptions.OverrideDefaultTrustStore(nullptr, caFile.c_str()); 73 } 74 75 uint16_t port = 8883; 76 if (Io::TlsContextOptions::IsAlpnSupported()) 77 { 78 /* 79 * Use ALPN to negotiate the mqtt protocol on a normal 80 * TLS port if possible. 81 */ 82 tlsCtxOptions.SetAlpnList("x-amzn-mqtt-ca"); 83 port = 443; 84 } 85 86 Aws::Crt::Io::TlsContext tlsCtx(tlsCtxOptions, Io::TlsMode::CLIENT); 87```` 88 89If you plan on using TLS, you will need a TlsContext. These are NOT CHEAP, so use as few as possible to perform your task. 90If you're in client mode and not doing anything fancy (e.g. mutual TLS), then you can likely get away with using a single 91instance for the entire application. 92 93```` 94Aws::Crt::Io::ClientBootstrap bootstrap(eventLoopGroup); 95```` 96 97Lastly, you will need a client or server bootstrap to use a client or server protocol implementation. Since everything is 98non-blocking and event driven, this handles most of the "callback hell" inherent in the design. Assuming you aren't partitioning 99threads for particular use-cases, you can have a single instance of this that you pass to multiple clients. 100 101## Mac-Only TLS Behavior 102 103Please note that on Mac, once a private key is used with a certificate, that certificate-key pair is imported into the Mac Keychain. All subsequent uses of that certificate will use the stored private key and ignore anything passed in programmatically. Beginning in v0.8.10, when a stored private key from the Keychain is used, the following will be logged at the "info" log level: 104 105``` 106static: certificate has an existing certificate-key pair that was previously imported into the Keychain. Using key from Keychain instead of the one provided. 107``` 108 109## License 110 111This library is licensed under the Apache 2.0 License. 112