lib/libcrypto/man/PKCS12_SAFEBAG_new.3

   1 .\"     $OpenBSD: PKCS12_SAFEBAG_new.3,v 1.2 2016/12/25 22:15:10 schwarze Exp $
   2 .\"
   3 .\" Copyright (c) 2016 Ingo Schwarze <schwarze@openbsd.org>
   4 .\"
   5 .\" Permission to use, copy, modify, and distribute this software for any
   6 .\" purpose with or without fee is hereby granted, provided that the above
   7 .\" copyright notice and this permission notice appear in all copies.
   8 .\"
   9 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  10 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  11 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  12 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  13 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  14 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  15 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  16 .\"
  17 .Dd $Mdocdate: December 25 2016 $
  18 .Dt PKCS12_SAFEBAG_NEW 3
  19 .Os
  20 .Sh NAME
  21 .Nm PKCS12_SAFEBAG_new ,
  22 .Nm PKCS12_SAFEBAG_free ,
  23 .Nm PKCS12_BAGS_new ,
  24 .Nm PKCS12_BAGS_free
  25 .Nd PKCS#12 container for one piece of information
  26 .Sh SYNOPSIS
  27 .In openssl/pkcs12.h
  28 .Ft PKCS12_SAFEBAG *
  29 .Fn PKCS12_SAFEBAG_new void
  30 .Ft void
  31 .Fn PKCS12_SAFEBAG_free "PKCS12_SAFEBAG *safebag"
  32 .Ft PKCS12_BAGS *
  33 .Fn PKCS12_BAGS_new void
  34 .Ft void
  35 .Fn PKCS12_BAGS_free "PKCS12_BAGS *bag"
  36 .Sh DESCRIPTION
  37 .Fn PKCS12_SAFEBAG_new
  38 allocates and initializes an empty
  39 .Vt PKCS12_SAFEBAG
  40 object, representing an ASN.1
  41 .Vt SafeBag
  42 structure defined in RFC 7292 section 4.2.
  43 It can hold a pointer to a
  44 .Vt PKCS12_BAGS
  45 object together with a type identifier and optional attributes.
  46 .Fn PKCS12_SAFEBAG_free
  47 frees
  48 .Fa safebag .
  49 .Pp
  50 .Fn PKCS12_BAGS_new
  51 allocates and initializes an empty
  52 .Vt PKCS12_BAGS
  53 object, representing the bagValue field of an ASN.1
  54 .Vt SafeBag
  55 structure.
  56 It is used in
  57 .Vt PKCS12_SAFEBAG
  58 and can hold a DER-encoded X.509 certificate,
  59 a base64-encoded SDSI certificate,
  60 a DER-encoded X.509 CRL,
  61 or other user-defined information.
  62 .Pp
  63 If an instance of
  64 .Vt PKCS12_SAFEBAG
  65 contains
  66 .Vt PKCS8_PRIV_KEY_INFO ,
  67 .Vt X509_SIG ,
  68 or nested
  69 .Vt PKCS12_SAFEBAG
  70 objects, the respective pointers are stored directly in the
  71 .Vt PKCS12_SAFEBAG
  72 object rather than in the contained
  73 .Vt PKCS12_BAGS
  74 object as required by RFC 7292.
  75 .Sh RETURN VALUES
  76 .Fn PKCS12_SAFEBAG_new
  77 and
  78 .Fn PKCS12_BAGS_new
  79 return the new
  80 .Vt PKCS12_SAFEBAG
  81 or
  82 .Vt PKCS12_BAGS
  83 object, respectively, or
  84 .Dv NULL
  85 if an error occurs.
  86 .Sh SEE ALSO
  87 .Xr PKCS12_new 3 ,
  88 .Xr PKCS8_PRIV_KEY_INFO_new 3 ,
  89 .Xr X509_ATTRIBUTE_new 3 ,
  90 .Xr X509_CRL_new 3 ,
  91 .Xr X509_new 3 ,
  92 .Xr X509_SIG_new 3
  93 .Sh STANDARDS
  94 RFC 7292: PKCS #12: Personal Information Exchange Syntax,
  95 section 4.2: The SafeBag Type