lib/libcrypto/man/d2i_ASN1_OBJECT.3

   1 .\"     $OpenBSD: d2i_ASN1_OBJECT.3,v 1.7 2018/03/20 18:35:13 schwarze Exp $
   2 .\"     OpenSSL 05ea606a May 20 20:52:46 2016 -0400
   3 .\"
   4 .\" Copyright (c) 2017 Ingo Schwarze <schwarze@openbsd.org>
   5 .\"
   6 .\" Permission to use, copy, modify, and distribute this software for any
   7 .\" purpose with or without fee is hereby granted, provided that the above
   8 .\" copyright notice and this permission notice appear in all copies.
   9 .\"
  10 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  11 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  12 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  13 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  14 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  15 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  16 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  17 .\"
  18 .Dd $Mdocdate: March 20 2018 $
  19 .Dt D2I_ASN1_OBJECT 3
  20 .Os
  21 .Sh NAME
  22 .Nm d2i_ASN1_OBJECT ,
  23 .Nm i2d_ASN1_OBJECT
  24 .Nd decode and encode ASN.1 object identifiers
  25 .Sh SYNOPSIS
  26 .In openssl/asn1.h
  27 .Ft ASN1_OBJECT *
  28 .Fo d2i_ASN1_OBJECT
  29 .Fa "ASN1_OBJECT **val_out"
  30 .Fa "unsigned char **der_in"
  31 .Fa "long length"
  32 .Fc
  33 .Ft int
  34 .Fo i2d_ASN1_OBJECT
  35 .Fa "ASN1_OBJECT *val_in"
  36 .Fa "unsigned char **der_out"
  37 .Fc
  38 .Sh DESCRIPTION
  39 These functions decode and encode ASN.1 object identifiers.
  40 For details about the semantics, examples, caveats, and bugs, see
  41 .Xr ASN1_item_d2i 3 .
  42 .Pp
  43 The objects returned from
  44 .Fn d2i_ASN1_OBJECT
  45 and the data contained in them are always marked as dynamically
  46 allocated, so when they are no longer needed,
  47 .Xr ASN1_OBJECT_free 3
  48 can be called on them.
  49 .Pp
  50 If reusing an existing object is attempted but the
  51 .Pf * Fa val_out
  52 passed in points to an object that is not marked as dynamically
  53 allocated, then the existing object is left untouched and
  54 .Fn d2i_ASN1_OBJECT
  55 behaves as if
  56 .Pf * Fa val_out
  57 would have been
  58 .Dv NULL :
  59 A new object is allocated and a pointer to it is both stored in
  60 .Pf * Fa val_out
  61 and returned.
  62 .Sh RETURN VALUES
  63 .Fn d2i_ASN1_OBJECT
  64 returns an
  65 .Vt ASN1_OBJECT
  66 object or
  67 .Dv NULL
  68 if an error occurs.
  69 .Pp
  70 .Fn i2d_ASN1_OBJECT
  71 returns the number of bytes successfully encoded
  72 or a value <= 0 if an error occurs.
  73 .Sh SEE ALSO
  74 .Xr ASN1_item_d2i 3 ,
  75 .Xr ASN1_OBJECT_new 3 ,
  76 .Xr OBJ_nid2obj 3
  77 .Sh HISTORY
  78 .Fn d2i_ASN1_OBJECT
  79 and
  80 .Fn i2d_ASN1_OBJECT
  81 appeared in SSLeay 0.8.1b or earlier and have been available since
  82 .Ox 2.4 .
  83 .Sh CAVEATS
  84 .Fn d2i_ASN1_OBJECT
  85 never sets the long and short names of the object, not even if the
  86 object identifier matches one that is built into the library.
  87 To find the names of an object identifier parsed from DER or BER
  88 input, call
  89 .Xr OBJ_obj2nid 3
  90 on the returned object, and then
  91 .Xr OBJ_nid2sn 3
  92 and
  93 .Xr OBJ_nid2ln 3
  94 on the result.
  95 .Sh BUGS
  96 When reusing a dynamically allocated object that contains dynamically
  97 allocated names, the old names are not freed and the memory containing
  98 them is leaked.