Debian Codegraph @

upstream/debian-unstable/man3/ASN1_STRING_length.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "ASN1_STRING_LENGTH 3SSL"
58 .TH ASN1_STRING_LENGTH 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 ASN1_STRING_dup, ASN1_STRING_cmp, ASN1_STRING_set, ASN1_STRING_length,
65 ASN1_STRING_type, ASN1_STRING_get0_data, ASN1_STRING_data,
66 ASN1_STRING_to_UTF8 \- ASN1_STRING utility functions
67 .SH SYNOPSIS
68 .IX Header "SYNOPSIS"
69 .Vb 1
70 \& #include <openssl/asn1.h>
71 \&
72 \& int ASN1_STRING_length(ASN1_STRING *x);
73 \& const unsigned char *ASN1_STRING_get0_data(const ASN1_STRING *x);
74 \& unsigned char *ASN1_STRING_data(ASN1_STRING *x);
75 \&
76 \& ASN1_STRING *ASN1_STRING_dup(const ASN1_STRING *a);
77 \&
78 \& int ASN1_STRING_cmp(ASN1_STRING *a, ASN1_STRING *b);
79 \&
80 \& int ASN1_STRING_set(ASN1_STRING *str, const void *data, int len);
81 \&
82 \& int ASN1_STRING_type(const ASN1_STRING *x);
83 \&
84 \& int ASN1_STRING_to_UTF8(unsigned char **out, const ASN1_STRING *in);
85 .Ve
86 .SH DESCRIPTION
87 .IX Header "DESCRIPTION"
88 These functions allow an \fBASN1_STRING\fR structure to be manipulated.
89 .PP
90 \&\fBASN1_STRING_length()\fR returns the length of the content of \fIx\fR. \fIx\fR \fBMUST NOT\fR be NULL.
91 .PP
92 \&\fBASN1_STRING_get0_data()\fR returns an internal pointer to the data of \fIx\fR.
93 Since this is an internal pointer it should \fBnot\fR be freed or
94 modified in any way. \fIx\fR \fBMUST NOT\fR be NULL.
95 .PP
96 \&\fBASN1_STRING_data()\fR is similar to \fBASN1_STRING_get0_data()\fR except the
97 returned value is not constant. This function is deprecated:
98 applications should use \fBASN1_STRING_get0_data()\fR instead.
99 .PP
100 \&\fBASN1_STRING_dup()\fR returns a copy of the structure \fIa\fR.
101 .PP
102 \&\fBASN1_STRING_cmp()\fR compares \fIa\fR and \fIb\fR returning 0 if the two
103 are identical. The string types and content are compared.
104 .PP
105 \&\fBASN1_STRING_set()\fR sets the data of string \fIstr\fR to the buffer
106 \&\fIdata\fR or length \fIlen\fR. The supplied data is copied. If \fIlen\fR
107 is \-1 then the length is determined by strlen(data).
108 .PP
109 \&\fBASN1_STRING_type()\fR returns the type of \fIx\fR, using standard constants
110 such as \fBV_ASN1_OCTET_STRING\fR.
111 .PP
112 \&\fBASN1_STRING_to_UTF8()\fR converts the string \fIin\fR to UTF8 format, the
113 converted data is allocated in a buffer in \fI*out\fR. The length of
114 \&\fIout\fR is returned or a negative error code. The buffer \fI*out\fR
115 should be freed using \fBOPENSSL_free()\fR.
116 .SH NOTES
117 .IX Header "NOTES"
118 Almost all ASN1 types in OpenSSL are represented as an \fBASN1_STRING\fR
119 structure. Other types such as \fBASN1_OCTET_STRING\fR are simply typedef'ed
120 to \fBASN1_STRING\fR and the functions call the \fBASN1_STRING\fR equivalents.
121 \&\fBASN1_STRING\fR is also used for some \fBCHOICE\fR types which consist
122 entirely of primitive string types such as \fBDirectoryString\fR and
123 \&\fBTime\fR.
124 .PP
125 These functions should \fBnot\fR be used to examine or modify \fBASN1_INTEGER\fR
126 or \fBASN1_ENUMERATED\fR types: the relevant \fBINTEGER\fR or \fBENUMERATED\fR
127 utility functions should be used instead.
128 .PP
129 In general it cannot be assumed that the data returned by \fBASN1_STRING_data()\fR
130 is null terminated or does not contain embedded nulls. The actual format
131 of the data will depend on the actual string type itself: for example
132 for an IA5String the data will be ASCII, for a BMPString two bytes per
133 character in big endian format, and for a UTF8String it will be in UTF8 format.
134 .PP
135 Similar care should be take to ensure the data is in the correct format
136 when calling \fBASN1_STRING_set()\fR.
137 .SH "RETURN VALUES"
138 .IX Header "RETURN VALUES"
139 \&\fBASN1_STRING_length()\fR returns the length of the content of \fIx\fR.
140 .PP
141 \&\fBASN1_STRING_get0_data()\fR and \fBASN1_STRING_data()\fR return an internal pointer to
142 the data of \fIx\fR.
143 .PP
144 \&\fBASN1_STRING_dup()\fR returns a valid \fBASN1_STRING\fR structure or NULL if an
145 error occurred.
146 .PP
147 \&\fBASN1_STRING_cmp()\fR returns an integer greater than, equal to, or less than 0,
148 according to whether \fIa\fR is greater than, equal to, or less than \fIb\fR.
149 .PP
150 \&\fBASN1_STRING_set()\fR returns 1 on success or 0 on error.
151 .PP
152 \&\fBASN1_STRING_type()\fR returns the type of \fIx\fR.
153 .PP
154 \&\fBASN1_STRING_to_UTF8()\fR returns the number of bytes in output string \fIout\fR or a
155 negative value if an error occurred.
156 .SH "SEE ALSO"
157 .IX Header "SEE ALSO"
158 \&\fBERR_get_error\fR\|(3)
159 .SH COPYRIGHT
160 .IX Header "COPYRIGHT"
161 Copyright 2002\-2020 The OpenSSL Project Authors. All Rights Reserved.
162 .PP
163 Licensed under the Apache License 2.0 (the "License"). You may not use
164 this file except in compliance with the License. You can obtain a copy
165 in the file LICENSE in the source distribution or at
166 <https://www.openssl.org/source/license.html>.