new manual pages

ASN1_item_digest(3), ASN1_item_sign(3), and ASN1_item_verify(3)

6 files changed, 288 insertions, 5 deletions

diff --git a/src/lib/libcrypto/man/ASN1_item_d2i.3 b/src/lib/libcrypto/man/ASN1_item_d2i.3
index 140ea6f1ba..19b290ef63 100644
--- a/src/lib/libcrypto/man/ASN1_item_d2i.3
+++ b/src/lib/libcrypto/man/ASN1_item_d2i.3
@@ -1,4 +1,4 @@
-.\"     $OpenBSD: ASN1_item_d2i.3,v 1.10 2021/07/11 15:30:21 schwarze Exp $
+.\"     $OpenBSD: ASN1_item_d2i.3,v 1.11 2021/11/07 15:29:01 schwarze Exp $
 .\"     OpenSSL doc/man3/d2i_X509.pod b97fdb57 Nov 11 09:33:09 2016 +0100
 .\"
 .\" This file is a derived work.
@@ -65,7 +65,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: July 11 2021 $
+.Dd $Mdocdate: November 7 2021 $
 .Dt ASN1_ITEM_D2I 3
 .Os
 .Sh NAME
@@ -362,7 +362,10 @@ if (d2i_X509(&x, &p, len) == NULL)
 .Ed
 .Sh SEE ALSO
 .Xr ASN1_get_object 3 ,
+.Xr ASN1_item_digest 3 ,
 .Xr ASN1_item_new 3 ,
+.Xr ASN1_item_sign 3 ,
+.Xr ASN1_item_verify 3 ,
 .Xr ASN1_TYPE_new 3
 .Sh HISTORY
 .Fn d2i_ASN1_TYPE
diff --git a/src/lib/libcrypto/man/ASN1_item_digest.3 b/src/lib/libcrypto/man/ASN1_item_digest.3
new file mode 100644
index 0000000000..e8af779c65
--- /dev/null
+++ b/src/lib/libcrypto/man/ASN1_item_digest.3
@@ -0,0 +1,71 @@
+.\" $OpenBSD: ASN1_item_digest.3,v 1.1 2021/11/07 15:29:01 schwarze Exp $
+.\"
+.\" Copyright (c) 2021 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: November 7 2021 $
+.Dt ASN1_ITEM_DIGEST 3
+.Os
+.Sh NAME
+.Nm ASN1_item_digest
+.Nd DER-encode and hash an ASN.1 value
+.Sh SYNOPSIS
+.In openssl/x509.h
+.Ft int
+.Fo ASN1_item_digest
+.Fa "const ASN1_ITEM *it"
+.Fa "const EVP_MD *type"
+.Fa "void *val_in"
+.Fa "unsigned char *md"
+.Fa "unsigned int *s"
+.Fc
+.Sh DESCRIPTION
+.Fn ASN1_item_digest
+assumes that that
+.Fa val_in
+is an
+.Vt ASN1_VALUE
+of the type specified by
+.Fa it ,
+encodes it into DER format by calling
+.Xr ASN1_item_i2d 3 ,
+hashes the resulting byte array using the digest
+.Fa type
+by calling
+.Xr EVP_Digest 3 ,
+places the digest value into
+.Pf * Fa md ,
+and, unless
+.Fa s
+is
+.Dv NULL ,
+places the length in bytes of the digest into
+.Pf * Fa s .
+Providing a buffer
+.Pf * Fa md
+large enough to contain the digest is the responsibility of the caller;
+providing a buffer of
+.Dv EVP_MAX_MD_SIZE
+bytes is recommended.
+.Sh RETURN VALUES
+.Fn ASN1_item_digest
+returns 1 for success or 0 if encoding or hashing fails.
+.Sh SEE ALSO
+.Xr ASN1_item_i2d 3 ,
+.Xr ASN1_item_sign 3 ,
+.Xr EVP_Digest 3
+.Sh HISTORY
+.Fn ASN1_item_digest
+first appeared in OpenSSL 0.9.7 and has been available since
+.Ox 3.1 .
diff --git a/src/lib/libcrypto/man/ASN1_item_new.3 b/src/lib/libcrypto/man/ASN1_item_new.3
index a5bf8aa58f..fd967bfc3f 100644
--- a/src/lib/libcrypto/man/ASN1_item_new.3
+++ b/src/lib/libcrypto/man/ASN1_item_new.3
@@ -1,4 +1,4 @@
-.\"     $OpenBSD: ASN1_item_new.3,v 1.6 2021/07/11 15:30:21 schwarze Exp $
+.\" $OpenBSD: ASN1_item_new.3,v 1.7 2021/11/07 15:29:01 schwarze Exp $
 .\"
 .\" Copyright (c) 2016, 2018 Ingo Schwarze <schwarze@openbsd.org>
 .\"
@@ -14,7 +14,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: July 11 2021 $
+.Dd $Mdocdate: November 7 2021 $
 .Dt ASN1_ITEM_NEW 3
 .Os
 .Sh NAME
@@ -107,6 +107,9 @@ is returned and an error code can be retrieved with
 .Sh SEE ALSO
 .Xr ASN1_get_object 3 ,
 .Xr ASN1_item_d2i 3 ,
+.Xr ASN1_item_digest 3 ,
+.Xr ASN1_item_sign 3 ,
+.Xr ASN1_item_verify 3 ,
 .Xr ASN1_TYPE_new 3 ,
 .Xr d2i_ASN1_NULL 3 ,
 .Xr OBJ_nid2obj 3
diff --git a/src/lib/libcrypto/man/ASN1_item_sign.3 b/src/lib/libcrypto/man/ASN1_item_sign.3
new file mode 100644
index 0000000000..9dfc346fcc
--- /dev/null
+++ b/src/lib/libcrypto/man/ASN1_item_sign.3
@@ -0,0 +1,127 @@
+.\" $OpenBSD: ASN1_item_sign.3,v 1.1 2021/11/07 15:29:01 schwarze Exp $
+.\"
+.\" Copyright (c) 2021 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: November 7 2021 $
+.Dt ASN1_ITEM_SIGN 3
+.Os
+.Sh NAME
+.Nm ASN1_item_sign ,
+.Nm ASN1_item_sign_ctx
+.Nd DER-encode and sign an ASN.1 value
+.Sh SYNOPSIS
+.In openssl/x509.h
+.Ft int
+.Fo ASN1_item_sign
+.Fa "const ASN1_ITEM *it"
+.Fa "X509_ALGOR *algor1"
+.Fa "X509_ALGOR *algor2"
+.Fa "ASN1_BIT_STRING *sig_out"
+.Fa "void *val_in"
+.Fa "EVP_PKEY *pkey"
+.Fa "const EVP_MD *type"
+.Fc
+.Ft int
+.Fo ASN1_item_sign_ctx
+.Fa "const ASN1_ITEM *it"
+.Fa "X509_ALGOR *algor1"
+.Fa "X509_ALGOR *algor2"
+.Fa "ASN1_BIT_STRING *sig_out"
+.Fa "void *val_in"
+.Fa "EVP_MD_CTX *ctx"
+.Fc
+.Sh DESCRIPTION
+.Fn ASN1_item_sign
+assumes that
+.Fa val_in
+is an
+.Vt ASN1_VALUE
+of the type specified by
+.Fa it ,
+encodes it into DER format by calling
+.Xr ASN1_item_i2d 3 ,
+and signs the resulting byte array in a way similar to
+.Xr EVP_DigestSign 3 ,
+using a signing context created with
+.Xr EVP_DigestSignInit 3
+for the given digest
+.Fa type
+and private key
+.Fa pkey .
+The created signature is placed into the
+.Fa sig_out
+object provided by the caller,
+freeing and replacing any data already contained in that object.
+.Pp
+.Fn ASN1_item_sign_ctx
+is similar except that the provided
+.Ft ctx
+is used rather than creating a new one.
+No matter whether
+.Fn ASN1_item_sign_ctx
+succeeds or fails,
+.Xr EVP_MD_CTX_cleanup 3
+is called on
+.Fa ctx
+before returning.
+.Pp
+For both functions, unless
+.Fa algor1
+is
+.Dv NULL ,
+its algorithm OID and parameter type are set according to the digest
+.Fa type
+used, and its parameter value is cleared.
+In RSA-PSS mode, the parameter value is also copied into
+.Fa algor1 .
+Unless
+.Fa algor2
+is
+.Dv NULL ,
+the same data is copied into it.
+.\" The following is not yet supported by LibreSSL
+.\" because we do not provide EVP_PKEY_asn1_set_item(3).
+.\" except that user-defined key types set up with
+.\" .Xr EVP_PKEY_asn1_new 3
+.\" may optionally provide information about a second algorithm in
+.\" .Fa algor2 .
+.Sh RETURN VALUES
+These functions return the length of the signature in bytes
+or 0 if memory allocation, encoding, or signing fails.
+.Pp
+.Fn ASN1_item_sign_ctx
+also fails and returns 0 if
+.Fa ctx
+is not fully initialized.
+.Sh SEE ALSO
+.Xr ASN1_BIT_STRING_new 3 ,
+.Xr ASN1_item_digest 3 ,
+.Xr ASN1_item_i2d 3 ,
+.Xr ASN1_item_verify 3 ,
+.Xr EVP_Digest 3 ,
+.Xr EVP_DigestSign 3 ,
+.Xr EVP_MD_CTX_new 3 ,
+.\" We do not provide EVP_PKEY_asn1_set_item(3).
+.\" .Xr EVP_PKEY_asn1_new 3 ,
+.Xr EVP_PKEY_new 3 ,
+.Xr X509_ALGOR_new 3
+.Sh HISTORY
+.Fn ASN1_item_sign
+first appeared in OpenSSL 0.9.7 and has been available since
+.Ox 3.1 .
+.Pp
+.Fn ASN1_item_sign_ctx
+first appeared in OpenSSL 1.0.1 and has been available since
+.Ox 5.3 .
diff --git a/src/lib/libcrypto/man/ASN1_item_verify.3 b/src/lib/libcrypto/man/ASN1_item_verify.3
new file mode 100644
index 0000000000..3e32558e7b
--- /dev/null
+++ b/src/lib/libcrypto/man/ASN1_item_verify.3
@@ -0,0 +1,76 @@
+.\" $OpenBSD: ASN1_item_verify.3,v 1.1 2021/11/07 15:29:01 schwarze Exp $
+.\"
+.\" Copyright (c) 2021 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: November 7 2021 $
+.Dt ASN1_ITEM_VERIFY 3
+.Os
+.Sh NAME
+.Nm ASN1_item_verify
+.Nd signature verification for ASN.1 values
+.Sh SYNOPSIS
+.In openssl/x509.h
+.Ft int
+.Fo ASN1_item_verify
+.Fa "const ASN1_ITEM *it"
+.Fa "X509_ALGOR *algor1"
+.Fa "ASN1_BIT_STRING *sig_in"
+.Fa "void *val_in"
+.Fa "EVP_PKEY *pkey"
+.Fc
+.Sh DESCRIPTION
+.Fn ASN1_item_verify
+assumes that
+.Fa val_in
+is an
+.Ft ASN1_VALUE
+of the type specified by
+.Fa it ,
+encodes it into DER format by calling
+.Xr ASN1_item_i2d 3 ,
+and verifies in a way similar to
+.Xr EVP_DigestVerify 3
+that
+.Fa sig_in
+contains a valid signature of the resulting byte array,
+a signature that was created with the digest type
+.Fa algor1
+and the private key corresponding to the public key
+.Fa pkey .
+.Sh RETURN VALUES
+.Fn ASN1_item_verify
+returns 1 if signure verification succeds, 0 if signature verification
+fails, or \-1 if
+.Fa pkey
+is
+.Dv NULL ,
+if
+.Fa sig_in
+contains invalid flags, or if
+.Fa algor1
+requests an invalid or unsupported digest algorithm
+or does not work with the given
+.Fa pkey .
+.Sh SEE ALSO
+.Xr ASN1_BIT_STRING_new 3 ,
+.Xr ASN1_item_i2d 3 ,
+.Xr ASN1_item_sign 3 ,
+.Xr EVP_DigestVerify 3 ,
+.Xr EVP_PKEY_new 3 ,
+.Xr X509_ALGOR_new 3
+.Sh HISTORY
+.Fn ASN1_item_verify
+first appeared in OpenSSL 0.9.7 and has been available since
+.Ox 3.1 .
diff --git a/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile
index 1e2c626d0c..53d20760eb 100644
--- a/src/lib/libcrypto/man/Makefile
+++ b/src/lib/libcrypto/man/Makefile
@@ -1,4 +1,4 @@
-# $OpenBSD: Makefile,v 1.208 2021/10/30 16:20:35 schwarze Exp $
+# $OpenBSD: Makefile,v 1.209 2021/11/07 15:29:01 schwarze Exp $
 
 .include <bsd.own.mk>
 
@@ -16,7 +16,10 @@ MAN=	\
         ASN1_generate_nconf.3 \
         ASN1_get_object.3 \
         ASN1_item_d2i.3 \
+        ASN1_item_digest.3 \
         ASN1_item_new.3 \
+        ASN1_item_sign.3 \
+        ASN1_item_verify.3 \
         ASN1_mbstring_copy.3 \
         ASN1_parse_dump.3 \
         ASN1_put_object.3 \