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