.\" $OpenBSD: ASN1_STRING_TABLE_add.3,v 1.9 2021/12/15 20:07:51 schwarze Exp $
.\" checked up to:
.\" OpenSSL ASN1_STRING_TABLE_add.pod 7b608d08 Jul 27 01:18:50 2017 +0800
.\"
.\" Copyright (c) 2017, 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: December 15 2021 $
.Dt ASN1_STRING_TABLE_ADD 3
.Os
.Sh NAME
.Nm ASN1_STRING_TABLE_add ,
.Nm ASN1_STRING_TABLE_get ,
.Nm ASN1_STRING_TABLE_cleanup
.Nd maintain the global ASN.1 string table
.Sh SYNOPSIS
.In openssl/asn1.h
.Ft int
.Fo ASN1_STRING_TABLE_add
.Fa "int nid"
.Fa "long minsize"
.Fa "long maxsize"
.Fa "unsigned long mask"
.Fa "unsigned long flags"
.Fc
.Ft ASN1_STRING_TABLE *
.Fo ASN1_STRING_TABLE_get
.Fa "int nid"
.Fc
.Ft void
.Fn ASN1_STRING_TABLE_cleanup void
.Sh DESCRIPTION
The ASN.1 string table is a unique global object.
Each entry is of the type
.Vt ASN1_STRING_TABLE
and contains information about one NID object.
Some entries are predefined according to RFC 3280 appendix A.1.
.Pp
By default, the upper bounds for the number of characters in various kinds of
.Vt ASN1_STRING
objects are:
.Pp
.Bl -column -compact NID_organizationalUnitNa maxsi ub_organization_unit_na
.It object type                   Ta maxsize Ta symbolic constant
.It Dv NID_commonName             Ta 64      Ta Dv ub_common_name
.It Dv NID_countryName            Ta 2       Ta \(em
.It Dv NID_givenName              Ta 32768   Ta Dv ub_name
.It Dv NID_initials               Ta 32768   Ta Dv ub_name
.It Dv NID_localityName           Ta 128     Ta Dv ub_locality_name
.It Dv NID_name                   Ta 32768   Ta Dv ub_name
.It Dv NID_organizationName       Ta 64      Ta Dv ub_organization_name
.It Dv NID_organizationalUnitName Ta 64      Ta Dv ub_organization_unit_name
.It Dv NID_pkcs9_emailAddress     Ta 128     Ta Dv ub_email_address
.It Dv NID_serialNumber           Ta 64      Ta Dv ub_serial_number
.It Dv NID_stateOrProvinceName    Ta 128     Ta Dv ub_state_name
.It Dv NID_surname                Ta 32768   Ta Dv ub_name
.El
.Pp
The function
.Fn ASN1_STRING_TABLE_add
changes the existing entry for
.Fa nid
or, if there is none, allocates a new entry.
The fields of the entry are overwritten with the function arguments
of the same name.
If
.Fa minsize
or
.Fa maxsize
is negative or
.Fa mask
is 0, that argument is ignored and the respective field remains unchanged,
or for a new entry, it is set to \-1, \-1, 0, or
.Dv STABLE_FLAGS_MALLOC ,
respectively.
.Pp
The bits set in the
.Fa flags
argument are OR'ed into the existing field rather than overwriting it.
The only useful flag is
.Dv STABLE_NO_MASK .
If it is set,
.Xr ASN1_STRING_set_by_NID 3
skips applying the global mask that can be set with
.Xr ASN1_STRING_set_default_mask 3 .
Otherwise, the table entry only accepts types
permitted by both the global mask and the
.Fa mask
argument.
Setting
.Dv STABLE_FLAGS_MALLOC
or any other bit in the
.Fa mask
argument has no effect.
.Pp
The function
.Fn ASN1_STRING_TABLE_get
retrieves the entry for
.Fa nid .
.Pp
The function
.Fn ASN1_STRING_TABLE_cleanup
removes and frees all entries except the predefined ones
and restores the predefined ones to their default state.
.Sh RETURN VALUES
The
.Fn ASN1_STRING_TABLE_add
function returns 1 if successful; otherwise 0 is returned
and an error code can be retrieved with
.Xr ERR_get_error 3 .
.Pp
.Fn ASN1_STRING_TABLE_get
returns a valid
.Vt ASN1_STRING_TABLE
structure or
.Dv NULL
if nothing is found.
.Sh SEE ALSO
.Xr ASN1_OBJECT_new 3 ,
.Xr ASN1_STRING_set_by_NID 3 ,
.Xr OBJ_create 3 ,
.Xr OBJ_nid2obj 3
.Sh HISTORY
.Fn ASN1_STRING_TABLE_add ,
.Fn ASN1_STRING_TABLE_get ,
and
.Fn ASN1_STRING_TABLE_cleanup
first appeared in OpenSSL 0.9.5 and have been available since
.Ox 2.7 .
.Sh BUGS
Most aspects of the semantics considerably differ from OpenSSL.