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 3
  8  .Os
  9  .Sh NAME
 10  .Nm libder ,
 11  .Nm libder_open ,
 12  .Nm libder_close ,
 13  .Nm libder_abort ,
 14  .Nm libder_get_error ,
 15  .Nm libder_has_error ,
 16  .Nm libder_get_normalize ,
 17  .Nm libder_set_normalize ,
 18  .Nm libder_get_strict ,
 19  .Nm libder_set_strict ,
 20  .Nm libder_get_verbose ,
 21  .Nm libder_set_verbose
 22  .Nd DER encoding and decoding library
 23  .Sh LIBRARY
 24  .Lb libder
 25  .Sh SYNOPSIS
 26  .In libder.h
 27  .Ft struct libder_ctx *
 28  .Fn libder_open "void"
 29  .Ft void
 30  .Fn libder_close "struct libder_ctx *ctx"
 31  .Ft void
 32  .Fn libder_abort "struct libder_ctx *ctx"
 33  .Ft const char *
 34  .Fn libder_get_error "struct libder_ctx *ctx"
 35  .Ft bool
 36  .Fn libder_has_error "struct libder_ctx *ctx"
 37  .Ft uint64_t
 38  .Fn libder_get_normalize "struct libder_ctx *ctx"
 39  .Ft uint64_t
 40  .Fn libder_set_normalize "struct libder_ctx *ctx" "uint64_t normalize"
 41  .Ft bool
 42  .Fn libder_get_strict "struct libder_ctx *ctx"
 43  .Ft bool
 44  .Fn libder_set_strict "struct libder_ctx *ctx" "bool strict"
 45  .Ft int
 46  .Fn libder_get_verbose "struct libder_ctx *ctx"
 47  .Ft int
 48  .Fn libder_set_verbose "struct libder_ctx *ctx" "int verbose"
 49  .Sh DESCRIPTION
 50  The
 51  .Nm
 52  library provides functionality for decoding BER and DER encoded data, and
 53  DER encoding data subjected to constraints outline in ITU-T
 54  Recommendation X.690.
 55  .Nm
 56  will apply relevant normalization rules on write, unless they've been disabled
 57  with
 58  .Ft libder_set_normalize ,
 59  under the assumption that it may not be reading strictly DER encoded data.
 60  .Pp
 61  Note that not all of the DER rules are currently implemented.
 62  .Nm
 63  will coalesce constructed types that DER specifies should be primitive.
 64  .Nm
 65  will primarily normalize bitstrings, booleans, and integers.
 66  This library was primarily written to be able to provide interoperability with
 67  OpenSSL keys and signatures, so the library was written with that in mind.
 68  Eventually it is intended that
 69  .Nm
 70  will support the full set of rules, but currently some responsibility is left
 71  to the library user.
 72  .Pp
 73  Also note that
 74  .Nm
 75  does not necessarily provide
 76  .Dq neat
 77  ways to construct primitives.
 78  For example, even booleans and integers currently work just by providing a
 79  buffer that is expected to be formatted in a sane fashion.
 80  The library user is expected to build the object tree and generally provide the
 81  object data in a format reasonably encoded as the data for that type should be,
 82  then
 83  .Nm
 84  will provide the proper framing on write and do any transformations that may
 85  need to be done for strict conformance.
 86  .Pp
 87  The
 88  .Fn libder_open
 89  function allocates a new
 90  .Nm
 91  context.
 92  The context does not hold any state about any particular structure.
 93  All of the state held in the context is generally described in this manpage.
 94  The
 95  .Fn libder_close
 96  function will free the context.
 97  .Pp
 98  The
 99  .Fn libder_abort
100  function will abort an in-progress
101  .Xr libder_read_fd 3
102  operation on the existing
103  .Fa ctx
104  if it is interrupted by a signal in the middle of a
105  .Xr read 2
106  syscall.
107  See
108  .Xr libder_read_fd 3
109  for further discussion.
110  .Pp
111  The
112  .Fn libder_get_error
113  function will return an error string appropriate for the current error, if any.
114  The
115  .Fn libder_has_error
116  function can be used to check if an error was raised in a previous operation.
117  .Pp
118  The
119  .Fn libder_get_normalize
120  and
121  .Fn libder_set_normalize
122  functions retrieve and manipulate any number of flags that detail how
123  functions may be used to check or set the normalization flags given
124  .Nm context ,
125  which dictates how
126  .Nm
127  will normalize data on write.
128  The following normalization flags may be specified:
129  .Bl -column "LIBDER_NORMALIZE_CONSTRUCTED"
130  .It LIBDER_NORMALIZE_CONSTRUCTED Ta Coalesce types that may be primitive or constructed
131  .It LIBDER_NORMALIZE_TAGS Ta Pack tags into the lowest possible encoded value
132  .El
133  .Pp
134  The
135  .Fn LIBDER_NORMALIZE_TYPE_FLAG "enum libder_ber_type"
136  macaro may also be used to specify normalization of the given universal type.
137  By default, every valid normalization flag is enabled.
138  .Pp
139  The
140  .Fn libder_get_strict
141  and
142  .Fn libder_set_strict
143  functions may used to check or set the strict read state of the given
144  .Nm
145  context.
146  By default,
147  .Nm
148  operates in strict mode and rejects various methods of expressing data that are
149  valid looking but not strictly conformant.
150  The
151  .Va LDE_STRICT_*
152  constants in
153  .In libder.h
154  describe the various scenarios that strict mode may reject.
155  .Pp
156  The
157  .Fn libder_get_verbose
158  and
159  .Fn libder_set_verbose
160  functions may be used to check or set the verbosity of the given
161  .Nm
162  context.
163  This primarily controls how
164  .Nm
165  behaves when an error is encountered.
166  By default, the library will silently set the error state and return.
167  With a verbosity level of 1, an error will be printed when the error state is
168  set that contains the string that would be returned by
169  .Fn libder_get_error .
170  With a verbosity level of 2, the filename and line within
171  .Nm
172  that the error occurred in will be printed, which is primarily intended for
173  debugging
174  .Nm .
175  .Sh SEE ALSO
176  .Xr libder_obj 3 ,
177  .Xr libder_read 3 ,
178  .Xr libder_type 3 ,
179  .Xr libder_write 3