doc/internal/man3/ossl_punycode_decode.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 ossl_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
  21 PUNYCODE encoding introduced in RFCs 3490-3492 is widely used for
  22 representation of hostnames in ASCII-only format. Some specifications,
  23 such as RFC 8398, require comparison of hostnames encoded in UTF-8 charset.
  24
  25 ossl_a2ulabel() decodes NUL-terminated hostname from PUNYCODE to UTF-8,
  26 using a provided buffer for output.  The output buffer is NUL-terminated.
  27
  28 ossl_a2ucompare() accepts two NUL-terminated hostnames, decodes the 1st
  29 from PUNYCODE to UTF-8 and compares it with the 2nd one as is.
  30
  31 ossl_punycode_decode() decodes one label (one dot-separated part) from
  32 a hostname, with stripped PUNYCODE marker I<xn-->.
  33
  34 =head1 RETURN VALUES
  35
  36 ossl_a2ulabel() returns 1 on success, 0 if the output buffer is too small and
  37 -1 if an invalid PUNYCODE string is passed or another error occurs.
  38
  39 ossl_a2ucompare() returns 1 on non-equal strings, 0 on equal strings,
  40 -1 when an invalid PUNYCODE string is passed or another error occurs.
  41
  42 ossl_punycode_decode() returns 1 on success, 0 on error. On success,
  43 *pout_length contains the number of codepoints decoded.
  44
  45 =head1 HISTORY
  46
  47 The functions described here were all added in OpenSSL 3.0.
  48
  49 =head1 COPYRIGHT
  50
  51 Copyright 2019-2020 The OpenSSL Project Authors. All Rights Reserved.
  52
  53 Licensed under the Apache License 2.0 (the "License").  You may not use
  54 this file except in compliance with the License.  You can obtain a copy
  55 in the file LICENSE in the source distribution or at
  56 L<https://www.openssl.org/source/license.html>.
  57
  58 =cut
  59