include/cryptopp/darn.h

0001 // darn.h - written and placed in public domain by Jeffrey Walton

0002 //          DARN requires POWER9/ISA 3.0.

0003
0004 // At the moment only GCC 7.0 (and above) seems to support __builtin_darn()

0005 // and __builtin_darn_32(). However, GCC generates incorrect code. Clang 7.0

0006 // does not provide them, but it does support assembly instructions. XLC is

0007 // unknown, but there are no hits when searching IBM's site. To cover more

0008 // platforms we provide GCC inline assembly like we do with RDRAND and RDSEED.

0009 // Platforms that don't support GCC inline assembly or the builtin will fail

0010 // to compile. Also see https://gcc.gnu.org/bugzilla/show_bug.cgi?id=91481 and

0011 // https://gcc.gnu.org/onlinedocs/gcc/Basic-PowerPC-Built-in-Functions-Available-on-ISA-3_002e0.html

0012
0013 /// \file darn.h

0014 /// \brief Classes for DARN RNG

0015 /// \sa <A HREF="https://openpowerfoundation.org/?resource_lib=power-isa-version-3-0">Power

0016 ///   ISA Version 3.0B</A>

0017 /// \since Crypto++ 8.0

0018
0019 #ifndef CRYPTOPP_DARN_H
0020 #define CRYPTOPP_DARN_H
0021
0022 #include "cryptlib.h"
0023
0024 NAMESPACE_BEGIN(CryptoPP)
0025
0026 /// \brief Exception thrown when a DARN generator encounters

0027 ///    a generator related error.

0028 /// \since Crypto++ 8.0

0029 class DARN_Err : public Exception
0030 {
0031 public:
0032     DARN_Err(const std::string &operation)
0033         : Exception(OTHER_ERROR, "DARN: " + operation + " operation failed") {}
0034 };
0035
0036 /// \brief Hardware generated random numbers using DARN instruction

0037 /// \details DARN() provides access to Power9's random number generator. The

0038 ///   Crypto++ implementation provides conditioned random numbers from the

0039 ///   generator as opposed to raw random numbers. According to Power ISA 3.0B

0040 ///   manual, a conditioned random number has been processed by hardware to

0041 ///   reduce bias. A raw random number is unconditioned noise source output.

0042 /// \details According to Power ISA 3.0B manual, the random number generator

0043 ///   provided by the <tt>darn</tt> instruction is NIST SP800-90B and SP800-90C

0044 ///   compliant to the extent possible given the completeness of the standards

0045 ///   at the time the hardware is designed. The random number generator provides

0046 ///   a minimum of 0.5 bits of entropy per bit.

0047 /// \par Wraps

0048 ///   darn instruction

0049 /// \sa <A HREF="https://openpowerfoundation.org/?resource_lib=power-isa-version-3-0">Power

0050 ///   ISA Version 3.0B</A>, MaurerRandomnessTest() for random bit generators

0051 /// \since Crypto++ 8.0

0052 class DARN : public RandomNumberGenerator
0053 {
0054 public:
0055     CRYPTOPP_STATIC_CONSTEXPR const char* StaticAlgorithmName() { return "DARN"; }
0056
0057     virtual ~DARN() {}
0058
0059     /// \brief Construct a DARN generator

0060      /// \throw DARN_Err if the random number generator is not available

0061     DARN();
0062
0063     /// \brief Generate random array of bytes

0064     /// \param output the byte buffer

0065     /// \param size the length of the buffer, in bytes

0066     virtual void GenerateBlock(byte *output, size_t size);
0067
0068     /// \brief Generate and discard n bytes

0069     /// \param n the number of bytes to generate and discard

0070     /// \details the RDSEED generator discards words, not bytes. If n is

0071     ///   not a multiple of a machine word, then it is rounded up to

0072     ///   that size.

0073     virtual void DiscardBytes(size_t n);
0074
0075     /// \brief Update RNG state with additional unpredictable values

0076     /// \param input unused

0077     /// \param length unused

0078     /// \details The operation is a nop for this generator.

0079     virtual void IncorporateEntropy(const byte *input, size_t length)
0080     {
0081         // Override to avoid the base class' throw.

0082         CRYPTOPP_UNUSED(input); CRYPTOPP_UNUSED(length);
0083     }
0084
0085     std::string AlgorithmProvider() const {
0086         return "Power9";
0087     }
0088
0089 private:
0090     SecBlock<byte, AllocatorWithCleanup<byte, true> > m_temp;
0091 };
0092
0093 NAMESPACE_END
0094
0095 #endif // CRYPTOPP_DARN_H