From a78e3240cf1019acaf4ee818396f983f38457b8f Mon Sep 17 00:00:00 2001 From: David Benjamin Date: Fri, 15 Oct 2021 12:06:32 -0400 Subject: [PATCH] Document ASN1_NULL. This starts expanding out the DECLARE_* macros in asn1.h. It also documents some ways in which ASN1_NULL is odd. Bug: 426 Change-Id: Ie166861d91ce78901c76b85de79dcc683e480275 Reviewed-on: https://boringssl-review.googlesource.com/c/boringssl/+/49909 Reviewed-by: Adam Langley --- include/openssl/asn1.h | 31 ++++++++++++++++++++++++++++++- 1 file changed, 30 insertions(+), 1 deletion(-) diff --git a/include/openssl/asn1.h b/include/openssl/asn1.h index 7de2331c6..29d4de72f 100644 --- a/include/openssl/asn1.h +++ b/include/openssl/asn1.h @@ -830,6 +830,36 @@ OPENSSL_EXPORT int ASN1_TIME_set_string(ASN1_TIME *s, const char *str); // TODO(davidben): Expand and document function prototypes generated in macros. +// NULL values. +// +// This library represents the ASN.1 NULL value by a non-NULL pointer to the +// opaque type |ASN1_NULL|. An omitted OPTIONAL ASN.1 NULL value is a NULL +// pointer. Unlike other pointer types, it is not necessary to free |ASN1_NULL| +// pointers, but it is safe to do so. + +// ASN1_NULL_new returns an opaque, non-NULL pointer. It is safe to call +// |ASN1_NULL_free| on the result, but not necessary. +OPENSSL_EXPORT ASN1_NULL *ASN1_NULL_new(void); + +// ASN1_NULL_free does nothing. +OPENSSL_EXPORT void ASN1_NULL_free(ASN1_NULL *null); + +// d2i_ASN1_NULL parses a DER-encoded ASN.1 NULL value from up to |len| bytes +// at |*inp|, as described in |d2i_SAMPLE|. +// +// TODO(https://crbug.com/boringssl/354): This function currently also accepts +// BER, but this will be removed in the future. +OPENSSL_EXPORT ASN1_NULL *d2i_ASN1_NULL(ASN1_NULL **out, const uint8_t **inp, + long len); + +// i2d_ASN1_NULL marshals |in| as a DER-encoded ASN.1 NULL value, as described +// in |i2d_SAMPLE|. +OPENSSL_EXPORT int i2d_ASN1_NULL(const ASN1_NULL *in, uint8_t **outp); + +// ASN1_NULL is an |ASN1_ITEM| with ASN.1 type NULL and C type |ASN1_NULL*|. +DECLARE_ASN1_ITEM(ASN1_NULL) + + // Arbitrary elements. // An asn1_type_st (aka |ASN1_TYPE|) represents an arbitrary ASN.1 element, @@ -1227,7 +1257,6 @@ OPENSSL_EXPORT int ASN1_OCTET_STRING_set(ASN1_OCTET_STRING *str, DECLARE_ASN1_FUNCTIONS_const(ASN1_VISIBLESTRING) DECLARE_ASN1_FUNCTIONS_const(ASN1_UNIVERSALSTRING) DECLARE_ASN1_FUNCTIONS_const(ASN1_UTF8STRING) -DECLARE_ASN1_FUNCTIONS_const(ASN1_NULL) DECLARE_ASN1_FUNCTIONS_const(ASN1_BMPSTRING) DECLARE_ASN1_FUNCTIONS_name(ASN1_STRING, ASN1_PRINTABLE)