Skip to content

Commit 8ec72d6

Browse files
DakshitBabbarDakshitBabbaraggarg
authored
Add CBMC Proofs for the new APIs (#315)
Description ----------- This PR: Adds CBMC proofs for the new APIs added for publish retransmits in #308 Test Steps ----------- Proofs run without any errors or warnings Checklist: ---------- - [x] I have tested my changes. No regression in existing tests. - [x] I have modified and/or added unit-tests to cover the code changes in this Pull Request. Related Issue ----------- <!-- If any, please provide issue ID. --> By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice. --------- Co-authored-by: DakshitBabbar <[email protected]> Co-authored-by: Gaurav-Aggarwal-AWS <[email protected]>
1 parent 86a5750 commit 8ec72d6

File tree

14 files changed

+303
-15
lines changed

14 files changed

+303
-15
lines changed

source/include/core_mqtt.h

+3-3
Original file line numberDiff line numberDiff line change
@@ -1228,7 +1228,7 @@ const char * MQTT_Status_strerror( MQTTStatus_t status );
12281228
/**
12291229
* @brief Get the bytes in a #MQTTVec pointer which can store the whole array as a an MQTT packet when calling MQTT_SerializeMQTTVec( void * pAllocatedMem, MQTTVec_t *pVec ) function.
12301230
*
1231-
* @param[in] pVec The #MQTTVec pointer.
1231+
* @param[in] pVec The #MQTTVec pointer given as input to the user defined #MQTTStorePacketForRetransmit callback function. Must not be NULL.
12321232
*
12331233
* @return The bytes in the provided #MQTTVec array which can then be used to set aside memory to be used with MQTT_SerializeMQTTVec( void * pAllocatedMem, MQTTVec_t *pVec ) function.
12341234
*/
@@ -1239,8 +1239,8 @@ size_t MQTT_GetBytesInMQTTVec( const MQTTVec_t * pVec );
12391239
/**
12401240
* @brief Serialize the bytes in an array of #MQTTVec in the provided \p pAllocatedMem
12411241
*
1242-
* @param[in] pAllocatedMem Memory in which to serialize the data in the #MQTTVec array. It must be of size provided by MQTT_GetBytesInMQTTVec( MQTTVec_t *pVec ).
1243-
* @param[in] pVec The #MQTTVec pointer.
1242+
* @param[in] pAllocatedMem Memory in which to serialize the data in the #MQTTVec array. It must be of size provided by MQTT_GetBytesInMQTTVec( MQTTVec_t *pVec ). Should not be NULL.
1243+
* @param[in] pVec The #MQTTVec pointer given as input to the user defined #MQTTStorePacketForRetransmit callback function. Must not be NULL.
12441244
*/
12451245
/* @[declare_mqtt_serializemqttvec] */
12461246
void MQTT_SerializeMQTTVec( uint8_t * pAllocatedMem,

test/cbmc/include/mqtt_cbmc_state.h

+9
Original file line numberDiff line numberDiff line change
@@ -165,4 +165,13 @@ MQTTContext_t * allocateMqttContext( MQTTContext_t * pContext );
165165
*/
166166
bool isValidMqttContext( const MQTTContext_t * pContext );
167167

168+
/**
169+
* @brief Allocate a #MQTTVec_t object.
170+
*
171+
* @param[in] mqttVec #MQTTVec_t object information.
172+
*
173+
* @return NULL or allocated #MQTTContext_t memory.
174+
*/
175+
MQTTVec_t * allocateMqttVec( MQTTVec_t * mqttVec );
176+
168177
#endif /* ifndef MQTT_CBMC_STATE_H_ */
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
/*
2+
* coreMQTT <DEVELOPMENT BRANCH>
3+
* Copyright (C) 2020 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+
25+
/**
26+
* @file MQTT_Disconnect_harness.c
27+
* @brief Implements the proof harness for MQTT_Disconnect function.
28+
*/
29+
#include "core_mqtt.h"
30+
#include "mqtt_cbmc_state.h"
31+
32+
void harness()
33+
{
34+
MQTTVec_t * mqttVec;
35+
size_t memoryRequired;
36+
37+
mqttVec = allocateMqttVec( NULL );
38+
39+
memoryRequired = MQTT_GetBytesInMQTTVec( mqttVec );
40+
}
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
#
2+
# Copyright (C) 2020 Amazon.com, Inc. or its affiliates. All Rights Reserved.
3+
#
4+
# Permission is hereby granted, free of charge, to any person obtaining a copy of
5+
# this software and associated documentation files (the "Software"), to deal in
6+
# the Software without restriction, including without limitation the rights to
7+
# use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
8+
# the Software, and to permit persons to whom the Software is furnished to do so,
9+
# subject to the following conditions:
10+
#
11+
# The above copyright notice and this permission notice shall be included in all
12+
# copies or substantial portions of the Software.
13+
#
14+
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
15+
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
16+
# FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
17+
# COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
18+
# IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
19+
# CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
20+
#
21+
22+
HARNESS_ENTRY=harness
23+
HARNESS_FILE=MQTT_GetBytesInMQTTVec_harness
24+
PROOF_UID=MQTT_GetBytesInMQTTVec
25+
26+
PUBLISH_PACKET_VECTORS = 5
27+
28+
DEFINES +=
29+
INCLUDES +=
30+
31+
REMOVE_FUNCTION_BODY +=
32+
UNWINDSET += MQTT_GetBytesInMQTTVec.0:${PUBLISH_PACKET_VECTORS}
33+
UNWINDSET += allocateMqttVec.0:${PUBLISH_PACKET_VECTORS}
34+
35+
PROOF_SOURCES += $(PROOFDIR)/$(HARNESS_FILE).c
36+
PROOF_SOURCES += $(SRCDIR)/test/cbmc/sources/mqtt_cbmc_state.c
37+
PROJECT_SOURCES += $(SRCDIR)/source/core_mqtt.c
38+
39+
include ../Makefile.common
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
MQTT_GetBytesInMQTTVec proof
2+
==============
3+
4+
This directory contains a memory safety proof for MQTT_GetBytesInMQTTVec.
5+
6+
To run the proof.
7+
* Add cbmc, goto-cc, goto-instrument, goto-analyzer, and cbmc-viewer
8+
to your path.
9+
* Run "make".
10+
* Open html/index.html in a web browser.
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
# This file marks this directory as containing a CBMC proof.
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
{ "expected-missing-functions":
2+
[
3+
4+
],
5+
"proof-name": "MQTT_GetBytesInMQTTVec",
6+
"proof-root": "test/cbmc/proofs"
7+
}
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
/*
2+
* coreMQTT <DEVELOPMENT BRANCH>
3+
* Copyright (C) 2020 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+
25+
/**
26+
* @file MQTT_Disconnect_harness.c
27+
* @brief Implements the proof harness for MQTT_Disconnect function.
28+
*/
29+
#include "core_mqtt.h"
30+
#include "mqtt_cbmc_state.h"
31+
32+
void harness()
33+
{
34+
MQTTVec_t * mqttVec;
35+
size_t memoryRequired;
36+
uint8_t * memoryBuffer;
37+
38+
mqttVec = allocateMqttVec( NULL );
39+
40+
memoryRequired = MQTT_GetBytesInMQTTVec( mqttVec );
41+
42+
/* It is a part of the API contract that #MQTT_SerializeMQTTVec will be called with
43+
* a memory buffer of size output by #MQTT_GetBytesInMQTTVec function and the
44+
* #MQTTVec_t pointer given by the library as an input to the user defined
45+
* #MQTTStorePacketForRetransmit callback function. Hence the memory buffer must
46+
* not be NULL.
47+
*/
48+
memoryBuffer = malloc( memoryRequired );
49+
__CPROVER_assume( memoryBuffer != NULL );
50+
51+
MQTT_SerializeMQTTVec( memoryBuffer, mqttVec );
52+
}
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
#
2+
# Copyright (C) 2020 Amazon.com, Inc. or its affiliates. All Rights Reserved.
3+
#
4+
# Permission is hereby granted, free of charge, to any person obtaining a copy of
5+
# this software and associated documentation files (the "Software"), to deal in
6+
# the Software without restriction, including without limitation the rights to
7+
# use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
8+
# the Software, and to permit persons to whom the Software is furnished to do so,
9+
# subject to the following conditions:
10+
#
11+
# The above copyright notice and this permission notice shall be included in all
12+
# copies or substantial portions of the Software.
13+
#
14+
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
15+
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
16+
# FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
17+
# COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
18+
# IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
19+
# CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
20+
#
21+
22+
HARNESS_ENTRY=harness
23+
HARNESS_FILE=MQTT_SerializeMQTTVec_harness
24+
PROOF_UID=MQTT_SerializeMQTTVec
25+
26+
PUBLISH_PACKET_VECTORS = 5
27+
28+
DEFINES +=
29+
INCLUDES +=
30+
31+
REMOVE_FUNCTION_BODY +=
32+
UNWINDSET += MQTT_GetBytesInMQTTVec.0:${PUBLISH_PACKET_VECTORS}
33+
UNWINDSET += allocateMqttVec.0:${PUBLISH_PACKET_VECTORS}
34+
UNWINDSET += MQTT_SerializeMQTTVec.0:${PUBLISH_PACKET_VECTORS}
35+
36+
PROOF_SOURCES += $(PROOFDIR)/$(HARNESS_FILE).c
37+
PROOF_SOURCES += $(SRCDIR)/test/cbmc/sources/mqtt_cbmc_state.c
38+
PROJECT_SOURCES += $(SRCDIR)/source/core_mqtt.c
39+
40+
include ../Makefile.common
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
MQTT_SerializeMQTTVec proof
2+
==============
3+
4+
This directory contains a memory safety proof for MQTT_SerializeMQTTVec.
5+
6+
To run the proof.
7+
* Add cbmc, goto-cc, goto-instrument, goto-analyzer, and cbmc-viewer
8+
to your path.
9+
* Run "make".
10+
* Open html/index.html in a web browser.
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
# This file marks this directory as containing a CBMC proof.
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
{ "expected-missing-functions":
2+
[
3+
4+
],
5+
"proof-name": "MQTT_SerializeMQTTVec",
6+
"proof-root": "test/cbmc/proofs"
7+
}

test/cbmc/sources/mqtt_cbmc_state.c

+68-1
Original file line numberDiff line numberDiff line change
@@ -67,7 +67,27 @@
6767
* @note This definition must exist in order to compile. 10U is a typical value
6868
* used in the MQTT demos.
6969
*/
70-
#define MAX_UNACKED_PACKETS ( 20U )
70+
#define MAX_UNACKED_PACKETS ( 20U )
71+
72+
/**
73+
* @brief Gives the maximum number of transport vectors required to encode
74+
* a publish packet to send over the network interface.
75+
*/
76+
#define PUBLISH_PACKET_VECTORS ( 4U )
77+
78+
/**
79+
* @brief Definition of the MQTTVec_t struct that is used to pass the outgoing
80+
* publish packet content to the user callback function to store the packet for
81+
* retransmission purposes
82+
*
83+
* @note The definition of this struct is hidden from the application code. The intent
84+
* behind defining the struct here is to simulate the actual process flow.
85+
*/
86+
struct MQTTVec
87+
{
88+
TransportOutVector_t * pVector; /**< Pointer to transport vector. USER SHOULD NOT ACCESS THIS DIRECTLY - IT IS AN INTERNAL DETAIL AND CAN CHANGE. */
89+
size_t vectorLen; /**< Length of the transport vector. USER SHOULD NOT ACCESS THIS DIRECTLY - IT IS AN INTERNAL DETAIL AND CAN CHANGE. */
90+
};
7191

7292
MQTTPacketInfo_t * allocateMqttPacketInfo( MQTTPacketInfo_t * pPacketInfo )
7393
{
@@ -284,3 +304,50 @@ bool isValidMqttContext( const MQTTContext_t * pContext )
284304

285305
return isValid;
286306
}
307+
308+
MQTTVec_t * allocateMqttVec( MQTTVec_t * mqttVec )
309+
{
310+
size_t vecLen;
311+
TransportOutVector_t * pVector;
312+
313+
if( mqttVec == NULL )
314+
{
315+
mqttVec = malloc( sizeof( MQTTVec_t ) );
316+
}
317+
318+
/* It is a part of the API contract that the #MQTT_GetBytesInMQTTVec API will be called
319+
* with the #MQTTVec_t pointer given by the library as an input to the user defined
320+
* #MQTTStorePacketForRetransmit callback function. The library would never provide with
321+
* a NULL pointer. As this is a simulation of the real flow, it can be assumed that the
322+
* mqttVec pointer is non-NULL.
323+
*/
324+
__CPROVER_assume( mqttVec != NULL );
325+
__CPROVER_assume( vecLen <= PUBLISH_PACKET_VECTORS );
326+
__CPROVER_assume( vecLen > 0U );
327+
328+
pVector = malloc( vecLen * sizeof( TransportOutVector_t ) );
329+
330+
/* The library is responsible with providing the memory for pVector within the mqttVec. Hence
331+
* it can be assumed that pVector is also non-NULL
332+
*/
333+
__CPROVER_assume( pVector != NULL );
334+
335+
for( int i = 0; i < vecLen; i++ )
336+
{
337+
/* One of there vectors will also hold the buffer pointing to the publish payload. The
338+
* maximum size of thepublish payload is limited by the remaining length field. Hence the maximum
339+
* size of the buffer in the vector can be 268435455 B.
340+
*/
341+
__CPROVER_assume( pVector[ i ].iov_len <= 268435455 );
342+
__CPROVER_assume( pVector[ i ].iov_len >= 0U );
343+
344+
pVector[ i ].iov_base = malloc( pVector[ i ].iov_len * sizeof( uint8_t ) );
345+
346+
__CPROVER_assume( pVector[ i ].iov_base != NULL );
347+
}
348+
349+
mqttVec->pVector = pVector;
350+
mqttVec->vectorLen = vecLen;
351+
352+
return mqttVec;
353+
}

tools/coverity/README.md

+16-11
Original file line numberDiff line numberDiff line change
@@ -25,32 +25,36 @@ To compile and run the Coverity target successfully, you must have the following
2525

2626
### To build and run coverity:
2727
Go to the root directory of the library and run the following commands in terminal:
28-
1. Update the compiler configuration in Coverity
28+
1. Create a local directory for the configuration files
2929
~~~
30-
cov-configure --force --compiler cc --comptype gcc
30+
mkdir covConfig
3131
~~~
32-
2. Create the build files using CMake in a `build` directory
32+
2. Update the compiler configuration in Coverity
33+
~~~
34+
cov-configure --config covConfig/coverity.xml --compiler cc --comptype gcc --template
35+
~~~
36+
3. Create the build files using CMake in a `build` directory
3337
~~~
3438
cmake -B build -S test
3539
~~~
36-
3. Go to the build directory and copy the coverity configuration file
40+
4. Go to the build directory and copy the coverity configuration file
3741
~~~
3842
cd build/
3943
~~~
40-
4. Build the static analysis target
44+
5. Build the static analysis target
4145
~~~
42-
cov-build --emit-complementary-info --dir cov-out make coverity_analysis
46+
cov-build --config ../covConfig/coverity.xml --emit-complementary-info --dir cov-out make coverity_analysis
4347
~~~
44-
5. Go to the Coverity output directory (`cov-out`) and begin Coverity static analysis
48+
6. Go to the Coverity output directory (`cov-out`) and begin Coverity static analysis
4549
~~~
4650
cd cov-out/
4751
cov-analyze --dir . --coding-standard-config ../../tools/coverity/misra.config --tu-pattern "file('.*/source/.*')"
4852
~~~
49-
6. Format the errors in HTML format so that it is more readable while removing the test and build directory from the report
53+
7. Format the errors in HTML format so that it is more readable while removing the test and build directory from the report
5054
~~~
5155
cov-format-errors --dir . --file "source" --exclude-files '(/build/|/test/)' --html-output html-out;
5256
~~~
53-
7. Format the errors in JSON format to perform a jq query to get a simplified list of any exceptions.
57+
8. Format the errors in JSON format to perform a jq query to get a simplified list of any exceptions.
5458
NOTE: A blank output means there are no defects that aren't being suppressed by the config or inline comments.
5559
~~~
5660
cov-format-errors --dir . --file "source" --exclude-files '(/build/|/test/)' --json-output-v2 defects.json;
@@ -61,10 +65,11 @@ Go to the root directory of the library and run the following commands in termin
6165

6266
For your convenience the commands above are below to be copy/pasted into a UNIX command friendly terminal.
6367
~~~
64-
cov-configure --force --compiler cc --comptype gcc;
68+
mkdir covConfig
69+
cov-configure --config covConfig/coverity.xml --compiler cc --comptype gcc --template
6570
cmake -B build -S test;
6671
cd build/;
67-
cov-build --emit-complementary-info --dir cov-out make coverity_analysis;
72+
cov-build --config ../covConfig/coverity.xml --emit-complementary-info --dir cov-out make coverity_analysis
6873
cd cov-out/
6974
cov-analyze --dir . --coding-standard-config ../../tools/coverity/misra.config --tu-pattern "file('.*/source/.*')";
7075
cov-format-errors --dir . --file "source" --exclude-files '(/build/|/test/)' --html-output html-out;

0 commit comments

Comments
 (0)