1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
|
/** @file
* Secrets management and processing.
* Copyright 2018, Peter Wu <peter@lekensteyn.nl>
*
* Wireshark - Network traffic analyzer
* By Gerald Combs <gerald@wireshark.org>
* Copyright 1998 Gerald Combs
*
* SPDX-License-Identifier: GPL-2.0-or-later
*/
#ifndef __SECRETS_H__
#define __SECRETS_H__
#include <glib.h>
#include "ws_symbol_export.h"
#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */
/**
* 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.
*/
void secrets_init(void);
void secrets_cleanup(void);
#if 0
/**
* Lifetime of provided secrets.
* HSM: tie information to epan scope? (but if disconnected, clear state?)
* wiretap pcang DSB: scoped to (capture) file.
* tls.keylog_file pref: epan-scoped (but if the file is deleted, clear it)
*/
enum secrets_scope {
SECRETS_SCOPE_EPAN,
SECRETS_SCOPE_FILE,
};
#endif
#ifdef HAVE_LIBGNUTLS
/** Identifier for a RSA public key (a SHA-1 hash). */
struct cert_key_id {
guint8 key_id[20];
};
typedef struct cert_key_id cert_key_id_t;
#endif /* HAVE_LIBGNUTLS */
/**
* Callback for the wiretap secrets provider (wtap_new_secrets_callback_t).
*/
WS_DLL_PUBLIC void
secrets_wtap_callback(guint32 secrets_type, const void *secrets, guint size);
/**
* Receives a new block of secrets from an external source (wiretap or files).
*/
typedef void (*secrets_block_callback_t)(const void *secrets, guint size);
/**
* Registers a consumer for pcapng Decryption Secrets Block (DSB). Only one
* dissector can register a type.
*
* @param secrets_type A Secrets Type as defined in wiretap/secrets-types.h
* @param cb Callback to be invoked for new secrets.
*/
void secrets_register_type(guint32 secrets_type, secrets_block_callback_t cb);
#ifdef HAVE_LIBGNUTLS
/**
* Retrieve a list of available key URIs. PKCS #11 token URIs begin with
* "pkcs11:".
*
* @return A list of strings, free with g_slist_free_full(keys, g_free).
*/
WS_DLL_PUBLIC GSList *
secrets_get_available_keys(void);
/**
* Checks whether a given PKCS #11 token or key file is valid.
*
* @param uri A value from secrets_get_available_keys() or a file path.
* @param password A token PIN or key file password, may be NULL.
* @param need_password Set to TRUE if a password may be required. Nullable.
* @param error The error string on failure, clean up with g_free. Nullable.
* @return TRUE if the key was valid, FALSE otherwise.
*/
WS_DLL_PUBLIC gboolean
secrets_verify_key(const char *uri, const char *password, gboolean *need_password, char **error);
/** Returns a new hash table, mapping cert_key_id_t -> gnutls_privkey_t. */
GHashTable *privkey_hash_table_new(void);
/**
* Tries to decrypt the given buffer using a private key identified by key_id.
* The private key was loaded through the 'rsa_keys' UAT.
*
* @param key_id Identifier for the public key.
* @param encr Encrypted input.
* @param encr_len Size of encrypted input.
* @param out Decrypted contents on success, free with g_free.
* @param out_len Size of decrypted contents on success.
* @return 0 if a private key was available and decryption succeeded, a negative
* error code otherwise.
*/
WS_DLL_PUBLIC int
secrets_rsa_decrypt(const cert_key_id_t *key_id, const guint8 *encr, int encr_len, guint8 **out, int *out_len);
#endif /* HAVE_LIBGNUTLS */
#ifdef __cplusplus
}
#endif /* __cplusplus */
#endif /* __SECRETS_H__ */
|
