.\"	$OpenBSD: SXNET_new.3,v 1.3 2018/03/21 17:57:48 schwarze Exp $
.\"
.\" Copyright (c) 2016 Ingo Schwarze <schwarze@openbsd.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: March 21 2018 $
.Dt SXNET_NEW 3
.Os
.Sh NAME
.Nm SXNET_new ,
.Nm SXNET_free ,
.Nm SXNETID_new ,
.Nm SXNETID_free ,
.Nm d2i_SXNET ,
.Nm i2d_SXNET ,
.Nm d2i_SXNETID ,
.Nm i2d_SXNETID
.Nd Thawte strong extranet X.509 extension
.Sh SYNOPSIS
.In openssl/x509v3.h
.Ft SXNET *
.Fn SXNET_new void
.Ft void
.Fn SXNET_free "SXNET *sxnet"
.Ft SXNETID *
.Fn SXNETID_new void
.Ft void
.Fn SXNETID_free "SXNETID *sxnetid"
.Ft SXNET *
.Fo d2i_SXNET
.Fa "SXNET **val_out"
.Fa "const unsigned char **der_in"
.Fa "long length"
.Fc
.Ft int
.Fo i2d_SXNET
.Fa "SXNET *val_in"
.Fa "unsigned char **der_out"
.Fc
.Ft SXNETID *
.Fo d2i_SXNETID
.Fa "SXNETID **val_out"
.Fa "const unsigned char **der_in"
.Fa "long length"
.Fc
.Ft int
.Fo i2d_SXNETID
.Fa "SXNETID *val_in"
.Fa "unsigned char **der_out"
.Fc
.Sh DESCRIPTION
.Fn SXNET_new
allocates and initializes an empty
.Vt SXNET
object representing a non-standard proprietary Thawte strong extranet
X.509 extension.
.Fn SXNET_free
frees
.Fa sxnet .
.Pp
.Fn SXNETID_new
allocates and initializes an empty
.Vt SXNETID
object.
It is used inside
.Vt SXNET .
.Fn SXNETID_free
frees
.Fa sxnetid .
.Pp
The remaining functions decode and encode these objects
using DER format.
For details about the semantics, examples, caveats, and bugs, see
.Xr ASN1_item_d2i 3 .
.Sh RETURN VALUES
.Fn SXNET_new
and
.Fn d2i_SXNET
return an
.Vt SXNET
object or
.Dv NULL
if an error occurs.
.Pp
.Fn SXNETID_new
and
.Fn d2i_SXNETID
return an
.Vt SXNETID
object or
.Dv NULL
if an error occurs.
.Pp
.Fn i2d_SXNET
and
.Fn i2d_SXNETID
return the number of bytes successfully encoded or a negative value
if an error occurs.
.Sh SEE ALSO
.Xr X509_EXTENSION_new 3 ,
.Xr X509_new 3
.Rs
.%A M. Shuttleworth
.%R The Strong Extranet: real-world personal certification
.%Q Thawte Consulting
.%C South Africa
.%D 1998
.Re
.Sh HISTORY
These functions first appeared in OpenSSL 0.9.3
and have been available since
.Ox 2.6 .
.Sh BUGS
This manual page does not explain what the extension actually does
because no authoritative information was found online so far.
.Pp
The only hint was found in an ancient white paper "Securing IBM
Applications with Public Key Infrastructure" on the IBM website,
dated June 13, 2001: "Thawte also has a technology called Strong
Extranet that allows institutions to encode customer information
in the extensions to their customer's certificates.
Because multiple institutions can add information, the user needs
only one certificate, making renewal and revocation simpler, although
the issue of modifying an extension to an existing certificate is
not addressed."
.Pp
It is unclear whether that explanation is accurate, but in any case,
it is not very specific.