From bd32a855e77be70d4bf689296862e8f1c7c23c06 Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Fri, 23 Aug 2019 12:23:39 +0000 Subject: document X509_get1_email(3), X509_get1_ocsp(3), X509_email_free(3) --- src/lib/libcrypto/man/Makefile | 3 +- src/lib/libcrypto/man/OCSP_SERVICELOC_new.3 | 5 +- src/lib/libcrypto/man/OCSP_sendreq_new.3 | 9 +- src/lib/libcrypto/man/X509_check_host.3 | 10 ++- src/lib/libcrypto/man/X509_get1_email.3 | 123 ++++++++++++++++++++++++++++ src/lib/libcrypto/man/X509_new.3 | 3 +- 6 files changed, 141 insertions(+), 12 deletions(-) create mode 100644 src/lib/libcrypto/man/X509_get1_email.3 diff --git a/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile index c9c74ca337..60bd8b53cc 100644 --- a/src/lib/libcrypto/man/Makefile +++ b/src/lib/libcrypto/man/Makefile @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile,v 1.153 2019/08/22 15:15:35 schwarze Exp $ +# $OpenBSD: Makefile,v 1.154 2019/08/23 12:23:39 schwarze Exp $ .include @@ -275,6 +275,7 @@ MAN= \ X509_get_version.3 \ X509_get0_notBefore.3 \ X509_get0_signature.3 \ + X509_get1_email.3 \ X509_new.3 \ X509_sign.3 \ X509_verify_cert.3 \ diff --git a/src/lib/libcrypto/man/OCSP_SERVICELOC_new.3 b/src/lib/libcrypto/man/OCSP_SERVICELOC_new.3 index febd71699b..62eb8c320f 100644 --- a/src/lib/libcrypto/man/OCSP_SERVICELOC_new.3 +++ b/src/lib/libcrypto/man/OCSP_SERVICELOC_new.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: OCSP_SERVICELOC_new.3,v 1.7 2018/05/13 14:36:05 schwarze Exp $ +.\" $OpenBSD: OCSP_SERVICELOC_new.3,v 1.8 2019/08/23 12:23:39 schwarze Exp $ .\" .\" Copyright (c) 2016 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: May 13 2018 $ +.Dd $Mdocdate: August 23 2019 $ .Dt OCSP_SERVICELOC_NEW 3 .Os .Sh NAME @@ -94,6 +94,7 @@ if an error occurred. .Sh SEE ALSO .Xr OCSP_REQUEST_new 3 , .Xr X509_EXTENSION_new 3 , +.Xr X509_get1_ocsp 3 , .Xr X509_get_issuer_name 3 , .Xr X509_NAME_new 3 .Sh STANDARDS diff --git a/src/lib/libcrypto/man/OCSP_sendreq_new.3 b/src/lib/libcrypto/man/OCSP_sendreq_new.3 index 42cb4159df..8392c61190 100644 --- a/src/lib/libcrypto/man/OCSP_sendreq_new.3 +++ b/src/lib/libcrypto/man/OCSP_sendreq_new.3 @@ -1,5 +1,5 @@ -.\" $OpenBSD: OCSP_sendreq_new.3,v 1.7 2018/03/23 04:34:23 schwarze Exp $ -.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" $OpenBSD: OCSP_sendreq_new.3,v 1.8 2019/08/23 12:23:39 schwarze Exp $ +.\" full merge up to: OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 .\" .\" This file was written by Dr. Stephen Henson . .\" Copyright (c) 2014, 2016 The OpenSSL Project. All rights reserved. @@ -48,7 +48,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: March 23 2018 $ +.Dd $Mdocdate: August 23 2019 $ .Dt OCSP_SENDREQ_NEW 3 .Os .Sh NAME @@ -227,7 +227,8 @@ Add a Host header for .Xr OCSP_request_add1_nonce 3 , .Xr OCSP_REQUEST_new 3 , .Xr OCSP_resp_find_status 3 , -.Xr OCSP_response_status 3 +.Xr OCSP_response_status 3 , +.Xr X509_get1_ocsp 3 .Sh HISTORY .Fn OCSP_sendreq_bio first appeared in OpenSSL 0.9.7 and has been available since diff --git a/src/lib/libcrypto/man/X509_check_host.3 b/src/lib/libcrypto/man/X509_check_host.3 index 9bd059a6fe..a2c91af1ad 100644 --- a/src/lib/libcrypto/man/X509_check_host.3 +++ b/src/lib/libcrypto/man/X509_check_host.3 @@ -1,9 +1,10 @@ -.\" $OpenBSD: X509_check_host.3,v 1.4 2019/06/06 01:06:59 schwarze Exp $ -.\" OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 +.\" $OpenBSD: X509_check_host.3,v 1.5 2019/08/23 12:23:39 schwarze Exp $ +.\" full merge up to: OpenSSL 6738bf14 Feb 13 12:51:29 2018 +0000 .\" .\" This file was written by Florian Weimer and .\" Viktor Dukhovni . -.\" Copyright (c) 2012, 2014, 2015, 2016 The OpenSSL Project. All rights reserved. +.\" Copyright (c) 2012, 2014, 2015, 2016 The OpenSSL Project. +.\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions @@ -49,7 +50,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: June 6 2019 $ +.Dd $Mdocdate: August 23 2019 $ .Dt X509_CHECK_HOST 3 .Os .Sh NAME @@ -234,6 +235,7 @@ returns -2 if the provided contains embedded NUL bytes. .Sh SEE ALSO .Xr X509_EXTENSION_new 3 , +.Xr X509_get1_email 3 , .Xr X509_new 3 .Sh HISTORY These functions first appeared in OpenSSL 1.0.2 diff --git a/src/lib/libcrypto/man/X509_get1_email.3 b/src/lib/libcrypto/man/X509_get1_email.3 new file mode 100644 index 0000000000..c38a604899 --- /dev/null +++ b/src/lib/libcrypto/man/X509_get1_email.3 @@ -0,0 +1,123 @@ +.\" $OpenBSD: X509_get1_email.3,v 1.1 2019/08/23 12:23:39 schwarze Exp $ +.\" +.\" Copyright (c) 2019 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: August 23 2019 $ +.Dt X509_GET1_EMAIL 3 +.Os +.Sh NAME +.Nm X509_get1_email , +.Nm X509_get1_ocsp , +.Nm X509_email_free +.Nd utilities for stacks of strings +.Sh SYNOPSIS +.In openssl/x509v3.h +.Vt typedef char *OPENSSL_STRING ; +.Ft STACK_OF(OPENSSL_STRING) * +.Fo X509_get1_email +.Fa "X509 *certificate" +.Fc +.Ft STACK_OF(OPENSSL_STRING) * +.Fo X509_get1_ocsp +.Fa "X509 *certificate" +.Fc +.Ft void +.Fo X509_email_free +.Fa "STACK_OF(OPENSSL_STRING) *stack" +.Fc +.Sh DESCRIPTION +.Fn X509_get1_email +retrieves all email addresses from the +.Fa subject +field and from any +Subject Alternative Name extension of the +.Fa certificate . +.Pp +.Fn X509_get1_ocsp +retrieves all uniform resource identifiers +from all +.Vt AccessDescription +objects having an +.Fa accessMethod +of OCSP which are contained in the Authority Information Access extension +of the +.Fa certificate . +.Pp +.Fn X509_email_free +frees all strings stored in the +.Fa stack +as well as the stack itself. +If +.Fa stack +is a +.Dv NULL +pointer, no action occurs. +.Sh RETURN VALUES +.Fn X509_REQ_get1_email +and +.Fn X509_get1_ocsp +return newly allocated stacks of +.Vt char * +containing copies of the addresses in question, or +.Dv NULL +if there are no addresses or if an error occurs. +.Sh SEE ALSO +.Xr OCSP_sendreq_new 3 , +.Xr OCSP_SERVICELOC_new 3 , +.Xr OPENSSL_sk_new 3 , +.Xr STACK_OF 3 , +.Xr X509_check_email 3 , +.Xr X509_get_ext_d2i 3 , +.Xr X509_get_subject_name 3 , +.Xr X509_new 3 , +.Xr x509v3.cnf 5 +.Sh STANDARDS +RFC 5280: Internet X.509 Public Key Infrastructure Certificate and +Certificate Revocation List (CRL) Profile +.Bl -dash -offset indent -compact +.It +section 4.1: Basic Certificate Fields +.It +section 4.1.2.6: Subject +.It +section 4.2.1.6: Subject Alternative Name +.It +section 4.2.2.1: Authority Information Access +.El +.Pp +RFC 2985: PKCS #9: Selected Object Classes and Attribute Types +.Bl -dash -offset indent -compact +.It +section 5.2.1: Electronic-mail address +.It +appendix B.3.5: emailAddress +.El +.Sh HISTORY +.Fn X509_get1_email +and +.Fn X509_email_free +first appeared in OpenSSL 0.9.6 and have been available since +.Ox 2.9 . +.Pp +.Fn X509_get1_ocsp +first appeared in OpenSSL 0.9.8h and has been available since +.Ox 4.5 . +.Sh BUGS +.Fn X509_email_free +is utterly misnamed. +It does not operate on any +.Vt X509 +object, nor is it in any way restricted to email addresses; +instead, it simply frees a stack of strings. diff --git a/src/lib/libcrypto/man/X509_new.3 b/src/lib/libcrypto/man/X509_new.3 index 5920384ffa..4ee31a67d2 100644 --- a/src/lib/libcrypto/man/X509_new.3 +++ b/src/lib/libcrypto/man/X509_new.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: X509_new.3,v 1.21 2019/08/23 09:41:49 schwarze Exp $ +.\" $OpenBSD: X509_new.3,v 1.22 2019/08/23 12:23:39 schwarze Exp $ .\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 .\" .\" This file is a derived work. @@ -183,6 +183,7 @@ if an error occurs. .Xr X509_EXTENSION_new 3 , .Xr X509_get0_notBefore 3 , .Xr X509_get0_signature 3 , +.Xr X509_get1_email 3 , .Xr X509_get_ex_new_index 3 , .Xr X509_get_pubkey 3 , .Xr X509_get_serialNumber 3 , -- cgit v1.2.3-55-g6feb