Sortix nightly manual
This manual documents Sortix nightly, a development build that has not been officially released. You can instead view this document in the latest official manual.
ASN1_TYPE_GET(3) | Library Functions Manual | ASN1_TYPE_GET(3) |
NAME
ASN1_TYPE_new
,
ASN1_TYPE_free
,
ASN1_TYPE_get
,
ASN1_TYPE_set
,
ASN1_TYPE_set1
,
ASN1_TYPE_set_octetstring
,
ASN1_TYPE_get_octetstring
,
ASN1_TYPE_set_int_octetstring
,
ASN1_TYPE_get_int_octetstring
,
ASN1_TYPE_cmp
—
ASN.1 objects of arbitrary type
SYNOPSIS
#include
<openssl/asn1.h>
ASN1_TYPE *
ASN1_TYPE_new
(void);
void
ASN1_TYPE_free
(ASN1_TYPE
*a);
int
ASN1_TYPE_get
(const
ASN1_TYPE *a);
void
ASN1_TYPE_set
(ASN1_TYPE
*a, int type,
void *value);
int
ASN1_TYPE_set1
(ASN1_TYPE
*a, int type,
const void *value);
int
ASN1_TYPE_set_octetstring
(ASN1_TYPE
*a, const unsigned char *data,
int len);
int
ASN1_TYPE_get_octetstring
(const
ASN1_TYPE *a, unsigned char *buffer,
int buflen);
int
ASN1_TYPE_set_int_octetstring
(ASN1_TYPE
*a, long num,
const unsigned char *data,
int len);
int
ASN1_TYPE_get_int_octetstring
(const
ASN1_TYPE *a, long *num,
unsigned char *buffer,
int buflen);
int
ASN1_TYPE_cmp
(const
ASN1_TYPE *a, const ASN1_TYPE *b);
DESCRIPTION
The ASN1_TYPE data type and theV_ASN1_ANY
type identifier constant
represent the ASN.1 ANY type. An ASN1_TYPE
object can store an ASN.1 value of arbitrary type, including constructed types
such as a SEQUENCE. It also remembers internally which type it currently
holds.
ASN1_TYPE_new
() allocates and initializes an
empty ASN1_TYPE object of undefined type.
ASN1_TYPE_free
() frees
a including the value stored in it, if any.
If a is a
NULL
pointer, no action occurs.
ASN1_TYPE_get
() returns the type currently
held by a, represented by one of the
V_ASN1_*
constants defined in
<openssl/asn1.h>
.
ASN1_TYPE_set
() frees the value contained in
a, if any, and sets the
value and
type now held in
a. This function uses the pointer
value internally so it must
not be freed up after the call.
ASN1_TYPE_set1
() sets the type held by
a to type
and its value to a copy of value. If copying
succeeds, the previous value that was contained in
a is freed. If copying fails,
a remains unchanged.
The type and meaning of the value argument of
ASN1_TYPE_set
() and
ASN1_TYPE_set1
() is determined by the
type argument. If
type is
V_ASN1_NULL
,
value is ignored. If
type is
V_ASN1_BOOLEAN
, then the boolean is set to
TRUE if value is not
NULL
. If
type is
V_ASN1_OBJECT
, then
value is an
ASN1_OBJECT structure. Otherwise
type is an
ASN1_STRING structure. If
type corresponds to a primitive type or a
string type, then the contents of the
ASN1_STRING contains the content octets of
the type. If type corresponds to a
constructed type or a tagged type
(V_ASN1_SEQUENCE
,
V_ASN1_SET
, or
V_ASN1_OTHER
), then the
ASN1_STRING contains the entire ASN.1
encoding verbatim, including tag and length octets.
ASN1_TYPE_set_octetstring
() allocates a new
ASN1_OCTET_STRING object, copies
len bytes of
data into it using
ASN1_STRING_set(3),
and replaces the value of a with it by
calling ASN1_TYPE_set
() with a type of
V_ASN1_OCTET_STRING
.
ASN1_TYPE_get_octetstring
() copies the
contents of the ASN1_OCTET_STRING object
contained in a, but not more than
buflen bytes, into the
buffer provided by the caller.
ASN1_TYPE_set_int_octetstring
() frees the
value contained in a, if any, sets its type
to V_ASN1_SEQUENCE
, and sets its value to a
two-element ASN.1 sequence consisting of an ASN.1 INTEGER object with the
value num and an ASN.1 OCTET STRING object
containing a copy of the len bytes pointed to
by data.
ASN1_TYPE_get_int_octetstring
() copies the
integer value from the first element of the ASN.1 sequence
a to *num
unless num is a
NULL
pointer and copies the octet string
value from the second element, but not more than
buflen bytes, into the
buffer provided by the caller unless
buffer is a
NULL
pointer.
ASN1_TYPE_cmp
() checks that
a and b hold
the same type, the same value, and are encoded in the same way.
If the types agree and the values have the same meaning but are encoded
differently, they are considered different. For example, a boolean value is
represented using a single content octet. Under BER, any non-zero octet
represents the TRUE value, but
ASN1_TYPE_cmp
() will only report a match if
the content octet is the same.
If either or both of the arguments passed to
ASN1_TYPE_cmp
() is
NULL
, the result is a mismatch.
Technically, if both arguments are NULL
,
the two types could be absent OPTIONAL fields and so should match, however
passing NULL
values could also indicate a
programming error (for example an unparsable type which returns
NULL
) for types which do
not match. So applications should handle the case
of two absent values separately.
RETURN VALUES
ASN1_TYPE_new
() returns the new
ASN1_TYPE object or
NULL
if an error occurs.
ASN1_TYPE_get
() returns the type currently
held by a or 0 if an error occurs. The latter
can happen if a does not contain a value even
though its type is not V_ASN1_NULL
. For
example, it will always happen for empty objects newly constructed with
ASN1_TYPE_new
().
ASN1_TYPE_set1
(),
ASN1_TYPE_set_octetstring
(), and
ASN1_TYPE_set_int_octetstring
() return 1 on
success or 0 on failure.
ASN1_TYPE_get_octetstring
() returns the
number of data bytes contained in the
ASN1_OCTET_STRING object contained in
a or -1 if a
is not of the type V_ASN1_OCTET_STRING
or
does not contain any object. If the return value is greater than the
buflen argument, the content was truncated
when copied to the buffer.
ASN1_TYPE_get_int_octetstring
() returns the
number of data bytes contained in the
ASN1_OCTET_STRING object that is the second
element of the ASN.1 sequence a or -1 if
a is not of the type
V_ASN1_SEQUENCE
or if decoding fails. If
the return value is greater than the buflen
argument, the content was truncated when copied to the
buffer.
ASN1_TYPE_cmp
() returns 0 for a match or
non-zero for a mismatch.
SEE ALSO
ASN1_generate_nconf(3), ASN1_get_object(3), ASN1_item_free(3), ASN1_OBJECT_new(3), ASN1_parse_dump(3), ASN1_put_object(3), ASN1_STRING_dup(3), ASN1_STRING_new(3), crypto(3), d2i_ASN1_NULL(3), d2i_ASN1_SEQUENCE_ANY(3), d2i_ASN1_TYPE(3), OBJ_dup(3)HISTORY
ASN1_TYPE_new
() and
ASN1_TYPE_free
() first appeared in SSLeay
0.5.1, ASN1_TYPE_get
() and
ASN1_TYPE_set
() in SSLeay 0.8.0, and
ASN1_TYPE_set_octetstring
(),
ASN1_TYPE_get_octetstring
(),
ASN1_TYPE_set_int_octetstring
(), and
ASN1_TYPE_get_int_octetstring
() in SSLeay
0.9.0. These functions have been available since OpenBSD
2.4.
ASN1_TYPE_set1
() first appeared in OpenSSL
0.9.8h and has been available since OpenBSD 4.5.
ASN1_TYPE_cmp
() first appeared in OpenSSL
0.9.8zd, 1.0.0p, and 1.0.1k and has been available since
OpenBSD 4.9.January 12, 2022 | Debian |