doc/man3/SSL_get_handshake_rtt.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 SSL_get_handshake_rtt
   6 - get round trip time for SSL Handshake
   7
   8 =head1 SYNOPSIS
   9
  10  #include <openssl/ssl.h>
  11
  12  int SSL_get_handshake_rtt(const SSL *s, uint64_t *rtt);
  13
  14 =head1 DESCRIPTION
  15
  16 SSL_get_handshake_rtt() retrieves the round-trip time (RTT) for I<ssl>.
  17
  18 This metric is represented in microseconds (us) as a uint64_t data type.
  19
  20 =head1 NOTES
  21
  22 This metric is created by taking two timestamps during the handshake and
  23 providing the difference between these two times.
  24
  25 When acting as the server, one timestamp is taken when the server is finished
  26 writing to the client. This is during the ServerFinished in TLS 1.3 and
  27 ServerHelloDone in TLS 1.2. The other timestamp is taken when the server is
  28 done reading the client's response. This is after the client has responded
  29 with ClientFinished.
  30
  31 When acting as the client, one timestamp is taken when the client is finished
  32 writing the ClientHello and early data (if any). The other is taken when
  33 client is done reading the server's response. This is after ServerFinished in
  34 TLS 1.3 and after ServerHelloDone in TLS 1.2.
  35
  36 In addition to network propagation delay and network stack overhead, this
  37 metric includes processing time on both endpoints, as this is based on TLS
  38 protocol-level messages and the TLS protocol is not designed to measure
  39 network timings. In some cases the processing time can be significant,
  40 especially when the processing includes asymmetric cryptographic operations.
  41
  42 =head1 RETURN VALUES
  43
  44 Returns 1 if the TLS handshake RTT is successfully retrieved.
  45 Returns 0 if the TLS handshake RTT cannot be determined yet.
  46 Returns -1 if, while retrieving the TLS handshake RTT, an error occurs.
  47
  48 =head1 COPYRIGHT
  49
  50 Copyright 2023 The OpenSSL Project Authors. All Rights Reserved.
  51
  52 Licensed under the Apache License 2.0 (the "License").  You may not use
  53 this file except in compliance with the License.  You can obtain a copy
  54 in the file LICENSE in the source distribution or at
  55 L<https://www.openssl.org/source/license.html>.
  56
  57 =cut