| Wireshark 4.7.3 The Wireshark network protocol analyzer

Loading...
Searching...
No Matches
Typedefs | Enumerations | Functions
secrets.h File Reference
`#include <inttypes.h>`
`#include <stdbool.h>`
`#include <glib.h>`
`#include "ws_symbol_export.h"`
`#include <wiretap/wtap.h>`

Go to the source code of this file.

## Typedefs
typedef void(* | secrets_block_callback_t) (const void *secrets, unsigned size)
typedef unsigned(* | secret_inject_count_func) (void)
typedef bool(* | secret_inject_export_func) (wtap *wth)
typedef char *(* | secret_export_func) (size_t *length)

## Enumerations
enum | secrets_export_values { SECRETS_EXPORT_SUCCESS = 0 , SECRETS_INVALID_CAPTURE_FILE , SECRETS_UNKNOWN_PROTOCOL , SECRETS_NO_SECRETS , SECRETS_EXPORT_FAILED }
| Return codes for a secrets (e.g., TLS key log) export operation. More...

## Functions
void | secrets_init (void)
| Initialize the secrets management system.
void | secrets_cleanup (void)
| Cleans up all secrets-related resources.
WS_DLL_PUBLIC void | secrets_wtap_callback (uint32_t secrets_type, const void *secrets, unsigned size)
WS_DLL_PUBLIC void | secrets_register_type (uint32_t secrets_type, secrets_block_callback_t cb)
WS_DLL_PUBLIC void | secrets_register_inject_type (const char *name, secret_inject_count_func count_func, secret_inject_export_func inject_func, secret_export_func export_func)
WS_DLL_PUBLIC unsigned | secrets_get_count (const char *name)
WS_DLL_PUBLIC secrets_export_values | secrets_export_dsb (const char *name, wtap *wth)
WS_DLL_PUBLIC secrets_export_values | secrets_export (const char *name, char **secrets, size_t *secrets_len, unsigned *num_secrets)
WS_DLL_PUBLIC void | secrets_inject_foreach (GHFunc func, void *param)

## Detailed Description

Secrets management and processing. Copyright 2018, Peter Wu peter.nosp@m.@lek.nosp@m.enste.nosp@m.yn.n.nosp@m.l

Wireshark - Network traffic analyzer By Gerald Combs geral.nosp@m.d@wi.nosp@m.resha.nosp@m.rk.o.nosp@m.rg Copyright 1998 Gerald Combs

SPDX-License-Identifier: GPL-2.0-or-later

## Typedef Documentation

## ◆ secrets_block_callback_t

typedef void(* secrets_block_callback_t) (const void *secrets, unsigned size)

Receives a new block of secrets from an external source (wiretap or files).

## Enumeration Type Documentation

## ◆ secrets_export_values

enum secrets_export_values

Return codes for a secrets (e.g., TLS key log) export operation.

Enumerator
SECRETS_EXPORT_SUCCESS | Secrets were exported successfully
SECRETS_INVALID_CAPTURE_FILE | The provided capture file is invalid or could not be opened
SECRETS_UNKNOWN_PROTOCOL | The requested protocol has no registered secrets exporter
SECRETS_NO_SECRETS | No secrets were found in the capture file for the requested protocol
SECRETS_EXPORT_FAILED | Export failed due to an I/O or serialization error

## Function Documentation

## ◆ secrets_export()

WS_DLL_PUBLIC secrets_export_values secrets_export | ( | const char * | name,
|  | char ** | secrets,
|  | size_t * | secrets_len,
|  | unsigned * | num_secrets )

Export the data for secrets as a character string from a single registered protocol.

Parameters

  name | Registered protocol abbreviation
  secrets | Returned secret data. Caller is responsible for g_ allocated memory returned
  secrets_len | Returned length of secrets data
  num_secrets | Number of secrets in the data

Returns
  Enumerated value for success or possible errors

## ◆ secrets_export_dsb()

WS_DLL_PUBLIC secrets_export_values secrets_export_dsb | ( | const char * | name,
|  | wtap * | wth )

Export the data for a pcapng Decryption Secrets Block (DSB) from a single registered protocol.

Parameters

  name | Registered protocol abbreviation
  wth | wiretap structure to export to

Returns
  Enumerated value for success or possible errors

## ◆ secrets_get_count()

WS_DLL_PUBLIC unsigned secrets_get_count | ( | const char * | name | ) |

Return the current number of secrets from a single registered protocol

Parameters

  name | Registered protocol abbreviation

Returns
  Number of secrets registered to that protocol

## ◆ secrets_init()

void secrets_init | ( | void |  | ) |

Initialize the secrets management system.

Interfaces for management and processing of secrets provided by external sources (wiretap, key files, HSMs, etc.). Dissectors can register themselves as consumers of these secrets.

Future idea: provide helper functions to manage external files. Typically these secrets can be erased when the file is truncated or deleted+created. Additionally, these secrets are not tied to the lifetime of a capture file.

Future idea: add a method for dissectors to mark secrets as "in use" such that unused entries can be removed when saving those secrets to file. Intended use case: read large TLS key log file (which is infrequently truncated by the user) and store only the bare minimum keys.

## ◆ secrets_inject_foreach()

WS_DLL_PUBLIC void secrets_inject_foreach | ( | GHFunc | func,
|  | void * | param )

Iterate through all of the registered secret injection protocols and call callback

Parameters

  func | Function to be called on each injector
  param | Optional data to be passed into the function as well

## ◆ secrets_register_inject_type()

WS_DLL_PUBLIC void secrets_register_inject_type | ( | const char * | name,
|  | secret_inject_count_func | count_func,
|  | secret_inject_export_func | inject_func,
|  | secret_export_func | export_func )

Registers a producer for pcapng Decryption Secrets Block (DSB).

Parameters

  name | Protocol abbreviation used by the UI to display secret type
  count_func | Callback function to provide number of secrets
  inject_func | Callback function to inject secrets into pcapng file
  export_func | Callback function to provide a stringified version of the secrets

## ◆ secrets_register_type()

WS_DLL_PUBLIC void secrets_register_type | ( | uint32_t | secrets_type,
|  | secrets_block_callback_t | cb )

Registers a consumer for pcapng Decryption Secrets Block (DSB). Only one dissector can register a type.

Parameters

  secrets_type | A Secrets Type as defined in wiretap/secrets-types.h
  cb | Callback to be invoked for new secrets.

## ◆ secrets_wtap_callback()

WS_DLL_PUBLIC void secrets_wtap_callback | ( | uint32_t | secrets_type,
|  | const void * | secrets,
|  | unsigned | size )

Callback for the wiretap secrets provider (wtap_new_secrets_callback_t).