1  .\"
  2  .\" SPDX-Copyright-Identifier: BSD-2-Clause
  3  .\"
  4  .\" Copyright (C) 2024 Kyle Evans <kevans@FreeBSD.org>
  5  .\"
  6  .Dd March 2, 2024
  7  .Dt LIBDER_OBJ 3
  8  .Os
  9  .Sh NAME
 10  .Nm libder_obj ,
 11  .Nm libder_obj_alloc ,
 12  .Nm libder_obj_alloc_simple ,
 13  .Nm libder_obj_free ,
 14  .Nm libder_obj_append ,
 15  .Nm libder_obj_child ,
 16  .Nm libder_obj_next ,
 17  .Nm libder_obj_type ,
 18  .Nm libder_obj_type_simple ,
 19  .Nm libder_obj_data ,
 20  .Nm libder_obj_dump
 21  .Nd inspecting and creating libder objects
 22  .Sh LIBRARY
 23  .Lb libder
 24  .Sh SYNOPSIS
 25  .In libder.h
 26  .Ft struct libder_object *
 27  .Fn libder_obj_alloc "struct libder_ctx *ctx" "struct libder_tag *type" "const uint8_t *data" "size_t datasz"
 28  .Ft struct libder_object *
 29  .Fn libder_obj_alloc_simple "struct libder_ctx *ctx" "uint8_t type" "const uint8_t *data" "size_t datasz"
 30  .Ft void
 31  .Fn libder_obj_free "struct libder_object *ctx"
 32  .Ft bool
 33  .Fn libder_obj_append "struct libder_object *parent" "struct libder_object *child"
 34  .Ft struct libder_object *
 35  .Fn libder_obj_child "const struct libder_object *obj" "size_t which"
 36  .Ft struct libder_object *
 37  .Fn libder_obj_next "const struct libder_object *obj"
 38  .Fn "DER_FOREACH_CHILD" "struct libder_obj *iter" "struct libder_obj *obj"
 39  .Fn "DER_FOREACH_CHILD_SAFE" "struct libder_obj *iter" "struct libder_obj *obj" "struct libder_obj *tmp"
 40  .Ft struct libder_tag *
 41  .Fn libder_obj_type "const struct libder_object *obj"
 42  .Ft uint8_t
 43  .Fn libder_obj_type_simple "const struct libder_object *obj"
 44  .Ft const uint8_t *
 45  .Fn libder_obj_data "const struct libder_object *obj" "size_t *sz"
 46  .Ft void
 47  .Fn libder_obj_dump "const struct libder_object *obj" "FILE *fp"
 48  .Sh DESCRIPTION
 49  The
 50  .Nm
 51  family of functions may be used by the application to create its own objects and
 52  object hierarchy, rather than reading them from an existing stream.
 53  .Pp
 54  The
 55  .Fn libder_obj_alloc
 56  and
 57  .Fn libder_obj_alloc_simple
 58  functions allocate a new object with the specified
 59  .Fa type
 60  and
 61  .Fa data .
 62  Most applications will likely prefer to use the
 63  .Dq simple
 64  variant to avoid having to manage a
 65  .Xr libder_type 3
 66  lifecycle and associated boilerplate.
 67  The base variant remains around for when
 68  .Xr libder_type 3
 69  grows the necessary API to create arbitrarily large tags.
 70  .Pp
 71  The
 72  .Fn libder_obj_append
 73  function is used to append
 74  .Fa obj
 75  to the
 76  .Fa parent
 77  object's children.
 78  For example, to add an object to a sequence.
 79  .Pp
 80  The
 81  .Fn libder_obj_child
 82  and
 83  .Fn libder_obj_next
 84  functions are used to iterate through the children of
 85  .Fa obj .
 86  The
 87  .Fa which
 88  argument to
 89  .Fn libder_obj_child
 90  specifies the index of the child requested, starting at
 91  .Dv 0 .
 92  The
 93  .Fn DER_FOREACH_CHILD
 94  and
 95  .Fn DER_FOREACH_CHILD_SAFE
 96  macros are provided for convenience.
 97  The difference between these two is that it is safe to free the iterator in the
 98  .Fn DER_FOREACH_CHILD_SAFE
 99  loop body.
100  .Pp
101  The
102  .Fn libder_obj_type
103  and
104  .Fn libder_obj_type_simple
105  functions are used to get the type information about an
106  .Fa obj .
107  As usual, the
108  .Dq simple
109  variant will return the one-byte encoding of a tag between 0 and 30.
110  If the tag is actually larger than 30, then all of the lower 5 bits will be set
111  to indicate that it's a long tag, and that the application should have used
112  .Fn libder_obj_type
113  instead.
114  .Pp
115  The
116  .Fn libder_obj_data
117  function returns a pointer to the
118  .Fa data
119  from
120  .Fa obj ,
121  and updates
122  .Fa *sz
123  with the data's size.
124  Note that the data is not copied out here, the application is responsible for
125  making its own copy of the returned buffer.
126  .Pp
127  The
128  .Fn libder_obj_dump
129  function is a debugging function that likely shouldn't be used.
130  A human readable representation of the provided
131  .Fa obj
132  will be written to the stream
133  .Fa fp .
134  .Sh SEE ALSO
135  .Xr libder 3 ,
136  .Xr libder_read 3 ,
137  .Xr libder_type 3 ,
138  .Xr libder_write 3