1 .\" Automatically generated by Pod::Man 2.12 (Pod::Simple 3.05)
4 .\" ========================================================================
5 .de Sh \" Subsection heading
13 .de Sp \" Vertical space (when we can't use .PP)
17 .de Vb \" Begin verbatim text
22 .de Ve \" End verbatim text
26 .\" Set up some character translations and predefined strings. \*(-- will
27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
28 .\" double quote, and \*(R" will give a right double quote. \*(C+ will
29 .\" give a nicer C++. Capital omega is used to do unbreakable dashes and
30 .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
31 .\" nothing in troff, for use with C<>.
33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
37 . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
38 . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
51 .\" If the F register is turned on, we'll generate index entries on stderr for
52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
53 .\" entries marked with X<> in POD. Of course, you'll have to process the
54 .\" output yourself in some meaningful fashion.
57 . tm Index:\\$1\t\\n%\t"\\$2"
63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
64 .\" Fear. Run. Save yourself. No user-serviceable parts.
65 . \" fudge factors for nroff and troff
74 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
80 . \" simple accents for nroff and troff
90 . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
91 . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
92 . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
93 . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
94 . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
95 . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
97 . \" troff and (daisy-wheel) nroff accents
98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
105 .ds ae a\h'-(\w'a'u*4/10)'e
106 .ds Ae A\h'-(\w'A'u*4/10)'E
107 . \" corrections for vroff
108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
110 . \" for low resolution devices (crt and lpr)
111 .if \n(.H>23 .if \n(.V>19 \
124 .\" ========================================================================
126 .IX Title "ASN1_STRING_length 3"
127 .TH ASN1_STRING_length 3 "2007-10-24" "0.9.8g" "OpenSSL"
128 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
129 .\" way too many mistakes in technical documents.
133 ASN1_STRING_dup, ASN1_STRING_cmp, ASN1_STRING_set, ASN1_STRING_length,
134 ASN1_STRING_length_set, ASN1_STRING_type, ASN1_STRING_data \-
135 ASN1_STRING utility functions
137 .IX Header "SYNOPSIS"
139 \& int ASN1_STRING_length(ASN1_STRING *x);
140 \& unsigned char * ASN1_STRING_data(ASN1_STRING *x);
142 \& ASN1_STRING * ASN1_STRING_dup(ASN1_STRING *a);
144 \& int ASN1_STRING_cmp(ASN1_STRING *a, ASN1_STRING *b);
146 \& int ASN1_STRING_set(ASN1_STRING *str, const void *data, int len);
148 \& int ASN1_STRING_type(ASN1_STRING *x);
150 \& int ASN1_STRING_to_UTF8(unsigned char **out, ASN1_STRING *in);
153 .IX Header "DESCRIPTION"
154 These functions allow an \fB\s-1ASN1_STRING\s0\fR structure to be manipulated.
156 \&\fIASN1_STRING_length()\fR returns the length of the content of \fBx\fR.
158 \&\fIASN1_STRING_data()\fR returns an internal pointer to the data of \fBx\fR.
159 Since this is an internal pointer it should \fBnot\fR be freed or
162 \&\fIASN1_STRING_dup()\fR returns a copy of the structure \fBa\fR.
164 \&\fIASN1_STRING_cmp()\fR compares \fBa\fR and \fBb\fR returning 0 if the two
165 are identical. The string types and content are compared.
167 \&\fIASN1_STRING_set()\fR sets the data of string \fBstr\fR to the buffer
168 \&\fBdata\fR or length \fBlen\fR. The supplied data is copied. If \fBlen\fR
169 is \-1 then the length is determined by strlen(data).
171 \&\fIASN1_STRING_type()\fR returns the type of \fBx\fR, using standard constants
172 such as \fBV_ASN1_OCTET_STRING\fR.
174 \&\fIASN1_STRING_to_UTF8()\fR converts the string \fBin\fR to \s-1UTF8\s0 format, the
175 converted data is allocated in a buffer in \fB*out\fR. The length of
176 \&\fBout\fR is returned or a negative error code. The buffer \fB*out\fR
177 should be free using \fIOPENSSL_free()\fR.
180 Almost all \s-1ASN1\s0 types in OpenSSL are represented as an \fB\s-1ASN1_STRING\s0\fR
181 structure. Other types such as \fB\s-1ASN1_OCTET_STRING\s0\fR are simply typedefed
182 to \fB\s-1ASN1_STRING\s0\fR and the functions call the \fB\s-1ASN1_STRING\s0\fR equivalents.
183 \&\fB\s-1ASN1_STRING\s0\fR is also used for some \fB\s-1CHOICE\s0\fR types which consist
184 entirely of primitive string types such as \fBDirectoryString\fR and
187 These functions should \fBnot\fR be used to examine or modify \fB\s-1ASN1_INTEGER\s0\fR
188 or \fB\s-1ASN1_ENUMERATED\s0\fR types: the relevant \fB\s-1INTEGER\s0\fR or \fB\s-1ENUMERATED\s0\fR
189 utility functions should be used instead.
191 In general it cannot be assumed that the data returned by \fIASN1_STRING_data()\fR
192 is null terminated or does not contain embedded nulls. The actual format
193 of the data will depend on the actual string type itself: for example
194 for and IA5String the data will be \s-1ASCII\s0, for a BMPString two bytes per
195 character in big endian format, UTF8String will be in \s-1UTF8\s0 format.
197 Similar care should be take to ensure the data is in the correct format
198 when calling \fIASN1_STRING_set()\fR.
200 .IX Header "RETURN VALUES"
202 .IX Header "SEE ALSO"
203 \&\fIERR_get_error\fR\|(3)