Branch data     Line data    Source code

       1                 :            : /*
       2                 :            :  * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
       3                 :            :  *
       4                 :            :  * Licensed under the Apache License, Version 2.0 (the "License").
       5                 :            :  * You may not use this file except in compliance with the License.
       6                 :            :  * A copy of the License is located at
       7                 :            :  *
       8                 :            :  *  http://aws.amazon.com/apache2.0
       9                 :            :  *
      10                 :            :  * or in the "license" file accompanying this file. This file is distributed
      11                 :            :  * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
      12                 :            :  * express or implied. See the License for the specific language governing
      13                 :            :  * permissions and limitations under the License.
      14                 :            :  */
      15                 :            : 
      16                 :            : #pragma once
      17                 :            : 
      18                 :            : #include <s2n.h>
      19                 :            : #include <stdint.h>
      20                 :            : 
      21                 :            : #ifdef __cplusplus
      22                 :            : extern "C" {
      23                 :            : #endif
      24                 :            : 
      25                 :            : /* This is a special value assigned to handshake_start_epoch_ns to indicate that
      26                 :            :  * it has already been sent to the application and should not be sent again.
      27                 :            :  */
      28                 :          3 : #define HANDSHAKE_EVENT_SENT UINT64_C(1) << 63
      29                 :            : 
      30                 :            : struct s2n_event_handshake {
      31                 :            :     /**
      32                 :            :      * The negotiated protocol version
      33                 :            :      * 
      34                 :            :      * This will be one of the protocol version constants defined in s2n.h 
      35                 :            :      */
      36                 :            :     int protocol_version;
      37                 :            :     /* static memory */
      38                 :            :     const char *cipher;
      39                 :            :     /* static memory */
      40                 :            :     const char *group;
      41                 :            :     /* static memory */
      42                 :            :     const char *security_policy_label;
      43                 :            :     /* the amount of time inside the synchronous s2n_negotiate method */
      44                 :            :     uint64_t handshake_time_ns;
      45                 :            :     /**
      46                 :            :      * The start of the handshake. This is not an interpretable time, and only has
      47                 :            :      * meaning in reference to handshake_end_ns. 
      48                 :            :      *
      49                 :            :      * This is also used as a flag to ensure that the same event isn't emitted 
      50                 :            :      * twice. After the event has been emitted this is set to HANDSHAKE_EVENT_SENT
      51                 :            :      */
      52                 :            :     uint64_t handshake_start_ns;
      53                 :            :     uint64_t handshake_end_ns;
      54                 :            :     /**
      55                 :            :      * If the handshake failed, this contains the error code.
      56                 :            :      * 0 indicates no error (successful handshake).
      57                 :            :      * The error name can be retrieved via s2n_strerror_name(error_code).
      58                 :            :      */
      59                 :            :     int error_code;
      60                 :            : };
      61                 :            : 
      62                 :            : typedef void (*s2n_event_on_handshake_cb)(struct s2n_connection *conn, void *subscriber, struct s2n_event_handshake *event);
      63                 :            : 
      64                 :            : S2N_API extern int s2n_config_set_subscriber(struct s2n_config *config, void *subscriber);
      65                 :            : /**
      66                 :            :  * Set a callback to receive a handshake event.
      67                 :            :  * 
      68                 :            :  * The `struct s2n_event_handshake *event` is only valid over the lifetime of the 
      69                 :            :  * callbacks, and must not be referenced after the callback returned.
      70                 :            :  * 
      71                 :            :  * An event is emitted both on success and failure. On failure, the event's
      72                 :            :  * error_code field will be set with the relevant error information.
      73                 :            :  */
      74                 :            : S2N_API extern int s2n_config_set_handshake_event(struct s2n_config *config, s2n_event_on_handshake_cb callback);
      75                 :            : 
      76                 :            : /**
      77                 :            :  * Per-message timing checkpoint emitted once when each handshake message
      78                 :            :  * handler finishes. Consumers reconstruct per-message durations by computing
      79                 :            :  * the delta between consecutive checkpoint timestamps.
      80                 :            :  *
      81                 :            :  * Checkpoints fire from the shared handshake dispatch loop, so they are emitted
      82                 :            :  * for every negotiated protocol version. The message names reflect whichever
      83                 :            :  * version was negotiated.
      84                 :            :  *
      85                 :            :  * The pointer passed to the callback is valid only for the duration of the
      86                 :            :  * callback invocation. Callers must copy any fields they want to retain.
      87                 :            :  */
      88                 :            : struct s2n_timing_checkpoint {
      89                 :            :     /* Static-lifetime string identifying which message just finished. Points
      90                 :            :      * into a `const char *[]` array, so the pointer itself is safe to read
      91                 :            :      * during the callback. Do not retain the pointer past the callback. */
      92                 :            :     const char *name;
      93                 :            :     /* 0 = S2N_SERVER, 1 = S2N_CLIENT — matches conn->mode */
      94                 :            :     uint8_t role;
      95                 :            :     /* Monotonic timestamp in nanoseconds, captured via the same clock used
      96                 :            :      * for handshake_start_ns / handshake_end_ns in struct s2n_event_handshake.
      97                 :            :      * Per-message checkpoints and total handshake time are therefore on the
      98                 :            :      * same timeline. */
      99                 :            :     uint64_t timestamp_ns;
     100                 :            : };
     101                 :            : 
     102                 :            : typedef void (*s2n_event_on_timing_checkpoint_cb)(struct s2n_connection *conn, void *subscriber, struct s2n_timing_checkpoint *checkpoint);
     103                 :            : 
     104                 :            : /**
     105                 :            :  * Register a per-message timing checkpoint callback on a config.
     106                 :            :  *
     107                 :            :  * The callback fires once after each TLS handshake message handler completes,
     108                 :            :  * with a single monotonic timestamp. The consumer reconstructs per-message
     109                 :            :  * durations by computing deltas between consecutive checkpoint timestamps.
     110                 :            :  *
     111                 :            :  * The same `subscriber` pointer set via s2n_config_set_subscriber is passed
     112                 :            :  * as the second argument to the callback. If no subscriber has been set,
     113                 :            :  * NULL is passed.
     114                 :            :  *
     115                 :            :  * Note: On a server using SNI-based config swap (s2n_connection_set_config
     116                 :            :  * called from the client hello callback), NEGOTIATE_START fires before the
     117                 :            :  * swap occurs. To receive NEGOTIATE_START, register this callback on the
     118                 :            :  * initial/default config, not only on the SNI-selected config.
     119                 :            :  *
     120                 :            :  * Returns S2N_SUCCESS on success.
     121                 :            :  * Returns S2N_FAILURE with S2N_ERR_NULL if config or callback is NULL.
     122                 :            :  */
     123                 :            : S2N_API extern int s2n_config_set_timing_checkpoint_cb(struct s2n_config *config, s2n_event_on_timing_checkpoint_cb callback);
     124                 :            : 
     125                 :            : #ifdef __cplusplus
     126                 :            : }
     127                 :            : #endif