From 7d15cb53a646c08495353f48291ab06e87f57f48 Mon Sep 17 00:00:00 2001 From: schwarze Date: Mon, 22 Nov 2021 12:06:51 +0000 Subject: [PATCH] document ASN1_OBJECT_create(3) --- lib/libcrypto/man/ASN1_OBJECT_new.3 | 71 +++++++++++++++++++++++++---- 1 file changed, 61 insertions(+), 10 deletions(-) diff --git a/lib/libcrypto/man/ASN1_OBJECT_new.3 b/lib/libcrypto/man/ASN1_OBJECT_new.3 index cf48cccef96..671631094b2 100644 --- a/lib/libcrypto/man/ASN1_OBJECT_new.3 +++ b/lib/libcrypto/man/ASN1_OBJECT_new.3 @@ -1,10 +1,10 @@ -.\" $OpenBSD: ASN1_OBJECT_new.3,v 1.11 2019/06/06 01:06:58 schwarze Exp $ -.\" OpenSSL 99d63d4 Mar 19 12:28:58 2016 -0400 +.\" $OpenBSD: ASN1_OBJECT_new.3,v 1.12 2021/11/22 12:06:51 schwarze Exp $ +.\" full merge up to: OpenSSL 99d63d4 Mar 19 12:28:58 2016 -0400 .\" .\" This file is a derived work. .\" The changes are covered by the following Copyright and license: .\" -.\" Copyright (c) 2017 Ingo Schwarze +.\" Copyright (c) 2017, 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 @@ -65,11 +65,12 @@ .\" 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: November 22 2021 $ .Dt ASN1_OBJECT_NEW 3 .Os .Sh NAME .Nm ASN1_OBJECT_new , +.Nm ASN1_OBJECT_create , .Nm ASN1_OBJECT_free .Nd ASN.1 object identifiers .Sh SYNOPSIS @@ -78,6 +79,14 @@ .Fo ASN1_OBJECT_new .Fa void .Fc +.Ft ASN1_OBJECT * +.Fo ASN1_OBJECT_create +.Fa "int nid" +.Fa "unsigned char *content" +.Fa "int len" +.Fa "const char *short_name" +.Fa "const char *long_name" +.Fc .Ft void .Fo ASN1_OBJECT_free .Fa "ASN1_OBJECT *a" @@ -92,10 +101,28 @@ and a sequence of integers identifying a node in the International Object Identifier tree as specified in ITU-T recommendation X.660. The new object is marked as dynamically allocated. .Pp +.Fn ASN1_OBJECT_create +allocates a new +.Vt ASN1_OBJECT +with the given +.Fa nid , +copies the +.Fa len +DER +.Fa content +octets, the +.Fa short_name , +and the +.Fa long_name +into it, and marks the new object and all data contained in it +as dynamically allocated. +.Pp Application programs normally use utility functions like .Xr OBJ_nid2obj 3 rather than using .Fn ASN1_OBJECT_new +or +.Fn ASN1_OBJECT_create directly. .Pp .Fn ASN1_OBJECT_free @@ -123,13 +150,34 @@ is a pointer or if neither the object itself nor any of its content is marked as dynamically allocated, no action occurs. .Sh RETURN VALUES -If the allocation fails, .Fn ASN1_OBJECT_new -returns +and +.Fn ASN1_OBJECT_create +return a pointer to the new object or .Dv NULL -and sets an error code that can be obtained by -.Xr ERR_get_error 3 . -Otherwise it returns a pointer to the new object. +if memory allocation fails, +.Sh ERRORS +After failure of +.Fn ASN1_OBJECT_new +or +.Fn ASN1_OBJECT_create , +the following diagnostic can be retrieved with +.Xr ERR_get_error 3 , +.Xr ERR_GET_REASON 3 , +and +.Xr ERR_reason_error_string 3 : +.Bl -tag -width Ds +.It Dv ERR_R_MALLOC_FAILURE Qq "malloc failure" +Memory allocation failed. +.El +.Pp +After some cases of failure of +.Fn ASN1_OBJECT_create , +the following diagnostic can be retrieved in addition to the above: +.Bl -tag -width Ds +.It Dv ERR_R_ASN1_LIB Qq "ASN1 lib" +Memory allocation failed. +.El .Sh SEE ALSO .Xr ASN1_TYPE_get 3 , .Xr d2i_ASN1_OBJECT 3 , @@ -138,5 +186,8 @@ Otherwise it returns a pointer to the new object. .Fn ASN1_OBJECT_new and .Fn ASN1_OBJECT_free -first appeared in SSLeay 0.5.1 and have been available since +first appeared in SSLeay 0.5.1 and +.Fn ASN1_OBJECT_create +in SSLeay 0.8.0. +These functions have been available since .Ox 2.4 . -- 2.20.1