From: schwarze Date: Sun, 7 Nov 2021 15:29:01 +0000 (+0000) Subject: new manual pages X-Git-Url: http://artulab.com/gitweb/?a=commitdiff_plain;h=a974b571a2240f5edb77212c01a8a78786b21ac8;p=openbsd new manual pages ASN1_item_digest(3), ASN1_item_sign(3), and ASN1_item_verify(3) --- diff --git a/lib/libcrypto/man/ASN1_item_d2i.3 b/lib/libcrypto/man/ASN1_item_d2i.3 index 140ea6f1bae..19b290ef637 100644 --- a/lib/libcrypto/man/ASN1_item_d2i.3 +++ b/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/lib/libcrypto/man/ASN1_item_digest.3 b/lib/libcrypto/man/ASN1_item_digest.3 new file mode 100644 index 00000000000..e8af779c657 --- /dev/null +++ b/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 +.\" +.\" 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/lib/libcrypto/man/ASN1_item_new.3 b/lib/libcrypto/man/ASN1_item_new.3 index a5bf8aa58f1..fd967bfc3fb 100644 --- a/lib/libcrypto/man/ASN1_item_new.3 +++ b/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 .\" @@ -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/lib/libcrypto/man/ASN1_item_sign.3 b/lib/libcrypto/man/ASN1_item_sign.3 new file mode 100644 index 00000000000..9dfc346fcc3 --- /dev/null +++ b/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 +.\" +.\" 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/lib/libcrypto/man/ASN1_item_verify.3 b/lib/libcrypto/man/ASN1_item_verify.3 new file mode 100644 index 00000000000..3e32558e7b9 --- /dev/null +++ b/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 +.\" +.\" 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/lib/libcrypto/man/Makefile b/lib/libcrypto/man/Makefile index 1e2c626d0cb..53d20760eb6 100644 --- a/lib/libcrypto/man/Makefile +++ b/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 @@ -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 \