Skip to content

Add router advertisement checks for RFC4861 section 6.1.2 conformance - #1369

Merged
kstribrnAmzn merged 6 commits into
FreeRTOS:mainfrom
kstribrnAmzn:raChecks
Oct 7, 2026
Merged

kstribrnAmzn merged 6 commits into
FreeRTOS:mainfrom
kstribrnAmzn:raChecks

Conversation

@kstribrnAmzn

Copy link
Copy Markdown
Member

Description

Adds router advertisement packet validations conforming with RFC4861 section 6.1.2. These new validations restrict where a router advertisement can come from.

We thank Causal Security (https://causalsecurity.com) for their help identifying this issue.
A big thank you to @htibosch for collaborating on this.

Test Steps

Adds extensive unit testing

Checklist:

  • I have tested my changes. No regression in existing tests.
  • I have modified and/or added unit-tests to cover the code changes in this Pull Request.

Related Issue

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

@kstribrnAmzn
kstribrnAmzn marked this pull request as ready for review September 29, 2026 20:11
Comment thread source/FreeRTOS_RA.c Resolved
Comment thread source/FreeRTOS_RA.c Resolved
Comment thread source/FreeRTOS_ND.c Resolved
Comment thread source/FreeRTOS_IPv6_Sockets.c Resolved
Comment thread source/include/FreeRTOS_IPv6_Private.h Resolved
Comment thread source/FreeRTOS_RA.c Resolved
aadityasg
aadityasg previously approved these changes Oct 1, 2026
/* Any address type other than link-local must be rejected. Expect the exact
* argument, so that classifying the destination address instead of the source
* address would fail this test. */
xIPv6_GetIPType_ExpectAndReturn( &( xICMPPacket.xIPHeader.xSourceAddress ), eIPv6_Global );

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The exact-argument expectation doesn't do what the comment above says. This repo's CMock config doesn't override :when_ptr, so it uses the default :compare_data, which compares the 16 pointed-to bytes rather than the pointer itself. prvBuildAcceptableRA() zeroes the whole frame, so xSourceAddress and xDestinationAddress are both 16 zero bytes. A mutant that classifies the destination address still passes.

The same applies to the ExpectAndReturn( &( ...xSourceAddress ), ... ) calls at L1239 and L1269.

Suggestion: in the fixture, give the source and destination different non-zero addresses (e.g. source fe80::1, destination ff02::1).

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This has been updated. The source and destination addressees will have differnt byte values now. See ceac135#diff-85a0b07a524bd6adb60b7d87ee2bc950b6176eb5ac747a1f4b394784625b89e7R548-R554

* observable difference between accepting and discarding the message. The discard
* tests deliberately register no FreeRTOS_FirstEndPoint() expectation, so if the
* check under test were removed, CMock would fail the test on the unexpected call.
* See test_vReceiveRA_vRAProcess() for the accepting counterpart of this fixture.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

test_vReceiveRA_vRAProcess() builds its own copy of the packet and never calls prvBuildAcceptableRA(). That means no test checks that the fixture itself is accepted. If the fixture changes later (for example ucLength = 4 becomes 1, which makes the prefix option too short), all six discard tests would stop testing anything and still pass.

Could test_vReceiveRA_vRAProcess() build its packet with prvBuildAcceptableRA() and keep its existing asserts?

Minor: the paragraph above is also slightly off about what catches a removed check. For the hop-limit, code and payload-length tests, the test fails on the unexpected xIPv6_GetIPType() call. Only SourceNotLinkLocal gets as far as FreeRTOS_FirstEndPoint().

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is now building with prvBuildAcceptableRA(), see this.


xICMPPacket.xIPHeader.ucHopLimit = raDEFAULT_HOP_LIMIT;

prvSetIPv6PayloadLength( pxNetworkBuffer );

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This test can't detect removal of the buffer-size guard in vReceiveRA() (FreeRTOS_RA.c:438). xDataLength is 69, so prvSetIPv6PayloadLength() writes 15, and the new uxPayloadLength < 16 check at L443 rejects the packet anyway. Both branches only print, so the outcome is the same either way.

To make the size guard the only thing that can reject it, set usPayloadLength large (e.g. FreeRTOS_htons( 0xFFFF )) while keeping the short xDataLength.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This has been fixed.


xIPv6_GetIPType_ExpectAnyArgsAndReturn( eIPv6_LinkLocal );

prvSetIPv6PayloadLength( pxNetworkBuffer );

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is the only test that reaches the "Not enough bytes" branch (FreeRTOS_RA.c:321-326). At that point no prefix has been parsed, so pxPrefixOption is NULL whether or not xMalformed is set. Deleting the new xMalformed = pdTRUE; at FreeRTOS_RA.c:325 leaves the whole suite green.

test_vReceiveRA_PrefixFollowedByZeroLengthOption already covers the zero-length half of "one bad option discards the whole RA". Could we add the same test for the overrun half: a valid prefix option followed by { type 5, length 2 } with only 8 bytes left, expecting no FreeRTOS_FirstEndPoint() call?

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The test_vReceiveRA_PrefixFollowedByOverrunOption test should cover what you were asking for.

Comment thread source/FreeRTOS_RA.c Outdated
uxLast = uxPayloadLength - uxICMPSize;
}

if( uxLast > uxReceived )

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No test covers this branch. Every test either sets usPayloadLength from xDataLength or sets it smaller, so uxLast > uxReceived is never true.

It also can't be reached in production. A packet whose payload length is longer than the frame is dropped before vReceiveRA() in both configurations: prvChecksumIPv6Checks() returns ipINVALID_LENGTH when ipconfigDRIVER_INCLUDED_RX_IP_CHECKSUM == 0, and xCheckIPv6SizeFields() fails at location 4 when it is 1.

Since it's a backstop, I'd reject rather than clamp. Add else if( uxPayloadLength > ( pxNetworkBuffer->xDataLength - ( ipSIZE_OF_ETH_HEADER + ipSIZE_OF_IPv6_HEADER ) ) ) to the validation chain in vReceiveRA(), then this block can become a configASSERT or be removed. As written, an inconsistent RA would be trimmed and then accepted if it ever got here. Either way, one test that drives this path would be good.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This branch has been removed.

Comment thread History.txt
Documentation and download available at https://www.FreeRTOS.org/

Changes to be included in the upcoming release:
+ Add Router Advertisement validations for RFC 4861 section 6.1.2

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This entry lists three checks, but the PR also makes these changes that users will notice:

  • the 16-octet minimum ICMP length, derived from the IP length
  • options are now bounded by the IPv6 payload length instead of the Ethernet frame length
  • a malformed option (zero length, or running past the end) now discards the whole RA, including a prefix option that parsed before it. Before, that prefix was still applied, so a sender relying on the old behaviour would see SLAAC stop working. That includes RAs with 2 to 7 trailing bytes after the last option.

Could these be added?

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've compressed the RFC 4861 checks down to a single point. I don't want to list every single thing added and bloat the history file.

I did keep the service->code rename separate since it's breaking for consumers.


/* The IP length accounts for the RA header only: the prefix option built above
* sits in the padding and is therefore not part of the ICMP message. */
xICMPPacket.xIPHeader.usPayloadLength = FreeRTOS_htons( sizeof( ICMPRouterAdvertisement_IPv6_t ) );

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This test sets usPayloadLength to exactly 16, so vReceiveRA_ReadReply() takes the false branch of uxPayloadLength > uxICMPSize at FreeRTOS_RA.c:292 and uxLast stays 0. This test never reaches L294. All the other tests derive the payload length from xDataLength, so uxPayloadLength - 16 == uxReceived for them.

As a result, these mutants of FreeRTOS_RA.c:294 all pass the full RA suite:

  • uxLast = uxReceived; (bounding by the frame again, i.e. the pre-PR behaviour)
  • uxLast = uxPayloadLength;
  • uxLast = uxPayloadLength - 8U;

Could we add a case where 16 < payload length < bytes received, with a malformed option in the trailing bytes, and assert the RA is still accepted? For example:

prvBuildAcceptableRA( &xNetworkBuffer, &xFrame.xPacket, &xInterface );
xNetworkBuffer.xDataLength = sizeof( xFrame );   /* RA + PIO + 8 trailing bytes */
xFrame.xPacket.xIPHeader.usPayloadLength =
    FreeRTOS_htons( sizeof( ICMPRouterAdvertisement_IPv6_t ) + sizeof( ICMPPrefixOption_IPv6_t ) );
xFrame.ucTrailing[ 0 ] = ndICMP_MTU_OPTION;
xFrame.ucTrailing[ 1 ] = 0U;                     /* would make the RA malformed if parsed */
xIPv6_GetIPType_ExpectAnyArgsAndReturn( eIPv6_LinkLocal );
FreeRTOS_FirstEndPoint_ExpectAnyArgsAndReturn( NULL );   /* accepted */
vReceiveRA( &xNetworkBuffer );

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is fixed in commit ceac135.

Comment thread source/include/FreeRTOS_IP_Private.h Resolved
Comment thread source/FreeRTOS_RA.c
}
}

while( ( uxIndex + 1U ) < uxLast )

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If exactly one byte trails the last option (uxLast - uxIndex == 1), the loop exits with xMalformed still pdFALSE and the prefix is accepted. With 2-7 trailing bytes the overrun check rejects the RA instead. Options are multiples of 8 octets, so could we add this after the loop?

if( ( xMalformed == pdFALSE ) && ( uxIndex != uxLast ) )
{
    xMalformed = pdTRUE;
}

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, I agree that every byte should be accounted for.

Comment thread source/FreeRTOS_RA.c Outdated
}
else if( pxICMPPacket->xIPHeader.ucHopLimit != raDEFAULT_HOP_LIMIT )
{
FreeRTOS_debug_printf( ( "vReceiveRA: Error: ucHopLimit equals %u\n", pxICMPPacket->xIPHeader.ucHopLimit ) );

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The new rejections (L445/451/455/462) log only via FreeRTOS_debug_printf, which is off by default. On a network whose router doesn't conform, SLAAC therefore falls back silently to ipv6_defaults after ipconfigRA_SEARCH_COUNT x ipconfigRA_SEARCH_TIME_OUT_MSEC (about 30 s), and all that's printed is "RA: Giving up waiting for a Router.". L440 in the same chain, and the new L301/316/324, use FreeRTOS_printf. Could the drops use one macro, plus an iptrace hook so operators can see why?

Nit: maybe cast ( unsigned ) on ucHopLimit here and on ucCode

Comment thread source/FreeRTOS_RA.c Outdated
{
/* usPayloadLength claims more data than was actually received. Never
* read beyond the buffer. */
FreeRTOS_printf( ( "RA: Payload length ( %u ) exceeds the buffer ( %u )\n",

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: the label says "Payload length … exceeds the buffer", but the values printed are uxLast and uxReceived, which are option-region lengths. Could we either relabel it or print uxPayloadLength and xDataLength?

/* The payload length is read from the packet by the caller, so it is entirely
* attacker controlled. Leave it unconstrained to prove that the option parsing
* stays inside the buffer for every possible value. */
pxReturn = __CPROVER_file_local_FreeRTOS_RA_c_vReceiveRA_ReadReply( pxNetworkBuffer, nondet_sizet() );

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The nondet payload length helps, but xDataLength is still fixed at uxNeededSize + 8 (L56) with --unwind 3. So uxLast <= 8, and a Prefix Information option (32 bytes) can never be parsed. That leaves the non-NULL return, the "valid prefix then malformed -> NULL" path and multi-option walks unexplored. Could we make uxDataLen nondet (e.g. <= 40), allocate exactly that size, use --unwind 7, and assert that a non-NULL return ends inside both xDataLength and the payload? With that assert, CBMC would also catch the L294 mutants.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The CBMC proof has been updated

aadityasg
aadityasg previously approved these changes Oct 1, 2026
Adds router advertisement packet validations conforming with RFC4861 section
6.1.2. These new validations restrict where a router advertisement can come from.

We thank Causal Security (https://causalsecurity.com) for their help identifying this issue.
A big thank you to @htibosch for collaborating on this.
FreeRTOS_RA.c: vReceiveRA passed a const IPv6_Address_t * to a %pip specifier, which GCC -Werror=format= rejects because %p requires void *. Pass the address byte array cast to void * (matching FreeRTOS_ND.c) so the ENABLE_ALL build check compiles.

FreeRTOS_Routing.h: apply the uncrustify 0.69.0 formatting the CI formatting job requires for the extern C closing brace.
* Remove uneeded macros, comment changes.
* Extend "Code" keyword usage to IPv4.
* Further deepen the RFC 4861 6.1.2 checks to verify overall lengths.
* Moves `xIPv6_GetIPType` into the chain of RA checks
* Enhance unit tests
@kstribrnAmzn
kstribrnAmzn force-pushed the raChecks branch 2 times, most recently from 778582c to 87ecdbd Compare October 1, 2026 23:02
@paabbs paabbs mentioned this pull request Oct 2, 2026
2 tasks done

@htibosch htibosch left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you @aadityasg @kstribrnAmzn @paabbs for all the good work.
I forgot to say about the end point field pcName[]. I used it in my testing framework, especially when I want to see the routing working with 2 interfaces (STM32 ETH and ESP32 WiFi).
I'm still in doubt whether to call it :

char pcName[ ipconfigENDPOINT_NAME_LENGTH ];

or

const char *pcName;

With the latter, you must guarantee that the space will not be overwritten.

#define FOnUdpSent FOnUDPSent_t
#define FOnTcpSent FOnTCPSent_t
#define ucTypeOfService ucCode
#endif /* ipconfigENABLE_BACKWARD_COMPATIBILITY */

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

#define ucTypeOfService ucCode

I very much agree, put it in the ipconfigENABLE_BACKWARD_COMPATIBILITY section.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Glad you agree with it :)

Comment thread source/FreeRTOS_RA.c
{
FreeRTOS_printf( ( "vReceiveRA: Error: ucHopLimit equals %u\n", ( unsigned ) pxICMPPacket->xIPHeader.ucHopLimit ) );
iptraceRA_DISCARDED( "hop limit is not 255" );
}

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What do you think, shall we remove the FreeRTOS_printf's now that iptraceRA_DISCARDED() is called?
These are important messages while testing IPv6. Without them, you must start a debugging session and follow the path. That is a lot of work.
I vote to keep them.

Comment thread source/FreeRTOS_RA.c
}
}

while( ( uxIndex + 1U ) < uxLast )

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, I agree that every byte should be accounted for.

Comment thread source/FreeRTOS_RA.c

return pxPrefixOption;
}
/*-----------------------------------------------------------*/

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The following proposed change is low priority:

-    case ndICMP_SOURCE_LINK_LAYER_ADDRESS: /* 1 */
-        FreeRTOS_printf( ( "RA: Source = %02x-%02x-%02x-%02x-%02x-%02x\n",
-                           pucBytes[ uxIndex + 2U ],
-                           pucBytes[ uxIndex + 3U ],
-                           pucBytes[ uxIndex + 4U ],
-                           pucBytes[ uxIndex + 5U ],
-                           pucBytes[ uxIndex + 6U ],
-                           pucBytes[ uxIndex + 7U ] ) );
-        break;
+   case ndICMP_SOURCE_LINK_LAYER_ADDRESS: /* 1 */
+       /* Standard check: SLLAO should be 8 bytes (Len=1) */
+      {
+          char pcBuffer[ 18 ];
+          FreeRTOS_EUI48_ntop( &( pucBytes[ uxIndex + 2U ] ), pcBuffer, 'A', '-' );
+          FreeRTOS_printf( ( "RA: Source = %s\n", pcBuffer ) );
+      }
+      break;

The length of pcBuffer, 18, could also become a macro, like 40 bytes for an IPv6 address.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's take this on in a later change given I didn't modify this in this PR. I'd like to keep this as small as possible.

@kstribrnAmzn
kstribrnAmzn merged commit 201d3b6 into FreeRTOS:main Oct 7, 2026
10 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants