// Copyright 1995-2016 The OpenSSL Project Authors. All Rights Reserved.

//

// Licensed under the Apache License, Version 2.0 (the "License");

// you may not use this file except in compliance with the License.

// You may obtain a copy of the License at

//

//     https://www.apache.org/licenses/LICENSE-2.0

//

// Unless required by applicable law or agreed to in writing, software

// distributed under the License is distributed on an "AS IS" BASIS,

// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

// See the License for the specific language governing permissions and

// limitations under the License.

#ifndef OPENSSL_HEADER_ASN1_H

#define OPENSSL_HEADER_ASN1_H

#include <openssl/base.h>   // IWYU pragma: export

#include <time.h>

#include <openssl/bio.h>

#include <openssl/bn.h>

#include <openssl/stack.h>

#if defined(__cplusplus)

extern "C" {

#endif

// Legacy ASN.1 library.

//

// This header is part of OpenSSL's ASN.1 implementation. It is retained for

// compatibility but should not be used by new code. The functions are difficult

// to use correctly, and have buggy or non-standard behaviors. They are thus

// particularly prone to behavior changes and API removals, as BoringSSL

// iterates on these issues.

//

// Use the new |CBS| and |CBB| library in <openssl/bytestring.h> instead.

// Tag constants.

//

// These constants are used in various APIs to specify ASN.1 types and tag

// components. See the specific API's documentation for details on which values

// are used and how.

// The following constants are tag classes.

#define V_ASN1_UNIVERSAL 0x00

#define V_ASN1_APPLICATION 0x40

#define V_ASN1_CONTEXT_SPECIFIC 0x80

#define V_ASN1_PRIVATE 0xc0

// V_ASN1_CONSTRUCTED indicates an element is constructed, rather than

// primitive.

#define V_ASN1_CONSTRUCTED 0x20

// V_ASN1_PRIMITIVE_TAG is the highest tag number which can be encoded in a

// single byte. Note this is unrelated to whether an element is constructed or

// primitive.

//

// TODO(davidben): Make this private.

#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| and |MBSTRING_FLAG|.

//

// TODO(davidben): Make this private.

#define V_ASN1_MAX_UNIVERSAL 0xff

// V_ASN1_UNDEF is used in some APIs to indicate an ASN.1 element is omitted.

#define V_ASN1_UNDEF (-1)

// V_ASN1_OTHER is used in |ASN1_TYPE| to indicate a non-universal ASN.1 type.

#define V_ASN1_OTHER (-3)

// V_ASN1_ANY is used by the ASN.1 templates to indicate an ANY type.

#define V_ASN1_ANY (-4)

// V_ASN1_ANY_AS_STRING is used by the ASN.1 templates to indicate an ANY type

// represented with |ASN1_STRING| instead of |ASN1_TYPE|.

#define V_ASN1_ANY_AS_STRING (-5)

// The following constants are tag numbers for universal types.

#define V_ASN1_EOC 0

#define V_ASN1_BOOLEAN 1

#define V_ASN1_INTEGER 2

#define V_ASN1_BIT_STRING 3

#define V_ASN1_OCTET_STRING 4

#define V_ASN1_NULL 5

#define V_ASN1_OBJECT 6

#define V_ASN1_OBJECT_DESCRIPTOR 7

#define V_ASN1_EXTERNAL 8

#define V_ASN1_REAL 9

#define V_ASN1_ENUMERATED 10

#define V_ASN1_UTF8STRING 12

#define V_ASN1_SEQUENCE 16

#define V_ASN1_SET 17

#define V_ASN1_NUMERICSTRING 18

#define V_ASN1_PRINTABLESTRING 19

#define V_ASN1_T61STRING 20

#define V_ASN1_TELETEXSTRING 20

#define V_ASN1_VIDEOTEXSTRING 21

#define V_ASN1_IA5STRING 22

#define V_ASN1_UTCTIME 23

#define V_ASN1_GENERALIZEDTIME 24

#define V_ASN1_GRAPHICSTRING 25

#define V_ASN1_ISO64STRING 26

#define V_ASN1_VISIBLESTRING 26

#define V_ASN1_GENERALSTRING 27

#define V_ASN1_UNIVERSALSTRING 28

#define V_ASN1_BMPSTRING 30

// The following constants are used for |ASN1_STRING| values that represent

// negative INTEGER and ENUMERATED values. See |ASN1_STRING| for more details.

#define V_ASN1_NEG 0x100

#define V_ASN1_NEG_INTEGER (V_ASN1_INTEGER | V_ASN1_NEG)

#define V_ASN1_NEG_ENUMERATED (V_ASN1_ENUMERATED | V_ASN1_NEG)

// The following constants are bitmask representations of ASN.1 types.

#define B_ASN1_NUMERICSTRING 0x0001

#define B_ASN1_PRINTABLESTRING 0x0002

#define B_ASN1_T61STRING 0x0004

#define B_ASN1_TELETEXSTRING 0x0004

#define B_ASN1_VIDEOTEXSTRING 0x0008

#define B_ASN1_IA5STRING 0x0010

#define B_ASN1_GRAPHICSTRING 0x0020

#define B_ASN1_ISO64STRING 0x0040

#define B_ASN1_VISIBLESTRING 0x0040

#define B_ASN1_GENERALSTRING 0x0080

#define B_ASN1_UNIVERSALSTRING 0x0100

#define B_ASN1_OCTET_STRING 0x0200

#define B_ASN1_BIT_STRING 0x0400

#define B_ASN1_BMPSTRING 0x0800

#define B_ASN1_UTF8STRING 0x2000

#define B_ASN1_UTCTIME 0x4000

#define B_ASN1_GENERALIZEDTIME 0x8000

#define B_ASN1_SEQUENCE 0x10000

// ASN1_tag2bit converts |tag| from the tag number of a universal type to a

// corresponding |B_ASN1_*| constant, or zero if |tag| has no bitmask.

OPENSSL_EXPORT unsigned long ASN1_tag2bit(int tag);

// ASN1_tag2str returns a string representation of |tag|, interpret as a tag

// number for a universal type, or |V_ASN1_NEG_*|.

OPENSSL_EXPORT const char *ASN1_tag2str(int tag);

// API conventions.

//

// The following sample functions document the calling conventions used by

// legacy ASN.1 APIs.

#if 0  // Sample functions

// d2i_SAMPLE parses a structure from up to |len| bytes at |*inp|. On success,

// it advances |*inp| by the number of bytes read and returns a newly-allocated

// |SAMPLE| object containing the parsed structure. If |out| is non-NULL, it

// additionally frees the previous value at |*out| and updates |*out| to the

// result. If parsing or allocating the result fails, it returns NULL.

//

// This function does not reject trailing data in the input. This allows the

// caller to parse a sequence of concatenated structures. Callers parsing only

// one structure should check for trailing data by comparing the updated |*inp|

// with the end of the input.

//

// Note: If |out| and |*out| are both non-NULL, the object at |*out| is not

// updated in-place. Instead, it is freed, and the pointer is updated to the

// new object. This differs from OpenSSL. Callers are recommended to set |out|

// to NULL and instead use the return value.

SAMPLE *d2i_SAMPLE(SAMPLE **out, const uint8_t **inp, long len);

// i2d_SAMPLE marshals |in|. On error, it returns a negative value. On success,

// it returns the length of the result and outputs it via |outp| as follows:

//

// If |outp| is NULL, the function writes nothing. This mode can be used to size

// buffers.

//

// If |outp| is non-NULL but |*outp| is NULL, the function sets |*outp| to a

// newly-allocated buffer containing the result. The caller is responsible for

// releasing |*outp| with |OPENSSL_free|. This mode is recommended for most

// callers.

//

// If |outp| and |*outp| are non-NULL, the function writes the result to

// |*outp|, which must have enough space available, and advances |*outp| just

// past the output.

//

// WARNING: In the third mode, the function does not internally check output

// bounds. Failing to correctly size the buffer will result in a potentially

// exploitable memory error.

int i2d_SAMPLE(const SAMPLE *in, uint8_t **outp);

#endif  // Sample functions

// The following typedefs are sometimes used for pointers to functions like

// |d2i_SAMPLE| and |i2d_SAMPLE|. Note, however, that these act on |void*|.

// Calling a function with a different pointer type is undefined in C, so this

// is only valid with a wrapper.

typedef void *d2i_of_void(void **, const unsigned char **, long);

typedef int i2d_of_void(const void *, unsigned char **);

// ASN.1 types.

//

// An |ASN1_ITEM| represents an ASN.1 type and allows working with ASN.1 types

// generically.

//

// |ASN1_ITEM|s use a different namespace from C types and are accessed via

// |ASN1_ITEM_*| macros. So, for example, |ASN1_OCTET_STRING| is both a C type

// and the name of an |ASN1_ITEM|, referenced as

// |ASN1_ITEM_rptr(ASN1_OCTET_STRING)|.

//

// Each |ASN1_ITEM| has a corresponding C type, typically with the same name,

// which represents values in the ASN.1 type. This type is either a pointer type

// or |ASN1_BOOLEAN|. When it is a pointer, NULL pointers represent omitted

// values. For example, an OCTET STRING value is declared with the C type

// |ASN1_OCTET_STRING*| and uses the |ASN1_ITEM| named |ASN1_OCTET_STRING|. An

// OPTIONAL OCTET STRING uses the same C type and represents an omitted value

// with a NULL pointer. |ASN1_BOOLEAN| is described in a later section.

// DECLARE_ASN1_ITEM declares an |ASN1_ITEM| with name |name|. The |ASN1_ITEM|

// may be referenced with |ASN1_ITEM_rptr|. Uses of this macro should document

// the corresponding ASN.1 and C types.

#define DECLARE_ASN1_ITEM(name) extern OPENSSL_EXPORT const ASN1_ITEM name##_it;

// ASN1_ITEM_rptr returns the |const ASN1_ITEM *| named |name|.

#define ASN1_ITEM_rptr(name) (&(name##_it))

// ASN1_ITEM_EXP is an abstraction for referencing an |ASN1_ITEM| in a

// constant-initialized structure, such as a method table. It exists because, on

// some OpenSSL platforms, |ASN1_ITEM| references are indirected through

// functions. Structures reference the |ASN1_ITEM| by declaring a field like

// |ASN1_ITEM_EXP *item| and initializing it with |ASN1_ITEM_ref|.

typedef const ASN1_ITEM ASN1_ITEM_EXP;

// ASN1_ITEM_ref returns an |ASN1_ITEM_EXP*| for the |ASN1_ITEM| named |name|.

#define ASN1_ITEM_ref(name) (&(name##_it))

// ASN1_ITEM_ptr converts |iptr|, which must be an |ASN1_ITEM_EXP*| to a

// |const ASN1_ITEM*|.

#define ASN1_ITEM_ptr(iptr) (iptr)

// ASN1_VALUE_st (aka |ASN1_VALUE|) is an opaque type used as a placeholder for

// the C type corresponding to an |ASN1_ITEM|.

typedef struct ASN1_VALUE_st ASN1_VALUE;

// ASN1_item_new allocates a new value of the C type corresponding to |it|, or

// NULL on error. On success, the caller must release the value with

// |ASN1_item_free|, or the corresponding C type's free function, when done. The

// new value will initialize fields of the value to some default state, such as

// an empty string. Note, however, that this default state sometimes omits

// required values, such as with CHOICE types.

//

// This function may not be used with |ASN1_ITEM|s whose C type is

// |ASN1_BOOLEAN|.

//

// WARNING: Casting the result of this function to the wrong type is a

// potentially exploitable memory error. Callers must ensure the value is used

// consistently with |it|. Prefer using type-specific functions such as

// |ASN1_OCTET_STRING_new|.

OPENSSL_EXPORT ASN1_VALUE *ASN1_item_new(const ASN1_ITEM *it);

// ASN1_item_free releases memory associated with |val|, which must be an object

// of the C type corresponding to |it|.

//

// This function may not be used with |ASN1_ITEM|s whose C type is

// |ASN1_BOOLEAN|.

//

// WARNING: Passing a pointer of the wrong type into this function is a

// potentially exploitable memory error. Callers must ensure |val| is consistent

// with |it|. Prefer using type-specific functions such as

// |ASN1_OCTET_STRING_free|.

OPENSSL_EXPORT void ASN1_item_free(ASN1_VALUE *val, const ASN1_ITEM *it);

// ASN1_item_d2i parses the ASN.1 type |it| from up to |len| bytes at |*inp|.

// It behaves like |d2i_SAMPLE|, except that |out| and the return value are cast

// to |ASN1_VALUE| pointers.

//

// TODO(https://crbug.com/boringssl/444): C strict aliasing forbids type-punning

// |T*| and |ASN1_VALUE*| the way this function signature does. When that bug is

// resolved, we will need to pick which type |*out| is (probably |T*|). Do not

// use a non-NULL |out| to avoid ending up on the wrong side of this question.

//

// This function may not be used with |ASN1_ITEM|s whose C type is

// |ASN1_BOOLEAN|.

//

// WARNING: Casting the result of this function to the wrong type, or passing a

// pointer of the wrong type into this function, are potentially exploitable

// memory errors. Callers must ensure |out| is consistent with |it|. Prefer

// using type-specific functions such as |d2i_ASN1_OCTET_STRING|.

OPENSSL_EXPORT ASN1_VALUE *ASN1_item_d2i(ASN1_VALUE **out,

                                         const unsigned char **inp, long len,

                                         const ASN1_ITEM *it);

// ASN1_item_i2d marshals |val| as the ASN.1 type associated with |it|, as

// described in |i2d_SAMPLE|.

//

// This function may not be used with |ASN1_ITEM|s whose C type is

// |ASN1_BOOLEAN|.

//

// WARNING: Passing a pointer of the wrong type into this function is a

// potentially exploitable memory error. Callers must ensure |val| is consistent

// with |it|. Prefer using type-specific functions such as

// |i2d_ASN1_OCTET_STRING|.

OPENSSL_EXPORT int ASN1_item_i2d(ASN1_VALUE *val, unsigned char **outp,

                                 const ASN1_ITEM *it);

// ASN1_item_dup returns a newly-allocated copy of |x|, or NULL on error. |x|

// must be an object of |it|'s C type.

//

// This function may not be used with |ASN1_ITEM|s whose C type is

// |ASN1_BOOLEAN|.

//

// WARNING: Casting the result of this function to the wrong type, or passing a

// pointer of the wrong type into this function, are potentially exploitable

// memory errors. Prefer using type-specific functions such as

// |ASN1_STRING_dup|.

OPENSSL_EXPORT void *ASN1_item_dup(const ASN1_ITEM *it, void *x);

// The following functions behave like |ASN1_item_d2i| but read from |in|

// instead. |out| is the same parameter as in |ASN1_item_d2i|, but written with

// |void*| instead. The return values similarly match.

//

// These functions may not be used with |ASN1_ITEM|s whose C type is

// |ASN1_BOOLEAN|.

//

// WARNING: These functions do not bound how much data is read from |in|.

// Parsing an untrusted input could consume unbounded memory.

OPENSSL_EXPORT void *ASN1_item_d2i_fp(const ASN1_ITEM *it, FILE *in, void *out);

OPENSSL_EXPORT void *ASN1_item_d2i_bio(const ASN1_ITEM *it, BIO *in, void *out);

// The following functions behave like |ASN1_item_i2d| but write to |out|

// instead. |in| is the same parameter as in |ASN1_item_i2d|, but written with

// |void*| instead.

//

// These functions may not be used with |ASN1_ITEM|s whose C type is

// |ASN1_BOOLEAN|.

OPENSSL_EXPORT int ASN1_item_i2d_fp(const ASN1_ITEM *it, FILE *out, void *in);

OPENSSL_EXPORT int ASN1_item_i2d_bio(const ASN1_ITEM *it, BIO *out, void *in);

// ASN1_item_unpack parses |oct|'s contents as |it|'s ASN.1 type. It returns a

// newly-allocated instance of |it|'s C type on success, or NULL on error.

//

// This function may not be used with |ASN1_ITEM|s whose C type is

// |ASN1_BOOLEAN|.

//

// WARNING: Casting the result of this function to the wrong type is a

// potentially exploitable memory error. Callers must ensure the value is used

// consistently with |it|.

OPENSSL_EXPORT void *ASN1_item_unpack(const ASN1_STRING *oct,

                                      const ASN1_ITEM *it);

// ASN1_item_pack marshals |obj| as |it|'s ASN.1 type. If |out| is NULL, it

// returns a newly-allocated |ASN1_STRING| with the result, or NULL on error.

// If |out| is non-NULL, but |*out| is NULL, it does the same but additionally

// sets |*out| to the result. If both |out| and |*out| are non-NULL, it writes

// the result to |*out| and returns |*out| on success or NULL on error.

//

// This function may not be used with |ASN1_ITEM|s whose C type is

// |ASN1_BOOLEAN|.

//

// WARNING: Passing a pointer of the wrong type into this function is a

// potentially exploitable memory error. Callers must ensure |val| is consistent

// with |it|.

OPENSSL_EXPORT ASN1_STRING *ASN1_item_pack(void *obj, const ASN1_ITEM *it,

                                           ASN1_STRING **out);

// Booleans.

//

// This library represents ASN.1 BOOLEAN values with |ASN1_BOOLEAN|, which is an

// integer type. FALSE is zero, TRUE is 0xff, and an omitted OPTIONAL BOOLEAN is

// -1.

// ASN1_BOOLEAN_FALSE is FALSE as an |ASN1_BOOLEAN|.

#define ASN1_BOOLEAN_FALSE 0

// ASN1_BOOLEAN_TRUE is TRUE as an |ASN1_BOOLEAN|. Some code incorrectly uses

// 1, so prefer |b != ASN1_BOOLEAN_FALSE| over |b == ASN1_BOOLEAN_TRUE|.

#define ASN1_BOOLEAN_TRUE 0xff

// ASN1_BOOLEAN_NONE, in contexts where the |ASN1_BOOLEAN| represents an

// OPTIONAL BOOLEAN, is an omitted value. Using this value in other contexts is

// undefined and may be misinterpreted as TRUE.

#define ASN1_BOOLEAN_NONE (-1)

// d2i_ASN1_BOOLEAN parses a DER-encoded ASN.1 BOOLEAN from up to |len| bytes at

// |*inp|. On success, it advances |*inp| by the number of bytes read and

// returns the result. If |out| is non-NULL, it additionally writes the result

// to |*out|. On error, it returns |ASN1_BOOLEAN_NONE|.

//

// This function does not reject trailing data in the input. This allows the

// caller to parse a sequence of concatenated structures. Callers parsing only

// one structure should check for trailing data by comparing the updated |*inp|

// with the end of the input.

//

// WARNING: This function's is slightly different from other |d2i_*| functions

// because |ASN1_BOOLEAN| is not a pointer type.

OPENSSL_EXPORT ASN1_BOOLEAN d2i_ASN1_BOOLEAN(ASN1_BOOLEAN *out,

                                             const unsigned char **inp,

                                             long len);

// i2d_ASN1_BOOLEAN marshals |a| as a DER-encoded ASN.1 BOOLEAN, as described in

// |i2d_SAMPLE|.

OPENSSL_EXPORT int i2d_ASN1_BOOLEAN(ASN1_BOOLEAN a, unsigned char **outp);

// The following |ASN1_ITEM|s have ASN.1 type BOOLEAN and C type |ASN1_BOOLEAN|.

// |ASN1_TBOOLEAN| and |ASN1_FBOOLEAN| must be marked OPTIONAL. When omitted,

// they are parsed as TRUE and FALSE, respectively, rather than

// |ASN1_BOOLEAN_NONE|.

DECLARE_ASN1_ITEM(ASN1_BOOLEAN)

DECLARE_ASN1_ITEM(ASN1_TBOOLEAN)

DECLARE_ASN1_ITEM(ASN1_FBOOLEAN)

// Strings.

//

// ASN.1 contains a myriad of string types, as well as types that contain data

// that may be encoded into a string. This library uses a single type,

// |ASN1_STRING|, to represent most values.

// An asn1_string_st (aka |ASN1_STRING|) represents a value of a string-like

// ASN.1 type. It contains a |type| field, and a byte string |data| field with a

// type-specific representation. This type-specific representation does not

// always correspond to the DER encoding of the type.

//

// If |type| is one of |V_ASN1_OCTET_STRING|, |V_ASN1_UTF8STRING|,

// |V_ASN1_NUMERICSTRING|, |V_ASN1_PRINTABLESTRING|, |V_ASN1_T61STRING|,

// |V_ASN1_VIDEOTEXSTRING|, |V_ASN1_IA5STRING|, |V_ASN1_GRAPHICSTRING|,

// |V_ASN1_ISO64STRING|, |V_ASN1_VISIBLESTRING|, |V_ASN1_GENERALSTRING|,

// |V_ASN1_UNIVERSALSTRING|, or |V_ASN1_BMPSTRING|, the object represents an

// ASN.1 string type. The data contains the byte representation of the

// string.

//

// If |type| is |V_ASN1_BIT_STRING|, the object represents a BIT STRING value.

// See bit string documentation below for the data and flags.

//

// If |type| is one of |V_ASN1_INTEGER|, |V_ASN1_NEG_INTEGER|,

// |V_ASN1_ENUMERATED|, or |V_ASN1_NEG_ENUMERATED|, the object represents an

// INTEGER or ENUMERATED value. See integer documentation below for details.

//

// If |type| is |V_ASN1_GENERALIZEDTIME| or |V_ASN1_UTCTIME|, the object

// represents a GeneralizedTime or UTCTime value, respectively. The data

// contains the DER encoding of the value. For example, the UNIX epoch would be

// "19700101000000Z" for a GeneralizedTime and "700101000000Z" for a UTCTime.

//

// If |type| is |V_ASN1_SEQUENCE|, |V_ASN1_SET|, or |V_ASN1_OTHER|, the object

// represents a SEQUENCE, SET, or arbitrary ASN.1 value, respectively. Unlike

// the above cases, the data contains the DER encoding of the entire structure,

// including the header. If the value is explicitly or implicitly tagged, this

// too will be reflected in the data field. As this case handles unknown types,

// the contents are not checked when parsing or serializing.

//

// Other values of |type| do not represent a valid ASN.1 value, though

// default-constructed objects may set |type| to -1. Such objects cannot be

// serialized.

//

// |ASN1_STRING| additionally has the following typedefs: |ASN1_BIT_STRING|,

// |ASN1_BMPSTRING|, |ASN1_ENUMERATED|, |ASN1_GENERALIZEDTIME|,

// |ASN1_GENERALSTRING|, |ASN1_IA5STRING|, |ASN1_INTEGER|, |ASN1_OCTET_STRING|,

// |ASN1_PRINTABLESTRING|, |ASN1_T61STRING|, |ASN1_TIME|,

// |ASN1_UNIVERSALSTRING|, |ASN1_UTCTIME|, |ASN1_UTF8STRING|, and

// |ASN1_VISIBLESTRING|. Other than |ASN1_TIME|, these correspond to universal

// ASN.1 types. |ASN1_TIME| represents a CHOICE of UTCTime and GeneralizedTime,

// with a cutoff of 2049, as used in Section 4.1.2.5 of RFC 5280.

//

// For clarity, callers are encouraged to use the appropriate typedef when

// available. They are the same type as |ASN1_STRING|, so a caller may freely

// pass them into functions expecting |ASN1_STRING|, such as

// |ASN1_STRING_length|.

//

// If a function returns an |ASN1_STRING| where the typedef or ASN.1 structure

// implies constraints on |type|, callers may assume that |type| is correct.

// However, if a function takes an |ASN1_STRING| as input, callers must ensure

// |type| matches. These invariants are not captured by the C type system and

// may not be checked at runtime. For example, callers may assume the output of

// |X509_get0_serialNumber| has type |V_ASN1_INTEGER| or |V_ASN1_NEG_INTEGER|.

// Callers must not pass a string of type |V_ASN1_OCTET_STRING| to

// |X509_set_serialNumber|. Doing so may break invariants on the |X509| object

// and break the |X509_get0_serialNumber| invariant.

//

// TODO(https://crbug.com/boringssl/445): This is very unfriendly. Getting the

// type field wrong should not cause memory errors, but it may do strange

// things. We should add runtime checks to anything that consumes |ASN1_STRING|s

// from the caller.

struct asn1_string_st {

  int length;

  int type;

  unsigned char *data;

  long flags;

};

// ASN1_STRING_FLAG_BITS_LEFT indicates, in a BIT STRING |ASN1_STRING|, that

// flags & 0x7 contains the number of padding bits added to the BIT STRING

// value. When not set, all trailing zero bits in the last byte are implicitly

// treated as padding. This behavior is deprecated and should not be used.

#define ASN1_STRING_FLAG_BITS_LEFT 0x08

// ASN1_STRING_type_new returns a newly-allocated empty |ASN1_STRING| object of

// type |type|, or NULL on error.

OPENSSL_EXPORT ASN1_STRING *ASN1_STRING_type_new(int type);

// ASN1_STRING_new returns a newly-allocated empty |ASN1_STRING| object with an

// arbitrary type. Prefer one of the type-specific constructors, such as

// |ASN1_OCTET_STRING_new|, or |ASN1_STRING_type_new|.

OPENSSL_EXPORT ASN1_STRING *ASN1_STRING_new(void);

// ASN1_STRING_free releases memory associated with |str|.

OPENSSL_EXPORT void ASN1_STRING_free(ASN1_STRING *str);

// ASN1_STRING_copy sets |dst| to a copy of |str|. It returns one on success and

// zero on error.

OPENSSL_EXPORT int ASN1_STRING_copy(ASN1_STRING *dst, const ASN1_STRING *str);

// ASN1_STRING_dup returns a newly-allocated copy of |str|, or NULL on error.

OPENSSL_EXPORT ASN1_STRING *ASN1_STRING_dup(const ASN1_STRING *str);

// ASN1_STRING_type returns the type of |str|. This value will be one of the

// |V_ASN1_*| constants.

OPENSSL_EXPORT int ASN1_STRING_type(const ASN1_STRING *str);

// ASN1_STRING_get0_data returns a pointer to |str|'s contents. Callers should

// use |ASN1_STRING_length| to determine the length of the string. The string

// may have embedded NUL bytes and may not be NUL-terminated.

//

// The contents of an |ASN1_STRING| encode the value in some type-specific

// representation that does not always correspond to the DER encoding of the

// type. See the documentation for |ASN1_STRING| for details.

OPENSSL_EXPORT const unsigned char *ASN1_STRING_get0_data(

    const ASN1_STRING *str);

// ASN1_STRING_data returns a mutable pointer to |str|'s contents. Callers

// should use |ASN1_STRING_length| to determine the length of the string. The

// string may have embedded NUL bytes and may not be NUL-terminated.

//

// The contents of an |ASN1_STRING| encode the value in some type-specific

// representation that does not always correspond to the DER encoding of the

// type. See the documentation for |ASN1_STRING| for details.

//

// Prefer |ASN1_STRING_get0_data|.

OPENSSL_EXPORT unsigned char *ASN1_STRING_data(ASN1_STRING *str);

// ASN1_STRING_length returns the length of |str|, in bytes.

//

// The contents of an |ASN1_STRING| encode the value in some type-specific

// representation that does not always correspond to the DER encoding of the

// type. See the documentation for |ASN1_STRING| for details.

OPENSSL_EXPORT int ASN1_STRING_length(const ASN1_STRING *str);

// ASN1_STRING_cmp compares |a| and |b|'s type and contents. It returns an

// integer equal to, less than, or greater than zero if |a| is equal to, less

// than, or greater than |b|, respectively. This function compares by length,

// then data, then type. Note the data compared is the |ASN1_STRING| internal

// representation and the type order is arbitrary. While this comparison is

// suitable for sorting, callers should not rely on the exact order when |a|

// and |b| are different types.

//

// Note that, if |a| and |b| are INTEGERs, this comparison does not order the

// values numerically. For a numerical comparison, use |ASN1_INTEGER_cmp|.

OPENSSL_EXPORT int ASN1_STRING_cmp(const ASN1_STRING *a, const ASN1_STRING *b);

// ASN1_STRING_set sets the contents of |str| to a copy of |len| bytes from

// |data|. It returns one on success and zero on error. If |data| is NULL, it

// updates the length and allocates the buffer as needed, but does not

// initialize the contents.

OPENSSL_EXPORT int ASN1_STRING_set(ASN1_STRING *str, const void *data,

                                   ossl_ssize_t len);

// ASN1_STRING_set0 sets the contents of |str| to |len| bytes from |data|. It

// takes ownership of |data|, which must have been allocated with

// |OPENSSL_malloc|.

OPENSSL_EXPORT void ASN1_STRING_set0(ASN1_STRING *str, void *data, int len);

// The following functions call |ASN1_STRING_type_new| with the corresponding

// |V_ASN1_*| constant.

OPENSSL_EXPORT ASN1_BMPSTRING *ASN1_BMPSTRING_new(void);

OPENSSL_EXPORT ASN1_GENERALSTRING *ASN1_GENERALSTRING_new(void);

OPENSSL_EXPORT ASN1_IA5STRING *ASN1_IA5STRING_new(void);

OPENSSL_EXPORT ASN1_OCTET_STRING *ASN1_OCTET_STRING_new(void);

OPENSSL_EXPORT ASN1_PRINTABLESTRING *ASN1_PRINTABLESTRING_new(void);

OPENSSL_EXPORT ASN1_T61STRING *ASN1_T61STRING_new(void);

OPENSSL_EXPORT ASN1_UNIVERSALSTRING *ASN1_UNIVERSALSTRING_new(void);

OPENSSL_EXPORT ASN1_UTF8STRING *ASN1_UTF8STRING_new(void);

OPENSSL_EXPORT ASN1_VISIBLESTRING *ASN1_VISIBLESTRING_new(void);

// The following functions call |ASN1_STRING_free|.

OPENSSL_EXPORT void ASN1_BMPSTRING_free(ASN1_BMPSTRING *str);

OPENSSL_EXPORT void ASN1_GENERALSTRING_free(ASN1_GENERALSTRING *str);

OPENSSL_EXPORT void ASN1_IA5STRING_free(ASN1_IA5STRING *str);

OPENSSL_EXPORT void ASN1_OCTET_STRING_free(ASN1_OCTET_STRING *str);

OPENSSL_EXPORT void ASN1_PRINTABLESTRING_free(ASN1_PRINTABLESTRING *str);

OPENSSL_EXPORT void ASN1_T61STRING_free(ASN1_T61STRING *str);

OPENSSL_EXPORT void ASN1_UNIVERSALSTRING_free(ASN1_UNIVERSALSTRING *str);

OPENSSL_EXPORT void ASN1_UTF8STRING_free(ASN1_UTF8STRING *str);

OPENSSL_EXPORT void ASN1_VISIBLESTRING_free(ASN1_VISIBLESTRING *str);

// The following functions parse up to |len| bytes from |*inp| as a

// DER-encoded ASN.1 value of the corresponding type, as described in

// |d2i_SAMPLE|.

OPENSSL_EXPORT ASN1_BMPSTRING *d2i_ASN1_BMPSTRING(ASN1_BMPSTRING **out,

                                                  const uint8_t **inp,

                                                  long len);

OPENSSL_EXPORT ASN1_GENERALSTRING *d2i_ASN1_GENERALSTRING(

    ASN1_GENERALSTRING **out, const uint8_t **inp, long len);

OPENSSL_EXPORT ASN1_IA5STRING *d2i_ASN1_IA5STRING(ASN1_IA5STRING **out,

                                                  const uint8_t **inp,

                                                  long len);

OPENSSL_EXPORT ASN1_OCTET_STRING *d2i_ASN1_OCTET_STRING(ASN1_OCTET_STRING **out,

                                                        const uint8_t **inp,

                                                        long len);

OPENSSL_EXPORT ASN1_PRINTABLESTRING *d2i_ASN1_PRINTABLESTRING(

    ASN1_PRINTABLESTRING **out, const uint8_t **inp, long len);

OPENSSL_EXPORT ASN1_T61STRING *d2i_ASN1_T61STRING(ASN1_T61STRING **out,

                                                  const uint8_t **inp,

                                                  long len);

OPENSSL_EXPORT ASN1_UNIVERSALSTRING *d2i_ASN1_UNIVERSALSTRING(

    ASN1_UNIVERSALSTRING **out, const uint8_t **inp, long len);

OPENSSL_EXPORT ASN1_UTF8STRING *d2i_ASN1_UTF8STRING(ASN1_UTF8STRING **out,

                                                    const uint8_t **inp,

                                                    long len);

OPENSSL_EXPORT ASN1_VISIBLESTRING *d2i_ASN1_VISIBLESTRING(

    ASN1_VISIBLESTRING **out, const uint8_t **inp, long len);

// The following functions marshal |in| as a DER-encoded ASN.1 value of the

// corresponding type, as described in |i2d_SAMPLE|.

OPENSSL_EXPORT int i2d_ASN1_BMPSTRING(const ASN1_BMPSTRING *in, uint8_t **outp);

OPENSSL_EXPORT int i2d_ASN1_GENERALSTRING(const ASN1_GENERALSTRING *in,

                                          uint8_t **outp);

OPENSSL_EXPORT int i2d_ASN1_IA5STRING(const ASN1_IA5STRING *in, uint8_t **outp);

OPENSSL_EXPORT int i2d_ASN1_OCTET_STRING(const ASN1_OCTET_STRING *in,

                                         uint8_t **outp);

OPENSSL_EXPORT int i2d_ASN1_PRINTABLESTRING(const ASN1_PRINTABLESTRING *in,

                                            uint8_t **outp);

OPENSSL_EXPORT int i2d_ASN1_T61STRING(const ASN1_T61STRING *in, uint8_t **outp);

OPENSSL_EXPORT int i2d_ASN1_UNIVERSALSTRING(const ASN1_UNIVERSALSTRING *in,

                                            uint8_t **outp);

OPENSSL_EXPORT int i2d_ASN1_UTF8STRING(const ASN1_UTF8STRING *in,

                                       uint8_t **outp);

OPENSSL_EXPORT int i2d_ASN1_VISIBLESTRING(const ASN1_VISIBLESTRING *in,

                                          uint8_t **outp);

// The following |ASN1_ITEM|s have the ASN.1 type referred to in their name and

// C type |ASN1_STRING*|. The C type may also be written as the corresponding

// typedef.

DECLARE_ASN1_ITEM(ASN1_BMPSTRING)

DECLARE_ASN1_ITEM(ASN1_GENERALSTRING)

DECLARE_ASN1_ITEM(ASN1_IA5STRING)

DECLARE_ASN1_ITEM(ASN1_OCTET_STRING)

DECLARE_ASN1_ITEM(ASN1_PRINTABLESTRING)

DECLARE_ASN1_ITEM(ASN1_T61STRING)

DECLARE_ASN1_ITEM(ASN1_UNIVERSALSTRING)

DECLARE_ASN1_ITEM(ASN1_UTF8STRING)

DECLARE_ASN1_ITEM(ASN1_VISIBLESTRING)

// ASN1_OCTET_STRING_dup calls |ASN1_STRING_dup|.

OPENSSL_EXPORT ASN1_OCTET_STRING *ASN1_OCTET_STRING_dup(

    const ASN1_OCTET_STRING *a);

// ASN1_OCTET_STRING_cmp calls |ASN1_STRING_cmp|.

OPENSSL_EXPORT int ASN1_OCTET_STRING_cmp(const ASN1_OCTET_STRING *a,

                                         const ASN1_OCTET_STRING *b);

// ASN1_OCTET_STRING_set calls |ASN1_STRING_set|.

OPENSSL_EXPORT int ASN1_OCTET_STRING_set(ASN1_OCTET_STRING *str,

                                         const unsigned char *data, int len);

// ASN1_STRING_to_UTF8 converts |in| to UTF-8. On success, sets |*out| to a

// newly-allocated buffer containing the resulting string and returns the length

// of the string. The caller must call |OPENSSL_free| to release |*out| when

// done. On error, it returns a negative number.

OPENSSL_EXPORT int ASN1_STRING_to_UTF8(unsigned char **out,

                                       const ASN1_STRING *in);

// The following formats define encodings for use with functions like

// |ASN1_mbstring_copy|. Note |MBSTRING_ASC| refers to Latin-1, not ASCII.

#define MBSTRING_FLAG 0x1000

#define MBSTRING_UTF8 (MBSTRING_FLAG)

#define MBSTRING_ASC (MBSTRING_FLAG | 1)

#define MBSTRING_BMP (MBSTRING_FLAG | 2)

#define MBSTRING_UNIV (MBSTRING_FLAG | 4)

// DIRSTRING_TYPE contains the valid string types in an X.509 DirectoryString.

#define DIRSTRING_TYPE                                            \

  (B_ASN1_PRINTABLESTRING | B_ASN1_T61STRING | B_ASN1_BMPSTRING | \

   B_ASN1_UTF8STRING)

// PKCS9STRING_TYPE contains the valid string types in a PKCS9String.

#define PKCS9STRING_TYPE (DIRSTRING_TYPE | B_ASN1_IA5STRING)

// ASN1_mbstring_copy converts |len| bytes from |in| to an ASN.1 string. If

// |len| is -1, |in| must be NUL-terminated and the length is determined by

// |strlen|. |in| is decoded according to |inform|, which must be one of

// |MBSTRING_*|. |mask| determines the set of valid output types and is a

// bitmask containing a subset of |B_ASN1_PRINTABLESTRING|, |B_ASN1_IA5STRING|,

// |B_ASN1_T61STRING|, |B_ASN1_BMPSTRING|, |B_ASN1_UNIVERSALSTRING|, and

// |B_ASN1_UTF8STRING|, in that preference order. This function chooses the

// first output type in |mask| which can represent |in|. It interprets T61String

// as Latin-1, rather than T.61.

//

// If |mask| is zero, |DIRSTRING_TYPE| is used by default.

//

// On success, this function returns the |V_ASN1_*| constant corresponding to

// the selected output type and, if |out| and |*out| are both non-NULL, updates

// the object at |*out| with the result. If |out| is non-NULL and |*out| is

// NULL, it instead sets |*out| to a newly-allocated |ASN1_STRING| containing

// the result. If |out| is NULL, it returns the selected output type without

// constructing an |ASN1_STRING|. On error, this function returns -1.

OPENSSL_EXPORT int ASN1_mbstring_copy(ASN1_STRING **out, const uint8_t *in,

                                      ossl_ssize_t len, int inform,

                                      unsigned long mask);

// ASN1_mbstring_ncopy behaves like |ASN1_mbstring_copy| but returns an error if

// the input is less than |minsize| or greater than |maxsize| codepoints long. A

// |maxsize| value of zero is ignored. Note the sizes are measured in

// codepoints, not output bytes.

OPENSSL_EXPORT int ASN1_mbstring_ncopy(ASN1_STRING **out, const uint8_t *in,

                                       ossl_ssize_t len, int inform,

                                       unsigned long mask, ossl_ssize_t minsize,

                                       ossl_ssize_t maxsize);

// ASN1_STRING_set_by_NID behaves like |ASN1_mbstring_ncopy|, but determines

// |mask|, |minsize|, and |maxsize| based on |nid|. When |nid| is a recognized

// X.509 attribute type, it will pick a suitable ASN.1 string type and bounds.

// For most attribute types, it preferentially chooses UTF8String. If |nid| is

// unrecognized, it uses UTF8String by default.

//

// Slightly unlike |ASN1_mbstring_ncopy|, this function interprets |out| and

// returns its result as follows: If |out| is NULL, it returns a newly-allocated

// |ASN1_STRING| containing the result. If |out| is non-NULL and

// |*out| is NULL, it additionally sets |*out| to the result. If both |out| and

// |*out| are non-NULL, it instead updates the object at |*out| and returns

// |*out|. In all cases, it returns NULL on error.

//

// This function supports the following NIDs: |NID_countryName|,

// |NID_dnQualifier|, |NID_domainComponent|, |NID_friendlyName|,

// |NID_givenName|, |NID_initials|, |NID_localityName|, |NID_ms_csp_name|,

// |NID_name|, |NID_organizationalUnitName|, |NID_organizationName|,

// |NID_pkcs9_challengePassword|, |NID_pkcs9_emailAddress|,

// |NID_pkcs9_unstructuredAddress|, |NID_pkcs9_unstructuredName|,

// |NID_serialNumber|, |NID_stateOrProvinceName|, and |NID_surname|. Additional

// NIDs may be registered with |ASN1_STRING_set_by_NID|, but it is recommended

// to call |ASN1_mbstring_ncopy| directly instead.

OPENSSL_EXPORT ASN1_STRING *ASN1_STRING_set_by_NID(ASN1_STRING **out,

                                                   const unsigned char *in,

                                                   ossl_ssize_t len, int inform,

                                                   int nid);

// STABLE_NO_MASK causes |ASN1_STRING_TABLE_add| to allow types other than

// UTF8String.

#define STABLE_NO_MASK 0x02

// ASN1_STRING_TABLE_add registers the corresponding parameters with |nid|, for

// use with |ASN1_STRING_set_by_NID|. It returns one on success and zero on

// error. It is an error to call this function if |nid| is a built-in NID, or

// was already registered by a previous call.

//

// WARNING: This function affects global state in the library. If two libraries

// in the same address space register information for the same OID, one call

// will fail. Prefer directly passing the desired parametrs to

// |ASN1_mbstring_copy| or |ASN1_mbstring_ncopy| instead.

OPENSSL_EXPORT int ASN1_STRING_TABLE_add(int nid, long minsize, long maxsize,

                                         unsigned long mask,

                                         unsigned long flags);

// Multi-strings.

//

// A multi-string, or "MSTRING", is an |ASN1_STRING| that represents a CHOICE of

// several string or string-like types, such as X.509's DirectoryString. The

// |ASN1_STRING|'s type field determines which type is used.

//

// Multi-string types are associated with a bitmask, using the |B_ASN1_*|

// constants, which defines which types are valid.

// B_ASN1_DIRECTORYSTRING is a bitmask of types allowed in an X.509

// DirectoryString (RFC 5280).

#define B_ASN1_DIRECTORYSTRING                                        \

  (B_ASN1_PRINTABLESTRING | B_ASN1_TELETEXSTRING | B_ASN1_BMPSTRING | \

   B_ASN1_UNIVERSALSTRING | B_ASN1_UTF8STRING)

// DIRECTORYSTRING_new returns a newly-allocated |ASN1_STRING| with type -1, or

// NULL on error. The resulting |ASN1_STRING| is not a valid X.509

// DirectoryString until initialized with a value.

OPENSSL_EXPORT ASN1_STRING *DIRECTORYSTRING_new(void);

// DIRECTORYSTRING_free calls |ASN1_STRING_free|.

OPENSSL_EXPORT void DIRECTORYSTRING_free(ASN1_STRING *str);

// d2i_DIRECTORYSTRING parses up to |len| bytes from |*inp| as a DER-encoded

// X.509 DirectoryString (RFC 5280), as described in |d2i_SAMPLE|.

//

// TODO(https://crbug.com/boringssl/354): This function currently also accepts

// BER, but this will be removed in the future.

//

// TODO(https://crbug.com/boringssl/449): DirectoryString's non-empty string

// requirement is not currently enforced.

OPENSSL_EXPORT ASN1_STRING *d2i_DIRECTORYSTRING(ASN1_STRING **out,

                                                const uint8_t **inp, long len);

// i2d_DIRECTORYSTRING marshals |in| as a DER-encoded X.509 DirectoryString (RFC

// 5280), as described in |i2d_SAMPLE|.

OPENSSL_EXPORT int i2d_DIRECTORYSTRING(const ASN1_STRING *in, uint8_t **outp);

// DIRECTORYSTRING is an |ASN1_ITEM| whose ASN.1 type is X.509 DirectoryString

// (RFC 5280) and C type is |ASN1_STRING*|.

DECLARE_ASN1_ITEM(DIRECTORYSTRING)

// B_ASN1_DISPLAYTEXT is a bitmask of types allowed in an X.509 DisplayText (RFC

// 5280).

#define B_ASN1_DISPLAYTEXT                                      \

  (B_ASN1_IA5STRING | B_ASN1_VISIBLESTRING | B_ASN1_BMPSTRING | \

   B_ASN1_UTF8STRING)

// DISPLAYTEXT_new returns a newly-allocated |ASN1_STRING| with type -1, or NULL

// on error. The resulting |ASN1_STRING| is not a valid X.509 DisplayText until

// initialized with a value.

OPENSSL_EXPORT ASN1_STRING *DISPLAYTEXT_new(void);

// DISPLAYTEXT_free calls |ASN1_STRING_free|.

OPENSSL_EXPORT void DISPLAYTEXT_free(ASN1_STRING *str);

// d2i_DISPLAYTEXT parses up to |len| bytes from |*inp| as a DER-encoded X.509

// DisplayText (RFC 5280), as described in |d2i_SAMPLE|.

//

// TODO(https://crbug.com/boringssl/354): This function currently also accepts

// BER, but this will be removed in the future.

//

// TODO(https://crbug.com/boringssl/449): DisplayText's size limits are not

// currently enforced.

OPENSSL_EXPORT ASN1_STRING *d2i_DISPLAYTEXT(ASN1_STRING **out,

                                            const uint8_t **inp, long len);

// i2d_DISPLAYTEXT marshals |in| as a DER-encoded X.509 DisplayText (RFC 5280),

// as described in |i2d_SAMPLE|.

OPENSSL_EXPORT int i2d_DISPLAYTEXT(const ASN1_STRING *in, uint8_t **outp);

// DISPLAYTEXT is an |ASN1_ITEM| whose ASN.1 type is X.509 DisplayText (RFC

// 5280) and C type is |ASN1_STRING*|.

DECLARE_ASN1_ITEM(DISPLAYTEXT)

// Bit strings.

//

// An ASN.1 BIT STRING type represents a string of bits. The string may not

// necessarily be a whole number of bytes. BIT STRINGs occur in ASN.1 structures

// in several forms:

//

// Some BIT STRINGs represent a bitmask of named bits, such as the X.509 key

// usage extension in RFC 5280, section 4.2.1.3. For such bit strings, DER

// imposes an additional restriction that trailing zero bits are removed. Some

// functions like |ASN1_BIT_STRING_set_bit| help in maintaining this.

//

// Other BIT STRINGs are arbitrary strings of bits used as identifiers and do

// not have this constraint, such as the X.509 issuerUniqueID field.

//

// Finally, some structures use BIT STRINGs as a container for byte strings. For

// example, the signatureValue field in X.509 and the subjectPublicKey field in

// SubjectPublicKeyInfo are defined as BIT STRINGs with a value specific to the

// AlgorithmIdentifier. While some unknown algorithm could choose to store

// arbitrary bit strings, all supported algorithms use a byte string, with bit

// order matching the DER encoding. Callers interpreting a BIT STRING as a byte

// string should use |ASN1_BIT_STRING_num_bytes| instead of |ASN1_STRING_length|

// and reject bit strings that are not a whole number of bytes.

//

// This library represents BIT STRINGs as |ASN1_STRING|s with type

// |V_ASN1_BIT_STRING|. The data contains the encoded form of the BIT STRING,

// including any padding bits added to round to a whole number of bytes, but

// excluding the leading byte containing the number of padding bits. If

// |ASN1_STRING_FLAG_BITS_LEFT| is set, the bottom three bits contains the

// number of padding bits. For example, DER encodes the BIT STRING {1, 0} as

// {0x06, 0x80 = 0b10_000000}. The |ASN1_STRING| representation has data of

// {0x80} and flags of ASN1_STRING_FLAG_BITS_LEFT | 6. If

// |ASN1_STRING_FLAG_BITS_LEFT| is unset, trailing zero bits are implicitly

// removed. Callers should not rely this representation when constructing bit

// strings. The padding bits in the |ASN1_STRING| data must be zero.

// ASN1_BIT_STRING_new calls |ASN1_STRING_type_new| with |V_ASN1_BIT_STRING|.

OPENSSL_EXPORT ASN1_BIT_STRING *ASN1_BIT_STRING_new(void);

// ASN1_BIT_STRING_free calls |ASN1_STRING_free|.

OPENSSL_EXPORT void ASN1_BIT_STRING_free(ASN1_BIT_STRING *str);

// d2i_ASN1_BIT_STRING parses up to |len| bytes from |*inp| as a DER-encoded

// ASN.1 BIT STRING, as described in |d2i_SAMPLE|.

OPENSSL_EXPORT ASN1_BIT_STRING *d2i_ASN1_BIT_STRING(ASN1_BIT_STRING **out,

                                                    const uint8_t **inp,

                                                    long len);

// i2d_ASN1_BIT_STRING marshals |in| as a DER-encoded ASN.1 BIT STRING, as

// described in |i2d_SAMPLE|.

OPENSSL_EXPORT int i2d_ASN1_BIT_STRING(const ASN1_BIT_STRING *in,

                                       uint8_t **outp);

// c2i_ASN1_BIT_STRING decodes |len| bytes from |*inp| as the contents of a

// DER-encoded BIT STRING, excluding the tag and length. It behaves like

// |d2i_SAMPLE| except, on success, it always consumes all |len| bytes.

OPENSSL_EXPORT ASN1_BIT_STRING *c2i_ASN1_BIT_STRING(ASN1_BIT_STRING **out,

                                                    const uint8_t **inp,

                                                    long len);

// i2c_ASN1_BIT_STRING encodes |in| as the contents of a DER-encoded BIT STRING,

// excluding the tag and length. If |outp| is non-NULL, it writes the result to

// |*outp|, advances |*outp| just past the output, and returns the number of

// bytes written. |*outp| must have space available for the result. If |outp| is

// NULL, it returns the number of bytes without writing anything. On error, it

// returns a value <= 0.

//

// Note this function differs slightly from |i2d_SAMPLE|. If |outp| is non-NULL

// and |*outp| is NULL, it does not allocate a new buffer.

//

// TODO(davidben): This function currently returns zero on error instead of -1,

// but it is also mostly infallible. I've currently documented <= 0 to suggest

// callers work with both.

OPENSSL_EXPORT int i2c_ASN1_BIT_STRING(const ASN1_BIT_STRING *in,

                                       uint8_t **outp);

// ASN1_BIT_STRING is an |ASN1_ITEM| with ASN.1 type BIT STRING and C type

// |ASN1_BIT_STRING*|.

DECLARE_ASN1_ITEM(ASN1_BIT_STRING)

// ASN1_BIT_STRING_num_bytes computes the length of |str| in bytes. If |str|'s

// bit length is a multiple of 8, it sets |*out| to the byte length and returns

// one. Otherwise, it returns zero.

//

// This function may be used with |ASN1_STRING_get0_data| to interpret |str| as

// a byte string.

OPENSSL_EXPORT int ASN1_BIT_STRING_num_bytes(const ASN1_BIT_STRING *str,

                                             size_t *out);

// ASN1_BIT_STRING_set calls |ASN1_STRING_set|. It leaves flags unchanged, so

// the caller must set the number of unused bits.

//

// TODO(davidben): Maybe it should? Wrapping a byte string in a bit string is a

// common use case.

OPENSSL_EXPORT int ASN1_BIT_STRING_set(ASN1_BIT_STRING *str,

                                       const unsigned char *d,

                                       ossl_ssize_t length);

// ASN1_BIT_STRING_set_bit sets bit |n| of |str| to one if |value| is non-zero

// and zero if |value| is zero, resizing |str| as needed. It then truncates

// trailing zeros in |str| to align with the DER represention for a bit string

// with named bits. It returns one on success and zero on error. |n| is indexed

// beginning from zero.

OPENSSL_EXPORT int ASN1_BIT_STRING_set_bit(ASN1_BIT_STRING *str, int n,

                                           int value);

// ASN1_BIT_STRING_get_bit returns one if bit |n| of |a| is in bounds and set,

// and zero otherwise. |n| is indexed beginning from zero.

OPENSSL_EXPORT int ASN1_BIT_STRING_get_bit(const ASN1_BIT_STRING *str, int n);

// ASN1_BIT_STRING_check returns one if |str| only contains bits that are set in

// the |flags_len| bytes pointed by |flags|. Otherwise it returns zero. Bits in

// |flags| are arranged according to the DER representation, so bit 0

// corresponds to the MSB of |flags[0]|.

OPENSSL_EXPORT int ASN1_BIT_STRING_check(const ASN1_BIT_STRING *str,

                                         const unsigned char *flags,

                                         int flags_len);

// Integers and enumerated values.

//

// INTEGER and ENUMERATED values are represented as |ASN1_STRING|s where the

// data contains the big-endian encoding of the absolute value of the integer.

// The sign bit is encoded in the type: non-negative values have a type of

// |V_ASN1_INTEGER| or |V_ASN1_ENUMERATED|, while negative values have a type of

// |V_ASN1_NEG_INTEGER| or |V_ASN1_NEG_ENUMERATED|. Note this differs from DER's

// two's complement representation.

//

// The data in the |ASN1_STRING| may not have leading zeros. Note this means

// zero is represented as the empty string. Parsing functions will never return

// invalid representations. If an invalid input is constructed, the marshaling

// functions will skip leading zeros, however other functions, such as

// |ASN1_INTEGER_cmp| or |ASN1_INTEGER_get|, may not return the correct result.

DEFINE_STACK_OF(ASN1_INTEGER)

// ASN1_INTEGER_new calls |ASN1_STRING_type_new| with |V_ASN1_INTEGER|. The

// resulting object has value zero.

OPENSSL_EXPORT ASN1_INTEGER *ASN1_INTEGER_new(void);

// ASN1_INTEGER_free calls |ASN1_STRING_free|.

OPENSSL_EXPORT void ASN1_INTEGER_free(ASN1_INTEGER *str);

// ASN1_INTEGER_dup calls |ASN1_STRING_dup|.

OPENSSL_EXPORT ASN1_INTEGER *ASN1_INTEGER_dup(const ASN1_INTEGER *x);

// d2i_ASN1_INTEGER parses up to |len| bytes from |*inp| as a DER-encoded

// ASN.1 INTEGER, as described in |d2i_SAMPLE|.

OPENSSL_EXPORT ASN1_INTEGER *d2i_ASN1_INTEGER(ASN1_INTEGER **out,

                                              const uint8_t **inp, long len);

// i2d_ASN1_INTEGER marshals |in| as a DER-encoded ASN.1 INTEGER, as

// described in |i2d_SAMPLE|.

OPENSSL_EXPORT int i2d_ASN1_INTEGER(const ASN1_INTEGER *in, uint8_t **outp);

// c2i_ASN1_INTEGER decodes |len| bytes from |*inp| as the contents of a

// DER-encoded INTEGER, excluding the tag and length. It behaves like

// |d2i_SAMPLE| except, on success, it always consumes all |len| bytes.

OPENSSL_EXPORT ASN1_INTEGER *c2i_ASN1_INTEGER(ASN1_INTEGER **in,

                                              const uint8_t **outp, long len);

// i2c_ASN1_INTEGER encodes |in| as the contents of a DER-encoded INTEGER,

// excluding the tag and length. If |outp| is non-NULL, it writes the result to

// |*outp|, advances |*outp| just past the output, and returns the number of

// bytes written. |*outp| must have space available for the result. If |outp| is

// NULL, it returns the number of bytes without writing anything. On error, it

// returns a value <= 0.

//

// Note this function differs slightly from |i2d_SAMPLE|. If |outp| is non-NULL

// and |*outp| is NULL, it does not allocate a new buffer.

//

// TODO(davidben): This function currently returns zero on error instead of -1,

// but it is also mostly infallible. I've currently documented <= 0 to suggest

// callers work with both.

OPENSSL_EXPORT int i2c_ASN1_INTEGER(const ASN1_INTEGER *in, uint8_t **outp);

// ASN1_INTEGER is an |ASN1_ITEM| with ASN.1 type INTEGER and C type

// |ASN1_INTEGER*|.

DECLARE_ASN1_ITEM(ASN1_INTEGER)

// ASN1_INTEGER_set_uint64 sets |a| to an INTEGER with value |v|. It returns one

// on success and zero on error.

OPENSSL_EXPORT int ASN1_INTEGER_set_uint64(ASN1_INTEGER *out, uint64_t v);

// ASN1_INTEGER_set_int64 sets |a| to an INTEGER with value |v|. It returns one

// on success and zero on error.

OPENSSL_EXPORT int ASN1_INTEGER_set_int64(ASN1_INTEGER *out, int64_t v);

// ASN1_INTEGER_get_uint64 converts |a| to a |uint64_t|. On success, it returns

// one and sets |*out| to the result. If |a| did not fit or has the wrong type,

// it returns zero.

OPENSSL_EXPORT int ASN1_INTEGER_get_uint64(uint64_t *out,

                                           const ASN1_INTEGER *a);

// ASN1_INTEGER_get_int64 converts |a| to a |int64_t|. On success, it returns

// one and sets |*out| to the result. If |a| did not fit or has the wrong type,

// it returns zero.

OPENSSL_EXPORT int ASN1_INTEGER_get_int64(int64_t *out, const ASN1_INTEGER *a);

// BN_to_ASN1_INTEGER sets |ai| to an INTEGER with value |bn| and returns |ai|

// on success or NULL or error. If |ai| is NULL, it returns a newly-allocated

// |ASN1_INTEGER| on success instead, which the caller must release with

// |ASN1_INTEGER_free|.

OPENSSL_EXPORT ASN1_INTEGER *BN_to_ASN1_INTEGER(const BIGNUM *bn,

                                                ASN1_INTEGER *ai);

// ASN1_INTEGER_to_BN sets |bn| to the value of |ai| and returns |bn| on success

// or NULL or error. If |bn| is NULL, it returns a newly-allocated |BIGNUM| on

// success instead, which the caller must release with |BN_free|.

OPENSSL_EXPORT BIGNUM *ASN1_INTEGER_to_BN(const ASN1_INTEGER *ai, BIGNUM *bn);

// ASN1_INTEGER_cmp compares the values of |x| and |y|. It returns an integer

// equal to, less than, or greater than zero if |x| is equal to, less than, or

// greater than |y|, respectively.

OPENSSL_EXPORT int ASN1_INTEGER_cmp(const ASN1_INTEGER *x,

                                    const ASN1_INTEGER *y);

// ASN1_ENUMERATED_new calls |ASN1_STRING_type_new| with |V_ASN1_ENUMERATED|.

// The resulting object has value zero.

OPENSSL_EXPORT ASN1_ENUMERATED *ASN1_ENUMERATED_new(void);

// ASN1_ENUMERATED_free calls |ASN1_STRING_free|.

OPENSSL_EXPORT void ASN1_ENUMERATED_free(ASN1_ENUMERATED *str);

// d2i_ASN1_ENUMERATED parses up to |len| bytes from |*inp| as a DER-encoded

// ASN.1 ENUMERATED, as described in |d2i_SAMPLE|.

OPENSSL_EXPORT ASN1_ENUMERATED *d2i_ASN1_ENUMERATED(ASN1_ENUMERATED **out,

                                                    const uint8_t **inp,

                                                    long len);

// i2d_ASN1_ENUMERATED marshals |in| as a DER-encoded ASN.1 ENUMERATED, as

// described in |i2d_SAMPLE|.

OPENSSL_EXPORT int i2d_ASN1_ENUMERATED(const ASN1_ENUMERATED *in,

                                       uint8_t **outp);

// ASN1_ENUMERATED is an |ASN1_ITEM| with ASN.1 type ENUMERATED and C type

// |ASN1_ENUMERATED*|.

DECLARE_ASN1_ITEM(ASN1_ENUMERATED)

// ASN1_ENUMERATED_set_uint64 sets |a| to an ENUMERATED with value |v|. It

// returns one on success and zero on error.

OPENSSL_EXPORT int ASN1_ENUMERATED_set_uint64(ASN1_ENUMERATED *out, uint64_t v);

// ASN1_ENUMERATED_set_int64 sets |a| to an ENUMERATED with value |v|. It

// returns one on success and zero on error.

OPENSSL_EXPORT int ASN1_ENUMERATED_set_int64(ASN1_ENUMERATED *out, int64_t v);

// ASN1_ENUMERATED_get_uint64 converts |a| to a |uint64_t|. On success, it

// returns one and sets |*out| to the result. If |a| did not fit or has the

// wrong type, it returns zero.

OPENSSL_EXPORT int ASN1_ENUMERATED_get_uint64(uint64_t *out,

                                              const ASN1_ENUMERATED *a);

// ASN1_ENUMERATED_get_int64 converts |a| to a |int64_t|. On success, it

// returns one and sets |*out| to the result. If |a| did not fit or has the

// wrong type, it returns zero.

OPENSSL_EXPORT int ASN1_ENUMERATED_get_int64(int64_t *out,

                                             const ASN1_ENUMERATED *a);

// BN_to_ASN1_ENUMERATED sets |ai| to an ENUMERATED with value |bn| and returns

// |ai| on success or NULL or error. If |ai| is NULL, it returns a

// newly-allocated |ASN1_ENUMERATED| on success instead, which the caller must

// release with |ASN1_ENUMERATED_free|.

OPENSSL_EXPORT ASN1_ENUMERATED *BN_to_ASN1_ENUMERATED(const BIGNUM *bn,

                                                      ASN1_ENUMERATED *ai);

// ASN1_ENUMERATED_to_BN sets |bn| to the value of |ai| and returns |bn| on

// success or NULL or error. If |bn| is NULL, it returns a newly-allocated

// |BIGNUM| on success instead, which the caller must release with |BN_free|.

OPENSSL_EXPORT BIGNUM *ASN1_ENUMERATED_to_BN(const ASN1_ENUMERATED *ai,

                                             BIGNUM *bn);

// Time.

//

// GeneralizedTime and UTCTime values are represented as |ASN1_STRING|s. The

// type field is |V_ASN1_GENERALIZEDTIME| or |V_ASN1_UTCTIME|, respectively. The

// data field contains the DER encoding of the value. For example, the UNIX

// epoch would be "19700101000000Z" for a GeneralizedTime and "700101000000Z"

// for a UTCTime.

//

// ASN.1 does not define how to interpret UTCTime's two-digit year. RFC 5280

// defines it as a range from 1950 to 2049 for X.509. The library uses the

// RFC 5280 interpretation. It does not currently enforce the restrictions from

// BER, and the additional restrictions from RFC 5280, but future versions may.

// Callers should not rely on fractional seconds and non-UTC time zones.

//

// The |ASN1_TIME| typedef is a multi-string representing the X.509 Time type,

// which is a CHOICE of GeneralizedTime and UTCTime, using UTCTime when the