Add a warning about OBJ_create and global state

This function is probably not what you want. I think the
X509V3_EXT_METHOD and ASN1_STRING_TABLE_add stuff are the only cases
where you actually need an OID. Those, themselves, have problems with
conflicting registrations and aren't really necessary.

ASN1_STRING_TABLE_add has a similar warning on it. X509V3_EXT_METHOD is
not yet documented, but should get a similar warning when we document
it.

Change-Id: I173918a3f7db25059ed078b2f67b23acfb43033d
Reviewed-on: https://boringssl-review.googlesource.com/c/boringssl/+/58365
Auto-Submit: David Benjamin <davidben@google.com>
Reviewed-by: Adam Langley <agl@google.com>
Commit-Queue: Adam Langley <agl@google.com>

include/openssl/obj.h

@@ -183,8 +183,15 @@ OPENSSL_EXPORT int OBJ_obj2txt(char *out, int out_len, const ASN1_OBJECT *obj,
 
 // Adding objects at runtime.
 
-// OBJ_create adds a known object and returns the nid of the new object, or
+// OBJ_create adds a known object and returns the NID of the new object, or
 // NID_undef on error.
+//
+// WARNING: This function modifies global state. The table cannot contain
+// duplicate OIDs, short names, or long names. If two callers in the same
+// address space add conflicting values, only one registration will take effect.
+// Avoid this function if possible. Instead, callers can process OIDs unknown to
+// BoringSSL by acting on the byte representation directly. See |OBJ_get0_data|
+// and |OBJ_length|.
 OPENSSL_EXPORT int OBJ_create(const char *oid, const char *short_name,
                               const char *long_name);