diff options
Diffstat (limited to 'lib/libutil/ber.3')
| -rw-r--r-- | lib/libutil/ber.3 | 454 |
1 files changed, 0 insertions, 454 deletions
diff --git a/lib/libutil/ber.3 b/lib/libutil/ber.3 deleted file mode 100644 index ad6978ec929..00000000000 --- a/lib/libutil/ber.3 +++ /dev/null @@ -1,454 +0,0 @@ -.\" $OpenBSD: ber.3,v 1.2 2019/05/12 19:29:41 rob Exp $ -.\" -.\" Copyright (c) 2007, 2012 Reyk Floeter <reyk@openbsd.org> -.\" -.\" Permission to use, copy, modify, and distribute this software for any -.\" purpose with or without fee is hereby granted, provided that the above -.\" copyright notice and this permission notice appear in all copies. -.\" -.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES -.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF -.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR -.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES -.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN -.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF -.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. -.\" -.Dd $Mdocdate: May 12 2019 $ -.Dt BER 3 -.Os -.Sh NAME -.Nm ber_get_element , -.Nm ber_set_header , -.Nm ber_link_elements , -.Nm ber_unlink_elements , -.Nm ber_replace_elements , -.Nm ber_add_sequence , -.Nm ber_add_set , -.Nm ber_add_enumerated , -.Nm ber_add_integer , -.Nm ber_get_integer , -.Nm ber_get_enumerated , -.Nm ber_add_boolean , -.Nm ber_get_boolean , -.Nm ber_add_string , -.Nm ber_add_nstring , -.Nm ber_add_ostring , -.Nm ber_add_bitstring , -.Nm ber_get_string , -.Nm ber_get_nstring , -.Nm ber_get_ostring , -.Nm ber_get_bitstring , -.Nm ber_add_null , -.Nm ber_get_null , -.Nm ber_add_eoc , -.Nm ber_get_eoc , -.Nm ber_add_oid , -.Nm ber_add_noid , -.Nm ber_add_oidstring , -.Nm ber_get_oid , -.Nm ber_oid2ber , -.Nm ber_string2oid , -.Nm ber_oid_cmp , -.Nm ber_printf_elements , -.Nm ber_scanf_elements , -.Nm ber_get_writebuf , -.Nm ber_write_elements , -.Nm ber_set_readbuf , -.Nm ber_read_elements , -.Nm ber_getpos , -.Nm ber_free_element , -.Nm ber_free_elements , -.Nm ber_calc_len , -.Nm ber_set_application , -.Nm ber_set_writecallback , -.Nm ber_free -.Nd encode and decode ASN.1 with Basic Encoding Rules -.Sh SYNOPSIS -.In sys/types.h -.In ber.h -.Ft "struct ber_element *" -.Fn "ber_get_element" "unsigned int encoding" -.Ft "void" -.Fn "ber_set_header" "struct ber_element *elm" "int class" "unsigned int type" -.Ft "void" -.Fn "ber_link_elements" "struct ber_element *prev" "struct ber_element *elm" -.Ft "struct ber_element *" -.Fn "ber_unlink_elements" "struct ber_element *prev" -.Ft "void" -.Fn "ber_replace_elements" "struct ber_element *prev" "struct ber_element *elm" -.Ft "struct ber_element *" -.Fn "ber_add_sequence" "struct ber_element *prev" -.Ft "struct ber_element *" -.Fn "ber_add_set" "struct ber_element *prev" -.Ft "struct ber_element *" -.Fn "ber_add_integer" "struct ber_element *prev" "long long val" -.Ft "int" -.Fn "ber_get_integer" "struct ber_element *root" "long long *val" -.Ft "struct ber_element *" -.Fn "ber_add_enumerated" "struct ber_element *prev" "long long val" -.Ft "int" -.Fn "ber_get_enumerated" "struct ber_element *root" "long long *val" -.Ft "struct ber_element *" -.Fn "ber_add_boolean" "struct ber_element *prev" "int bool" -.Ft "int" -.Fn "ber_get_boolean" "struct ber_element *root" "int *bool" -.Ft "struct ber_element *" -.Fn "ber_add_string" "struct ber_element *prev" "const char *string" -.Ft "struct ber_element *" -.Fn "ber_add_nstring" "struct ber_element *prev" "const char *string" "size_t size" -.Ft "struct ber_element *" -.Fo "ber_add_ostring" -.Fa "struct ber_element *prev" -.Fa "struct ber_octetstring *ostring" -.Fc -.Ft "int" -.Fn "ber_get_string" "struct ber_element *root" "char **charbuf" -.Ft "int" -.Fn "ber_get_nstring" "struct ber_element *root" "void **buf" "size_t *size" -.Ft "int" -.Fn "ber_get_ostring" "struct ber_element *root" "struct ber_octetstring *ostring" -.Ft "struct ber_element *" -.Fo "ber_add_bitstring" -.Fa "struct ber_element *prev" -.Fa "const void *buf" -.Fa "size_t size" -.Fc -.Ft "int" -.Fn "ber_get_bitstring" "struct ber_element *root" "void **buf" "size_t *size" -.Ft "struct ber_element *" -.Fn "ber_add_null" "struct ber_element *prev" -.Ft "int" -.Fn "ber_get_null" "struct ber_element *root" -.Ft "struct ber_element *" -.Fn "ber_add_eoc" "struct ber_element *prev" -.Ft "int" -.Fn "ber_get_eoc" "struct ber_element *root" -.Ft "struct ber_element *" -.Fn "ber_add_oid" "struct ber_element *prev" "struct ber_oid *oid" -.Ft "struct ber_element *" -.Fn "ber_add_noid" "struct ber_element *prev" "struct ber_oid *oid" "int n" -.Ft "struct ber_element *" -.Fn "ber_add_oidstring" "struct ber_element *prev" "const char *string" -.Ft "int" -.Fn "ber_get_oid" "struct ber_element *root" "struct ber_oid *oid" -.Ft "size_t" -.Fn "ber_oid2ber" "struct ber_oid *oid" "u_int8_t *buf" "size_t size" -.Ft "int" -.Fn "ber_string2oid" "const char *string" "struct ber_oid *oid" -.Ft "int" -.Fn "ber_oid_cmp" "struct ber_oid *oid" "struct ber_oid *oid" -.Ft "struct ber_element *" -.Fn "ber_printf_elements" "struct ber_element *prev" "char *format" "..." -.Ft "int" -.Fn "ber_scanf_elements" "struct ber_element *root" "char *format" "..." -.Ft "ssize_t" -.Fn "ber_get_writebuf" "struct ber *ber" "void **buf" -.Ft "ssize_t" -.Fn "ber_write_elements" "struct ber *ber" "struct ber_element *root" -.Ft "void" -.Fn "ber_set_readbuf" "struct ber *ber" "void *buf" "size_t len" -.Ft "struct ber_element *" -.Fn "ber_read_elements" "struct ber *ber" "struct ber_element *root" -.Ft off_t -.Fn "ber_getpos" "struct ber_element *elm" -.Ft "void" -.Fn "ber_free_element" "struct ber_element *root" -.Ft "void" -.Fn "ber_free_elements" "struct ber_element *root" -.Ft "size_t" -.Fn "ber_calc_len" "struct ber_element *root" -.Ft "void" -.Fo "ber_set_application" -.Fa "struct ber *ber" -.Fa "unsigned int (*cb)(struct ber_element *)" -.Fc -.Ft "void" -.Fo "ber_set_writecallback" -.Fa "struct ber_element *elm" -.Fa "void (*cb)(void *arg, size_t offs)" -.Fa "void *arg" -.Fc -.Ft "void" -.Fn "ber_free" "struct ber *ber" -.Sh DESCRIPTION -The -.Nm ber -API provides a mechanism to read and write ASN.1 streams and buffers using the -Basic Encoding Rules. -.Pp -Encoded -.Nm ber -is stored in the following structure: -.Bd -literal -struct ber { - off_t br_offs; - u_char *br_wbuf; - u_char *br_wptr; - u_char *br_wend; - u_char *br_rbuf; - u_char *br_rptr; - u_char *br_rend; - - unsigned int (*br_application)(struct ber_element *); -}; -.Ed -.Pp -.Fa br_rbuf -and -.Fa br_wbuf -are the read and write buffers for a -.Nm ber -stream. -These buffers are used when reading an existing byte stream (e.g. received from -a TLS connection), or when writing a new byte stream in preparation for -subsequent operations performed by the calling application (e.g. network -transmission or export to a file). -.Pp -Intermediary storage of ber elements during decoding and encoding uses the -following structure: -.Bd -literal -struct ber_element { - struct ber_element *be_next; - unsigned int be_type; - unsigned int be_encoding; - size_t be_len; - off_t be_offs; - int be_free; - u_int8_t be_class; - void (*be_cb)(void *, size_t); - void *be_cbarg; - union { - struct ber_element *bv_sub; - void *bv_val; - long long bv_numeric; - } be_union; -#define be_sub be_union.bv_sub -#define be_val be_union.bv_val -#define be_numeric be_union.bv_numeric -}; -.Ed -.Pp -A linked list containing one or more -.Vt ber_element -is created during the decoding and encoding of -.Vt ber . -.Pp -Once the -.Vt ber -and -.Vt ber_element -data structures have been declared, -.Fn ber_set_readbuf -may be called to initialize -.Fa br_rbuf -in preparation for decoding. -It is assumed that a pointer to a ber byte stream is already available to the -application, commonly obtained by -.Xr read 2 , -.Xr recv 2 , -or -.Xr tls_read 3 . -.Fn ber_read_elements -may then be called to parse, validate, and store the data stream into its -consituent parts for subsequent processing. -.Fn ber_read_elements -returns a pointer to a fully populated list of one or more -.Vt ber_element , -or -.Dv NULL -on a type mismatch or read error. -.Pp -The calling application must have explicit knowledge of the expected data -types in order for correct decoding. -.Fn ber_scanf_elements -may be called to extract -.Vt ber_element -content into local variables. -The -.Fn ber_get_* -functions extract the value of a single -.Vt ber_element -instance. -.Fn ber_scanf_elements -and the -.Fn ber_get_* -functions return 0 on success and -1 on failure. -.Pp -The first step when creating new ber is to populate -.Vt ber_element -with the desired content. -This may be achieved using the -.Fn ber_add_* -and -.Fn ber_printf_elements -functions, each of which return a pointer to -.Vt ber_element -on success or -.Dv NULL -on failure. -.Pp -Once -.Vt ber_element -has been fully populated, -.Fn ber_get_writebuf -may be used to initialize -.Fa br_wbuf -for writing. -.Fn ber_write_elements -encodes -.Vt ber_element -into a compliant -.Nm ber -byte stream for subsequent use by the calling application, most commonly using -.Xr send 2 , -.Xr write 2 , -or -.Xr tls_write 3 . -.Sh I/O OPERATIONS -.Fn ber_get_writebuf , -.Fn ber_write_elements , -.Fn ber_set_readbuf , -.Fn ber_read_elements , -.Fn ber_getpos , -.Fn ber_free_element , -.Fn ber_free_elements , -.Fn ber_set_application , -.Fn ber_set_writecallback , -.Fn ber_free -.Sh BER ELEMENTS -.Fn ber_get_element , -.Fn ber_set_header , -.Fn ber_link_elements , -.Fn ber_unlink_elements , -.Fn ber_replace_elements , -.Fn ber_calc_len -.Sh BER TYPES -.Fn ber_add_sequence , -.Fn ber_add_set , -.Fn ber_add_integer , -.Fn ber_get_integer , -.Fn ber_add_enumerated , -.Fn ber_get_enumerated , -.Fn ber_add_boolean , -.Fn ber_get_boolean , -.Fn ber_add_string , -.Fn ber_add_nstring , -.Fn ber_add_ostring , -.Fn ber_add_bitstring , -.Fn ber_get_string , -.Fn ber_get_nstring , -.Fn ber_get_ostring , -.Fn ber_get_bitstring , -.Fn ber_add_null , -.Fn ber_get_null , -.Fn ber_add_eoc , -.Fn ber_get_eoc -.Sh FORMAT STRINGS -.Fn ber_printf_elements , -.Fn ber_scanf_elements -.Sh OBJECT IDS -Object Identifiers are commonly used in ASN.1-based protocols. -These functions provide an interface to parse OIDs. -For internal representation of OIDs, the following structure -.Vt struct ber_oid -is being used: -.Bd -literal -#define BER_MIN_OID_LEN 2 -#define BER_MAX_OID_LEN 32 - -struct ber_oid { - u_int32_t bo_id[BER_MAX_OID_LEN + 1]; - size_t bo_n; -}; -.Ed -.Pp -.Fn ber_add_oid , -.Fn ber_add_noid , -.Fn ber_add_oidstring , -.Fn ber_get_oid , -.Fn ber_oid2ber , -.Fn ber_string2oid -.Fn ber_oid_cmp , -.Sh RETURN VALUES -Upon successful completion -.Fn ber_get_integer , -.Fn ber_get_enumerated , -.Fn ber_get_boolean , -.Fn ber_get_string , -.Fn ber_get_nstring , -.Fn ber_get_ostring , -.Fn ber_get_bitstring , -.Fn ber_get_null , -.Fn ber_get_eoc , -.Fn ber_get_oid , -.Fn ber_string2oid -and -.Fn ber_scanf_elements -return 0, while -.Fn ber_write_elements -returns the number of bytes written. -Otherwise, \-1 is returned and the global variable errno is -set to indicate the error. -.Sh SEE ALSO -.Xr read 2 , -.Xr recv 2 , -.Xr send 2 , -.Xr write 2 , -.Xr tls_read 3 -.Sh STANDARDS -ITU-T Recommendation X.690, also known as ISO/IEC 8825-1: -Information technology - ASN.1 encoding rules. -.Sh HISTORY -The -.Nm ber -manpage first appeared in -.Ox 4.3 . -.Sh AUTHORS -.An -nosplit -The -.Nm ber -library was written by -.An Claudio Jeker Aq Mt claudio@openbsd.org , -.An Marc Balmer Aq Mt marc@openbsd.org -and -.An Reyk Floeter Aq Mt reyk@openbsd.org . -.Sh CAVEATS -The -.Nm ber -API is subject to the following restrictions which are common to the -Distinguished Encoding Rules as defined by X.690: -.Pp -.Bl -enum -compact -.It -Only the definite form of length encoding shall be used, encoded in the -minimum number of octets. -.It -For bitstring, octetstring and restricted character string types, the -constructed form of encoding shall not be used. -.It -If a boolean encoding represents the boolean value TRUE, its single contents -octet shall have all eight bits set to one. -.It -Each unused bit in the final octet of the encoding of a bit string value shall -be set to zero. -.It -If a bitstring value has no 1 bits, then an encoder shall encode the value with -a length of 1 and an initial octet set to 0. -.El -.Pp -In addition, set and sequence values are limited to a maximum of 65535 elements. -No alternative encodings are permitted. -.Pp -.Do -Whereas the basic encoding rules give the sender of an encoding various choices -as to how data values may be encoded, the canonical and distinguished encoding -rules select just one encoding from those allowed by the basic encoding rules. -.Dc -.Bq X.690 -.Pp -The restrictions placed on this API avoid the ambiguity inherent in -.Nm ber -encoded ASN.1 thereby acting as a security mitigation. -.Sh BUGS -This manpage is a stub. |