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_READ 3
  8  .Os
  9  .Sh NAME
 10  .Nm libder_read ,
 11  .Nm libder_read_fd ,
 12  .Nm libder_read_file
 13  .Nd reading DER encoded streams
 14  .Sh LIBRARY
 15  .Lb libder
 16  .Sh SYNOPSIS
 17  .In libder.h
 18  .Ft struct libder_object *
 19  .Fn libder_read "struct libder_ctx *ctx" "const uint8_t *buf" "size_t *bufsz"
 20  .Ft struct libder_object *
 21  .Fn libder_read_fd "struct libder_ctx *ctx" "int fd" "size_t *readsz"
 22  .Ft struct libder_object *
 23  .Fn libder_read_file "struct libder_ctx *ctx" "FILE *fp" "size_t *readsz"
 24  .Sh DESCRIPTION
 25  The
 26  .Nm
 27  family of functions are used to parse BER/DER encoded data into an object tree
 28  that
 29  .Xr libder 3
 30  can work with.
 31  All of these functions will return an object on success and update
 32  .Fa *readsz
 33  with the number of bytes consumed, or
 34  .Dv NULL
 35  on failure.
 36  .Pp
 37  The
 38  .Fn libder_read
 39  function will read from a buffer
 40  .Fa buf
 41  of known size
 42  .Fa bufsz .
 43  It is not considered an error for
 44  .Fa buf
 45  to have contents past the first valid object encountered.
 46  The application is
 47  expected to check
 48  .Fa *bufsz
 49  upon success and determine if any residual buffer exists, and if that residual
 50  is OK.
 51  .Pp
 52  .Xr libder 3
 53  can also stream a BER encoded object with either of the
 54  .Fn libder_read_fd
 55  or
 56  .Fn libder_read_file
 57  functions from a file descriptor or
 58  .Xr stdio 3
 59  stream respectively.
 60  Both functions will try very hard not to over-read from the stream to avoid
 61  putting it in a precarious state, but bogus looking data may still cause them
 62  to consume more of the stream than intended.
 63  .Pp
 64  Note that
 65  .Fn libder_read_fd
 66  will ignore an
 67  .Ev EINTR
 68  return value from
 69  .Xr read 2
 70  by default and continue reading from the
 71  .Fa fd .
 72  If the application is signalled, it can abort the
 73  .Xr read 2
 74  operation instead with
 75  .Xr libder_abort 3 .
 76  Note that
 77  .Nm libder
 78  does not currently have other points that an abort can be signalled from, so if
 79  .Fn libder_read_fd
 80  is not specifically waiting for data from the
 81  .Va fd
 82  when a signal hits, then the operation will continue until successful with
 83  one exception.
 84  If
 85  .Xr libder_abort 3
 86  is called at any other point in the middle of
 87  .Fn libder_read_fd ,
 88  then the abort flag will not be cleared until it does receive an interrupted
 89  .Xr read 2
 90  call, or until the next call to one of the
 91  .Nm
 92  family of functions.
 93  In the future,
 94  .Nm
 95  may support resuming an aborted operation and allow cancellation at other
 96  specific points within the operation.
 97  .Sh SEE ALSO
 98  .Xr libder 3 ,
 99  .Xr libder_obj 3 ,
100  .Xr libder_type 3 ,
101  .Xr libder_write 3