142 lines
4.4 KiB
Groff
142 lines
4.4 KiB
Groff
.\" $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.
|