| 1 | =pod
|
|---|
| 2 |
|
|---|
| 3 | =head1 NAME
|
|---|
| 4 |
|
|---|
| 5 | ASN1_STRING_dup, ASN1_STRING_cmp, ASN1_STRING_set, ASN1_STRING_length,
|
|---|
| 6 | ASN1_STRING_type, ASN1_STRING_get0_data, ASN1_STRING_data,
|
|---|
| 7 | ASN1_STRING_to_UTF8 - ASN1_STRING utility functions
|
|---|
| 8 |
|
|---|
| 9 | =head1 SYNOPSIS
|
|---|
| 10 |
|
|---|
| 11 | #include <openssl/asn1.h>
|
|---|
| 12 |
|
|---|
| 13 | int ASN1_STRING_length(ASN1_STRING *x);
|
|---|
| 14 | const unsigned char * ASN1_STRING_get0_data(const ASN1_STRING *x);
|
|---|
| 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 |
|
|---|
| 23 | int ASN1_STRING_type(const ASN1_STRING *x);
|
|---|
| 24 |
|
|---|
| 25 | int ASN1_STRING_to_UTF8(unsigned char **out, const ASN1_STRING *in);
|
|---|
| 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 |
|
|---|
| 33 | ASN1_STRING_get0_data() returns an internal pointer to the data of B<x>.
|
|---|
| 34 | Since this is an internal pointer it should B<not> be freed or
|
|---|
| 35 | modified in any way.
|
|---|
| 36 |
|
|---|
| 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 |
|
|---|
| 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>
|
|---|
| 56 | should be freed using OPENSSL_free().
|
|---|
| 57 |
|
|---|
| 58 | =head1 NOTES
|
|---|
| 59 |
|
|---|
| 60 | Almost all ASN1 types in OpenSSL are represented as an B<ASN1_STRING>
|
|---|
| 61 | structure. Other types such as B<ASN1_OCTET_STRING> are simply typedef'ed
|
|---|
| 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
|
|---|
| 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.
|
|---|
| 76 |
|
|---|
| 77 | Similar care should be take to ensure the data is in the correct format
|
|---|
| 78 | when calling ASN1_STRING_set().
|
|---|
| 79 |
|
|---|
| 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 |
|
|---|
| 100 | =head1 SEE ALSO
|
|---|
| 101 |
|
|---|
| 102 | L<ERR_get_error(3)>
|
|---|
| 103 |
|
|---|
| 104 | =head1 COPYRIGHT
|
|---|
| 105 |
|
|---|
| 106 | Copyright 2002-2018 The OpenSSL Project Authors. All Rights Reserved.
|
|---|
| 107 |
|
|---|
| 108 | Licensed under the OpenSSL license (the "License"). You may not use
|
|---|
| 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
|
|---|
