aboutsummaryrefslogtreecommitdiff
path: root/src/crypto/slow-hash.c
diff options
context:
space:
mode:
authorDavid G. Andersen <dave.andersen@gmail.com>2014-10-05 12:33:39 -0400
committerDavid G. Andersen <dave.andersen@gmail.com>2014-10-05 12:33:39 -0400
commit4d493f6d4f7a1501549056029ad0ca219e7e884a (patch)
treeb298bfbd12acff22600fa574d9e760ca90346e42 /src/crypto/slow-hash.c
parentadded other skipped commit (diff)
downloadmonero-4d493f6d4f7a1501549056029ad0ca219e7e884a.tar.xz
initial doxygen commenting of the CryptoNight proof-of-work code
Diffstat (limited to 'src/crypto/slow-hash.c')
-rw-r--r--src/crypto/slow-hash.c86
1 files changed, 85 insertions, 1 deletions
diff --git a/src/crypto/slow-hash.c b/src/crypto/slow-hash.c
index d4f27e1e1..46edb0fc1 100644
--- a/src/crypto/slow-hash.c
+++ b/src/crypto/slow-hash.c
@@ -166,6 +166,11 @@ STATIC INLINE void xor_blocks(uint8_t *a, const uint8_t *b)
U64(a)[1] ^= U64(b)[1];
}
+/**
+ * @brief uses cpuid to determine if the CPU supports the AES instructions
+ * @return true if the CPU supports AES, false otherwise
+ */
+
STATIC INLINE int check_aes_hw(void)
{
int cpuid_results[4];
@@ -205,6 +210,20 @@ STATIC INLINE void aes_256_assist2(__m128i* t1, __m128i * t3)
*t3 = _mm_xor_si128(*t3, t2);
}
+/**
+ * @brief expands 'key' into a form it can be used for AES encryption.
+ *
+ * This is an SSE-optimized implementation of AES key schedule generation. It
+ * expands the key into multiple round keys, each of which is used in one round
+ * of the AES encryption used to fill (and later, extract randomness from)
+ * the large 2MB buffer. Note that CryptoNight does not use a completely
+ * standard AES encryption for its buffer expansion, so do not copy this
+ * function outside of Monero without caution!
+ *
+ * @param key the input 128 bit key
+ * @param expandedKey An output buffer to hold the generated key schedule
+ */
+
STATIC INLINE void aes_expand_key(const uint8_t *key, uint8_t *expandedKey)
{
__m128i *ek = R128(expandedKey);
@@ -245,6 +264,22 @@ STATIC INLINE void aes_expand_key(const uint8_t *key, uint8_t *expandedKey)
ek[10] = t1;
}
+/*
+ * @brief a "pseudo" round of AES (similar to slightly different from normal AES encryption)
+ *
+ * To fill its 2MB scratch buffer, CryptoNight uses a nonstandard implementation
+ * of AES encryption: It applies 10 rounds of the basic AES encryption operation
+ * to an input 128 bit chunk of data <in>. Unlike normal AES, however, this is
+ * all it does; it does not perform the initial AddRoundKey step (this is done
+ * in subsequent steps by aesenc_si128), and it does not use the simpler final round.
+ * Hence, this is a "pseudo" round - though the function actually implements 10 rounds together.
+ *
+ * @param in a pointer to nblocks * 128 bits of data to be encrypted
+ * @param out a pointer to an nblocks * 128 bit buffer where the output will be stored
+ * @param expandedKey the expanded AES key
+ * @param nblocks the number of 128 blocks of data to be encrypted
+ */
+
STATIC INLINE void aes_pseudo_round(const uint8_t *in, uint8_t *out,
const uint8_t *expandedKey, int nblocks)
{
@@ -376,9 +411,37 @@ void slow_hash_free_state(void)
hp_allocated = 0;
}
+/**
+ * @brief the hash function implementing CryptoNight, used for the Monero proof-of-work
+ *
+ * Computes the hash of <data> (which consists of <length> bytes), returning the
+ * hash in <hash>. The CryptoNight hash operates by first using Keccak 1600,
+ * the 1600 bit variant of the Keccak hash used in SHA-3, to create a 200 byte
+ * buffer of pseudorandom data by hashing the supplied data. It then uses this
+ * random data to fill a large 2MB buffer with pseudorandom data by iteratively
+ * encrypting it using 10 rounds of AES per entry. After this initialization,
+ * it executes 500,000 rounds of mixing through the random 2MB buffer using
+ * AES (typically provided in hardware on modern CPUs) and a 64 bit multiply.
+ * Finally, it re-mixes this large buffer back into
+ * the 200 byte "text" buffer, and then hashes this buffer using one of four
+ * pseudorandomly selected hash functions (Blake, Groestl, JH, or Skein)
+ * to populate the output.
+ *
+ * The 2MB buffer and choice of functions for mixing are designed to make the
+ * algorithm "CPU-friendly" (and thus, reduce the advantage of GPU, FPGA,
+ * or ASIC-based implementations): the functions used are fast on modern
+ * CPUs, and the 2MB size matches the typical amount of L3 cache available per
+ * core on 2013-era CPUs. When available, this implementation will use hardware
+ * AES support on x86 CPUs.
+ *
+ * @param data the data to hash
+ * @param length the length in bytes of the data
+ * @param hash a pointer to a buffer in which the final hash will be stored
+ */
+
void cn_slow_hash(const void *data, size_t length, char *hash)
{
- RDATA_ALIGN16 uint8_t expandedKey[240];
+ RDATA_ALIGN16 uint8_t expandedKey[240]; /* These buffers are aligned to use later with SSE functions */
uint8_t text[INIT_SIZE_BYTE];
RDATA_ALIGN16 uint64_t a[2];
@@ -402,9 +465,15 @@ void cn_slow_hash(const void *data, size_t length, char *hash)
if(hp_state == NULL)
slow_hash_allocate_state();
+ /* CryptoNight Step 1: Use Keccak1600 to initialize the 'state' (and 'text') buffers from the data. */
+
hash_process(&state.hs, data, length);
memcpy(text, state.init, INIT_SIZE_BYTE);
+ /* CryptoNight Step 2: Iteratively encrypt the results from keccak to fill
+ * the 2MB large random access buffer.
+ */
+
if(useAes)
{
aes_expand_key(state.hs.b, expandedKey);
@@ -432,6 +501,11 @@ void cn_slow_hash(const void *data, size_t length, char *hash)
U64(b)[0] = U64(&state.k[16])[0] ^ U64(&state.k[48])[0];
U64(b)[1] = U64(&state.k[16])[1] ^ U64(&state.k[48])[1];
+ /* CryptoNight Step 3: Bounce randomly 1 million times through the mixing buffer,
+ * using 500,000 iterations of the following mixing function. Each execution
+ * performs two reads and writes from the mixing buffer.
+ */
+
_b = _mm_load_si128(R128(b));
// this is ugly but the branching affects the loop somewhat so put it outside.
if(useAes)
@@ -454,6 +528,10 @@ void cn_slow_hash(const void *data, size_t length, char *hash)
}
}
+ /* CryptoNight Step 4: Sequentially pass through the mixing buffer and use 10 rounds
+ * of AES encryption to mix the random data back into the 'text' buffer. 'text'
+ * was originally created with the output of Keccak1600. */
+
memcpy(text, state.init, INIT_SIZE_BYTE);
if(useAes)
{
@@ -478,6 +556,12 @@ void cn_slow_hash(const void *data, size_t length, char *hash)
oaes_free((OAES_CTX **) &aes_ctx);
}
+ /* CryptoNight Step 5: Use the resulting data to select which of four
+ * finalizer hash functions to apply to the data (Blake, Groestl, JH, or Skein).
+ * Use this hash to squeeze the 200 byte pseudorandom state array down
+ * to the final hash output.
+ */
+
memcpy(state.init, text, INIT_SIZE_BYTE);
hash_permutation(&state.hs);
extra_hashes[state.hs.b[0] & 3](&state, 200, hash);