Skip to content

Commit ec57e90

Browse files
davidbennebeid
davidben
authored and
nebeid
committed
Document GENERAL_NAME-related APIs
Update-Note: In the process, unexport the ASN1_ITEMs, and the d2i/i2d functions for OTHERNAME and EDIPARTYNAME. These do not appear to be used and removing them will cut down on the amount of compatibility glue needed when we rewrite the parsers with a safer calling convention. Bug: 426 Change-Id: Ifc45867c0a0c832e5ef72deaec5a2c88b8d8ac6a Reviewed-on: https://boringssl-review.googlesource.com/c/boringssl/+/64628 Reviewed-by: Bob Beck <[email protected]> Commit-Queue: David Benjamin <[email protected]> (cherry picked from commit e89d99af0e4d7fb1df4d961d7aafdfed30d08d41)
1 parent 41039db commit ec57e90

File tree

5 files changed

+199
-80
lines changed

5 files changed

+199
-80
lines changed

‎crypto/ocsp/ocsp_asn.c

+1
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@
1111
// https://tools.ietf.org/html/rfc6960#section-4.2.1
1212

1313
#include "internal.h"
14+
#include "../x509/internal.h"
1415

1516
ASN1_SEQUENCE(OCSP_SIGNATURE) = {
1617
ASN1_SIMPLE(OCSP_SIGNATURE, signatureAlgorithm, X509_ALGOR),

‎crypto/x509/internal.h

+8
Original file line numberDiff line numberDiff line change
@@ -246,6 +246,14 @@ struct X509_crl_st {
246246
unsigned char crl_hash[SHA256_DIGEST_LENGTH];
247247
} /* X509_CRL */;
248248

249+
// GENERAL_NAME is an |ASN1_ITEM| whose ASN.1 type is GeneralName and C type is
250+
// |GENERAL_NAME*|.
251+
DECLARE_ASN1_ITEM(GENERAL_NAME)
252+
253+
// GENERAL_NAMES is an |ASN1_ITEM| whose ASN.1 type is SEQUENCE OF GeneralName
254+
// and C type is |GENERAL_NAMES*|, aka |STACK_OF(GENERAL_NAME)*|.
255+
DECLARE_ASN1_ITEM(GENERAL_NAMES)
256+
249257
struct X509_VERIFY_PARAM_st {
250258
int64_t check_time; // POSIX time to use
251259
unsigned long flags; // Various verify flags

‎crypto/x509/v3_akeya.c

+2
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,8 @@
6161
#include <openssl/conf.h>
6262
#include <openssl/x509.h>
6363

64+
#include "internal.h"
65+
6466

6567
ASN1_SEQUENCE(AUTHORITY_KEYID) = {
6668
ASN1_IMP_OPT(AUTHORITY_KEYID, keyid, ASN1_OCTET_STRING, 0),

‎crypto/x509/v3_genn.c

+11-11
Original file line numberDiff line numberDiff line change
@@ -70,15 +70,15 @@ ASN1_SEQUENCE(OTHERNAME) = {
7070
ASN1_EXP(OTHERNAME, value, ASN1_ANY, 0),
7171
} ASN1_SEQUENCE_END(OTHERNAME)
7272

73-
IMPLEMENT_ASN1_FUNCTIONS_const(OTHERNAME)
73+
IMPLEMENT_ASN1_ALLOC_FUNCTIONS(OTHERNAME)
7474

7575
ASN1_SEQUENCE(EDIPARTYNAME) = {
7676
// DirectoryString is a CHOICE type, so use explicit tagging.
7777
ASN1_EXP_OPT(EDIPARTYNAME, nameAssigner, DIRECTORYSTRING, 0),
7878
ASN1_EXP(EDIPARTYNAME, partyName, DIRECTORYSTRING, 1),
7979
} ASN1_SEQUENCE_END(EDIPARTYNAME)
8080

81-
IMPLEMENT_ASN1_FUNCTIONS_const(EDIPARTYNAME)
81+
IMPLEMENT_ASN1_ALLOC_FUNCTIONS(EDIPARTYNAME)
8282

8383
ASN1_CHOICE(GENERAL_NAME) = {
8484
ASN1_IMP(GENERAL_NAME, d.otherName, OTHERNAME, GEN_OTHERNAME),
@@ -208,9 +208,9 @@ void GENERAL_NAME_set0_value(GENERAL_NAME *a, int type, void *value) {
208208
a->type = type;
209209
}
210210

211-
void *GENERAL_NAME_get0_value(const GENERAL_NAME *a, int *ptype) {
212-
if (ptype) {
213-
*ptype = a->type;
211+
void *GENERAL_NAME_get0_value(const GENERAL_NAME *a, int *out_type) {
212+
if (out_type) {
213+
*out_type = a->type;
214214
}
215215
switch (a->type) {
216216
case GEN_X400:
@@ -255,16 +255,16 @@ int GENERAL_NAME_set0_othername(GENERAL_NAME *gen, ASN1_OBJECT *oid,
255255
return 1;
256256
}
257257

258-
int GENERAL_NAME_get0_otherName(const GENERAL_NAME *gen, ASN1_OBJECT **poid,
259-
ASN1_TYPE **pvalue) {
258+
int GENERAL_NAME_get0_otherName(const GENERAL_NAME *gen, ASN1_OBJECT **out_oid,
259+
ASN1_TYPE **out_value) {
260260
if (gen->type != GEN_OTHERNAME) {
261261
return 0;
262262
}
263-
if (poid) {
264-
*poid = gen->d.otherName->type_id;
263+
if (out_oid != NULL) {
264+
*out_oid = gen->d.otherName->type_id;
265265
}
266-
if (pvalue) {
267-
*pvalue = gen->d.otherName->value;
266+
if (out_value != NULL) {
267+
*out_value = gen->d.otherName->value;
268268
}
269269
return 1;
270270
}

‎include/openssl/x509.h

+177-69
Original file line numberDiff line numberDiff line change
@@ -1381,8 +1381,7 @@ DEFINE_STACK_OF(X509_NAME)
13811381
// type is |X509_NAME*|.
13821382
DECLARE_ASN1_ITEM(X509_NAME)
13831383

1384-
// X509_NAME_new returns a new, empty |X509_NAME_new|, or NULL on
1385-
// error.
1384+
// X509_NAME_new returns a new, empty |X509_NAME|, or NULL on error.
13861385
OPENSSL_EXPORT X509_NAME *X509_NAME_new(void);
13871386

13881387
// X509_NAME_free releases memory associated with |name|.
@@ -1517,8 +1516,7 @@ OPENSSL_EXPORT int X509_NAME_add_entry_by_txt(X509_NAME *name,
15171516
// (RFC 5280) and C type is |X509_NAME_ENTRY*|.
15181517
DECLARE_ASN1_ITEM(X509_NAME_ENTRY)
15191518

1520-
// X509_NAME_ENTRY_new returns a new, empty |X509_NAME_ENTRY_new|, or NULL on
1521-
// error.
1519+
// X509_NAME_ENTRY_new returns a new, empty |X509_NAME_ENTRY|, or NULL on error.
15221520
OPENSSL_EXPORT X509_NAME_ENTRY *X509_NAME_ENTRY_new(void);
15231521

15241522
// X509_NAME_ENTRY_free releases memory associated with |entry|.
@@ -1841,6 +1839,181 @@ OPENSSL_EXPORT STACK_OF(X509_EXTENSION) *X509v3_add_ext(
18411839
STACK_OF(X509_EXTENSION) **x, const X509_EXTENSION *ex, int loc);
18421840

18431841

1842+
// General names.
1843+
//
1844+
// A |GENERAL_NAME| represents an X.509 GeneralName structure, defined in RFC
1845+
// 5280, Section 4.2.1.6. General names are distinct from names (|X509_NAME|). A
1846+
// general name is a CHOICE type which may contain one of several name types,
1847+
// most commonly a DNS name or an IP address. General names most commonly appear
1848+
// in the subject alternative name (SAN) extension, though they are also used in
1849+
// other extensions.
1850+
//
1851+
// Many extensions contain a SEQUENCE OF GeneralName, or GeneralNames, so
1852+
// |STACK_OF(GENERAL_NAME)| is defined and aliased to |GENERAL_NAMES|.
1853+
1854+
typedef struct otherName_st {
1855+
ASN1_OBJECT *type_id;
1856+
ASN1_TYPE *value;
1857+
} OTHERNAME;
1858+
1859+
typedef struct EDIPartyName_st {
1860+
ASN1_STRING *nameAssigner;
1861+
ASN1_STRING *partyName;
1862+
} EDIPARTYNAME;
1863+
1864+
// GEN_* are constants for the |type| field of |GENERAL_NAME|, defined below.
1865+
#define GEN_OTHERNAME 0
1866+
#define GEN_EMAIL 1
1867+
#define GEN_DNS 2
1868+
#define GEN_X400 3
1869+
#define GEN_DIRNAME 4
1870+
#define GEN_EDIPARTY 5
1871+
#define GEN_URI 6
1872+
#define GEN_IPADD 7
1873+
#define GEN_RID 8
1874+
1875+
// A GENERAL_NAME_st, aka |GENERAL_NAME|, represents an X.509 GeneralName. The
1876+
// |type| field determines which member of |d| is active. A |GENERAL_NAME| may
1877+
// also be empty, in which case |type| is -1 and |d| is NULL. Empty
1878+
// |GENERAL_NAME|s are invalid and will never be returned from the parser, but
1879+
// may be created temporarily, e.g. by |GENERAL_NAME_new|.
1880+
struct GENERAL_NAME_st {
1881+
int type;
1882+
union {
1883+
char *ptr;
1884+
OTHERNAME *otherName;
1885+
ASN1_IA5STRING *rfc822Name;
1886+
ASN1_IA5STRING *dNSName;
1887+
ASN1_STRING *x400Address;
1888+
X509_NAME *directoryName;
1889+
EDIPARTYNAME *ediPartyName;
1890+
ASN1_IA5STRING *uniformResourceIdentifier;
1891+
ASN1_OCTET_STRING *iPAddress;
1892+
ASN1_OBJECT *registeredID;
1893+
1894+
// Old names
1895+
ASN1_OCTET_STRING *ip; // iPAddress
1896+
X509_NAME *dirn; // dirn
1897+
ASN1_IA5STRING *ia5; // rfc822Name, dNSName, uniformResourceIdentifier
1898+
ASN1_OBJECT *rid; // registeredID
1899+
} d;
1900+
} /* GENERAL_NAME */;
1901+
1902+
// GENERAL_NAME_new returns a new, empty |GENERAL_NAME|, or NULL on error.
1903+
OPENSSL_EXPORT GENERAL_NAME *GENERAL_NAME_new(void);
1904+
1905+
// GENERAL_NAME_free releases memory associated with |gen|.
1906+
OPENSSL_EXPORT void GENERAL_NAME_free(GENERAL_NAME *gen);
1907+
1908+
// d2i_GENERAL_NAME parses up to |len| bytes from |*inp| as a DER-encoded X.509
1909+
// GeneralName (RFC 5280), as described in |d2i_SAMPLE|.
1910+
OPENSSL_EXPORT GENERAL_NAME *d2i_GENERAL_NAME(GENERAL_NAME **out,
1911+
const uint8_t **inp, long len);
1912+
1913+
// i2d_GENERAL_NAME marshals |in| as a DER-encoded X.509 GeneralName (RFC 5280),
1914+
// as described in |i2d_SAMPLE|.
1915+
//
1916+
// TODO(https://crbug.com/boringssl/407): This function should be const and
1917+
// thread-safe but is currently neither in some cases, notably if |in| is an
1918+
// directoryName and the |X509_NAME| has been modified.
1919+
OPENSSL_EXPORT int i2d_GENERAL_NAME(GENERAL_NAME *in, uint8_t **outp);
1920+
1921+
// GENERAL_NAME_dup returns a newly-allocated copy of |gen|, or NULL on error.
1922+
// This function works by serializing the structure, so it will fail if |gen| is
1923+
// empty.
1924+
//
1925+
// TODO(https://crbug.com/boringssl/407): This function should be const and
1926+
// thread-safe but is currently neither in some cases, notably if |gen| is an
1927+
// directoryName and the |X509_NAME| has been modified.
1928+
OPENSSL_EXPORT GENERAL_NAME *GENERAL_NAME_dup(GENERAL_NAME *gen);
1929+
1930+
// GENERAL_NAMES_new returns a new, empty |GENERAL_NAMES|, or NULL on error.
1931+
OPENSSL_EXPORT GENERAL_NAMES *GENERAL_NAMES_new(void);
1932+
1933+
// GENERAL_NAMES_free releases memory associated with |gens|.
1934+
OPENSSL_EXPORT void GENERAL_NAMES_free(GENERAL_NAMES *gens);
1935+
1936+
// d2i_GENERAL_NAMES parses up to |len| bytes from |*inp| as a DER-encoded
1937+
// SEQUENCE OF GeneralName, as described in |d2i_SAMPLE|.
1938+
OPENSSL_EXPORT GENERAL_NAMES *d2i_GENERAL_NAMES(GENERAL_NAMES **out,
1939+
const uint8_t **inp, long len);
1940+
1941+
// i2d_GENERAL_NAMES marshals |in| as a DER-encoded SEQUENCE OF GeneralName, as
1942+
// described in |i2d_SAMPLE|.
1943+
//
1944+
// TODO(https://crbug.com/boringssl/407): This function should be const and
1945+
// thread-safe but is currently neither in some cases, notably if some element
1946+
// of |in| is an directoryName and the |X509_NAME| has been modified.
1947+
OPENSSL_EXPORT int i2d_GENERAL_NAMES(GENERAL_NAMES *in, uint8_t **outp);
1948+
1949+
// OTHERNAME_new returns a new, empty |OTHERNAME|, or NULL on error.
1950+
OPENSSL_EXPORT OTHERNAME *OTHERNAME_new(void);
1951+
1952+
// OTHERNAME_free releases memory associated with |name|.
1953+
OPENSSL_EXPORT void OTHERNAME_free(OTHERNAME *name);
1954+
1955+
// EDIPARTYNAME_new returns a new, empty |EDIPARTYNAME|, or NULL on error.
1956+
// EDIPartyName is rarely used in practice, so callers are unlikely to need this
1957+
// function.
1958+
OPENSSL_EXPORT EDIPARTYNAME *EDIPARTYNAME_new(void);
1959+
1960+
// EDIPARTYNAME_free releases memory associated with |name|. EDIPartyName is
1961+
// rarely used in practice, so callers are unlikely to need this function.
1962+
OPENSSL_EXPORT void EDIPARTYNAME_free(EDIPARTYNAME *name);
1963+
1964+
// GENERAL_NAME_set0_value set |gen|'s type and value to |type| and |value|.
1965+
// |type| must be a |GEN_*| constant and |value| must be an object of the
1966+
// corresponding type. |gen| takes ownership of |value|, so |value| must have
1967+
// been an allocated object.
1968+
//
1969+
// WARNING: |gen| must be empty (typically as returned from |GENERAL_NAME_new|)
1970+
// before calling this function. If |gen| already contained a value, the
1971+
// previous contents will be leaked.
1972+
OPENSSL_EXPORT void GENERAL_NAME_set0_value(GENERAL_NAME *gen, int type,
1973+
void *value);
1974+
1975+
// GENERAL_NAME_get0_value returns the in-memory representation of |gen|'s
1976+
// contents and, |out_type| is not NULL, sets |*out_type| to the type of |gen|,
1977+
// which will be a |GEN_*| constant. If |gen| is incomplete, the return value
1978+
// will be NULL and the type will be -1.
1979+
//
1980+
// WARNING: Casting the result of this function to the wrong type is a
1981+
// potentially exploitable memory error. Callers must check |gen|'s type, either
1982+
// via |*out_type| or checking |gen->type| directly, before inspecting the
1983+
// result.
1984+
//
1985+
// WARNING: This function is not const-correct. The return value should be
1986+
// const. Callers shoudl not mutate the returned object.
1987+
OPENSSL_EXPORT void *GENERAL_NAME_get0_value(const GENERAL_NAME *gen,
1988+
int *out_type);
1989+
1990+
// GENERAL_NAME_set0_othername sets |gen| to be an OtherName with type |oid| and
1991+
// value |value|. On success, it returns one and takes ownership of |oid| and
1992+
// |value|, which must be created in a way compatible with |ASN1_OBJECT_free|
1993+
// and |ASN1_TYPE_free|, respectively. On allocation failure, it returns zero.
1994+
// In the failure case, the caller retains ownership of |oid| and |value| and
1995+
// must release them when done.
1996+
//
1997+
// WARNING: |gen| must be empty (typically as returned from |GENERAL_NAME_new|)
1998+
// before calling this function. If |gen| already contained a value, the
1999+
// previously contents will be leaked.
2000+
OPENSSL_EXPORT int GENERAL_NAME_set0_othername(GENERAL_NAME *gen,
2001+
ASN1_OBJECT *oid,
2002+
ASN1_TYPE *value);
2003+
2004+
// GENERAL_NAME_get0_otherName, if |gen| is an OtherName, sets |*out_oid| and
2005+
// |*out_value| to the OtherName's type-id and value, respectively, and returns
2006+
// one. If |gen| is not an OtherName, it returns zero and leaves |*out_oid| and
2007+
// |*out_value| unmodified. Either of |out_oid| or |out_value| may be NULL to
2008+
// ignore the value.
2009+
//
2010+
// WARNING: This function is not const-correct. |out_oid| and |out_value| are
2011+
// not const, but callers should not mutate the resulting objects.
2012+
OPENSSL_EXPORT int GENERAL_NAME_get0_otherName(const GENERAL_NAME *gen,
2013+
ASN1_OBJECT **out_oid,
2014+
ASN1_TYPE **out_value);
2015+
2016+
18442017
// Algorithm identifiers.
18452018
//
18462019
// An |X509_ALGOR| represents an AlgorithmIdentifier structure, used in X.509
@@ -3225,7 +3398,6 @@ struct X509_algor_st {
32253398
// the end of the certificate itself
32263399

32273400
DECLARE_STACK_OF(DIST_POINT)
3228-
DECLARE_STACK_OF(GENERAL_NAME)
32293401

32303402
// This is used for a table of trust checking functions
32313403

@@ -4011,49 +4183,6 @@ struct BASIC_CONSTRAINTS_st {
40114183
ASN1_INTEGER *pathlen;
40124184
};
40134185

4014-
4015-
typedef struct otherName_st {
4016-
ASN1_OBJECT *type_id;
4017-
ASN1_TYPE *value;
4018-
} OTHERNAME;
4019-
4020-
typedef struct EDIPartyName_st {
4021-
ASN1_STRING *nameAssigner;
4022-
ASN1_STRING *partyName;
4023-
} EDIPARTYNAME;
4024-
4025-
struct GENERAL_NAME_st {
4026-
#define GEN_OTHERNAME 0
4027-
#define GEN_EMAIL 1
4028-
#define GEN_DNS 2
4029-
#define GEN_X400 3
4030-
#define GEN_DIRNAME 4
4031-
#define GEN_EDIPARTY 5
4032-
#define GEN_URI 6
4033-
#define GEN_IPADD 7
4034-
#define GEN_RID 8
4035-
4036-
int type;
4037-
union {
4038-
char *ptr;
4039-
OTHERNAME *otherName; // otherName
4040-
ASN1_IA5STRING *rfc822Name;
4041-
ASN1_IA5STRING *dNSName;
4042-
ASN1_STRING *x400Address;
4043-
X509_NAME *directoryName;
4044-
EDIPARTYNAME *ediPartyName;
4045-
ASN1_IA5STRING *uniformResourceIdentifier;
4046-
ASN1_OCTET_STRING *iPAddress;
4047-
ASN1_OBJECT *registeredID;
4048-
4049-
// Old names
4050-
ASN1_OCTET_STRING *ip; // iPAddress
4051-
X509_NAME *dirn; // dirn
4052-
ASN1_IA5STRING *ia5; // rfc822Name, dNSName, uniformResourceIdentifier
4053-
ASN1_OBJECT *rid; // registeredID
4054-
} d;
4055-
} /* GENERAL_NAME */;
4056-
40574186
typedef struct ACCESS_DESCRIPTION_st {
40584187
ASN1_OBJECT *method;
40594188
GENERAL_NAME *location;
@@ -4213,27 +4342,6 @@ DECLARE_ASN1_FUNCTIONS_const(BASIC_CONSTRAINTS)
42134342
// an |X509_NAME|.
42144343
DECLARE_ASN1_FUNCTIONS(AUTHORITY_KEYID)
42154344

4216-
// TODO(https://crbug.com/boringssl/407): This is not const because it contains
4217-
// an |X509_NAME|.
4218-
DECLARE_ASN1_FUNCTIONS(GENERAL_NAME)
4219-
OPENSSL_EXPORT GENERAL_NAME *GENERAL_NAME_dup(GENERAL_NAME *a);
4220-
4221-
// TODO(https://crbug.com/boringssl/407): This is not const because it contains
4222-
// an |X509_NAME|.
4223-
DECLARE_ASN1_FUNCTIONS(GENERAL_NAMES)
4224-
4225-
DECLARE_ASN1_FUNCTIONS_const(OTHERNAME)
4226-
DECLARE_ASN1_FUNCTIONS_const(EDIPARTYNAME)
4227-
OPENSSL_EXPORT void GENERAL_NAME_set0_value(GENERAL_NAME *a, int type,
4228-
void *value);
4229-
OPENSSL_EXPORT void *GENERAL_NAME_get0_value(const GENERAL_NAME *a, int *ptype);
4230-
OPENSSL_EXPORT int GENERAL_NAME_set0_othername(GENERAL_NAME *gen,
4231-
ASN1_OBJECT *oid,
4232-
ASN1_TYPE *value);
4233-
OPENSSL_EXPORT int GENERAL_NAME_get0_otherName(const GENERAL_NAME *gen,
4234-
ASN1_OBJECT **poid,
4235-
ASN1_TYPE **pvalue);
4236-
42374345
DECLARE_ASN1_FUNCTIONS_const(EXTENDED_KEY_USAGE)
42384346

42394347
DECLARE_ASN1_FUNCTIONS_const(CERTIFICATEPOLICIES)

0 commit comments

Comments
 (0)