internal: document the name-list truncation rule

GetNameListRaw() stops at the first empty element and drops the rest, as
OpenSSH's match_list() does. Record that at the function, along with the
two things that keep it safe for the library's own lists: the canned
defaults carry only the trailing comma AlgoListSz() strips, and a
caller's list is screened by CheckAlgoList() in the ssh.c setters.

- leave a pointer in regress.c rather than a second copy of the contract

Author: ejohnstown

src/internal.c

@@ -5840,7 +5840,15 @@ int GetStringRef(word32* strSz, const byte** str,
 
 /* Name-list to IDs. *idListSz is capacity in, count out, and bounds every
  * store. One ID per name at most, and names are capped at
- * WOLFSSH_MAX_NAMELIST_CNT, so an idList that size never trips the bound. */
+ * WOLFSSH_MAX_NAMELIST_CNT, so an idList that size never trips the bound.
+ * An empty element ends the list, silently dropping every name past it, as
+ * OpenSSH's match_list() does with a peer proposal. That is safe for the
+ * library's own lists on two counts: the canned defaults are built one
+ * "name," at a time, so they carry nothing but the trailing comma that
+ * AlgoListSz() strips, and a caller's list reaches those fields only
+ * through the ssh.c setters, which run CheckAlgoList() and reject every
+ * other empty element. A list built at runtime through neither route would
+ * lose algorithms; truncation is not an error, only a debug log. */
 static int GetNameListRaw(byte* idList, word32* idListSz,
         const byte* nameList, word32 nameListSz)
 {
@@ -5866,8 +5874,7 @@ static int GetNameListRaw(byte* idList, word32* idListSz,
      * length of the list. Find the commas, or end of list, and then decode
      * the values. A name has a non-zero length, RFC 4251 section 5, so an
      * empty element -- what a leading, doubled, or trailing comma leaves
-     * behind -- ends the list. Names past it are dropped rather than
-     * rejected, which is what OpenSSH's match_list() does with a peer list.
+     * behind -- ends the list, per the contract above.
      */
 
     for (i = 0; i <= nameListSz; i++) {

tests/regress.c

@@ -14150,10 +14150,9 @@ typedef struct {
 /* RFC 4251 section 5: a name-list holds zero or more names separated by
  * commas, and every name has a non-zero length. So an empty element -- what a
  * leading, doubled, or trailing comma leaves behind -- can't be a name, and
- * the list ends there. Names past it are dropped rather than rejected, which
- * is what OpenSSH's match_list() does with a peer proposal. A local list never
- * arrives here with an empty element: CheckAlgoList() rejects one up front,
- * except for the single trailing comma that AlgoListSz() strips. */
+ * the list ends there. Names past it are dropped rather than rejected. See
+ * GetNameListRaw() in src/internal.c for the contract and the CheckAlgoList()
+ * invariant the library's own lists rely on. */
 static const EmptyNameCase emptyNameCases[] = {
     /* Nothing before the empty element, so nothing to negotiate with. */
     { "",                            ID_UNKNOWN, "zero names" },