lib/libcrypto/man/SXNET_new.3

   1 .\"     $OpenBSD: SXNET_new.3,v 1.3 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 SXNET_NEW 3
  19 .Os
  20 .Sh NAME
  21 .Nm SXNET_new ,
  22 .Nm SXNET_free ,
  23 .Nm SXNETID_new ,
  24 .Nm SXNETID_free ,
  25 .Nm d2i_SXNET ,
  26 .Nm i2d_SXNET ,
  27 .Nm d2i_SXNETID ,
  28 .Nm i2d_SXNETID
  29 .Nd Thawte strong extranet X.509 extension
  30 .Sh SYNOPSIS
  31 .In openssl/x509v3.h
  32 .Ft SXNET *
  33 .Fn SXNET_new void
  34 .Ft void
  35 .Fn SXNET_free "SXNET *sxnet"
  36 .Ft SXNETID *
  37 .Fn SXNETID_new void
  38 .Ft void
  39 .Fn SXNETID_free "SXNETID *sxnetid"
  40 .Ft SXNET *
  41 .Fo d2i_SXNET
  42 .Fa "SXNET **val_out"
  43 .Fa "const unsigned char **der_in"
  44 .Fa "long length"
  45 .Fc
  46 .Ft int
  47 .Fo i2d_SXNET
  48 .Fa "SXNET *val_in"
  49 .Fa "unsigned char **der_out"
  50 .Fc
  51 .Ft SXNETID *
  52 .Fo d2i_SXNETID
  53 .Fa "SXNETID **val_out"
  54 .Fa "const unsigned char **der_in"
  55 .Fa "long length"
  56 .Fc
  57 .Ft int
  58 .Fo i2d_SXNETID
  59 .Fa "SXNETID *val_in"
  60 .Fa "unsigned char **der_out"
  61 .Fc
  62 .Sh DESCRIPTION
  63 .Fn SXNET_new
  64 allocates and initializes an empty
  65 .Vt SXNET
  66 object representing a non-standard proprietary Thawte strong extranet
  67 X.509 extension.
  68 .Fn SXNET_free
  69 frees
  70 .Fa sxnet .
  71 .Pp
  72 .Fn SXNETID_new
  73 allocates and initializes an empty
  74 .Vt SXNETID
  75 object.
  76 It is used inside
  77 .Vt SXNET .
  78 .Fn SXNETID_free
  79 frees
  80 .Fa sxnetid .
  81 .Pp
  82 The remaining functions decode and encode these objects
  83 using DER format.
  84 For details about the semantics, examples, caveats, and bugs, see
  85 .Xr ASN1_item_d2i 3 .
  86 .Sh RETURN VALUES
  87 .Fn SXNET_new
  88 and
  89 .Fn d2i_SXNET
  90 return an
  91 .Vt SXNET
  92 object or
  93 .Dv NULL
  94 if an error occurs.
  95 .Pp
  96 .Fn SXNETID_new
  97 and
  98 .Fn d2i_SXNETID
  99 return an
 100 .Vt SXNETID
 101 object or
 102 .Dv NULL
 103 if an error occurs.
 104 .Pp
 105 .Fn i2d_SXNET
 106 and
 107 .Fn i2d_SXNETID
 108 return the number of bytes successfully encoded or a negative value
 109 if an error occurs.
 110 .Sh SEE ALSO
 111 .Xr X509_EXTENSION_new 3 ,
 112 .Xr X509_new 3
 113 .Rs
 114 .%A M. Shuttleworth
 115 .%R The Strong Extranet: real-world personal certification
 116 .%Q Thawte Consulting
 117 .%C South Africa
 118 .%D 1998
 119 .Re
 120 .Sh HISTORY
 121 These functions first appeared in OpenSSL 0.9.3
 122 and have been available since
 123 .Ox 2.6 .
 124 .Sh BUGS
 125 This manual page does not explain what the extension actually does
 126 because no authoritative information was found online so far.
 127 .Pp
 128 The only hint was found in an ancient white paper "Securing IBM
 129 Applications with Public Key Infrastructure" on the IBM website,
 130 dated June 13, 2001: "Thawte also has a technology called Strong
 131 Extranet that allows institutions to encode customer information
 132 in the extensions to their customer's certificates.
 133 Because multiple institutions can add information, the user needs
 134 only one certificate, making renewal and revocation simpler, although
 135 the issue of modifying an extension to an existing certificate is
 136 not addressed."
 137 .Pp
 138 It is unclear whether that explanation is accurate, but in any case,
 139 it is not very specific.