From: tb Date: Thu, 20 Apr 2023 16:15:29 +0000 (+0000) Subject: Add documentation for s2i_ASN1_INTEGER and related functions X-Git-Url: http://artulab.com/gitweb/?a=commitdiff_plain;h=58c86195e0ab6d49b64f33b9340ef9824bc17e66;p=openbsd Add documentation for s2i_ASN1_INTEGER and related functions These functions convert strings to internal objects and vice versa. This is a best effort, probably with a lot of room for improvement, which can happen in tree if anyone cares. It's better than nothing. Nothing in turn would be significantly better than the utter garbage a related project has managed to land as part of their efforts towards significant documentation improvements in a recent major relase. This leaves a dangling reference to the misnamed X509V3_METHOD_get_nid(3) which I may or may not fill in the future. I am unsure about the HISTORY section's precision, but that's what I got from cvs history. All these functions are about a quarter century old (and it shows), so I don't think it matters very much. --- diff --git a/lib/libcrypto/man/s2i_ASN1_INTEGER.3 b/lib/libcrypto/man/s2i_ASN1_INTEGER.3 new file mode 100644 index 00000000000..83633d684bb --- /dev/null +++ b/lib/libcrypto/man/s2i_ASN1_INTEGER.3 @@ -0,0 +1,195 @@ +.\" $OpenBSD: s2i_ASN1_INTEGER.3,v 1.1 2023/04/20 16:15:29 tb Exp $ +.\" +.\" Copyright (c) 2023 Theo Buehler +.\" +.\" 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: April 20 2023 $ +.Dt I2S_ASN1_ENUMERATED 3 +.Os +.Sh NAME +.Nm i2s_ASN1_ENUMERATED , +.Nm i2s_ASN1_ENUMERATED_TABLE , +.Nm i2s_ASN1_INTEGER , +.Nm s2i_ASN1_INTEGER , +.Nm i2s_ASN1_OCTET_STRING , +.Nm s2i_ASN1_OCTET_STRING +.Nd ASN.1 data type conversion utilities for certificate extensions +.Sh SYNOPSIS +.In openssl/asn1.h +.In openssl/x509v3.h +.Ft "char *" +.Fo i2s_ASN1_ENUMERATED +.Fa "X509V3_EXT_METHOD *method" +.Fa "const ASN1_ENUMERATED *a" +.Fc +.Ft "char *" +.Fo i2s_ASN1_INTEGER +.Fa "X509V3_EXT_METHOD *method" +.Fa "const ASN1_INTEGER *a" +.Fc +.Ft "ASN1_INTEGER *" +.Fo s2i_ASN1_INTEGER +.Fa "X509V3_EXT_METHOD *method" +.Fa "const char *value" +.Fc +.Ft "char *" +.Fo i2s_ASN1_OCTET_STRING +.Fa "X509V3_EXT_METHOD *method" +.Fa "const ASN1_OCTET_STRING *aos" +.Fc +.Ft "ASN1_OCTET_STRING *" +.Fo s2i_ASN1_OCTET_STRING +.Fa "X509V3_EXT_METHOD *method" +.Fa "X509V3_CTX *ctx" +.Fa "const char *value" +.Fc +.Ft "char *" +.Fo i2s_ASN1_ENUMERATED_TABLE +.Fa "X509V3_EXT_METHOD *method" +.Fa "const ASN1_ENUMERATED *aenum" +.Fc +.Sh DESCRIPTION +These functions convert to and from +.Vt ASN1_ENUMERATED , +.Vt ASN1_INTEGER , +and +.Vt ASN1_OCTET_STRING +objects. +They are primarily used internally for parsing configuration files and +displaying of X.509v3 certificate extensions. +With the exception of +.Fn i2s_ASN1_ENUMERATED_TABLE , +these functions ignore the +.Fa method +argument. +Any object or string returned by these functions must be freed by the caller. +.Pp +.Fn i2s_ASN1_ENUMERATED +and +.Fn i2s_ASN1_INTEGER +first convert +.Fa a +into a +.Vt BIGNUM +object with +.Xr ASN1_ENUMERATED_to_BN 3 +or +.Xr ASN1_INTEGER_to_BN 3 +and then derive a string representation using +.Xr BN_bn2dec 3 +or +.Xr BN_bn2hex 3 . +Decimal representation is used if the number has less than 128 bits, +otherwise hexadecimal representation is used to avoid excessive conversion cost. +.Pp +.Fn s2i_ASN1_INTEGER +converts a NUL-terminated decimal or hexadecimal string representation of +an integer into an +.Vt ASN1_INTEGER +object. +A sign prefix of +.Sq - +indicates a negative number +and +.Sq 0x +and +.Sq 0X +indicate hexadecimal representation, +otherwise decimal representation is assumed. +After skipping the sign and base prefixes, an intermediate conversion into a +.Vt BIGNUM +is performed using +.Xr BN_dec2bn 3 +or +.Xr BN_hex2bn 3 +and the +.Vt ASN1_INTEGER +is then obtained with +.Xr BN_to_ASN1_INTEGER 3 . +.Pp +.Fn i2s_ASN1_OCTET_STRING +converts the octets in +.Fa aos +into a string where the octets are represented by pairs of colon-separated +hexadecimal digits. +.Pp +.Fn s2i_ASN1_OCTET_STRING +converts the NUL-terminated string +.Fa str +into an +.Vt ASN1_OCTET_STRING . +The +.Fa method +and +.Fa ctx +arguments are ignored. +Every pair of hexadecimal digits is converted into an octet, while +any number of colons separating two pairs are ignored. +.Pp +.Fn i2s_ASN1_ENUMERATED_TABLE +uses strings provided in the usr_data field of the non-NULL +.Fa method +to convert the value of +.Fa a +into a string. +If no such string is available, +.Fa a +is passed to +.Fn i2s_ASN1_ENUMERATED . +The +.Fa method +argument can be provided by application programs or it can be a +default method obtained from +.Xr X509V3_METHOD_get_nid 3 . +The default +.Fa methods +corresponding to the following +.Fa nid +arguments have strings configured in their usr_data field: +.Pp +.Bl -column NID_netscape_cert_type "Netscape certificate type (obsolete)" -compact +.It Dv NID_crl_reason Ta reason codes, RFC 5280, 5.3.1 +.It Dv NID_key_usage Ta key usage, RFC 5280, 4.2.1.3 +.It Dv NID_netscape_cert_type Ta Netscape certificate type (obsolete) +.El +.Sh RETURN VALUES +.Fn i2s_ASN1_ENUMERATED , +.Fn i2s_ASN1_ENUMERATED_TABLE , +.Fn i2s_ASN1_INTEGER , +and +.Fn i2s_ASN1_OCTET_STRING +return a NUL-terminated string, or NULL on error, +usually memory allocation failure. +.Pp +.Fn s2i_ASN1_INTEGER +returns an +.Vt ASN1_INTEGER , +or NULL on error. +.Pp +.Fn s2i_ASN1_OCTET_STRING +returns an +.Vt ASN1_OCTET_STRING , +or NULL on error. +.Pp +Error codes can be obtained by +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr ASN1_INTEGER_new 3 , +.Xr ASN1_INTEGER_to_BN 3 , +.Xr ASN1_OCTET_STRING_new 3 , +.Xr X509V3_get_d2i 3 +.Sh HISTORY +These functions first appeared in OpenSSL 0.9.4 and +have been available since +.Ox 2.6 .