Document a few more x509.h functions.
I stopped short of documenting the add1_attr_by functions because the
type parameter is a bit of a mess. It appears to be several enums put
together. To that end, I've updated the documentation on
V_ASN1_MAX_UNIVERSAL to note that we also need to avoid MBSTRING_FLAG.
As a preview of what I'm putting off to later, see
X509_ATTRIBUTE_set1_data for how the type parameter is used. set1_data
is extra fun because PKCS#10 attributes are set-valued. Plus there's
upstream's e20b57270dece66ce2c68aeb5d14dd6d9f3c5d68, which we should
import first.
Change-Id: I3453a0b224e42c6e22828c7d332ee133e09e6173
Reviewed-on: https://boringssl-review.googlesource.com/c/boringssl/+/46945
Reviewed-by: Adam Langley <agl@google.com>
diff --git a/crypto/x509/x509_req.c b/crypto/x509/x509_req.c
index 719257e..22279d3 100644
--- a/crypto/x509/x509_req.c
+++ b/crypto/x509/x509_req.c
@@ -253,7 +253,7 @@
return X509at_get_attr_by_NID(req->req_info->attributes, nid, lastpos);
}
-int X509_REQ_get_attr_by_OBJ(const X509_REQ *req, ASN1_OBJECT *obj,
+int X509_REQ_get_attr_by_OBJ(const X509_REQ *req, const ASN1_OBJECT *obj,
int lastpos)
{
return X509at_get_attr_by_OBJ(req->req_info->attributes, obj, lastpos);
diff --git a/include/openssl/asn1.h b/include/openssl/asn1.h
index b32c0ca..5e9aa3f 100644
--- a/include/openssl/asn1.h
+++ b/include/openssl/asn1.h
@@ -103,7 +103,7 @@
#define V_ASN1_PRIMITIVE_TAG 0x1f
// V_ASN1_MAX_UNIVERSAL is the highest supported universal tag number. It is
-// necessary to avoid ambiguity with |V_ASN1_NEG|.
+// necessary to avoid ambiguity with |V_ASN1_NEG| and |MBSTRING_FLAG|.
//
// TODO(davidben): Make this private.
#define V_ASN1_MAX_UNIVERSAL 0xff
diff --git a/include/openssl/x509.h b/include/openssl/x509.h
index 4916959..b6dcc7f 100644
--- a/include/openssl/x509.h
+++ b/include/openssl/x509.h
@@ -1258,14 +1258,42 @@
OPENSSL_EXPORT int X509_REQ_add_extensions(
X509_REQ *req, const STACK_OF(X509_EXTENSION) *exts);
+// X509_REQ_get_attr_count returns the number of attributes in |req|.
OPENSSL_EXPORT int X509_REQ_get_attr_count(const X509_REQ *req);
+
+// X509_REQ_get_attr_by_NID returns the index of the attribute in |req| of type
+// |nid|, or a negative number if not found. If found, callers can use
+// |X509_REQ_get_attr| to look up the attribute by index.
+//
+// If |lastpos| is non-negative, it begins searching at |lastpos| + 1. Callers
+// can thus loop over all matching attributes by first passing -1 and then
+// passing the previously-returned value until no match is returned.
OPENSSL_EXPORT int X509_REQ_get_attr_by_NID(const X509_REQ *req, int nid,
int lastpos);
+
+// X509_REQ_get_attr_by_OBJ behaves like |X509_REQ_get_attr_by_NID| but looks
+// for attributes of type |obj|.
OPENSSL_EXPORT int X509_REQ_get_attr_by_OBJ(const X509_REQ *req,
- ASN1_OBJECT *obj, int lastpos);
+ const ASN1_OBJECT *obj,
+ int lastpos);
+
+// X509_REQ_get_attr returns the attribute at index |loc| in |req|, or NULL if
+// out of bounds.
OPENSSL_EXPORT X509_ATTRIBUTE *X509_REQ_get_attr(const X509_REQ *req, int loc);
+
+// X509_REQ_delete_attr removes the attribute at index |loc| in |req|. It
+// returns the removed attribute to the caller, or NULL if |loc| was out of
+// bounds. If non-NULL, the caller must release the result with
+// |X509_ATTRIBUTE_free| when done. It is also safe, but not necessary, to call
+// |X509_ATTRIBUTE_free| if the result is NULL.
OPENSSL_EXPORT X509_ATTRIBUTE *X509_REQ_delete_attr(X509_REQ *req, int loc);
+
+// X509_REQ_add1_attr appends a copy of |attr| to |req|'s list of attributes. It
+// returns one on success and zero on error.
+//
+// TODO(https://crbug.com/boringssl/407): |attr| should be const.
OPENSSL_EXPORT int X509_REQ_add1_attr(X509_REQ *req, X509_ATTRIBUTE *attr);
+
OPENSSL_EXPORT int X509_REQ_add1_attr_by_OBJ(X509_REQ *req,
const ASN1_OBJECT *obj, int type,
const unsigned char *bytes,
