1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
|
.\" $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.
|
