NAME
ASN1_put_object,
ASN1_put_eoc,
ASN1_object_size —
start and end the BER encoding of an
arbitrary ASN.1 data element
SYNOPSIS
#include
<openssl/asn1.h>
void
ASN1_put_object(unsigned char
**ber_out, int constructed, int
content_length, int tag, int
class);
int
ASN1_put_eoc(unsigned char
**ber_out);
int
ASN1_object_size(int
constructed, int content_length,
int tag);
DESCRIPTION
ASN1_put_object()
begins writing the BER encoding of an arbitrary ASN.1 data element to the
buffer *ber_out by writing the identifier and the length bytes. Making sure
that there is sufficient space in the buffer is the responsibility of the
caller. This function does not write any content bytes nor any
end-of-content bytes.
The tag class can be
V_ASN1_UNIVERSAL,
V_ASN1_APPLICATION,
V_ASN1_CONTEXT_SPECIFIC, or
V_ASN1_PRIVATE and is written to the two most
significant bits of the first byte written.
The constructed argument can have the following values:
- 0
- Start a primitive value by setting the third most significant bit of the first byte written to 0. Always use the definite form.
- 1
- Start a constructed value by setting the third most significant bit of the first byte written to 1, and use the definite form.
- 2
- Start a constructed value and use the indefinite form,
If the tag is less than
V_ASN1_PRIMITIVE_TAG (= 0x1f), it is written to the
five least significant bits of the only identifier byte written. Otherwise,
these five bits are all set to 1, and the tag is
encoded in one or more following identifier bytes as needed.
After completing the identifier byte(s), when using the definite form, the given content_length is encoded in one or more bytes as needed, using the long form if and only if the content_length is greater than 127. When using the indefinite form, the special byte 0x80 is written instead and the content_length argument is ignored.
At the end, *ber_out is set to the byte following the last byte written. The calling code can then start writing content bytes.
If the indefinite form was selected, the calling
code is also responsible for calling
ASN1_put_eoc()
which writes an end-of-content marker to *ber_out,
consisting of two NUL bytes, and advances *ber_out by
two bytes.
ASN1_object_size()
calculates the total length in bytes of the BER encoding of an ASN.1 data
element with the given tag and the number of content
bytes given by content_length. The
constructed argument has the same meaning as for
ASN1_put_object(). The return value includes the
identifier, length, and content bytes. If constructed
is 2, it also includes the end-of-content bytes. For the definite form, only
the short form is supported if the content_length is
less than 128.
RETURN VALUES
ASN1_put_eoc() returns the number of bytes
written, which is always 2.
ASN1_object_size() returns the total
number of bytes in the encoding of the data element.
SEE ALSO
ASN1_item_i2d(3), ASN1_TYPE_get(3), i2d_ASN1_NULL(3), i2d_ASN1_OBJECT(3), i2d_ASN1_OCTET_STRING(3), i2d_ASN1_SEQUENCE_ANY(3)
STANDARDS
ITU-T Recommendation X.690, also known as ISO/IEC 8825-1: Information technology - ASN.1 encoding rules: Specification of Basic Encoding Rules (BER), Canonical Encoding Rules (CER) and Distinguished Encoding Rules (DER), section 8.1: General rules for encoding
HISTORY
ASN1_put_object() and
ASN1_object_size() first appeared in SSLeay 0.5.1
and have been available since OpenBSD 2.4.
ASN1_put_eoc() first appeared in OpenSSL
0.9.8 and has been available since OpenBSD 4.5.
CAVEATS
None of these functions do any sanity checking. When called in inconsistent ways, invalid content may result in *ber_out, for example
- a tag number less than
V_ASN1_PRIMITIVE_TAGwith a class other thanV_ASN1_UNIVERSAL - a tag number equal to
V_ASN1_EOC(0x00) orV_ASN1_PRIMITIVE_TAG(0x1f) - a BOOLEAN, INTEGER, NULL etc. with the constructed bit set
- a SEQUENCE or SET etc. without the constructed bit set
- a content_length that makes no sense for the given tag
- a content_length that disagrees with the following data
- a BOOLEAN, INTEGER, NULL etc. in indefinite form
- an end-of-content marker even though no indefinite form was started
- ...
If the calling code wants to find out how many bytes were written,
it needs to save a copy of the pointer *ber_out before
calling ASN1_put_object().