Crypto++ 7.0 Free C++ class library of cryptographic schemes

darn.h
Go to the documentation of this file.
1 // darn.h - written and placed in public domain by Jeffrey Walton
2 // DARN requires POWER9/ISA 3.0.
3
4 // At the moment only GCC 7.0 (and above) seems to support __builtin_darn()
5 // and __builtin_darn_32(). Clang 7.0 does not provide them, but it does
6 // support assembly instructions. XLC is unknown, but there are no hits when
7 // searching IBM's site. To cover more platforms we provide GCC inline
8 // assembly like we do with RDRAND and RDSEED. Platforms that don't support
9 // GCC inline assembly or the builtin will fail the compile. Also see
10 // https://gcc.gnu.org/onlinedocs/gcc/Basic-PowerPC-Built-in-Functions-Available-on-ISA-3_002e0.html
11
12 /// \file darn.h
13 /// \brief Classes for DARN RNG
14 /// \sa <A HREF="https://openpowerfoundation.org/?resource_lib=power-isa-version-3-0">Power
15 /// ISA Version 3.0B</A>
16 /// \since Crypto++ 8.0
17
18 #ifndef CRYPTOPP_DARN_H
19 #define CRYPTOPP_DARN_H
20
21 #include "cryptlib.h"
22
23 NAMESPACE_BEGIN(CryptoPP)
24
25 /// \brief Exception thrown when a DARN generator encounters
26 /// a generator related error.
27 /// \since Crypto++ 8.0
28 class DARN_Err : public Exception
29 {
30 public:
31 DARN_Err(const std::string &operation)
32 : Exception(OTHER_ERROR, "DARN: " + operation + " operation failed") {}
33 };
34
35 /// \brief Hardware generated random numbers using DARN instruction
36 /// \details DARN() provides access to Power9's random number generator. The
37 /// Crypto++ implementation provides conditioned random numbers from the
38 /// generator as opposed to raw random numbers. According to Power ISA 3.0B
39 /// manual, a conditioned random number has been processed by hardware to
40 /// reduce bias. A raw random number is unconditioned noise source output.
41 /// \details According to Power ISA 3.0B manual, the random number generator
42 /// provided by the <tt>darn</tt> instruction is NIST SP800-90B and SP800-90C
43 /// compliant to the extent possible given the completeness of the standards
44 /// at the time the hardware is designed. The random number generator provides
45 /// a minimum of 0.5 bits of entropy per bit.
46 /// \par Wraps
47 /// darn instruction
48 /// \sa <A HREF="https://openpowerfoundation.org/?resource_lib=power-isa-version-3-0">Power
49 /// ISA Version 3.0B</A>, MaurerRandomnessTest() for random bit generators
50 /// \since Crypto++ 8.0
51 class DARN : public RandomNumberGenerator
52 {
53 public:
54 CRYPTOPP_STATIC_CONSTEXPR const char* StaticAlgorithmName() { return "DARN"; }
55
56 virtual ~DARN() {}
57
58 /// \brief Construct a DARN generator
59 /// \throws DARN_Err if the random number generator is not available
60 DARN();
61
62 /// \brief Generate random array of bytes
63 /// \param output the byte buffer
64 /// \param size the length of the buffer, in bytes
65 virtual void GenerateBlock(byte *output, size_t size);
66
67 /// \brief Generate and discard n bytes
68 /// \param n the number of bytes to generate and discard
69 /// \details the RDSEED generator discards words, not bytes. If n is
70 /// not a multiple of a machine word, then it is rounded up to
71 /// that size.
72 virtual void DiscardBytes(size_t n);
73
74 /// \brief Update RNG state with additional unpredictable values
75 /// \param input unused
76 /// \param length unused
77 /// \details The operation is a nop for this generator.
78 virtual void IncorporateEntropy(const byte *input, size_t length)
79 {
80 // Override to avoid the base class' throw.
81 CRYPTOPP_UNUSED(input); CRYPTOPP_UNUSED(length);
82 }
83
84 std::string AlgorithmProvider() const {
85 return "Power9";
86 }
87
88 private:
89 SecBlock<byte, AllocatorWithCleanup<byte, true> > m_temp;
90 };
91
92 NAMESPACE_END
93
94 #endif // CRYPTOPP_DARN_H
DARN::DARN
DARN()
Construct a DARN generator.
Definition: darn.cpp:216
DARN::AlgorithmProvider
std::string AlgorithmProvider() const
Retrieve the provider of this algorithm.
Definition: darn.h:84
Exception
Base class for all exceptions thrown by the library.
Definition: cryptlib.h:158
DARN_Err
Exception thrown when a DARN generator encounters a generator related error.
Definition: darn.h:28
SecBlock
Secure memory block with allocator and cleanup.
Definition: secblock.h:682
cryptlib.h
Abstract base classes that provide a uniform interface to this library.
RandomNumberGenerator
Interface for random number generators.
Definition: cryptlib.h:1349
DARN::GenerateBlock
virtual void GenerateBlock(byte *output, size_t size)
Generate random array of bytes.
Definition: darn.cpp:221
DARN::DiscardBytes
virtual void DiscardBytes(size_t n)
Generate and discard n bytes.
Definition: darn.cpp:227
DARN
Hardware generated random numbers using DARN instruction.
Definition: darn.h:51
CryptoPP
Crypto++ library namespace.
DARN::IncorporateEntropy
virtual void IncorporateEntropy(const byte *input, size_t length)
Update RNG state with additional unpredictable values.
Definition: darn.h:78