secrets.h File Reference

#include <inttypes.h>
#include <stdbool.h>
#include <glib.h>
#include "ws_symbol_export.h"
#include "cfile.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) (capture_file *cf)
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 }

Functions
void	secrets_init (void)
void	secrets_cleanup (void)
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, capture_file *cf)
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).

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 responsibile 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,
		capture_file *	cf
	)

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

Parameters

name	Registered protocol abbreviation
cf	Capture file 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

)

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).