secure/lib/libcrypto/man/man3/ASN1_STRING_length.3

   1 .\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.39)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 .    ds C`
  42 .    ds C'
  43 'br\}
  44 .\"
  45 .\" Escape single quotes in literal strings from groff's Unicode transform.
  46 .ie \n(.g .ds Aq \(aq
  47 .el       .ds Aq '
  48 .\"
  49 .\" If the F register is >0, we'll generate index entries on stderr for
  50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  51 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  52 .\" output yourself in some meaningful fashion.
  53 .\"
  54 .\" Avoid warning from groff about undefined register 'F'.
  55 .de IX
  56 ..
  57 .nr rF 0
  58 .if \n(.g .if rF .nr rF 1
  59 .if (\n(rF:(\n(.g==0)) \{\
  60 .    if \nF \{\
  61 .        de IX
  62 .        tm Index:\\$1\t\\n%\t"\\$2"
  63 ..
  64 .        if !\nF==2 \{\
  65 .            nr % 0
  66 .            nr F 2
  67 .        \}
  68 .    \}
  69 .\}
  70 .rr rF
  71 .\"
  72 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  73 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  74 .    \" fudge factors for nroff and troff
  75 .if n \{\
  76 .    ds #H 0
  77 .    ds #V .8m
  78 .    ds #F .3m
  79 .    ds #[ \f1
  80 .    ds #] \fP
  81 .\}
  82 .if t \{\
  83 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  84 .    ds #V .6m
  85 .    ds #F 0
  86 .    ds #[ \&
  87 .    ds #] \&
  88 .\}
  89 .    \" simple accents for nroff and troff
  90 .if n \{\
  91 .    ds ' \&
  92 .    ds ` \&
  93 .    ds ^ \&
  94 .    ds , \&
  95 .    ds ~ ~
  96 .    ds /
  97 .\}
  98 .if t \{\
  99 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 100 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 101 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 102 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 103 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 104 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 105 .\}
 106 .    \" troff and (daisy-wheel) nroff accents
 107 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 108 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 109 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 110 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 111 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 112 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 113 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 114 .ds ae a\h'-(\w'a'u*4/10)'e
 115 .ds Ae A\h'-(\w'A'u*4/10)'E
 116 .    \" corrections for vroff
 117 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 118 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 119 .    \" for low resolution devices (crt and lpr)
 120 .if \n(.H>23 .if \n(.V>19 \
 121 \{\
 122 .    ds : e
 123 .    ds 8 ss
 124 .    ds o a
 125 .    ds d- d\h'-1'\(ga
 126 .    ds D- D\h'-1'\(hy
 127 .    ds th \o'bp'
 128 .    ds Th \o'LP'
 129 .    ds ae ae
 130 .    ds Ae AE
 131 .\}
 132 .rm #[ #] #H #V #F C
 133 .\" ========================================================================
 134 .\"
 135 .IX Title "ASN1_STRING_LENGTH 3"
 136 .TH ASN1_STRING_LENGTH 3 "2019-09-10" "1.1.1d" "OpenSSL"
 137 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 138 .\" way too many mistakes in technical documents.
 139 .if n .ad l
 140 .nh
 141 .SH "NAME"
 142 ASN1_STRING_dup, ASN1_STRING_cmp, ASN1_STRING_set, ASN1_STRING_length, ASN1_STRING_type, ASN1_STRING_get0_data, ASN1_STRING_data, ASN1_STRING_to_UTF8 \- ASN1_STRING utility functions
 143 .SH "SYNOPSIS"
 144 .IX Header "SYNOPSIS"
 145 .Vb 1
 146 \& #include <openssl/asn1.h>
 147 \&
 148 \& int ASN1_STRING_length(ASN1_STRING *x);
 149 \& const unsigned char * ASN1_STRING_get0_data(const ASN1_STRING *x);
 150 \& unsigned char * ASN1_STRING_data(ASN1_STRING *x);
 151 \&
 152 \& ASN1_STRING * ASN1_STRING_dup(ASN1_STRING *a);
 153 \&
 154 \& int ASN1_STRING_cmp(ASN1_STRING *a, ASN1_STRING *b);
 155 \&
 156 \& int ASN1_STRING_set(ASN1_STRING *str, const void *data, int len);
 157 \&
 158 \& int ASN1_STRING_type(const ASN1_STRING *x);
 159 \&
 160 \& int ASN1_STRING_to_UTF8(unsigned char **out, const ASN1_STRING *in);
 161 .Ve
 162 .SH "DESCRIPTION"
 163 .IX Header "DESCRIPTION"
 164 These functions allow an \fB\s-1ASN1_STRING\s0\fR structure to be manipulated.
 165 .PP
 166 \&\fBASN1_STRING_length()\fR returns the length of the content of \fBx\fR.
 167 .PP
 168 \&\fBASN1_STRING_get0_data()\fR returns an internal pointer to the data of \fBx\fR.
 169 Since this is an internal pointer it should \fBnot\fR be freed or
 170 modified in any way.
 171 .PP
 172 \&\fBASN1_STRING_data()\fR is similar to \fBASN1_STRING_get0_data()\fR except the
 173 returned value is not constant. This function is deprecated:
 174 applications should use \fBASN1_STRING_get0_data()\fR instead.
 175 .PP
 176 \&\fBASN1_STRING_dup()\fR returns a copy of the structure \fBa\fR.
 177 .PP
 178 \&\fBASN1_STRING_cmp()\fR compares \fBa\fR and \fBb\fR returning 0 if the two
 179 are identical. The string types and content are compared.
 180 .PP
 181 \&\fBASN1_STRING_set()\fR sets the data of string \fBstr\fR to the buffer
 182 \&\fBdata\fR or length \fBlen\fR. The supplied data is copied. If \fBlen\fR
 183 is \-1 then the length is determined by strlen(data).
 184 .PP
 185 \&\fBASN1_STRING_type()\fR returns the type of \fBx\fR, using standard constants
 186 such as \fBV_ASN1_OCTET_STRING\fR.
 187 .PP
 188 \&\fBASN1_STRING_to_UTF8()\fR converts the string \fBin\fR to \s-1UTF8\s0 format, the
 189 converted data is allocated in a buffer in \fB*out\fR. The length of
 190 \&\fBout\fR is returned or a negative error code. The buffer \fB*out\fR
 191 should be freed using \fBOPENSSL_free()\fR.
 192 .SH "NOTES"
 193 .IX Header "NOTES"
 194 Almost all \s-1ASN1\s0 types in OpenSSL are represented as an \fB\s-1ASN1_STRING\s0\fR
 195 structure. Other types such as \fB\s-1ASN1_OCTET_STRING\s0\fR are simply typedef'ed
 196 to \fB\s-1ASN1_STRING\s0\fR and the functions call the \fB\s-1ASN1_STRING\s0\fR equivalents.
 197 \&\fB\s-1ASN1_STRING\s0\fR is also used for some \fB\s-1CHOICE\s0\fR types which consist
 198 entirely of primitive string types such as \fBDirectoryString\fR and
 199 \&\fBTime\fR.
 200 .PP
 201 These functions should \fBnot\fR be used to examine or modify \fB\s-1ASN1_INTEGER\s0\fR
 202 or \fB\s-1ASN1_ENUMERATED\s0\fR types: the relevant \fB\s-1INTEGER\s0\fR or \fB\s-1ENUMERATED\s0\fR
 203 utility functions should be used instead.
 204 .PP
 205 In general it cannot be assumed that the data returned by \fBASN1_STRING_data()\fR
 206 is null terminated or does not contain embedded nulls. The actual format
 207 of the data will depend on the actual string type itself: for example
 208 for an IA5String the data will be \s-1ASCII,\s0 for a BMPString two bytes per
 209 character in big endian format, and for an UTF8String it will be in \s-1UTF8\s0 format.
 210 .PP
 211 Similar care should be take to ensure the data is in the correct format
 212 when calling \fBASN1_STRING_set()\fR.
 213 .SH "RETURN VALUES"
 214 .IX Header "RETURN VALUES"
 215 \&\fBASN1_STRING_length()\fR returns the length of the content of \fBx\fR.
 216 .PP
 217 \&\fBASN1_STRING_get0_data()\fR and \fBASN1_STRING_data()\fR return an internal pointer to
 218 the data of \fBx\fR.
 219 .PP
 220 \&\fBASN1_STRING_dup()\fR returns a valid \fB\s-1ASN1_STRING\s0\fR structure or \fB\s-1NULL\s0\fR if an
 221 error occurred.
 222 .PP
 223 \&\fBASN1_STRING_cmp()\fR returns an integer greater than, equal to, or less than 0,
 224 according to whether \fBa\fR is greater than, equal to, or less than \fBb\fR.
 225 .PP
 226 \&\fBASN1_STRING_set()\fR returns 1 on success or 0 on error.
 227 .PP
 228 \&\fBASN1_STRING_type()\fR returns the type of \fBx\fR.
 229 .PP
 230 \&\fBASN1_STRING_to_UTF8()\fR returns the number of bytes in output string \fBout\fR or a
 231 negative value if an error occurred.
 232 .SH "SEE ALSO"
 233 .IX Header "SEE ALSO"
 234 \&\fBERR_get_error\fR\|(3)
 235 .SH "COPYRIGHT"
 236 .IX Header "COPYRIGHT"
 237 Copyright 2002\-2018 The OpenSSL Project Authors. All Rights Reserved.
 238 .PP
 239 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 240 this file except in compliance with the License.  You can obtain a copy
 241 in the file \s-1LICENSE\s0 in the source distribution or at
 242 <https://www.openssl.org/source/license.html>.