From: tb <tb@openbsd.org>
Date: Tue, 26 Oct 2021 23:37:56 +0000 (+0000)
Subject: Merge documentation for i2d_re_X509*_tbs(3) from OpenSSL 1.1
X-Git-Url: http://artulab.com/gitweb/?a=commitdiff_plain;h=6aa720d0ddcbd73f62d8da50f0f1ffce64816a7e;p=openbsd

Merge documentation for i2d_re_X509*_tbs(3) from OpenSSL 1.1
---

diff --git a/lib/libcrypto/man/d2i_X509.3 b/lib/libcrypto/man/d2i_X509.3
index 94b136a0ced..12163d9e485 100644
--- a/lib/libcrypto/man/d2i_X509.3
+++ b/lib/libcrypto/man/d2i_X509.3
@@ -1,5 +1,6 @@
-.\"	$OpenBSD: d2i_X509.3,v 1.9 2018/03/27 17:35:50 schwarze Exp $
+.\"	$OpenBSD: d2i_X509.3,v 1.10 2021/10/26 23:37:56 tb Exp $
 .\"	OpenSSL 94480b57 Sep 12 23:34:41 2009 +0000
+.\" selective merge up to: OpenSSL 61f805c1 Jan 16 01:01:46 2018 +0800
 .\"
 .\" This file is a derived work.
 .\" The changes are covered by the following Copyright and license:
@@ -18,7 +19,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.\" The original file was written by Dr. Stephen Henson <steve@openssl.org>.
+.\" The original files were written by Dr. Stephen Henson <steve@openssl.org>.
 .\" Copyright (c) 2002, 2003, 2005, 2009, 2016 The OpenSSL Project.
 .\" All rights reserved.
 .\"
@@ -66,7 +67,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: March 27 2018 $
+.Dd $Mdocdate: October 26 2021 $
 .Dt D2I_X509 3
 .Os
 .Sh NAME
@@ -83,7 +84,10 @@
 .Nm d2i_X509_CINF ,
 .Nm i2d_X509_CINF ,
 .Nm d2i_X509_VAL ,
-.Nm i2d_X509_VAL
+.Nm i2d_X509_VAL ,
+.Nm i2d_re_X509_tbs ,
+.Nm i2d_re_X509_CRL_tbs ,
+.Nm i2d_re_X509_REQ_tbs
 .Nd decode and encode X.509 certificates
 .Sh SYNOPSIS
 .In openssl/x509.h
@@ -162,6 +166,21 @@
 .Fa "X509_VAL *val_in"
 .Fa "unsigned char **der_out"
 .Fc
+.Ft int
+.Fo i2d_re_X509_tbs
+.Fa "X509 *x"
+.Fa "unsigned char **out"
+.Fc
+.Ft int
+.Fo i2d_re_X509_CRL_tbs
+.Fa "X509_CRL *crl"
+.Fa "unsigned char **pp"
+.Fc
+.Ft int
+.Fo i2d_re_X509_REQ_tbs
+.Fa "X509_REQ *req"
+.Fa "unsigned char **pp"
+.Fc
 .Sh DESCRIPTION
 These functions decode and encode X.509 certificates
 and some of their substructures.
@@ -221,6 +240,37 @@ and
 decode and encode an ASN.1
 .Vt Validity
 structure defined in RFC 5280 section 4.1.
+.Pp
+.Fn i2d_re_X509_tbs
+is similar to
+.Fn i2d_X509 ,
+except it encodes only the TBSCertificate portion of the certificate.
+.Fn i2d_re_X509_CRL_tbs
+and
+.Fn i2d_re_X509_REQ_tbs
+are analogous for CRL and certificate request, respectively.
+The "re" in
+.Fn i2d_re_X509_tbs
+stands for "re-encode", and ensures that a fresh encoding is generated
+in case the object has been modified after creation (see the BUGS
+section).
+.Pp
+The encoding of the TBSCertificate portion of a certificate is cached in
+the
+.Vt X509
+structure internally to improve encoding performance and to ensure
+certificate signatures are verified correctly in some certificates with
+broken (non-DER) encodings.
+.Pp
+If, after modification, the
+.Vt X509
+object is re-signed with
+.Xr X509_sign 3 ,
+the encoding is automatically renewed.
+Otherwise, the encoding of the TBSCertificate portion of the
+.Vt X509
+can be manually renewed by calling
+.Fn i2d_re_X509_tbs .
 .Sh RETURN VALUES
 .Fn d2i_X509 ,
 .Fn d2i_X509_bio ,
@@ -260,6 +310,12 @@ and
 .Fn i2d_X509_fp
 return 1 for success or 0 if an error occurs.
 .Pp
+.Fn i2d_re_X509_tbs ,
+.Fn i2d_re_X509_CRL_tbs ,
+and
+.Fn i2d_re_X509_REQ_tbs
+return the length of bytes successfully encoded or 0 if an error occurs.
+.Pp
 For all functions, the error code can be obtained by
 .Xr ERR_get_error 3 .
 .Sh SEE ALSO
@@ -294,3 +350,10 @@ and
 .Fn i2d_X509_CERT_AUX
 first appeared in OpenSSL 0.9.5 and have been available since
 .Ox 2.7 .
+.Pp
+.Fn i2d_re_X509_tbs ,
+.Fn i2d_re_X509_CRL_tbs ,
+and
+.Fn i2d_re_X509_REQ_tbs
+first appeared in OpenSSL 1.1.0 and have been available since
+.Ox 7.1 .