1=pod
2
3=head1 NAME
4
5ossl_punycode_decode, ossl_a2ulabel, ossl_a2ucompare
6- internal punycode-related functions
7
8=head1 SYNOPSIS
9
10  #include "crypto/punycode.h"
11
12  int ossl_punycode_decode(const char *pEncoded, const size_t enc_len,
13                           unsigned int *pDecoded, unsigned int *pout_length);
14
15  int ossl_a2ulabel(const char *in, char *out, size_t *outlen);
16
17  int ossl_a2ucompare(const char *a, const char *u);
18
19=head1 DESCRIPTION
20
21PUNYCODE encoding introduced in RFCs 3490-3492 is widely used for
22representation of host names in ASCII-only format. Some specifications,
23such as RFC 8398, require comparison of host names encoded in UTF-8 charset.
24
25ossl_a2ulabel() decodes NUL-terminated hostname from PUNYCODE to UTF-8,
26using a provided buffer for output.
27
28ossl_a2ucompare() accepts two NUL-terminated hostnames, decodes the 1st
29from PUNYCODE to UTF-8 and compares it with the 2nd one as is.
30
31ossl_punycode_decode() decodes one label (one dot-separated part) from
32a hostname, with stripped PUNYCODE marker I<xn-->.
33
34=head1 RETURN VALUES
35
36ossl_a2ulabel() returns 1 on success, 0 on not enough buf passed,
37-1 on invalid PUNYCODE string passed. When valid string is provided, it sets the
38I<*outlen> to the length of required buffer to perform correct decoding.
39
40ossl_a2ucompare() returns 1 on non-equal strings, 0 on equal strings,
41-1 when invalid PUNYCODE string passed.
42
43ossl_punycode_decode() returns 1 on success, 0 on error. On success,
44*pout_length contains the number of codepoints decoded.
45
46=head1 HISTORY
47
48The functions described here were all added in OpenSSL 3.0.
49
50=head1 COPYRIGHT
51
52Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved.
53
54Licensed under the Apache License 2.0 (the "License").  You may not use
55this file except in compliance with the License.  You can obtain a copy
56in the file LICENSE in the source distribution or at
57L<https://www.openssl.org/source/license.html>.
58
59=cut
60
61