]>
Commit | Line | Data |
---|---|---|
0711be16 DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | ASN1_STRING_dup, ASN1_STRING_cmp, ASN1_STRING_set, ASN1_STRING_length, | |
17ebf85a DSH |
6 | ASN1_STRING_type, ASN1_STRING_get0_data, ASN1_STRING_data, |
7 | ASN1_STRING_to_UTF8 - ASN1_STRING utility functions | |
0711be16 DSH |
8 | |
9 | =head1 SYNOPSIS | |
10 | ||
c264592d UM |
11 | #include <openssl/asn1.h> |
12 | ||
0711be16 | 13 | int ASN1_STRING_length(ASN1_STRING *x); |
17ebf85a | 14 | const unsigned char * ASN1_STRING_get0_data(const ASN1_STRING *x); |
0711be16 DSH |
15 | unsigned char * ASN1_STRING_data(ASN1_STRING *x); |
16 | ||
17 | ASN1_STRING * ASN1_STRING_dup(ASN1_STRING *a); | |
18 | ||
19 | int ASN1_STRING_cmp(ASN1_STRING *a, ASN1_STRING *b); | |
20 | ||
21 | int ASN1_STRING_set(ASN1_STRING *str, const void *data, int len); | |
22 | ||
08275a29 | 23 | int ASN1_STRING_type(const ASN1_STRING *x); |
0711be16 | 24 | |
08275a29 | 25 | int ASN1_STRING_to_UTF8(unsigned char **out, const ASN1_STRING *in); |
0711be16 DSH |
26 | |
27 | =head1 DESCRIPTION | |
28 | ||
29 | These functions allow an B<ASN1_STRING> structure to be manipulated. | |
30 | ||
31 | ASN1_STRING_length() returns the length of the content of B<x>. | |
32 | ||
17ebf85a | 33 | ASN1_STRING_get0_data() returns an internal pointer to the data of B<x>. |
0711be16 DSH |
34 | Since this is an internal pointer it should B<not> be freed or |
35 | modified in any way. | |
36 | ||
17ebf85a DSH |
37 | ASN1_STRING_data() is similar to ASN1_STRING_get0_data() except the |
38 | returned value is not constant. This function is deprecated: | |
39 | applications should use ASN1_STRING_get0_data() instead. | |
40 | ||
0711be16 DSH |
41 | ASN1_STRING_dup() returns a copy of the structure B<a>. |
42 | ||
43 | ASN1_STRING_cmp() compares B<a> and B<b> returning 0 if the two | |
44 | are identical. The string types and content are compared. | |
45 | ||
46 | ASN1_STRING_set() sets the data of string B<str> to the buffer | |
47 | B<data> or length B<len>. The supplied data is copied. If B<len> | |
48 | is -1 then the length is determined by strlen(data). | |
49 | ||
50 | ASN1_STRING_type() returns the type of B<x>, using standard constants | |
51 | such as B<V_ASN1_OCTET_STRING>. | |
52 | ||
53 | ASN1_STRING_to_UTF8() converts the string B<in> to UTF8 format, the | |
54 | converted data is allocated in a buffer in B<*out>. The length of | |
55 | B<out> is returned or a negative error code. The buffer B<*out> | |
dd14f911 | 56 | should be freed using OPENSSL_free(). |
0711be16 DSH |
57 | |
58 | =head1 NOTES | |
59 | ||
60 | Almost all ASN1 types in OpenSSL are represented as an B<ASN1_STRING> | |
0ad69cd6 | 61 | structure. Other types such as B<ASN1_OCTET_STRING> are simply typedef'ed |
0711be16 DSH |
62 | to B<ASN1_STRING> and the functions call the B<ASN1_STRING> equivalents. |
63 | B<ASN1_STRING> is also used for some B<CHOICE> types which consist | |
64 | entirely of primitive string types such as B<DirectoryString> and | |
65 | B<Time>. | |
66 | ||
67 | These functions should B<not> be used to examine or modify B<ASN1_INTEGER> | |
68 | or B<ASN1_ENUMERATED> types: the relevant B<INTEGER> or B<ENUMERATED> | |
69 | utility functions should be used instead. | |
70 | ||
71 | In general it cannot be assumed that the data returned by ASN1_STRING_data() | |
72 | is null terminated or does not contain embedded nulls. The actual format | |
73 | of the data will depend on the actual string type itself: for example | |
4a56d2a3 IF |
74 | for an IA5String the data will be ASCII, for a BMPString two bytes per |
75 | character in big endian format, and for an UTF8String it will be in UTF8 format. | |
0711be16 DSH |
76 | |
77 | Similar care should be take to ensure the data is in the correct format | |
78 | when calling ASN1_STRING_set(). | |
79 | ||
1f13ad31 PY |
80 | =head1 RETURN VALUES |
81 | ||
82 | ASN1_STRING_length() returns the length of the content of B<x>. | |
83 | ||
84 | ASN1_STRING_get0_data() and ASN1_STRING_data() return an internal pointer to | |
85 | the data of B<x>. | |
86 | ||
87 | ASN1_STRING_dup() returns a valid B<ASN1_STRING> structure or B<NULL> if an | |
88 | error occurred. | |
89 | ||
90 | ASN1_STRING_cmp() returns an integer greater than, equal to, or less than 0, | |
91 | according to whether B<a> is greater than, equal to, or less than B<b>. | |
92 | ||
93 | ASN1_STRING_set() returns 1 on success or 0 on error. | |
94 | ||
95 | ASN1_STRING_type() returns the type of B<x>. | |
96 | ||
97 | ASN1_STRING_to_UTF8() returns the number of bytes in output string B<out> or a | |
98 | negative value if an error occurred. | |
99 | ||
0711be16 DSH |
100 | =head1 SEE ALSO |
101 | ||
9b86974e | 102 | L<ERR_get_error(3)> |
0711be16 | 103 | |
e2f92610 RS |
104 | =head1 COPYRIGHT |
105 | ||
61f805c1 | 106 | Copyright 2002-2018 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 107 | |
4746f25a | 108 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
109 | this file except in compliance with the License. You can obtain a copy |
110 | in the file LICENSE in the source distribution or at | |
111 | L<https://www.openssl.org/source/license.html>. | |
112 | ||
113 | =cut |