lib/libcrypto/man/d2i_PKCS12.3

   1 .\"     $OpenBSD: d2i_PKCS12.3,v 1.2 2018/03/21 17:57:48 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: March 21 2018 $
  18 .Dt D2I_PKCS12 3
  19 .Os
  20 .Sh NAME
  21 .Nm d2i_PKCS12 ,
  22 .Nm i2d_PKCS12 ,
  23 .Nm d2i_PKCS12_bio ,
  24 .Nm i2d_PKCS12_bio ,
  25 .Nm d2i_PKCS12_fp ,
  26 .Nm i2d_PKCS12_fp ,
  27 .Nm d2i_PKCS12_MAC_DATA ,
  28 .Nm i2d_PKCS12_MAC_DATA ,
  29 .Nm d2i_PKCS12_SAFEBAG ,
  30 .Nm i2d_PKCS12_SAFEBAG ,
  31 .Nm d2i_PKCS12_BAGS ,
  32 .Nm i2d_PKCS12_BAGS
  33 .Nd decode and encode PKCS#12 structures
  34 .Sh SYNOPSIS
  35 .In openssl/pkcs12.h
  36 .Ft PKCS12 *
  37 .Fo d2i_PKCS12
  38 .Fa "PKCS12 **val_out"
  39 .Fa "const unsigned char **der_in"
  40 .Fa "long length"
  41 .Fc
  42 .Ft int
  43 .Fo i2d_PKCS12
  44 .Fa "PKCS12 *val_in"
  45 .Fa "unsigned char **der_out"
  46 .Fc
  47 .Ft PKCS12 *
  48 .Fo d2i_PKCS12_bio
  49 .Fa "BIO *in_bio"
  50 .Fa "PKCS12 **val_out"
  51 .Fc
  52 .Ft int
  53 .Fo i2d_PKCS12_bio
  54 .Fa "BIO *out_bio"
  55 .Fa "PKCS12 *val_in"
  56 .Fc
  57 .Ft PKCS12 *
  58 .Fo d2i_PKCS12_fp
  59 .Fa "FILE *in_fp"
  60 .Fa "PKCS12 **val_out"
  61 .Fc
  62 .Ft int
  63 .Fo i2d_PKCS12_fp
  64 .Fa "FILE *out_fp"
  65 .Fa "PKCS12 *val_in"
  66 .Fc
  67 .Ft PKCS12_MAC_DATA *
  68 .Fo d2i_PKCS12_MAC_DATA
  69 .Fa "PKCS12_MAC_DATA **val_out"
  70 .Fa "const unsigned char **der_in"
  71 .Fa "long length"
  72 .Fc
  73 .Ft int
  74 .Fo i2d_PKCS12_MAC_DATA
  75 .Fa "PKCS12_MAC_DATA *val_in"
  76 .Fa "unsigned char **der_out"
  77 .Fc
  78 .Ft PKCS12_SAFEBAG *
  79 .Fo d2i_PKCS12_SAFEBAG
  80 .Fa "PKCS12_SAFEBAG **val_out"
  81 .Fa "const unsigned char **der_in"
  82 .Fa "long length"
  83 .Fc
  84 .Ft int
  85 .Fo i2d_PKCS12_SAFEBAG
  86 .Fa "PKCS12_SAFEBAG *val_in"
  87 .Fa "unsigned char **der_out"
  88 .Fc
  89 .Ft PKCS12_BAGS *
  90 .Fo d2i_PKCS12_BAGS
  91 .Fa "PKCS12_BAGS **val_out"
  92 .Fa "const unsigned char **der_in"
  93 .Fa "long length"
  94 .Fc
  95 .Ft int
  96 .Fo i2d_PKCS12_BAGS
  97 .Fa "PKCS12_BAGS *val_in"
  98 .Fa "unsigned char **der_out"
  99 .Fc
 100 .Sh DESCRIPTION
 101 These functions decode and encode PKCS#12 structures.
 102 For details about the semantics, examples, caveats, and bugs, see
 103 .Xr ASN1_item_d2i 3 .
 104 .Pp
 105 .Fn d2i_PKCS12
 106 and
 107 .Fn i2d_PKCS12
 108 decode and encode an ASN.1
 109 .Vt PFX
 110 .Pq personal information exchange
 111 structure defined in RFC 7292 section 4.
 112 .Fn d2i_PKCS12_bio ,
 113 .Fn i2d_PKCS12_bio ,
 114 .Fn d2i_PKCS12_fp ,
 115 and
 116 .Fn i2d_PKCS12_fp
 117 are similar except that they decode or encode using a
 118 .Vt BIO
 119 or
 120 .Vt FILE
 121 pointer.
 122 .Pp
 123 .Fn d2i_PKCS12_MAC_DATA
 124 and
 125 .Fn i2d_PKCS12_MAC_DATA
 126 decode and encode an ASN.1
 127 .Vt MacData
 128 structure defined in RFC 7292 section 4.
 129 .Pp
 130 .Fn d2i_PKCS12_SAFEBAG
 131 and
 132 .Fn i2d_PKCS12_SAFEBAG
 133 decode and encode an ASN.1
 134 .Vt SafeBag
 135 structure defined in RFC 7292 section 4.2.
 136 .Pp
 137 .Fn d2i_PKCS12_BAGS
 138 and
 139 .Fn i2d_PKCS12_BAGS
 140 decode and encode the bagValue field of an ASN.1
 141 .Vt SafeBag
 142 structure.
 143 .Sh RETURN VALUES
 144 .Fn d2i_PKCS12 ,
 145 .Fn d2i_PKCS12_bio ,
 146 and
 147 .Fn d2i_PKCS12_fp
 148 return a
 149 .Vt PKCS12
 150 object or
 151 .Dv NULL
 152 if an error occurs.
 153 .Pp
 154 .Fn d2i_PKCS12_MAC_DATA ,
 155 .Fn d2i_PKCS12_SAFEBAG ,
 156 and
 157 .Fn d2i_PKCS12_BAGS
 158 return a
 159 .Vt PKCS12_MAC_DATA ,
 160 .Vt PKCS12_SAFEBAG ,
 161 or
 162 .Vt PKCS12_BAGS
 163 object, respectively, or
 164 .Dv NULL
 165 if an error occurs.
 166 .Pp
 167 .Fn i2d_PKCS12 ,
 168 .Fn i2d_PKCS12_MAC_DATA ,
 169 .Fn i2d_PKCS12_SAFEBAG ,
 170 and
 171 .Fn i2d_PKCS12_BAGS
 172 return the number of bytes successfully encoded or a negative value
 173 if an error occurs.
 174 .Pp
 175 .Fn i2d_PKCS12_bio
 176 and
 177 .Fn i2d_PKCS12_fp
 178 return 1 for success or 0 if an error occurs.
 179 .Sh SEE ALSO
 180 .Xr ASN1_item_d2i 3 ,
 181 .Xr PKCS12_create 3 ,
 182 .Xr PKCS12_new 3 ,
 183 .Xr PKCS12_parse 3 ,
 184 .Xr PKCS12_SAFEBAG_new 3
 185 .Sh STANDARDS
 186 RFC 7292: PKCS #12: Personal Information Exchange Syntax
 187 .Sh HISTORY
 188 .Fn d2i_PKCS12 ,
 189 .Fn i2d_PKCS12 ,
 190 .Fn d2i_PKCS12_bio ,
 191 .Fn i2d_PKCS12_bio ,
 192 .Fn d2i_PKCS12_fp ,
 193 .Fn i2d_PKCS12_fp ,
 194 .Fn d2i_PKCS12_MAC_DATA ,
 195 .Fn i2d_PKCS12_MAC_DATA ,
 196 .Fn d2i_PKCS12_SAFEBAG ,
 197 .Fn i2d_PKCS12_SAFEBAG ,
 198 .Fn d2i_PKCS12_BAGS ,
 199 and
 200 .Fn i2d_PKCS12_BAGS
 201 first appeared in OpenSSL 0.9.3 and have been available since
 202 .Ox 2.6 .