Update Argon2 for style

- Make sure notice licenses are embedded
- Remove copyright and docs from headers

third_party/argon2/core.c

@@ -1,27 +1,32 @@
+/*-*- mode:c;indent-tabs-mode:nil;c-basic-offset:4;tab-width:8;coding:utf-8 -*-│
+│vi: set net ft=c ts=4 sts=4 sw=4 fenc=utf-8                                :vi│
+╚──────────────────────────────────────────────────────────────────────────────╝
+│                                                                              │
+│ Argon2 reference source code package - reference C implementations           │
+│                                                                              │
+│ Copyright 2015                                                               │
+│ Daniel Dinu, Dmitry Khovratovich, Jean-Philippe Aumasson, and Samuel Neves   │
+│                                                                              │
+│ You may use this work under the terms of a Creative Commons CC0 1.0          │
+│ License/Waiver or the Apache Public License 2.0, at your option. The         │
+│ terms of these licenses can be found at:                                     │
+│                                                                              │
+│ - CC0 1.0 Universal : https://creativecommons.org/publicdomain/zero/1.0      │
+│ - Apache 2.0        : https://www.apache.org/licenses/LICENSE-2.0            │
+│                                                                              │
+╚─────────────────────────────────────────────────────────────────────────────*/
 #include "libc/mem/mem.h"
 #include "third_party/argon2/blake2-impl.h"
 #include "third_party/argon2/blake2.h"
 #include "third_party/argon2/core.h"
+
+asm(".ident\t\"\\n\\n\
+argon2 (CC0 or Apache2)\\n\
+Copyright 2016 Daniel Dinu, Dmitry Khovratovich\\n\
+Copyright 2016 Jean-Philippe Aumasson, Samuel Neves\"");
 /* clang-format off */
 
-/*
- * Argon2 reference source code package - reference C implementations
- *
- * Copyright 2015
- * Daniel Dinu, Dmitry Khovratovich, Jean-Philippe Aumasson, and Samuel Neves
- *
- * You may use this work under the terms of a Creative Commons CC0 1.0
- * License/Waiver or the Apache Public License 2.0, at your option. The terms of
- * these licenses can be found at:
- *
- * - CC0 1.0 Universal : https://creativecommons.org/publicdomain/zero/1.0
- * - Apache 2.0        : https://www.apache.org/licenses/LICENSE-2.0
- *
- * You should have received a copy of both of these licenses along with this
- * software. If not, they may be obtained at the above URLs.
- */
-
-/***************Instance and Position constructors**********/
+int FLAG_clear_internal_memory = 1;
 
 void init_block_value(block *b, uint8_t in) {
     memset(b->v, in, sizeof(b->v));
@@ -52,34 +57,45 @@ static void store_block(void *output, const block *src) {
     }
 }
 
-/***************Memory functions*****************/
-
+/**
+ * Allocates memory to the given pointer, uses the appropriate allocator as
+ * specified in the context. Total allocated memory is num*size.
+ * @param context argon2_context which specifies the allocator
+ * @param memory pointer to the pointer to the memory
+ * @param size the size in bytes for each element to be allocated
+ * @param num the number of elements to be allocated
+ * @return ARGON2_OK if @memory is a valid pointer and memory is allocated
+ */
 int allocate_memory(const argon2_context *context, uint8_t **memory,
                     size_t num, size_t size) {
     size_t memory_size = num*size;
     if (memory == NULL) {
         return ARGON2_MEMORY_ALLOCATION_ERROR;
     }
-
     /* 1. Check for multiplication overflow */
     if (size != 0 && memory_size / size != num) {
         return ARGON2_MEMORY_ALLOCATION_ERROR;
     }
-
     /* 2. Try to allocate with appropriate allocator */
     if (context->allocate_cbk) {
         (context->allocate_cbk)(memory, memory_size);
     } else {
         *memory = malloc(memory_size);
     }
-
     if (*memory == NULL) {
         return ARGON2_MEMORY_ALLOCATION_ERROR;
     }
-
     return ARGON2_OK;
 }
 
+/**
+ * Frees memory at the given pointer, uses the appropriate deallocator as
+ * specified in the context. Also cleans the memory using clear_internal_memory.
+ * @param context argon2_context which specifies the deallocator
+ * @param memory pointer to buffer to be freed
+ * @param size the size in bytes for each element to be deallocated
+ * @param num the number of elements to be deallocated
+ */
 void free_memory(const argon2_context *context, uint8_t *memory,
                  size_t num, size_t size) {
     size_t memory_size = num*size;
@@ -91,14 +107,31 @@ void free_memory(const argon2_context *context, uint8_t *memory,
     }
 }
 
-/* Memory clear flag defaults to true. */
-int FLAG_clear_internal_memory = 1;
+/**
+ * Function that securely clears the memory if
+ * FLAG_clear_internal_memory is set. If the flag isn't set, this
+ * function does nothing.
+ *
+ * @param mem Pointer to the memory
+ * @param s Memory size in bytes
+ */
 void clear_internal_memory(void *v, size_t n) {
   if (FLAG_clear_internal_memory && v) {
     explicit_bzero(v, n);
   }
 }
 
+/**
+ * XORing the last block of each lane, hashing it, making the tag.
+ * Deallocates the memory.
+ *
+ * @param context current Argon2 context (use only the out parameters from it)
+ * @param instance Pointer to current instance of Argon2
+ * @pre instance->state must point to necessary amount of memory
+ * @pre context->out must point to outlen bytes of memory
+ * @pre if context->free_cbk is not NULL, it should point to a function that
+ * deallocates memory
+ */
 void finalize(const argon2_context *context, argon2_instance_t *instance) {
     if (context != NULL && instance != NULL) {
         block blockhash;
@@ -129,6 +162,16 @@ void finalize(const argon2_context *context, argon2_instance_t *instance) {
     }
 }
 
+/**
+ * Computes absolute position of reference block in the lane following a skewed
+ * distribution and using a pseudo-random value as input
+ * @param instance Pointer to the current instance
+ * @param position Pointer to the current position
+ * @param pseudo_rand 32-bit pseudo-random value used to determine the position
+ * @param same_lane Indicates if the block will be taken from the current lane.
+ * If so we can reference the current segment
+ * @pre All pointers must be valid
+ */
 uint32_t index_alpha(const argon2_instance_t *instance,
                      const argon2_position_t *position, uint32_t pseudo_rand,
                      int same_lane) {
@@ -309,6 +352,12 @@ fail:
 
 #endif /* ARGON2_NO_THREADS */
 
+/**
+ * Function that fills the entire memory t_cost times based on the first two
+ * blocks in each lane
+ * @param instance Pointer to the current instance
+ * @return ARGON2_OK if successful, @context->state
+ */
 int fill_memory_blocks(argon2_instance_t *instance) {
 	if (instance == NULL || instance->lanes == 0) {
 	    return ARGON2_INCORRECT_PARAMETER;
@@ -321,6 +370,14 @@ int fill_memory_blocks(argon2_instance_t *instance) {
 #endif
 }
 
+/**
+ * Function that validates all inputs against predefined restrictions
+ * and return an error code.
+ *
+ * @param context Pointer to current Argon2 context
+ * @return ARGON2_OK if everything is all right, otherwise one of error
+ *     codes (all defined in argon.h)
+ */
 int validate_inputs(const argon2_context *context) {
     if (NULL == context) {
         return ARGON2_INCORRECT_PARAMETER;
@@ -448,6 +505,12 @@ int validate_inputs(const argon2_context *context) {
     return ARGON2_OK;
 }
 
+/**
+ * Function creates first 2 blocks per lane
+ * @param instance Pointer to the current instance
+ * @param blockhash Pointer to the pre-hashing digest
+ * @pre blockhash must point to @a PREHASH_SEED_LENGTH allocated values
+ */
 void fill_first_blocks(uint8_t *blockhash, const argon2_instance_t *instance) {
     uint32_t l;
     /* Make the first and second block in each lane as G(H0||0||i) or
@@ -471,6 +534,17 @@ void fill_first_blocks(uint8_t *blockhash, const argon2_instance_t *instance) {
     clear_internal_memory(blockhash_bytes, ARGON2_BLOCK_SIZE);
 }
 
+/**
+ * Hashes all the inputs into @a blockhash[PREHASH_DIGEST_LENGTH],
+ * clears password and secret if needed
+ *
+ * @param context Pointer to the Argon2 internal structure containing
+ *     memory pointer, and parameters for time and space requirements
+ * @param  blockhash Buffer for pre-hashing digest
+ * @param  type Argon2 type
+ * @pre @a blockhash must have at least @a PREHASH_DIGEST_LENGTH bytes
+ *         allocated
+ */
 void initial_hash(uint8_t *blockhash, argon2_context *context,
                   argon2_type type) {
     blake2b_state BlakeHash;
@@ -545,6 +619,17 @@ void initial_hash(uint8_t *blockhash, argon2_context *context,
     blake2b_final(&BlakeHash, blockhash, ARGON2_PREHASH_DIGEST_LENGTH);
 }
 
+/**
+ * Function allocates memory, hashes the inputs with Blake, and creates
+ * first two blocks. Returns the pointer to the main memory with 2
+ * blocks per lane initialized.
+ *
+ * @param  context  Pointer to the Argon2 internal structure containing memory
+ *     pointer, and parameters for time and space requirements.
+ * @param  instance Current Argon2 instance
+ * @return Zero if successful, -1 if memory failed to allocate. @context->state
+ *     will be modified if successful.
+ */
 int initialize(argon2_instance_t *instance, argon2_context *context) {
     uint8_t blockhash[ARGON2_PREHASH_SEED_LENGTH];
     int result = ARGON2_OK;