AWS IoT Fleet Provisioning  v1.0.0
AWS IoT Fleet Provisioning Library
fleet_provisioning.h
Go to the documentation of this file.
1 /*
2  * AWS IoT Fleet Provisioning v1.0.0
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 
55 typedef enum
56 {
57  FleetProvisioningError = 0,
58  FleetProvisioningSuccess,
59  FleetProvisioningNoMatch,
60  FleetProvisioningBadParameter,
61  FleetProvisioningBufferTooSmall
62 } FleetProvisioningStatus_t;
63 
68 typedef 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 
95 typedef enum
96 {
97  FleetProvisioningPublish,
98  FleetProvisioningAccepted,
99  FleetProvisioningRejected
100 } FleetProvisioningApiTopics_t;
101 
106 typedef 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] */
642 FleetProvisioningStatus_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] */
706 FleetProvisioningStatus_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
fleet_provisioning_config_defaults.h
Default config values for the AWS IoT Fleet Provisioning Library.
FleetProvisioningStatus_t
FleetProvisioningStatus_t
Return codes for Fleet Provisioning APIs.
Definition: fleet_provisioning.h:56
FleetProvisioningApiTopics_t
FleetProvisioningApiTopics_t
Topics for each Fleet Provisioning APIs.
Definition: fleet_provisioning.h:96
FleetProvisioningFormat_t
FleetProvisioningFormat_t
Message format for Fleet Provisioning APIs.
Definition: fleet_provisioning.h:107
FleetProvisioningTopic_t
FleetProvisioningTopic_t
Fleet Provisioning topic values.
Definition: fleet_provisioning.h:69
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