Document that null STACK_OF(T) can be used with several functions

Lots of code relies on this, so we ought to document it. A null
STACK_OF(T) is treated as an immutable empty list.

AWS-LC:
- sk_TEST_INT_find takes 2 arguments only due to
  9860446
- Based on changes to stack.h L-513-515 in the same commit, in compatibility
  with OpenSSL, -1 is returned in the last check in NullIsEmpty test.

Change-Id: I10d0ba8f7b33c7f3febaf92c2cd3da25a0eb0f80
Reviewed-on: https://boringssl-review.googlesource.com/c/boringssl/+/67407
Reviewed-by: Theo Buehler <[email protected]>
Auto-Submit: David Benjamin <[email protected]>
Commit-Queue: Bob Beck <[email protected]>
Reviewed-by: Bob Beck <[email protected]>
(cherry picked from commit 821fe3380cce646fa3557b882d91fba318981b9b)

crypto/stack/stack_test.cc

@@ -508,3 +508,17 @@ TEST(StackTest, IsSorted) {
   sk_TEST_INT_set_cmp_func(sk.get(), nullptr);
   EXPECT_FALSE(sk_TEST_INT_is_sorted(sk.get()));
 }
+
+TEST(StackTest, NullIsEmpty) {
+  EXPECT_EQ(0u, sk_TEST_INT_num(nullptr));
+
+  EXPECT_EQ(nullptr, sk_TEST_INT_value(nullptr, 0));
+  EXPECT_EQ(nullptr, sk_TEST_INT_value(nullptr, 1));
+
+  bssl::UniquePtr<TEST_INT> value = TEST_INT_new(6);
+  ASSERT_TRUE(value);
+  // The return value of -1 is compatible with OpenSSL
+  // BoringSSL's function takes 3 arguments in this case
+  // and returns False.
+  EXPECT_EQ(-1, sk_TEST_INT_find(nullptr, value.get()));
+}

include/openssl/stack.h

@@ -143,15 +143,17 @@ STACK_OF(SAMPLE) *sk_SAMPLE_new(sk_SAMPLE_cmp_func comp);
 STACK_OF(SAMPLE) *sk_SAMPLE_new_null(void);
 
 // sk_SAMPLE_num returns the number of elements in |sk|. It is safe to cast this
-// value to |int|. |sk| is guaranteed to have at most |INT_MAX| elements.
+// value to |int|. |sk| is guaranteed to have at most |INT_MAX| elements. If
+// |sk| is NULL, it is treated as the empty list and this function returns zero.
 size_t sk_SAMPLE_num(const STACK_OF(SAMPLE) *sk);
 
 // sk_SAMPLE_zero resets |sk| to the empty state but does nothing to free the
 // individual elements themselves.
 void sk_SAMPLE_zero(STACK_OF(SAMPLE) *sk);
 
 // sk_SAMPLE_value returns the |i|th pointer in |sk|, or NULL if |i| is out of
-// range.
+// range. If |sk| is NULL, it is treated as an empty list and the function
+// returns NULL.
 SAMPLE *sk_SAMPLE_value(const STACK_OF(SAMPLE) *sk, size_t i);
 
 // sk_SAMPLE_set sets the |i|th pointer in |sk| to |p| and returns |p|. If |i|
@@ -199,6 +201,8 @@ void sk_SAMPLE_delete_if(STACK_OF(SAMPLE) *sk, sk_SAMPLE_delete_if_func func,
 // If the stack is sorted (see |sk_SAMPLE_sort|), this function uses a binary
 // search. Otherwise it performs a linear search. If it finds a matching
 // element, it returns the index of that element. Otherwise, it returns -1.
+// If |sk| is NULL, it is treated as the empty list and the function returns
+// zero.
 //
 // Note this differs from OpenSSL in that OpenSSL's version will implicitly
 // sort |sk| if it has a comparison function defined.