AWS IoT Fleet Provisioning v1.0.1
AWS IoT Fleet Provisioning Library
fleet_provisioning.h
Go to the documentation of this file.
1/*
2 * AWS IoT Fleet Provisioning v1.0.1
3 * Copyright (C) 2021 Amazon.com, Inc. or its affiliates. All Rights Reserved.
4 *
5 * Permission is hereby granted, free of charge, to any person obtaining a copy of
6 * this software and associated documentation files (the "Software"), to deal in
7 * the Software without restriction, including without limitation the rights to
8 * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
9 * the Software, and to permit persons to whom the Software is furnished to do so,
10 * subject to the following conditions:
11 *
12 * The above copyright notice and this permission notice shall be included in all
13 * copies or substantial portions of the Software.
14 *
15 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
17 * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
18 * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
19 * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
20 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
21 */
22
28#ifndef FLEET_PROVISIONING_H_
29#define FLEET_PROVISIONING_H_
30
31/* Standard includes. */
32#include <stdint.h>
33
34/* *INDENT-OFF* */
35#ifdef __cplusplus
36 extern "C" {
37#endif
38/* *INDENT-ON* */
39
40/* FLEET_PROVISIONING_DO_NOT_USE_CUSTOM_CONFIG allows building the Fleet
41 * Provisioning library without a config file. If a config file is provided,
42 * FLEET_PROVISIONING_DO_NOT_USE_CUSTOM_CONFIG macro must not be defined.
43 */
44#ifndef FLEET_PROVISIONING_DO_NOT_USE_CUSTOM_CONFIG
45 #include "fleet_provisioning_config.h"
46#endif
47
48/* Default config values. */
49#include "fleet_provisioning_config_defaults.h"
50
55typedef enum
56{
57 FleetProvisioningError = 0,
58 FleetProvisioningSuccess,
59 FleetProvisioningNoMatch,
60 FleetProvisioningBadParameter,
61 FleetProvisioningBufferTooSmall
62} FleetProvisioningStatus_t;
63
68typedef enum
69{
70 FleetProvisioningInvalidTopic = 0,
71 FleetProvJsonCreateCertFromCsrPublish,
72 FleetProvJsonCreateCertFromCsrAccepted,
73 FleetProvJsonCreateCertFromCsrRejected,
74 FleetProvJsonCreateKeysAndCertPublish,
75 FleetProvJsonCreateKeysAndCertAccepted,
76 FleetProvJsonCreateKeysAndCertRejected,
77 FleetProvJsonRegisterThingPublish,
78 FleetProvJsonRegisterThingAccepted,
79 FleetProvJsonRegisterThingRejected,
80 FleetProvCborCreateCertFromCsrPublish,
81 FleetProvCborCreateCertFromCsrAccepted,
82 FleetProvCborCreateCertFromCsrRejected,
83 FleetProvCborCreateKeysAndCertPublish,
84 FleetProvCborCreateKeysAndCertAccepted,
85 FleetProvCborCreateKeysAndCertRejected,
86 FleetProvCborRegisterThingPublish,
87 FleetProvCborRegisterThingAccepted,
88 FleetProvCborRegisterThingRejected
89} FleetProvisioningTopic_t;
90
95typedef enum
96{
97 FleetProvisioningPublish,
98 FleetProvisioningAccepted,
99 FleetProvisioningRejected
100} FleetProvisioningApiTopics_t;
101
106typedef enum
107{
108 FleetProvisioningJson,
109 FleetProvisioningCbor
110} FleetProvisioningFormat_t;
111
112/*-----------------------------------------------------------*/
113
118#define FP_TEMPLATENAME_MAX_LENGTH 36U
119
120/*-----------------------------------------------------------*/
121
127#define FP_CREATE_CERT_API_PREFIX "$aws/certificates/create-from-csr/"
128#define FP_CREATE_CERT_API_LENGTH_PREFIX ( ( uint16_t ) ( sizeof( FP_CREATE_CERT_API_PREFIX ) - 1U ) )
129
130#define FP_CREATE_KEYS_API_PREFIX "$aws/certificates/create/"
131#define FP_CREATE_KEYS_API_LENGTH_PREFIX ( ( uint16_t ) ( sizeof( FP_CREATE_KEYS_API_PREFIX ) - 1U ) )
132
133#define FP_REGISTER_API_PREFIX "$aws/provisioning-templates/"
134#define FP_REGISTER_API_LENGTH_PREFIX ( ( uint16_t ) ( sizeof( FP_REGISTER_API_PREFIX ) - 1U ) )
135
136#define FP_REGISTER_API_BRIDGE "/provision/"
137#define FP_REGISTER_API_LENGTH_BRIDGE ( ( uint16_t ) ( sizeof( FP_REGISTER_API_BRIDGE ) - 1U ) )
138
139#define FP_API_JSON_FORMAT "json"
140#define FP_API_LENGTH_JSON_FORMAT ( ( uint16_t ) ( sizeof( FP_API_JSON_FORMAT ) - 1U ) )
141
142#define FP_API_CBOR_FORMAT "cbor"
143#define FP_API_LENGTH_CBOR_FORMAT ( ( uint16_t ) ( sizeof( FP_API_CBOR_FORMAT ) - 1U ) )
144
145#define FP_API_ACCEPTED_SUFFIX "/accepted"
146#define FP_API_LENGTH_ACCEPTED_SUFFIX ( ( uint16_t ) ( sizeof( FP_API_ACCEPTED_SUFFIX ) - 1U ) )
147
148#define FP_API_REJECTED_SUFFIX "/rejected"
149#define FP_API_LENGTH_REJECTED_SUFFIX ( ( uint16_t ) ( sizeof( FP_API_REJECTED_SUFFIX ) - 1U ) )
150
153/*-----------------------------------------------------------*/
154
155/* Fleet Provisioning CreateCertificateFromCSR macros */
156
160#define FP_JSON_CREATE_CERT_PUBLISH_TOPIC \
161 ( FP_CREATE_CERT_API_PREFIX \
162 FP_API_JSON_FORMAT )
163
167#define FP_JSON_CREATE_CERT_ACCEPTED_TOPIC \
168 ( FP_CREATE_CERT_API_PREFIX \
169 FP_API_JSON_FORMAT \
170 FP_API_ACCEPTED_SUFFIX )
171
175#define FP_JSON_CREATE_CERT_REJECTED_TOPIC \
176 ( FP_CREATE_CERT_API_PREFIX \
177 FP_API_JSON_FORMAT \
178 FP_API_REJECTED_SUFFIX )
179
183#define FP_CBOR_CREATE_CERT_PUBLISH_TOPIC \
184 ( FP_CREATE_CERT_API_PREFIX \
185 FP_API_CBOR_FORMAT )
186
190#define FP_CBOR_CREATE_CERT_ACCEPTED_TOPIC \
191 ( FP_CREATE_CERT_API_PREFIX \
192 FP_API_CBOR_FORMAT \
193 FP_API_ACCEPTED_SUFFIX )
194
198#define FP_CBOR_CREATE_CERT_REJECTED_TOPIC \
199 ( FP_CREATE_CERT_API_PREFIX \
200 FP_API_CBOR_FORMAT \
201 FP_API_REJECTED_SUFFIX )
202
206#define FP_JSON_CREATE_CERT_PUBLISH_LENGTH \
207 ( ( uint16_t ) ( sizeof( FP_JSON_CREATE_CERT_PUBLISH_TOPIC ) - 1U ) )
208
212#define FP_JSON_CREATE_CERT_ACCEPTED_LENGTH \
213 ( ( uint16_t ) ( sizeof( FP_JSON_CREATE_CERT_ACCEPTED_TOPIC ) - 1U ) )
214
218#define FP_JSON_CREATE_CERT_REJECTED_LENGTH \
219 ( ( uint16_t ) ( sizeof( FP_JSON_CREATE_CERT_REJECTED_TOPIC ) - 1U ) )
220
224#define FP_CBOR_CREATE_CERT_PUBLISH_LENGTH \
225 ( ( uint16_t ) ( sizeof( FP_CBOR_CREATE_CERT_PUBLISH_TOPIC ) - 1U ) )
226
230#define FP_CBOR_CREATE_CERT_ACCEPTED_LENGTH \
231 ( ( uint16_t ) ( sizeof( FP_CBOR_CREATE_CERT_ACCEPTED_TOPIC ) - 1U ) )
232
236#define FP_CBOR_CREATE_CERT_REJECTED_LENGTH \
237 ( ( uint16_t ) ( sizeof( FP_CBOR_CREATE_CERT_REJECTED_TOPIC ) - 1U ) )
238
239/*-----------------------------------------------------------*/
240
241/* Fleet Provisioning CreateKeysAndCertificate macros */
242
246#define FP_JSON_CREATE_KEYS_PUBLISH_TOPIC \
247 ( FP_CREATE_KEYS_API_PREFIX \
248 FP_API_JSON_FORMAT )
249
253#define FP_JSON_CREATE_KEYS_ACCEPTED_TOPIC \
254 ( FP_CREATE_KEYS_API_PREFIX \
255 FP_API_JSON_FORMAT \
256 FP_API_ACCEPTED_SUFFIX )
257
262#define FP_JSON_CREATE_KEYS_REJECTED_TOPIC \
263 ( FP_CREATE_KEYS_API_PREFIX \
264 FP_API_JSON_FORMAT \
265 FP_API_REJECTED_SUFFIX )
266
270#define FP_CBOR_CREATE_KEYS_PUBLISH_TOPIC \
271 ( FP_CREATE_KEYS_API_PREFIX \
272 FP_API_CBOR_FORMAT )
273
277#define FP_CBOR_CREATE_KEYS_ACCEPTED_TOPIC \
278 ( FP_CREATE_KEYS_API_PREFIX \
279 FP_API_CBOR_FORMAT \
280 FP_API_ACCEPTED_SUFFIX )
281
286#define FP_CBOR_CREATE_KEYS_REJECTED_TOPIC \
287 ( FP_CREATE_KEYS_API_PREFIX \
288 FP_API_CBOR_FORMAT \
289 FP_API_REJECTED_SUFFIX )
290
294#define FP_JSON_CREATE_KEYS_PUBLISH_LENGTH \
295 ( ( uint16_t ) ( sizeof( FP_JSON_CREATE_KEYS_PUBLISH_TOPIC ) - 1U ) )
296
300#define FP_JSON_CREATE_KEYS_ACCEPTED_LENGTH \
301 ( ( uint16_t ) ( sizeof( FP_JSON_CREATE_KEYS_ACCEPTED_TOPIC ) - 1U ) )
302
306#define FP_JSON_CREATE_KEYS_REJECTED_LENGTH \
307 ( ( uint16_t ) ( sizeof( FP_JSON_CREATE_KEYS_REJECTED_TOPIC ) - 1U ) )
308
312#define FP_CBOR_CREATE_KEYS_PUBLISH_LENGTH \
313 ( ( uint16_t ) ( sizeof( FP_CBOR_CREATE_KEYS_PUBLISH_TOPIC ) - 1U ) )
314
318#define FP_CBOR_CREATE_KEYS_ACCEPTED_LENGTH \
319 ( ( uint16_t ) ( sizeof( FP_CBOR_CREATE_KEYS_ACCEPTED_TOPIC ) - 1U ) )
320
324#define FP_CBOR_CREATE_KEYS_REJECTED_LENGTH \
325 ( ( uint16_t ) ( sizeof( FP_CBOR_CREATE_KEYS_REJECTED_TOPIC ) - 1U ) )
326
327/*-----------------------------------------------------------*/
328
329/* Fleet Provisioning RegisterThing macros */
330
331
341#define FP_JSON_REGISTER_PUBLISH_TOPIC( templateName ) \
342 ( FP_REGISTER_API_PREFIX \
343 templateName \
344 FP_REGISTER_API_BRIDGE \
345 FP_API_JSON_FORMAT )
346
356#define FP_JSON_REGISTER_ACCEPTED_TOPIC( templateName ) \
357 ( FP_REGISTER_API_PREFIX \
358 templateName \
359 FP_REGISTER_API_BRIDGE \
360 FP_API_JSON_FORMAT \
361 FP_API_ACCEPTED_SUFFIX )
362
372#define FP_JSON_REGISTER_REJECTED_TOPIC( templateName ) \
373 ( FP_REGISTER_API_PREFIX \
374 templateName \
375 FP_REGISTER_API_BRIDGE \
376 FP_API_JSON_FORMAT \
377 FP_API_REJECTED_SUFFIX )
378
388#define FP_CBOR_REGISTER_PUBLISH_TOPIC( templateName ) \
389 ( FP_REGISTER_API_PREFIX \
390 templateName \
391 FP_REGISTER_API_BRIDGE \
392 FP_API_CBOR_FORMAT )
393
403#define FP_CBOR_REGISTER_ACCEPTED_TOPIC( templateName ) \
404 ( FP_REGISTER_API_PREFIX \
405 templateName \
406 FP_REGISTER_API_BRIDGE \
407 FP_API_CBOR_FORMAT \
408 FP_API_ACCEPTED_SUFFIX )
409
419#define FP_CBOR_REGISTER_REJECTED_TOPIC( templateName ) \
420 ( FP_REGISTER_API_PREFIX \
421 templateName \
422 FP_REGISTER_API_BRIDGE \
423 FP_API_CBOR_FORMAT \
424 FP_API_REJECTED_SUFFIX )
425
435#define FP_JSON_REGISTER_PUBLISH_LENGTH( templateNameLength ) \
436 ( FP_REGISTER_API_LENGTH_PREFIX + \
437 ( templateNameLength ) + \
438 FP_REGISTER_API_LENGTH_BRIDGE + \
439 FP_API_LENGTH_JSON_FORMAT )
440
450#define FP_JSON_REGISTER_ACCEPTED_LENGTH( templateNameLength ) \
451 ( FP_REGISTER_API_LENGTH_PREFIX + \
452 ( templateNameLength ) + \
453 FP_REGISTER_API_LENGTH_BRIDGE + \
454 FP_API_LENGTH_JSON_FORMAT + \
455 FP_API_LENGTH_ACCEPTED_SUFFIX )
456
466#define FP_JSON_REGISTER_REJECTED_LENGTH( templateNameLength ) \
467 ( FP_REGISTER_API_LENGTH_PREFIX + \
468 ( templateNameLength ) + \
469 FP_REGISTER_API_LENGTH_BRIDGE + \
470 FP_API_LENGTH_JSON_FORMAT + \
471 FP_API_LENGTH_REJECTED_SUFFIX )
472
482#define FP_CBOR_REGISTER_PUBLISH_LENGTH( templateNameLength ) \
483 ( FP_REGISTER_API_LENGTH_PREFIX + \
484 ( templateNameLength ) + \
485 FP_REGISTER_API_LENGTH_BRIDGE + \
486 FP_API_LENGTH_CBOR_FORMAT )
487
497#define FP_CBOR_REGISTER_ACCEPTED_LENGTH( templateNameLength ) \
498 ( FP_REGISTER_API_LENGTH_PREFIX + \
499 ( templateNameLength ) + \
500 FP_REGISTER_API_LENGTH_BRIDGE + \
501 FP_API_LENGTH_CBOR_FORMAT + \
502 FP_API_LENGTH_ACCEPTED_SUFFIX )
503
513#define FP_CBOR_REGISTER_REJECTED_LENGTH( templateNameLength ) \
514 ( FP_REGISTER_API_LENGTH_PREFIX + \
515 ( templateNameLength ) + \
516 FP_REGISTER_API_LENGTH_BRIDGE + \
517 FP_API_LENGTH_CBOR_FORMAT + \
518 FP_API_LENGTH_REJECTED_SUFFIX )
519
520/*-----------------------------------------------------------*/
521
522/* Key names for Fleet Provisioning MQTT API JSON/CBOR payloads. */
523
528#define FP_API_CSR_KEY "certificateSigningRequest"
529
535#define FP_API_OWNERSHIP_TOKEN_KEY "certificateOwnershipToken"
536
541#define FP_API_CERTIFICATE_ID_KEY "certificateId"
542
547#define FP_API_CERTIFICATE_PEM_KEY "certificatePem"
548
553#define FP_API_PRIVATE_KEY_KEY "privateKey"
554
558#define FP_API_PARAMETERS_KEY "parameters"
559
564#define FP_API_DEVICE_CONFIG_KEY "deviceConfiguration"
565
570#define FP_API_THING_NAME_KEY "thingName"
571
576#define FP_API_STATUS_CODE_KEY "statusCode"
577
581#define FP_API_ERROR_CODE_KEY "errorCode"
582
587#define FP_API_ERROR_MESSAGE_KEY "errorMessage"
588
589/*-----------------------------------------------------------*/
590
641/* @[declare_fleet_provisioning_getregisterthingtopic] */
642FleetProvisioningStatus_t FleetProvisioning_GetRegisterThingTopic( char * pTopicBuffer,
643 uint16_t bufferLength,
644 FleetProvisioningFormat_t format,
645 FleetProvisioningApiTopics_t topic,
646 const char * pTemplateName,
647 uint16_t templateNameLength,
648 uint16_t * pOutLength );
649/* @[declare_fleet_provisioning_getregisterthingtopic] */
650
651/*-----------------------------------------------------------*/
652
705/* @[declare_fleet_provisioning_matchtopic] */
706FleetProvisioningStatus_t FleetProvisioning_MatchTopic( const char * pTopic,
707 uint16_t topicLength,
708 FleetProvisioningTopic_t * pOutApi );
709/* @[declare_fleet_provisioning_matchtopic] */
710
711/*-----------------------------------------------------------*/
712
713/* *INDENT-OFF* */
714#ifdef __cplusplus
715 }
716#endif
717/* *INDENT-ON* */
718
719#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:729
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:638
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:69
FleetProvisioningApiTopics_t
FleetProvisioningApiTopics_t
Topics for each Fleet Provisioning APIs.
Definition: fleet_provisioning.h:96
FleetProvisioningStatus_t
FleetProvisioningStatus_t
Return codes for Fleet Provisioning APIs.
Definition: fleet_provisioning.h:56
FleetProvisioningFormat_t
FleetProvisioningFormat_t
Message format for Fleet Provisioning APIs.
Definition: fleet_provisioning.h:107