Added paragraph to free objects alloced by X509V3_add1_i2d()

Fixes #18665

Reviewed-by: Hugo Landau <hlandau@openssl.org>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/18786)

diff --git a/doc/man3/X509V3_get_d2i.pod b/doc/man3/X509V3_get_d2i.pod
index 7c3b2c960432b2fc88fdb5be7eb40fb95521e795..4a2e81b0dbdff9ec966ccdc7acdc5e7fb4abc7dc 100644 (file)
--- a/doc/man3/X509V3_get_d2i.pod
+++ b/doc/man3/X509V3_get_d2i.pod
@@ -19,7 +19,7 @@ X509_REVOKED_get0_extensions - X509 extension decode and encode functions
                      int crit, unsigned long flags);
 
  void *X509V3_EXT_d2i(X509_EXTENSION *ext);
- X509_EXTENSION *X509V3_EXT_i2d(int ext_nid, int crit, void *ext);
+ X509_EXTENSION *X509V3_EXT_i2d(int ext_nid, int crit, void *ext_struc);
 
  void *X509_get_ext_d2i(const X509 *x, int nid, int *crit, int *idx);
  int X509_add1_ext_i2d(X509 *x, int nid, void *value, int crit,
@@ -41,7 +41,7 @@ X509_REVOKED_get0_extensions - X509 extension decode and encode functions
 
 X509V3_get_d2i() looks for an extension with OID I<nid> in the extensions
 I<x> and, if found, decodes it. If I<idx> is NULL then only one
-occurrence of an extension is permissible otherwise the first extension after
+occurrence of an extension is permissible, otherwise the first extension after
 index I<*idx> is returned and I<*idx> updated to the location of the extension.
 If I<crit> is not NULL then I<*crit> is set to a status value: -2 if the
 extension occurs multiple times (this is only returned if I<idx> is NULL),
@@ -57,24 +57,24 @@ X509V3_EXT_d2i() attempts to decode the ASN.1 data contained in extension
 I<ext> and returns a pointer to an extension specific structure or NULL
 if the extension could not be decoded (invalid syntax or not supported).
 
-X509V3_EXT_i2d() encodes the extension specific structure I<ext>
+X509V3_EXT_i2d() encodes the extension specific structure I<ext_struc>
 with OID I<ext_nid> and criticality I<crit>.
 
 X509_get_ext_d2i() and X509_add1_ext_i2d() operate on the extensions of
-certificate I<x>, they are otherwise identical to X509V3_get_d2i() and
-X509V3_add_i2d().
+certificate I<x>. They are otherwise identical to X509V3_get_d2i() and
+X509V3_add1_i2d().
 
 X509_CRL_get_ext_d2i() and X509_CRL_add1_ext_i2d() operate on the extensions
-of CRL I<crl>, they are otherwise identical to X509V3_get_d2i() and
-X509V3_add_i2d().
+of CRL I<crl>. They are otherwise identical to X509V3_get_d2i() and
+X509V3_add1_i2d().
 
 X509_REVOKED_get_ext_d2i() and X509_REVOKED_add1_ext_i2d() operate on the
-extensions of B<X509_REVOKED> structure I<r> (i.e for CRL entry extensions),
-they are otherwise identical to X509V3_get_d2i() and X509V3_add_i2d().
+extensions of B<X509_REVOKED> structure I<r> (i.e for CRL entry extensions).
+They are otherwise identical to X509V3_get_d2i() and X509V3_add1_i2d().
 
 X509_get0_extensions(), X509_CRL_get0_extensions() and
-X509_REVOKED_get0_extensions() return a stack of all the extensions
-of a certificate a CRL or a CRL entry respectively.
+X509_REVOKED_get0_extensions() return a STACK of all the extensions
+of a certificate, a CRL or a CRL entry respectively.
 
 =head1 NOTES
 
@@ -84,32 +84,35 @@ occurrences is an error. Therefore, the I<idx> parameter is usually NULL.
 The I<flags> parameter may be one of the following values.
 
 B<X509V3_ADD_DEFAULT> appends a new extension only if the extension does
-not already exist. An error is returned if the extension does already
-exist.
+not exist. An error is returned if the extension exists.
 
 B<X509V3_ADD_APPEND> appends a new extension, ignoring whether the extension
-already exists.
+exists.
 
-B<X509V3_ADD_REPLACE> replaces an extension if it exists otherwise appends
-a new extension.
+B<X509V3_ADD_REPLACE> replaces an existing extension. If the extension does
+not exist, appends a new extension.
 
-B<X509V3_ADD_REPLACE_EXISTING> replaces an existing extension if it exists
-otherwise returns an error.
+B<X509V3_ADD_REPLACE_EXISTING> replaces an existing extension. If the
+extension does not exist, returns an error.
 
 B<X509V3_ADD_KEEP_EXISTING> appends a new extension only if the extension does
-not already exist. An error B<is not> returned if the extension does already
-exist.
+not exist. An error is B<not> returned if the extension exists.
 
-B<X509V3_ADD_DELETE> extension I<nid> is deleted: no new extension is added.
+B<X509V3_ADD_DELETE> deletes and frees an existing extension. If the extension
+does not exist, returns an error. No new extension is added.
 
-If B<X509V3_ADD_SILENT> is ored with I<flags>: any error returned will not
-be added to the error queue.
+If B<X509V3_ADD_SILENT> is bitwise ORed with I<flags>: any error returned
+will not be added to the error queue.
 
 The function X509V3_get_d2i() and its variants
 will return NULL if the extension is not
 found, occurs multiple times or cannot be decoded. It is possible to
 determine the precise reason by checking the value of I<*crit>.
 
+The function X509V3_add1_i2d() and its variants allocate B<X509_EXTENSION>
+objects on STACK I<*x> depending on I<flags>. The B<X509_EXTENSION> objects
+must be explicitly freed using X509_EXTENSION_free().
+
 =head1 SUPPORTED EXTENSIONS
 
 The following sections contain a list of all supported extensions