Elaborate a bit on static vs dynamic EC_GROUPs in documentation
Also move EC_GROUP_free and EC_GROUP_dup to the deprecated section,
because it's now usually unnecessary.
Change-Id: Ica4aa8d2b993555f977792bf284a5dbf29a3d710
Reviewed-on: https://boringssl-review.googlesource.com/c/boringssl/+/63245
Commit-Queue: David Benjamin <davidben@google.com>
Auto-Submit: David Benjamin <davidben@google.com>
Reviewed-by: Adam Langley <agl@google.com>
diff --git a/include/openssl/ec.h b/include/openssl/ec.h
index e8a2db0..085222c 100644
--- a/include/openssl/ec.h
+++ b/include/openssl/ec.h
@@ -100,6 +100,16 @@
// Elliptic curve groups.
+//
+// Elliptic curve groups are represented by |EC_GROUP| objects. Unlike OpenSSL,
+// if limited to the APIs in this section, callers may treat |EC_GROUP|s as
+// static, immutable objects which do not need to be copied or released. In
+// BoringSSL, only custom |EC_GROUP|s created by |EC_GROUP_new_curve_GFp|
+// (deprecated) are dynamic.
+//
+// Callers may cast away |const| and use |EC_GROUP_dup| and |EC_GROUP_free| with
+// static groups, for compatibility with OpenSSL or dynamic groups, but it is
+// otherwise unnecessary.
// EC_group_p224 returns an |EC_GROUP| for P-224, also known as secp224r1.
OPENSSL_EXPORT const EC_GROUP *EC_group_p224(void);
@@ -133,12 +143,6 @@
// more modern primitives.
OPENSSL_EXPORT EC_GROUP *EC_GROUP_new_by_curve_name(int nid);
-// EC_GROUP_free releases a reference to |group|.
-OPENSSL_EXPORT void EC_GROUP_free(EC_GROUP *group);
-
-// EC_GROUP_dup takes a reference to |a| and returns it.
-OPENSSL_EXPORT EC_GROUP *EC_GROUP_dup(const EC_GROUP *a);
-
// EC_GROUP_cmp returns zero if |a| and |b| are the same group and non-zero
// otherwise.
OPENSSL_EXPORT int EC_GROUP_cmp(const EC_GROUP *a, const EC_GROUP *b,
@@ -363,9 +367,27 @@
// Deprecated functions.
+// EC_GROUP_free releases a reference to |group|, if |group| was created by
+// |EC_GROUP_new_curve_GFp|. If |group| is static, it does nothing.
+//
+// This function exists for OpenSSL compatibilty, and to manage dynamic
+// |EC_GROUP|s constructed by |EC_GROUP_new_curve_GFp|. Callers that do not need
+// either may ignore this function.
+OPENSSL_EXPORT void EC_GROUP_free(EC_GROUP *group);
+
+// EC_GROUP_dup increments |group|'s reference count and returns it, if |group|
+// was created by |EC_GROUP_new_curve_GFp|. If |group| is static, it simply
+// returns |group|.
+//
+// This function exists for OpenSSL compatibilty, and to manage dynamic
+// |EC_GROUP|s constructed by |EC_GROUP_new_curve_GFp|. Callers that do not need
+// either may ignore this function.
+OPENSSL_EXPORT EC_GROUP *EC_GROUP_dup(const EC_GROUP *group);
+
// EC_GROUP_new_curve_GFp creates a new, arbitrary elliptic curve group based
// on the equation y² = x³ + a·x + b. It returns the new group or NULL on
-// error.
+// error. The lifetime of the resulting object must be managed with
+// |EC_GROUP_dup| and |EC_GROUP_free|.
//
// This new group has no generator. It is an error to use a generator-less group
// with any functions except for |EC_GROUP_free|, |EC_POINT_new|,
