AWS IoT Fleet Provisioning v1.1.0
AWS IoT Fleet Provisioning Library
fleet_provisioning.h
Go to the documentation of this file.
1/*
2 * AWS IoT Fleet Provisioning v1.1.0
3 * Copyright (C) 2021 Amazon.com, Inc. or its affiliates. All Rights Reserved.
4 *
5 * SPDX-License-Identifier: MIT
6 *
7 * Permission is hereby granted, free of charge, to any person obtaining a copy of
8 * this software and associated documentation files (the "Software"), to deal in
9 * the Software without restriction, including without limitation the rights to
10 * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
11 * the Software, and to permit persons to whom the Software is furnished to do so,
12 * subject to the following conditions:
13 *
14 * The above copyright notice and this permission notice shall be included in all
15 * copies or substantial portions of the Software.
16 *
17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
18 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
19 * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
20 * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
21 * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
22 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
23 */
24
30#ifndef FLEET_PROVISIONING_H_
31#define FLEET_PROVISIONING_H_
32
33/* Standard includes. */
34#include <stdint.h>
35
36/* *INDENT-OFF* */
37#ifdef __cplusplus
38 extern "C" {
39#endif
40/* *INDENT-ON* */
41
42/* FLEET_PROVISIONING_DO_NOT_USE_CUSTOM_CONFIG allows building the Fleet
43 * Provisioning library without a config file. If a config file is provided,
44 * FLEET_PROVISIONING_DO_NOT_USE_CUSTOM_CONFIG macro must not be defined.
45 */
46#ifndef FLEET_PROVISIONING_DO_NOT_USE_CUSTOM_CONFIG
47 #include "fleet_provisioning_config.h"
48#endif
49
50/* Default config values. */
51#include "fleet_provisioning_config_defaults.h"
52
57typedef enum
58{
59 FleetProvisioningError = 0,
60 FleetProvisioningSuccess,
61 FleetProvisioningNoMatch,
62 FleetProvisioningBadParameter,
63 FleetProvisioningBufferTooSmall
64} FleetProvisioningStatus_t;
65
70typedef enum
71{
72 FleetProvisioningInvalidTopic = 0,
73 FleetProvJsonCreateCertFromCsrPublish,
74 FleetProvJsonCreateCertFromCsrAccepted,
75 FleetProvJsonCreateCertFromCsrRejected,
76 FleetProvJsonCreateKeysAndCertPublish,
77 FleetProvJsonCreateKeysAndCertAccepted,
78 FleetProvJsonCreateKeysAndCertRejected,
79 FleetProvJsonRegisterThingPublish,
80 FleetProvJsonRegisterThingAccepted,
81 FleetProvJsonRegisterThingRejected,
82 FleetProvCborCreateCertFromCsrPublish,
83 FleetProvCborCreateCertFromCsrAccepted,
84 FleetProvCborCreateCertFromCsrRejected,
85 FleetProvCborCreateKeysAndCertPublish,
86 FleetProvCborCreateKeysAndCertAccepted,
87 FleetProvCborCreateKeysAndCertRejected,
88 FleetProvCborRegisterThingPublish,
89 FleetProvCborRegisterThingAccepted,
90 FleetProvCborRegisterThingRejected
91} FleetProvisioningTopic_t;
92
97typedef enum
98{
99 FleetProvisioningPublish,
100 FleetProvisioningAccepted,
101 FleetProvisioningRejected
102} FleetProvisioningApiTopics_t;
103
108typedef enum
109{
110 FleetProvisioningJson,
111 FleetProvisioningCbor
112} FleetProvisioningFormat_t;
113
114/*-----------------------------------------------------------*/
115
120#define FP_TEMPLATENAME_MAX_LENGTH 36U
121
122/*-----------------------------------------------------------*/
123
129#define FP_CREATE_CERT_API_PREFIX "$aws/certificates/create-from-csr/"
130#define FP_CREATE_CERT_API_LENGTH_PREFIX ( ( uint16_t ) ( sizeof( FP_CREATE_CERT_API_PREFIX ) - 1U ) )
131
132#define FP_CREATE_KEYS_API_PREFIX "$aws/certificates/create/"
133#define FP_CREATE_KEYS_API_LENGTH_PREFIX ( ( uint16_t ) ( sizeof( FP_CREATE_KEYS_API_PREFIX ) - 1U ) )
134
135#define FP_REGISTER_API_PREFIX "$aws/provisioning-templates/"
136#define FP_REGISTER_API_LENGTH_PREFIX ( ( uint16_t ) ( sizeof( FP_REGISTER_API_PREFIX ) - 1U ) )
137
138#define FP_REGISTER_API_BRIDGE "/provision/"
139#define FP_REGISTER_API_LENGTH_BRIDGE ( ( uint16_t ) ( sizeof( FP_REGISTER_API_BRIDGE ) - 1U ) )
140
141#define FP_API_JSON_FORMAT "json"
142#define FP_API_LENGTH_JSON_FORMAT ( ( uint16_t ) ( sizeof( FP_API_JSON_FORMAT ) - 1U ) )
143
144#define FP_API_CBOR_FORMAT "cbor"
145#define FP_API_LENGTH_CBOR_FORMAT ( ( uint16_t ) ( sizeof( FP_API_CBOR_FORMAT ) - 1U ) )
146
147#define FP_API_ACCEPTED_SUFFIX "/accepted"
148#define FP_API_LENGTH_ACCEPTED_SUFFIX ( ( uint16_t ) ( sizeof( FP_API_ACCEPTED_SUFFIX ) - 1U ) )
149
150#define FP_API_REJECTED_SUFFIX "/rejected"
151#define FP_API_LENGTH_REJECTED_SUFFIX ( ( uint16_t ) ( sizeof( FP_API_REJECTED_SUFFIX ) - 1U ) )
152
155/*-----------------------------------------------------------*/
156
157/* Fleet Provisioning CreateCertificateFromCSR macros */
158
162#define FP_JSON_CREATE_CERT_PUBLISH_TOPIC \
163 ( FP_CREATE_CERT_API_PREFIX \
164 FP_API_JSON_FORMAT )
165
169#define FP_JSON_CREATE_CERT_ACCEPTED_TOPIC \
170 ( FP_CREATE_CERT_API_PREFIX \
171 FP_API_JSON_FORMAT \
172 FP_API_ACCEPTED_SUFFIX )
173
177#define FP_JSON_CREATE_CERT_REJECTED_TOPIC \
178 ( FP_CREATE_CERT_API_PREFIX \
179 FP_API_JSON_FORMAT \
180 FP_API_REJECTED_SUFFIX )
181
185#define FP_CBOR_CREATE_CERT_PUBLISH_TOPIC \
186 ( FP_CREATE_CERT_API_PREFIX \
187 FP_API_CBOR_FORMAT )
188
192#define FP_CBOR_CREATE_CERT_ACCEPTED_TOPIC \
193 ( FP_CREATE_CERT_API_PREFIX \
194 FP_API_CBOR_FORMAT \
195 FP_API_ACCEPTED_SUFFIX )
196
200#define FP_CBOR_CREATE_CERT_REJECTED_TOPIC \
201 ( FP_CREATE_CERT_API_PREFIX \
202 FP_API_CBOR_FORMAT \
203 FP_API_REJECTED_SUFFIX )
204
208#define FP_JSON_CREATE_CERT_PUBLISH_LENGTH \
209 ( ( uint16_t ) ( sizeof( FP_JSON_CREATE_CERT_PUBLISH_TOPIC ) - 1U ) )
210
214#define FP_JSON_CREATE_CERT_ACCEPTED_LENGTH \
215 ( ( uint16_t ) ( sizeof( FP_JSON_CREATE_CERT_ACCEPTED_TOPIC ) - 1U ) )
216
220#define FP_JSON_CREATE_CERT_REJECTED_LENGTH \
221 ( ( uint16_t ) ( sizeof( FP_JSON_CREATE_CERT_REJECTED_TOPIC ) - 1U ) )
222
226#define FP_CBOR_CREATE_CERT_PUBLISH_LENGTH \
227 ( ( uint16_t ) ( sizeof( FP_CBOR_CREATE_CERT_PUBLISH_TOPIC ) - 1U ) )
228
232#define FP_CBOR_CREATE_CERT_ACCEPTED_LENGTH \
233 ( ( uint16_t ) ( sizeof( FP_CBOR_CREATE_CERT_ACCEPTED_TOPIC ) - 1U ) )
234
238#define FP_CBOR_CREATE_CERT_REJECTED_LENGTH \
239 ( ( uint16_t ) ( sizeof( FP_CBOR_CREATE_CERT_REJECTED_TOPIC ) - 1U ) )
240
241/*-----------------------------------------------------------*/
242
243/* Fleet Provisioning CreateKeysAndCertificate macros */
244
248#define FP_JSON_CREATE_KEYS_PUBLISH_TOPIC \
249 ( FP_CREATE_KEYS_API_PREFIX \
250 FP_API_JSON_FORMAT )
251
255#define FP_JSON_CREATE_KEYS_ACCEPTED_TOPIC \
256 ( FP_CREATE_KEYS_API_PREFIX \
257 FP_API_JSON_FORMAT \
258 FP_API_ACCEPTED_SUFFIX )
259
264#define FP_JSON_CREATE_KEYS_REJECTED_TOPIC \
265 ( FP_CREATE_KEYS_API_PREFIX \
266 FP_API_JSON_FORMAT \
267 FP_API_REJECTED_SUFFIX )
268
272#define FP_CBOR_CREATE_KEYS_PUBLISH_TOPIC \
273 ( FP_CREATE_KEYS_API_PREFIX \
274 FP_API_CBOR_FORMAT )
275
279#define FP_CBOR_CREATE_KEYS_ACCEPTED_TOPIC \
280 ( FP_CREATE_KEYS_API_PREFIX \
281 FP_API_CBOR_FORMAT \
282 FP_API_ACCEPTED_SUFFIX )
283
288#define FP_CBOR_CREATE_KEYS_REJECTED_TOPIC \
289 ( FP_CREATE_KEYS_API_PREFIX \
290 FP_API_CBOR_FORMAT \
291 FP_API_REJECTED_SUFFIX )
292
296#define FP_JSON_CREATE_KEYS_PUBLISH_LENGTH \
297 ( ( uint16_t ) ( sizeof( FP_JSON_CREATE_KEYS_PUBLISH_TOPIC ) - 1U ) )
298
302#define FP_JSON_CREATE_KEYS_ACCEPTED_LENGTH \
303 ( ( uint16_t ) ( sizeof( FP_JSON_CREATE_KEYS_ACCEPTED_TOPIC ) - 1U ) )
304
308#define FP_JSON_CREATE_KEYS_REJECTED_LENGTH \
309 ( ( uint16_t ) ( sizeof( FP_JSON_CREATE_KEYS_REJECTED_TOPIC ) - 1U ) )
310
314#define FP_CBOR_CREATE_KEYS_PUBLISH_LENGTH \
315 ( ( uint16_t ) ( sizeof( FP_CBOR_CREATE_KEYS_PUBLISH_TOPIC ) - 1U ) )
316
320#define FP_CBOR_CREATE_KEYS_ACCEPTED_LENGTH \
321 ( ( uint16_t ) ( sizeof( FP_CBOR_CREATE_KEYS_ACCEPTED_TOPIC ) - 1U ) )
322
326#define FP_CBOR_CREATE_KEYS_REJECTED_LENGTH \
327 ( ( uint16_t ) ( sizeof( FP_CBOR_CREATE_KEYS_REJECTED_TOPIC ) - 1U ) )
328
329/*-----------------------------------------------------------*/
330
331/* Fleet Provisioning RegisterThing macros */
332
333
343#define FP_JSON_REGISTER_PUBLISH_TOPIC( templateName ) \
344 ( FP_REGISTER_API_PREFIX \
345 templateName \
346 FP_REGISTER_API_BRIDGE \
347 FP_API_JSON_FORMAT )
348
358#define FP_JSON_REGISTER_ACCEPTED_TOPIC( templateName ) \
359 ( FP_REGISTER_API_PREFIX \
360 templateName \
361 FP_REGISTER_API_BRIDGE \
362 FP_API_JSON_FORMAT \
363 FP_API_ACCEPTED_SUFFIX )
364
374#define FP_JSON_REGISTER_REJECTED_TOPIC( templateName ) \
375 ( FP_REGISTER_API_PREFIX \
376 templateName \
377 FP_REGISTER_API_BRIDGE \
378 FP_API_JSON_FORMAT \
379 FP_API_REJECTED_SUFFIX )
380
390#define FP_CBOR_REGISTER_PUBLISH_TOPIC( templateName ) \
391 ( FP_REGISTER_API_PREFIX \
392 templateName \
393 FP_REGISTER_API_BRIDGE \
394 FP_API_CBOR_FORMAT )
395
405#define FP_CBOR_REGISTER_ACCEPTED_TOPIC( templateName ) \
406 ( FP_REGISTER_API_PREFIX \
407 templateName \
408 FP_REGISTER_API_BRIDGE \
409 FP_API_CBOR_FORMAT \
410 FP_API_ACCEPTED_SUFFIX )
411
421#define FP_CBOR_REGISTER_REJECTED_TOPIC( templateName ) \
422 ( FP_REGISTER_API_PREFIX \
423 templateName \
424 FP_REGISTER_API_BRIDGE \
425 FP_API_CBOR_FORMAT \
426 FP_API_REJECTED_SUFFIX )
427
437#define FP_JSON_REGISTER_PUBLISH_LENGTH( templateNameLength ) \
438 ( FP_REGISTER_API_LENGTH_PREFIX + \
439 ( templateNameLength ) + \
440 FP_REGISTER_API_LENGTH_BRIDGE + \
441 FP_API_LENGTH_JSON_FORMAT )
442
452#define FP_JSON_REGISTER_ACCEPTED_LENGTH( templateNameLength ) \
453 ( FP_REGISTER_API_LENGTH_PREFIX + \
454 ( templateNameLength ) + \
455 FP_REGISTER_API_LENGTH_BRIDGE + \
456 FP_API_LENGTH_JSON_FORMAT + \
457 FP_API_LENGTH_ACCEPTED_SUFFIX )
458
468#define FP_JSON_REGISTER_REJECTED_LENGTH( templateNameLength ) \
469 ( FP_REGISTER_API_LENGTH_PREFIX + \
470 ( templateNameLength ) + \
471 FP_REGISTER_API_LENGTH_BRIDGE + \
472 FP_API_LENGTH_JSON_FORMAT + \
473 FP_API_LENGTH_REJECTED_SUFFIX )
474
484#define FP_CBOR_REGISTER_PUBLISH_LENGTH( templateNameLength ) \
485 ( FP_REGISTER_API_LENGTH_PREFIX + \
486 ( templateNameLength ) + \
487 FP_REGISTER_API_LENGTH_BRIDGE + \
488 FP_API_LENGTH_CBOR_FORMAT )
489
499#define FP_CBOR_REGISTER_ACCEPTED_LENGTH( templateNameLength ) \
500 ( FP_REGISTER_API_LENGTH_PREFIX + \
501 ( templateNameLength ) + \
502 FP_REGISTER_API_LENGTH_BRIDGE + \
503 FP_API_LENGTH_CBOR_FORMAT + \
504 FP_API_LENGTH_ACCEPTED_SUFFIX )
505
515#define FP_CBOR_REGISTER_REJECTED_LENGTH( templateNameLength ) \
516 ( FP_REGISTER_API_LENGTH_PREFIX + \
517 ( templateNameLength ) + \
518 FP_REGISTER_API_LENGTH_BRIDGE + \
519 FP_API_LENGTH_CBOR_FORMAT + \
520 FP_API_LENGTH_REJECTED_SUFFIX )
521
522/*-----------------------------------------------------------*/
523
524/* Key names for Fleet Provisioning MQTT API JSON/CBOR payloads. */
525
530#define FP_API_CSR_KEY "certificateSigningRequest"
531
537#define FP_API_OWNERSHIP_TOKEN_KEY "certificateOwnershipToken"
538
543#define FP_API_CERTIFICATE_ID_KEY "certificateId"
544
549#define FP_API_CERTIFICATE_PEM_KEY "certificatePem"
550
555#define FP_API_PRIVATE_KEY_KEY "privateKey"
556
560#define FP_API_PARAMETERS_KEY "parameters"
561
566#define FP_API_DEVICE_CONFIG_KEY "deviceConfiguration"
567
572#define FP_API_THING_NAME_KEY "thingName"
573
578#define FP_API_STATUS_CODE_KEY "statusCode"
579
583#define FP_API_ERROR_CODE_KEY "errorCode"
584
589#define FP_API_ERROR_MESSAGE_KEY "errorMessage"
590
591/*-----------------------------------------------------------*/
592
643/* @[declare_fleet_provisioning_getregisterthingtopic] */
644FleetProvisioningStatus_t FleetProvisioning_GetRegisterThingTopic( char * pTopicBuffer,
645 uint16_t bufferLength,
646 FleetProvisioningFormat_t format,
647 FleetProvisioningApiTopics_t topic,
648 const char * pTemplateName,
649 uint16_t templateNameLength,
650 uint16_t * pOutLength );
651/* @[declare_fleet_provisioning_getregisterthingtopic] */
652
653/*-----------------------------------------------------------*/
654
707/* @[declare_fleet_provisioning_matchtopic] */
708FleetProvisioningStatus_t FleetProvisioning_MatchTopic( const char * pTopic,
709 uint16_t topicLength,
710 FleetProvisioningTopic_t * pOutApi );
711/* @[declare_fleet_provisioning_matchtopic] */
712
713/*-----------------------------------------------------------*/
714
715/* *INDENT-OFF* */
716#ifdef __cplusplus
717 }
718#endif
719/* *INDENT-ON* */
720
721#endif /* FLEET_PROVISIONING_H_ */
FleetProvisioning_MatchTopic
FleetProvisioningStatus_t FleetProvisioning_MatchTopic(const char *pTopic, uint16_t topicLength, FleetProvisioningTopic_t *pOutApi)
Check if the given topic is one of the Fleet Provisioning topics.
Definition: fleet_provisioning.c:731
FleetProvisioning_GetRegisterThingTopic
FleetProvisioningStatus_t FleetProvisioning_GetRegisterThingTopic(char *pTopicBuffer, uint16_t bufferLength, FleetProvisioningFormat_t format, FleetProvisioningApiTopics_t topic, const char *pTemplateName, uint16_t templateNameLength, uint16_t *pOutLength)
Populate the topic string for a Fleet Provisioning RegisterThing topic.
Definition: fleet_provisioning.c:640
fleet_provisioning_config_defaults.h
Default config values for the AWS IoT Fleet Provisioning Library.
FleetProvisioningTopic_t
FleetProvisioningTopic_t
Fleet Provisioning topic values.
Definition: fleet_provisioning.h:71
FleetProvisioningApiTopics_t
FleetProvisioningApiTopics_t
Topics for each Fleet Provisioning APIs.
Definition: fleet_provisioning.h:98
FleetProvisioningStatus_t
FleetProvisioningStatus_t
Return codes for Fleet Provisioning APIs.
Definition: fleet_provisioning.h:58
FleetProvisioningFormat_t
FleetProvisioningFormat_t
Message format for Fleet Provisioning APIs.
Definition: fleet_provisioning.h:109