224 lines
7.8 KiB
C
224 lines
7.8 KiB
C
|
/* **********************************************************
|
||
|
|
* Copyright 1998 - 2009 VMware, Inc. All rights reserved.
|
||
|
|
* **********************************************************/
|
||
|
|
|
||
|
|
/*
|
||
|
|
* @VMKAPIMOD_LICENSE@
|
||
|
|
*/
|
||
|
|
|
||
|
|
/*
|
||
|
|
***********************************************************************
|
||
|
|
* Entropy */ /**
|
||
|
|
* \defgroup Entropy Entropy
|
||
|
|
*
|
||
|
|
* These interfaces to deal with entropy in vmkernel.
|
||
|
|
*
|
||
|
|
* Two types of interfaces are provided:
|
||
|
|
* \li To provide various types of entropy directly to the VMkernel
|
||
|
|
* and device drivers (as opposed to via reads to /dev/{,u}random).
|
||
|
|
* \li To allow VMkernel and device drivers to submit hardware entropy.
|
||
|
|
*
|
||
|
|
* @{
|
||
|
|
***********************************************************************
|
||
|
|
*/
|
||
|
|
|
||
|
|
|
||
|
|
#ifndef _VMKAPI_ENTROPY_H_
|
||
|
|
#define _VMKAPI_ENTROPY_H_
|
||
|
|
|
||
|
|
/** \cond never */
|
||
|
|
#ifndef VMK_HEADER_INCLUDED_FROM_VMKAPI_H
|
||
|
|
#error This vmkapi file should never be included directly but only via vmkapi.h
|
||
|
|
#endif
|
||
|
|
/** \endcond never */
|
||
|
|
|
||
|
|
#include "base/vmkapi_types.h"
|
||
|
|
#include "base/vmkapi_status.h"
|
||
|
|
|
||
|
|
typedef enum {
|
||
|
|
VMK_ENTROPY_HARDWARE_INTERRUPT = 0,
|
||
|
|
VMK_ENTROPY_HARDWARE_RNG = 1,
|
||
|
|
VMK_ENTROPY_KEYBOARD = 2,
|
||
|
|
VMK_ENTROPY_MOUSE = 3,
|
||
|
|
VMK_ENTROPY_OTHER_HID = 4,
|
||
|
|
VMK_ENTROPY_STORAGE = 5,
|
||
|
|
VMK_ENTROPY_SOURCE_LIMIT = VMK_ENTROPY_STORAGE
|
||
|
|
} vmk_EntropySource;
|
||
|
|
|
||
|
|
typedef enum {
|
||
|
|
VMK_ENTROPY_HARDWARE = 0,
|
||
|
|
VMK_ENTROPY_HARDWARE_NON_BLOCKING = 1,
|
||
|
|
VMK_ENTROPY_SOFTWARE = 2,
|
||
|
|
VMK_ENTROPY_SOFTWARE_ONLY = 3,
|
||
|
|
VMK_ENTROPY_TYPE_LIMIT = VMK_ENTROPY_SOFTWARE_ONLY
|
||
|
|
} vmk_EntropyType;
|
||
|
|
|
||
|
|
/*
|
||
|
|
***********************************************************************
|
||
|
|
*
|
||
|
|
* Entropy Modules export two types of interfaces:
|
||
|
|
*
|
||
|
|
*
|
||
|
|
*
|
||
|
|
***********************************************************************
|
||
|
|
*/
|
||
|
|
|
||
|
|
/*
|
||
|
|
***********************************************************************
|
||
|
|
* vmk_AddEntropyFunction -- */ /**
|
||
|
|
*
|
||
|
|
* \ingroup Entropy
|
||
|
|
* \brief Submit hardware entropy to the entropy driveer
|
||
|
|
*
|
||
|
|
* vmk_AddEntropyFunctions transfer hardware entropy to an entropy module
|
||
|
|
* and are guaranteed to be non-blocking and have minimal overhead.
|
||
|
|
* There is no return status because for security reasons any failure is
|
||
|
|
* cloaked from all callers who lack privilege to know entropy status
|
||
|
|
|
||
|
|
* \param[in] typeSpecificInfo Source specific info (example: interrupt vector)
|
||
|
|
*
|
||
|
|
* \retval none; caller has no need to know success/failure and cannot be told.
|
||
|
|
*
|
||
|
|
***********************************************************************
|
||
|
|
*/
|
||
|
|
typedef void (*vmk_AddEntropyFunction)(int sourceSpecificInfo);
|
||
|
|
|
||
|
|
/*
|
||
|
|
***********************************************************************
|
||
|
|
* vmk_GetEntropyFunction -- */ /**
|
||
|
|
*
|
||
|
|
* \ingroup Entropy
|
||
|
|
* \brief Retrieve entropy from the entropy driveer
|
||
|
|
*
|
||
|
|
* vmk_GetEntropyFunctions return various types of entropy:
|
||
|
|
* VMK_ENTROPY_HARDWARE always returns VMK_OK but may block
|
||
|
|
* VMK_ENTROPY_HARDWARE_NON_BLOCKING may return VMK_FAILURE but wont block
|
||
|
|
* VMK_ENTROPY_SOFTWARE always returns VMK_OK and wont block
|
||
|
|
* VMK_ENTROPY_SOFTWARE_ONLY always returns VMK_OK and wont block
|
||
|
|
*
|
||
|
|
* Note: SOFTWARE entropy may include (and thus consume) HARDWARE
|
||
|
|
* entropy but SOFTWARE_ONLY entropy is guaranteed not to.
|
||
|
|
*
|
||
|
|
* \param[in,out] entropy Buffer to store retrieved entropy
|
||
|
|
* \param[in] bytesRequested Amount of entropy requested
|
||
|
|
* \param[out] bytesReturned Amount of entropy actually returned
|
||
|
|
*
|
||
|
|
* \retval VMK_OK All requested bytes of entropy returned
|
||
|
|
* \retval VMK_FAILURE Less than all requested bytes of entropy returned
|
||
|
|
*
|
||
|
|
***********************************************************************
|
||
|
|
*/
|
||
|
|
typedef VMK_ReturnStatus (*vmk_GetEntropyFunction)(void *entropy,
|
||
|
|
int bytesRequested,
|
||
|
|
int *bytesReturned);
|
||
|
|
|
||
|
|
/*
|
||
|
|
***********************************************************************
|
||
|
|
* vmk_RegisterAddEntropyFunction -- */ /**
|
||
|
|
*
|
||
|
|
* \ingroup Entropy
|
||
|
|
* \brief Register a function to be used to submit hardware entropy to the
|
||
|
|
* entropy driver
|
||
|
|
*
|
||
|
|
* \param[in] moduleID Module ID of the entropy module
|
||
|
|
* \param[in] function Function to call when various hardware events occur
|
||
|
|
* (e.g., hardware interrupts)
|
||
|
|
* \param[in] source Type of hardware entropy
|
||
|
|
*
|
||
|
|
* \retval VMK_OK Add entropy function was sucessfully registered.
|
||
|
|
* \retval VMK_FAILURE Add entropy function was not registered.
|
||
|
|
*
|
||
|
|
***********************************************************************
|
||
|
|
*/
|
||
|
|
VMK_ReturnStatus vmk_RegisterAddEntropyFunction(
|
||
|
|
vmk_ModuleID moduleID,
|
||
|
|
vmk_AddEntropyFunction function,
|
||
|
|
vmk_EntropySource source);
|
||
|
|
|
||
|
|
/*
|
||
|
|
***********************************************************************
|
||
|
|
* vmk_RegisterGetEntropyFunction -- */ /**
|
||
|
|
*
|
||
|
|
* \ingroup Entropy
|
||
|
|
* \brief Register an entropy function to be used to obtain hardware
|
||
|
|
* or software entropy from an external entropy pool
|
||
|
|
*
|
||
|
|
* \param[in] moduleID Module ID of the entropy module
|
||
|
|
* \param[in] function Function that returns entropy
|
||
|
|
* \param[in] type Type of entropy (e.g., hardware)
|
||
|
|
*
|
||
|
|
* \retval VMK_OK Entropy function was sucessfully registered.
|
||
|
|
* \retval VMK_FAILURE Entropy function was not registered.
|
||
|
|
*
|
||
|
|
***********************************************************************
|
||
|
|
*/
|
||
|
|
VMK_ReturnStatus vmk_RegisterGetEntropyFunction(
|
||
|
|
vmk_ModuleID moduleID,
|
||
|
|
vmk_GetEntropyFunction function,
|
||
|
|
vmk_EntropyType type);
|
||
|
|
|
||
|
|
/*
|
||
|
|
***********************************************************************
|
||
|
|
* vmk_GetRegisteredGetEntropyFunction -- */ /**
|
||
|
|
*
|
||
|
|
* \ingroup Entropy
|
||
|
|
* \brief Get a registered get entropy function to be used to obtain hardware
|
||
|
|
* or software entropy from an external entropy pool. Note that this
|
||
|
|
* function must be called with VMKMODCALL
|
||
|
|
*
|
||
|
|
* \param[out] *moduleID Module ID of the entropy module providing the function
|
||
|
|
* \param[out] *function Function that returns entropy
|
||
|
|
* \param[in] type Type of entropy desired (e.g., hardware)
|
||
|
|
*
|
||
|
|
* \retval VMK_OK Entropy function was sucessfully found and returned.
|
||
|
|
* \retval VMK_FAILURE Entropy function was not found.
|
||
|
|
*
|
||
|
|
***********************************************************************
|
||
|
|
*/
|
||
|
|
VMK_ReturnStatus vmk_GetRegisteredEntropyFunction(
|
||
|
|
vmk_ModuleID *moduleID,
|
||
|
|
vmk_GetEntropyFunction *function,
|
||
|
|
vmk_EntropyType type);
|
||
|
|
|
||
|
|
/*
|
||
|
|
***********************************************************************
|
||
|
|
* vmk_UnregisterAddEntropyFunction -- */ /**
|
||
|
|
*
|
||
|
|
* \ingroup Entropy
|
||
|
|
* \brief Unregister a submit entropy function (removes for all sources
|
||
|
|
* of entropy)
|
||
|
|
*
|
||
|
|
* \param[in] moduleID Module ID of the entropy module
|
||
|
|
* \param[in] function Function to unregister
|
||
|
|
*
|
||
|
|
* \retval VMK_OK Add entropy function was sucessfully unregistered.
|
||
|
|
* \retval VMK_FAILURE Add entropy function was not unregistered.
|
||
|
|
*
|
||
|
|
***********************************************************************
|
||
|
|
*/
|
||
|
|
VMK_ReturnStatus vmk_UnregisterAddEntropyFunction(
|
||
|
|
vmk_ModuleID moduleID,
|
||
|
|
vmk_AddEntropyFunction function);
|
||
|
|
|
||
|
|
/*
|
||
|
|
***********************************************************************
|
||
|
|
* vmk_UnregisterGetEntropyFunction -- */ /**
|
||
|
|
*
|
||
|
|
* \ingroup Entropy
|
||
|
|
* \brief Unregister an entropy function (removes for all types of entropy)
|
||
|
|
*
|
||
|
|
* \param[in] moduleID Module ID of the entropy module
|
||
|
|
* \param[in] function Function that returns entropy
|
||
|
|
*
|
||
|
|
* \retval VMK_OK Entropy function was sucessfully unregistered.
|
||
|
|
* \retval VMK_FAILURE Entropy function was not unregistered.
|
||
|
|
*
|
||
|
|
***********************************************************************
|
||
|
|
*/
|
||
|
|
VMK_ReturnStatus vmk_UnregisterGetEntropyFunction(
|
||
|
|
vmk_ModuleID moduleID,
|
||
|
|
vmk_GetEntropyFunction function);
|
||
|
|
|
||
|
|
#endif /* _VMKAPI_ENTROPY_H_ */
|
||
|
|
/** @} */
|