epan/secrets.h

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