rework build hierarchy to prepare for generated headers

Doxyfile

@@ -58,7 +58,7 @@ PROJECT_LOGO           =
 # entered, it will be relative to the location where doxygen was started. If
 # left blank the current directory will be used.
 
-OUTPUT_DIRECTORY       = doc
+OUTPUT_DIRECTORY       = build/doc
 
 # If the CREATE_SUBDIRS tag is set to YES, then doxygen will create 4096 sub-
 # directories (in 2 levels) under the output directory of each output format and

Makefile

@@ -5,6 +5,20 @@
 UNAME := $(shell uname)
 MACHINE := $(shell uname -m)
 
+# Subdirectories for objects etc.
+# Many of them are mapped to build/obj right now, but could be split later.
+# The non-build/obj directories are the public interface.
+BUILD_ASM = build/obj
+BUILD_OBJ = build/obj
+BUILD_C   = build/obj
+BUILD_PY  = build/obj
+BUILD_LIB = build/lib
+BUILD_INC = build/include
+BUILD_BIN = build/bin
+BUILD_IBIN = build/obj/bin
+BATBASE=ed448goldilocks_decaf_bats_$(TODAY)
+BATNAME=build/$(BATBASE)
+
 ifeq ($(UNAME),Darwin)
 CC = clang
 CXX = clang++
@@ -29,9 +43,8 @@ FIELD ?= p25519
 
 WARNFLAGS = -pedantic -Wall -Wextra -Werror -Wunreachable-code \
 	 -Wmissing-declarations -Wunused-function -Wno-overlength-strings $(EXWARN)
-	 
-	 
-INCFLAGS = -Isrc/include -Iinclude -Isrc/$(FIELD) -Isrc/$(FIELD)/$(ARCH)
+
+INCFLAGS = -Isrc/include -Isrc/public_include -Isrc/$(FIELD) -Isrc/$(FIELD)/$(ARCH)
 LANGFLAGS = -std=c99 -fno-strict-aliasing
 LANGXXFLAGS = -fno-strict-aliasing
 GENFLAGS = -ffunction-sections -fdata-sections -fvisibility=hidden -fomit-frame-pointer -fPIC
@@ -55,136 +68,143 @@ ifeq ($(CC),clang)
 WARNFLAGS += -Wgcc-compat
 endif
 
-SAGE ?= sage
-SAGES= $(shell ls test/*.sage)
-BUILDPYS= $(SAGES:test/%.sage=build/%.py)
-
 ARCHFLAGS += $(XARCHFLAGS)
 CFLAGS  = $(LANGFLAGS) $(WARNFLAGS) $(INCFLAGS) $(OFLAGS) $(ARCHFLAGS) $(GENFLAGS) $(XCFLAGS)
 CXXFLAGS = $(LANGXXFLAGS) $(WARNFLAGS) $(INCFLAGS) $(OFLAGS) $(ARCHFLAGS) $(GENFLAGS) $(XCXXFLAGS) 
 LDFLAGS = $(ARCHFLAGS) $(XLDFLAGS)
 ASFLAGS = $(ARCHFLAGS) $(XASFLAGS)
 
-.PHONY: clean all test bench todo doc lib bat sage sagetest
-.PRECIOUS: build/%.s
+SAGE ?= sage
+SAGES= $(shell ls test/*.sage)
+BUILDPYS= $(SAGES:test/%.sage=$(BUILD_PY)/%.py)
 
-HEADERS= Makefile $(shell find src include test -name "*.h") $(shell find . -name "*.hxx") build/timestamp
+.PHONY: clean all test bench todo doc lib bat sage sagetest
+.PRECIOUS: $(BUILD_ASM)/%.s
 
+HEADERS= Makefile $(shell find src test -name "*.h") $(shell find . -name "*.hxx") $(BUILD_OBJ)/timestamp
 
-DECAFCOMPONENTS= build/$(DECAF).o build/shake.o build/decaf_crypto.o \
-	build/$(FIELD).o build/f_arithmetic.o build/utils.o
+DECAFCOMPONENTS= $(BUILD_OBJ)/$(DECAF).o $(BUILD_OBJ)/shake.o $(BUILD_OBJ)/decaf_crypto.o \
+	$(BUILD_OBJ)/$(FIELD).o $(BUILD_OBJ)/f_arithmetic.o $(BUILD_OBJ)/utils.o
 ifeq ($(DECAF),decaf_fast)
-DECAFCOMPONENTS += build/decaf_tables.o
+DECAFCOMPONENTS += $(BUILD_OBJ)/decaf_tables.o
 endif
 
-BENCHCOMPONENTS = build/bench.o build/shake.o
-
-BATBASE=ed448goldilocks_decaf_bats_$(TODAY)
-BATNAME=build/$(BATBASE)
+BENCHCOMPONENTS = $(BUILD_OBJ)/bench.o $(BUILD_OBJ)/shake.o
 
-all: lib  build/test build/bench build/shakesum
+all: lib $(BUILD_IBIN)/test $(BUILD_IBIN)/bench $(BUILD_BIN)/shakesum
 
 scan: clean
 	scan-build --use-analyzer=`which clang` \
 		 -enable-checker deadcode -enable-checker llvm \
 		 -enable-checker osx -enable-checker security -enable-checker unix \
-		make build/bench build/test all
+		make all
+		
+# The shakesum utility is in the public bin directory.
+$(BUILD_BIN)/shakesum: $(BUILD_OBJ)/shakesum.o $(BUILD_OBJ)/shake.o $(BUILD_OBJ)/utils.o
+	$(LD) $(LDFLAGS) -o $@ $^
+
+# The main decaf library, and its symlinks.
+lib: $(BUILD_LIB)/libdecaf.so
 
-build/test: build/test_decaf.o lib
+$(BUILD_LIB)/libdecaf.so: $(BUILD_LIB)/libdecaf.so.1
+	ln -sf `basename $^` $@
+
+$(BUILD_LIB)/libdecaf.so.1: $(DECAFCOMPONENTS)
+	rm -f $@
 ifeq ($(UNAME),Darwin)
-	$(LDXX) $(LDFLAGS) -o $@ $< -Lbuild -ldecaf
+	libtool -macosx_version_min 10.6 -dynamic -dead_strip -lc -x -o $@ \
+		  $(DECAFCOMPONENTS)
 else
-	$(LDXX) $(LDFLAGS) -Wl,-rpath,`pwd`/build -o $@ $< -Lbuild -ldecaf
+	$(LD) $(LDFLAGS) -shared -Wl,-soname,`basename $@` -Wl,--gc-sections -o $@ $(DECAFCOMPONENTS)
+	strip --discard-all $@
 endif
 
-build/bench: build/bench_decaf.o lib
+# Internal test programs, which are not part of the final build/bin directory.
+$(BUILD_IBIN)/test: $(BUILD_OBJ)/test_decaf.o lib
 ifeq ($(UNAME),Darwin)
-	$(LDXX) $(LDFLAGS) -o $@ $< -Lbuild -ldecaf
+	$(LDXX) $(LDFLAGS) -o $@ $< -L$(BUILD_LIB) -ldecaf
 else
-	$(LDXX) $(LDFLAGS) -Wl,-rpath,`pwd`/build -o $@ $< -Lbuild -ldecaf
+	$(LDXX) $(LDFLAGS) -Wl,-rpath,`pwd`/$(BUILD_LIB) -o $@ $< -L$(BUILD_LIB) -ldecaf
 endif
-	
-build/shakesum: build/shakesum.o build/shake.o build/utils.o
-	$(LD) $(LDFLAGS) -o $@ $^
-
-lib: build/libdecaf.so
 
-build/libdecaf.so: $(DECAFCOMPONENTS)
-	rm -f $@
+$(BUILD_IBIN)/bench: $(BUILD_OBJ)/bench_decaf.o lib
 ifeq ($(UNAME),Darwin)
-	libtool -macosx_version_min 10.6 -dynamic -dead_strip -lc -x -o $@ \
-		  $(DECAFCOMPONENTS)
+	$(LDXX) $(LDFLAGS) -o $@ $< -L$(BUILD_LIB) -ldecaf
 else
-	$(LD) $(LDFLAGS) -shared -Wl,-soname,libdecaf.so.1 -Wl,--gc-sections -o $@ $(DECAFCOMPONENTS)
-	strip --discard-all $@
-	ln -sf `basename $@` build/libdecaf.so.1
+	$(LDXX) $(LDFLAGS) -Wl,-rpath,`pwd`/$(BUILD_LIB) -o $@ $< -L$(BUILD_LIB) -ldecaf
 endif
 
-build/timestamp:
-	mkdir -p build
+# Create all the build subdirectories
+$(BUILD_OBJ)/timestamp:
+	mkdir -p $(BUILD_ASM) $(BUILD_OBJ) $(BUILD_C) $(BUILD_PY) \
+		$(BUILD_LIB) $(BUILD_INC) $(BUILD_BIN) $(BUILD_IBIN) $(BUILD_INC)/decaf
 	touch $@
 
-build/%.o: build/%.s
+$(BUILD_OBJ)/%.o: $(BUILD_ASM)/%.s
 	$(ASM) $(ASFLAGS) -c -o $@ $<
 
-build/decaf_gen_tables: build/decaf_gen_tables.o build/$(DECAF).o build/$(FIELD).o build/f_arithmetic.o build/utils.o
+$(BUILD_IBIN)/decaf_gen_tables: $(BUILD_OBJ)/decaf_gen_tables.o \
+		$(BUILD_OBJ)/$(DECAF).o $(BUILD_OBJ)/$(FIELD).o $(BUILD_OBJ)/f_arithmetic.o $(BUILD_OBJ)/utils.o
 	$(LD) $(LDFLAGS) -o $@ $^
 	
-build/decaf_tables.c: build/decaf_gen_tables
+$(BUILD_C)/decaf_tables.c: $(BUILD_IBIN)/decaf_gen_tables
 	./$< > $@
 	
-build/decaf_tables.s: build/decaf_tables.c $(HEADERS)
+$(BUILD_ASM)/decaf_tables.s: $(BUILD_C)/decaf_tables.c $(HEADERS)
 	$(CC) $(CFLAGS) -S -c -o $@ $<
 	
-build/%.s: src/%.c $(HEADERS)
+$(BUILD_ASM)/%.s: src/%.c $(HEADERS)
 	$(CC) $(CFLAGS) -S -c -o $@ $<
 	
-build/%.s: src/%.cxx $(HEADERS)
+$(BUILD_ASM)/%.s: src/%.cxx $(HEADERS)
 	$(CXX) $(CXXFLAGS) -S -c -o $@ $<
 
-build/%.s: test/%.c $(HEADERS)
+$(BUILD_ASM)/%.s: test/%.c $(HEADERS)
 	$(CC) $(CFLAGS) -S -c -o $@ $<
 
-build/%.s: test/%.cxx $(HEADERS)
+$(BUILD_ASM)/%.s: test/%.cxx $(HEADERS)
 	$(CXX) $(CXXFLAGS) -S -c -o $@ $<
 
-build/%.s: src/$(FIELD)/$(ARCH)/%.c $(HEADERS)
+$(BUILD_ASM)/%.s: src/$(FIELD)/$(ARCH)/%.c $(HEADERS)
 	$(CC) $(CFLAGS) -S -c -o $@ $<
 
-build/%.s: src/$(FIELD)/%.c $(HEADERS)
+$(BUILD_ASM)/%.s: src/$(FIELD)/%.c $(HEADERS)
 	$(CC) $(CFLAGS) -S -c -o $@ $<
-	
+
+# The sage test scripts
 sage: $(BUILDPYS)
 
 sagetest: sage lib
-	LD_LIBRARY_PATH=build sage build/test_decaf.sage
+	LD_LIBRARY_PATH=$(BUILD_LIB) sage $(BUILD_PY)/test_decaf.sage
 
-$(BUILDPYS): $(SAGES) build/timestamp
-	cp -f $(SAGES) build/
-	$(SAGE) --preparse $(SAGES:test/%.sage=build/%.sage)
+$(BUILDPYS): $(SAGES) $(BUILD_OBJ)/timestamp
+	cp -f $(SAGES) $(BUILD_PY)/
+	$(SAGE) --preparse $(SAGES:test/%.sage=$(BUILD_PY)/%.sage)
 	# some sage versions compile to .sage.py
-	for f in $(SAGES:test/%.sage=build/%); do \
+	for f in $(SAGES:test/%.sage=$(BUILD_PY)/%); do \
 		 if [ -e $$f.sage.py ]; then \
 		 	 mv $$f.sage.py $$f.py; \
 		 fi; \
 	  done
 
-doc/timestamp:
-	mkdir -p doc
+# The documentation files
+$(BUILD_DOC)/timestamp:
+	mkdir -p `dirname $@`
 	touch $@
 
-doc: Doxyfile doc/timestamp include/*.h src/*.c src/include/*.h src/$(FIELD)/$(ARCH)/*.c src/$(FIELD)/$(ARCH)/*.h
+doc: Doxyfile $(BUILD_OBJ)/timestamp $(HEADERS) src/*.c src/$(FIELD)/$(ARCH)/*.c src/$(FIELD)/$(ARCH)/*.h
 	doxygen > /dev/null
 
+# The eBATS benchmarking script
 bat: $(BATNAME)
 
-$(BATNAME): include/* src/* src/*/* test/batarch.map build/decaf_tables.c # TODO tables some other way
+$(BATNAME): include/* src/* src/*/* test/batarch.map $(BUILD_C)/decaf_tables.c # TODO tables some other way
 	rm -fr $@
 	for prim in dh sign; do \
           targ="$@/crypto_$$prim/ed448goldilocks_decaf"; \
 	  (while read arch where; do \
 	    mkdir -p $$targ/`basename $$arch`; \
-	    cp include/*.h build/decaf_tables.c src/decaf_fast.c src/decaf_crypto.c src/shake.c src/include/*.h src/bat/$$prim.c src/p448/$$where/*.c src/p448/$$where/*.h src/p448/*.c src/p448/*.h $$targ/`basename $$arch`; \
+	    cp include/*.h $(BUILD_C)/decaf_tables.c src/decaf_fast.c src/decaf_crypto.c src/shake.c src/include/*.h src/bat/$$prim.c src/p448/$$where/*.c src/p448/$$where/*.h src/p448/*.c src/p448/*.h $$targ/`basename $$arch`; \
 	    cp src/bat/api_$$prim.h $$targ/`basename $$arch`/api.h; \
 	    perl -p -i -e 's/SYSNAME/'`basename $(BATNAME)`_`basename $$arch`'/g' $$targ/`basename $$arch`/api.h;  \
 	    perl -p -i -e 's/__TODAY__/'$(TODAY)'/g' $$targ/`basename $$arch`/api.h;  \
@@ -193,31 +213,31 @@ $(BATNAME): include/* src/* src/*/* test/batarch.map build/decaf_tables.c # TODO
 	  echo 'Mike Hamburg' > $$targ/designers; \
 	  echo 'Ed448-Goldilocks Decaf sign and dh' > $$targ/description; \
         done
-	(cd build && tar czf $(BATBASE).tgz $(BATBASE) )
+	(cd $(BATNAME)/.. && tar czf $(BATBASE).tgz $(BATBASE) )
 	
-
+# Finds todo items in .h and .c files
 todo::
-	@(find * -name '*.h'; find * -name '*.c') | xargs egrep --color=auto -w \
+	@(find * -name '*.h' -or -name '*.c' -or -name '*.cxx' -or -name '*.hxx') | xargs egrep --color=auto -w \
 		'HACK|TODO|FIXME|BUG|XXX|PERF|FUTURE|REMOVE|MAGIC'
 	@echo '============================='
 	@(for i in FIXME BUG XXX TODO HACK PERF FUTURE REMOVE MAGIC; do \
-	  (find * -name '*.h'; find * -name '*.c') | xargs egrep -w $$i > /dev/null || continue; \
+	  (find * -name '*.h' -or -name '*.c' -or -name '*.cxx' -or -name '*.hxx') | xargs egrep -w $$i > /dev/null || continue; \
 	  /bin/echo -n $$i'       ' | head -c 10; \
-	  (find * -name '*.h'; find * -name '*.c') | xargs egrep -w $$i| wc -l; \
+	  (find * -name '*.h' -or -name '*.c' -or -name '*.cxx' -or -name '*.hxx') | xargs egrep -w $$i| wc -l; \
 	done)
 	@echo '============================='
 	@echo -n 'Total     '
-	@(find * -name '*.h'; find * -name '*.c') | xargs egrep -w \
+	@(find * -name '*.h' -or -name '*.c' -or -name '*.cxx' -or -name '*.hxx') | xargs egrep -w \
 		'HACK|TODO|FIXME|BUG|XXX|PERF|FUTURE|REMOVE|MAGIC' | wc -l
 
-bench: build/bench
+bench: $(BUILD_IBIN)/bench
 	./$<
 
-test: build/test
-	build/test
+test: $(BUILD_IBIN)/test
+	./$<
 	
-microbench: build/bench
+microbench: $(BUILD_IBIN)/bench
 	./$< --micro
 
 clean:
-	rm -fr build doc $(BATNAME)
+	rm -fr build $(BATNAME)

src/decaf.c

@@ -9,7 +9,7 @@
  */
 
 #define __STDC_WANT_LIB_EXT1__ 1 /* for memset_s */
-#include "decaf.h"
+#include <decaf.h>
 #include <string.h>
 #include <assert.h>
 

src/decaf_crypto.c

@@ -8,7 +8,7 @@
  * @brief Example Decaf cyrpto routines.
  */
 
-#include "decaf_crypto.h"
+#include <decaf/crypto.h>
 #include <string.h>
 
 static const unsigned int DECAF_255_SCALAR_OVERKILL_BYTES = DECAF_255_SCALAR_BYTES + 8;

src/decaf_fast.c

@@ -10,7 +10,7 @@
 
 #define _XOPEN_SOURCE 600 /* for posix_memalign */
 #define __STDC_WANT_LIB_EXT1__ 1 /* for memset_s */
-#include "decaf.h"
+#include <decaf.h>
 #include <string.h>
 #include "field.h"
 #include "decaf_config.h"

include/decaf.h → src/public_include/decaf.h

@@ -25,8 +25,8 @@
 #include <stdint.h>
 #include <sys/types.h>
 
-#include "decaf_255.h"
-#include "decaf_448.h"
+#include <decaf/decaf_255.h>
+#include <decaf/decaf_448.h>
 
 #endif /* __DECAF_H__ */
 

include/decaf.hxx → src/public_include/decaf.hxx

@@ -2,7 +2,7 @@
 #ifndef __DECAF_HXX__
 #define __DECAF_HXX__ 1
 
-#include "decaf_255.hxx" // MAGIC
+#include <decaf/decaf_255.hxx> // MAGIC
 
 #endif /* __DECAF_H__ */
 

include/decaf_common.h → src/public_include/decaf/common.h

@@ -1,5 +1,5 @@
 /**
- * @file decaf_common.h
+ * @file decaf/common.h
  * @author Mike Hamburg
  *
  * @copyright

include/decaf_crypto.h → src/public_include/decaf/crypto.h

@@ -1,5 +1,5 @@
 /**
- * @file decaf_crypto.h
+ * @file decaf/crypto.h
  * @copyright
  *   Copyright (c) 2015 Cryptography Research, Inc.  \n
  *   Released under the MIT License.  See LICENSE.txt for license information.
@@ -14,8 +14,8 @@
 #ifndef __DECAF_CRYPTO_H__
 #define __DECAF_CRYPTO_H__ 1
 
-#include "decaf.h"
-#include "shake.h"
+#include <decaf.h>
+#include <decaf/shake.h>
 
 /** Number of bytes for a symmetric key (expanded to full key) */
 #define DECAF_255_SYMMETRIC_KEY_BYTES 32

include/decaf_255.h → src/public_include/decaf/decaf_255.h

@@ -1,5 +1,5 @@
 /**
- * @file decaf_255.h
+ * @file decaf/decaf_255.h
  * @author Mike Hamburg
  *
  * @copyright
@@ -11,7 +11,7 @@
 #ifndef __DECAF_255_H__
 #define __DECAF_255_H__ 1
 
-#include "decaf_common.h"
+#include <decaf/common.h>
 
 #ifdef __cplusplus
 extern "C" {
@@ -467,7 +467,7 @@ void decaf_255_point_debugging_pscale (
  *   A factor of 2 due to the isogeny.
  *   A factor of 2 because we quotient out the 2-torsion.
  *
- * This makes it about 8:1 overall.
+ * This makes it about 8:1 overall, or 16:1 overall on curves with cofactor 8.
  *
  * Negating the input (mod q) results in the same point.  Inverting the input
  * (mod q) results in the negative point.  This is the same as Elligator.
@@ -486,19 +486,36 @@ decaf_255_point_from_hash_nonuniform (
     const unsigned char hashed_data[DECAF_255_SER_BYTES]
 ) API_VIS NONNULL2 NOINLINE;
 
+/**
+ * @brief Indifferentiable hash function encoding to curve.
+ *
+ * Equivalent to calling decaf_255_point_from_hash_nonuniform twice and adding.
+ *
+ * @param [in] hashed_data Output of some hash function.
+ * @param [out] pt The data hashed to the curve.
+ */ 
+void decaf_255_point_from_hash_uniform (
+    decaf_255_point_t pt,
+    const unsigned char hashed_data[2*DECAF_255_SER_BYTES]
+) API_VIS NONNULL2 NOINLINE;
+
 /**
  * @brief Inverse of elligator-like hash to curve.
  *
  * This function writes to the buffer, to make it so that
- * decaf_255_point_from_hash_nonuniform(buffer) = pt if possible.
+ * decaf_255_point_from_hash_nonuniform(buffer) = pt if
+ * possible.  Since there may be multiple preimages, the
+ * "which" parameter chooses between them.  To ensure uniform
+ * inverse sampling, this function succeeds or fails
+ * independently for different "which" values.
  *
  * @param [out] recovered_hash Encoded data.
  * @param [in] pt The point to encode.
- * @param [in] which A "hint" that indicates which inverse to return.
+ * @param [in] which A value determining which inverse point
+ * to return.
  *
  * @retval DECAF_SUCCESS The inverse succeeded.
- * @retval DECAF_FAILURE The pt isn't the image of 
- *    decaf_255_point_from_hash_nonuniform with the given hint.
+ * @retval DECAF_FAILURE The inverse failed.
  */
 decaf_bool_t
 decaf_255_invert_elligator_nonuniform (
@@ -508,19 +525,22 @@ decaf_255_invert_elligator_nonuniform (
 ) API_VIS NONNULL2 NOINLINE WARN_UNUSED;
 
 /**
- * @brief Inverse of elligator-like hash to curve, uniform.
+ * @brief Inverse of elligator-like hash to curve.
  *
- * This function modifies the first DECAF_255_SER_BYTES of the
- * buffer, to make it so that
- * decaf_255_point_from_hash_uniform(buffer) = pt if possible.
+ * This function writes to the buffer, to make it so that
+ * decaf_255_point_from_hash_uniform(buffer) = pt if
+ * possible.  Since there may be multiple preimages, the
+ * "which" parameter chooses between them.  To ensure uniform
+ * inverse sampling, this function succeeds or fails
+ * independently for different "which" values.
  *
  * @param [out] recovered_hash Encoded data.
  * @param [in] pt The point to encode.
- * @param [in] which A "hint" that indicates which inverse to return.
+ * @param [in] which A value determining which inverse point
+ * to return.
  *
  * @retval DECAF_SUCCESS The inverse succeeded.
- * @retval DECAF_FAILURE The pt isn't the image of 
- *    decaf_255_point_from_hash_uniform with the given hint.
+ * @retval DECAF_FAILURE The inverse failed.
  */
 decaf_bool_t
 decaf_255_invert_elligator_uniform (
@@ -529,19 +549,6 @@ decaf_255_invert_elligator_uniform (
     uint16_t which
 ) API_VIS NONNULL2 NOINLINE WARN_UNUSED;
 
-/**
- * @brief Indifferentiable hash function encoding to curve.
- *
- * Equivalent to calling decaf_255_point_from_hash_nonuniform twice and adding.
- *
- * @param [in] hashed_data Output of some hash function.
- * @param [out] pt The data hashed to the curve.
- */ 
-void decaf_255_point_from_hash_uniform (
-    decaf_255_point_t pt,
-    const unsigned char hashed_data[2*DECAF_255_SER_BYTES]
-) API_VIS NONNULL2 NOINLINE;
-
 /**
  * @brief Overwrite scalar with zeros.
  */

include/decaf_255.hxx → src/public_include/decaf/decaf_255.hxx

@@ -1,5 +1,5 @@
 /**
- * @file decaf_255.hxx
+ * @file decaf/decaf_255.hxx
  * @author Mike Hamburg
  *
  * @copyright
@@ -27,8 +27,8 @@
 #include <stdlib.h>
 #include <string.h> /* for memcpy */
 
-#include "decaf.h"
-#include "secure_buffer.hxx"
+#include <decaf.h>
+#include <decaf/secure_buffer.hxx>
 #include <string>
 #include <sys/types.h>
 #include <limits.h>

include/decaf_448.h → src/public_include/decaf/decaf_448.h

@@ -1,5 +1,5 @@
 /**
- * @file decaf_448.h
+ * @file decaf/decaf_448.h
  * @author Mike Hamburg
  *
  * @copyright
@@ -11,7 +11,7 @@
 #ifndef __DECAF_448_H__
 #define __DECAF_448_H__ 1
 
-#include "decaf_common.h"
+#include <decaf/common.h>
 
 #ifdef __cplusplus
 extern "C" {
@@ -22,9 +22,9 @@ extern "C" {
 #define DECAF_448_SCALAR_LIMBS (448/DECAF_WORD_BITS)
 
 /** Galois field element internal structure */
-typedef struct gf_s {
+typedef struct gf_448_s {
     decaf_word_t limb[DECAF_448_LIMBS];
-} __attribute__((aligned(32))) gf_s, gf[1];
+} __attribute__((aligned(32))) gf_448_s, gf_448_t[1];
 /** @endcond */
 
 /** Number of bytes in a serialized point. */
@@ -34,7 +34,7 @@ typedef struct gf_s {
 #define DECAF_448_SCALAR_BYTES 56
 
 /** Twisted Edwards (-1,d-1) extended homogeneous coordinates */
-typedef struct decaf_448_point_s { /**@cond internal*/gf x,y,z,t;/**@endcond*/ } decaf_448_point_t[1];
+typedef struct decaf_448_point_s { /**@cond internal*/gf_448_t x,y,z,t;/**@endcond*/ } decaf_448_point_t[1];
 
 /** Precomputed table based on a point.  Can be trivial implementation. */
 struct decaf_448_precomputed_s;
@@ -451,7 +451,7 @@ void decaf_448_point_debugging_torque (
  *   A factor of 2 due to the isogeny.
  *   A factor of 2 because we quotient out the 2-torsion.
  *
- * This makes it about 8:1 overall.
+ * This makes it about 8:1 overall, or 16:1 overall on curves with cofactor 8.
  *
  * Negating the input (mod q) results in the same point.  Inverting the input
  * (mod q) results in the negative point.  This is the same as Elligator.
@@ -463,77 +463,76 @@ void decaf_448_point_debugging_torque (
  *
  * @param [in] hashed_data Output of some hash function.
  * @param [out] pt The data hashed to the curve.
- * @return A "hint" value which can be used to help invert the encoding.
  */
-unsigned char
+void
 decaf_448_point_from_hash_nonuniform (
     decaf_448_point_t pt,
     const unsigned char hashed_data[DECAF_448_SER_BYTES]
 ) API_VIS NONNULL2 NOINLINE;
 
+/**
+ * @brief Indifferentiable hash function encoding to curve.
+ *
+ * Equivalent to calling decaf_448_point_from_hash_nonuniform twice and adding.
+ *
+ * @param [in] hashed_data Output of some hash function.
+ * @param [out] pt The data hashed to the curve.
+ */ 
+void decaf_448_point_from_hash_uniform (
+    decaf_448_point_t pt,
+    const unsigned char hashed_data[2*DECAF_448_SER_BYTES]
+) API_VIS NONNULL2 NOINLINE;
+
 /**
  * @brief Inverse of elligator-like hash to curve.
  *
  * This function writes to the buffer, to make it so that
- * decaf_448_point_from_hash_nonuniform(buffer) = pt,hint
- * if possible.
+ * decaf_448_point_from_hash_nonuniform(buffer) = pt if
+ * possible.  Since there may be multiple preimages, the
+ * "which" parameter chooses between them.  To ensure uniform
+ * inverse sampling, this function succeeds or fails
+ * independently for different "which" values.
  *
  * @param [out] recovered_hash Encoded data.
  * @param [in] pt The point to encode.
- * @param [in] hint The hint value returned from 
- *   decaf_448_point_from_hash_nonuniform.
+ * @param [in] which A value determining which inverse point
+ * to return.
  *
  * @retval DECAF_SUCCESS The inverse succeeded.
- * @retval DECAF_FAILURE The pt isn't the image of 
- *    decaf_448_point_from_hash_nonuniform with the given hint.
+ * @retval DECAF_FAILURE The inverse failed.
  */
 decaf_bool_t
 decaf_448_invert_elligator_nonuniform (
     unsigned char recovered_hash[DECAF_448_SER_BYTES],
     const decaf_448_point_t pt,
-    unsigned char hint
+    uint16_t which
 ) API_VIS NONNULL2 NOINLINE WARN_UNUSED;
 
 /**
- * @brief Inverse of elligator-like hash to curve, uniform.
+ * @brief Inverse of elligator-like hash to curve.
  *
- * This function modifies the first DECAF_448_SER_BYTES of the
- * buffer, to make it so that
- * decaf_448_point_from_hash_uniform(buffer) = pt,hint
- * if possible.
+ * This function writes to the buffer, to make it so that
+ * decaf_448_point_from_hash_uniform(buffer) = pt if
+ * possible.  Since there may be multiple preimages, the
+ * "which" parameter chooses between them.  To ensure uniform
+ * inverse sampling, this function succeeds or fails
+ * independently for different "which" values.
  *
  * @param [out] recovered_hash Encoded data.
  * @param [in] pt The point to encode.
- * @param [in] hint The hint value returned from 
- *   decaf_448_point_from_hash_nonuniform.
+ * @param [in] which A value determining which inverse point
+ * to return.
  *
  * @retval DECAF_SUCCESS The inverse succeeded.
- * @retval DECAF_FAILURE The pt isn't the image of 
- *    decaf_448_point_from_hash_uniform with the given hint.
- *
- * @warning The hinting system is subject to change, especially in corner cases.
+ * @retval DECAF_FAILURE The inverse failed.
  */
 decaf_bool_t
 decaf_448_invert_elligator_uniform (
     unsigned char recovered_hash[2*DECAF_448_SER_BYTES],
     const decaf_448_point_t pt,
-    unsigned char hint
+    uint16_t which
 ) API_VIS NONNULL2 NOINLINE WARN_UNUSED;
 
-/**
- * @brief Indifferentiable hash function encoding to curve.
- *
- * Equivalent to calling decaf_448_point_from_hash_nonuniform twice and adding.
- *
- * @param [in] hashed_data Output of some hash function.
- * @param [out] pt The data hashed to the curve.
- * @return A "hint" value which can be used to help invert the encoding.
- */ 
-unsigned char decaf_448_point_from_hash_uniform (
-    decaf_448_point_t pt,
-    const unsigned char hashed_data[2*DECAF_448_SER_BYTES]
-) API_VIS NONNULL2 NOINLINE;
-
 /**
  * @brief Overwrite scalar with zeros.
  */

include/decaf_448.hxx → src/public_include/decaf/decaf_448.hxx

@@ -1,5 +1,5 @@
 /**
- * @file decaf_448.hxx
+ * @file decaf/decaf_448.hxx
  * @author Mike Hamburg
  *
  * @copyright
@@ -27,7 +27,7 @@
 #include <stdlib.h>
 #include <string.h> /* for memcpy */
 
-#include "decaf.h"
+#include <decaf.h>
 #include <string>
 #include <sys/types.h>
 #include <limits.h>

include/secure_buffer.hxx → src/public_include/decaf/secure_buffer.hxx

@@ -1,5 +1,5 @@
 /**
- * @file secure_buffer.hxx
+ * @file decaf/secure_buffer.hxx
  * @author Mike Hamburg
  *
  * @copyright

include/shake.h → src/public_include/decaf/shake.h

@@ -1,5 +1,5 @@
 /**
- * @file shake.h
+ * @file decaf/shake.h
  * @copyright
  *   Based on CC0 code by David Leon Gil, 2015 \n
  *   Copyright (c) 2015 Cryptography Research, Inc.  \n
@@ -15,7 +15,7 @@
 #include <stdint.h>
 #include <sys/types.h>
 
-#include "decaf_common.h"
+#include <decaf/common.h>
 
 /** @cond internal */
 #define API_VIS __attribute__((visibility("default")))

include/shake.hxx → src/public_include/decaf/shake.hxx

@@ -1,5 +1,5 @@
 /**
- * @file shake.hxx
+ * @file decaf/shake.hxx
  * @copyright
  *   Based on CC0 code by David Leon Gil, 2015 \n
  *   Copyright (c) 2015 Cryptography Research, Inc.  \n
@@ -12,7 +12,7 @@
 #ifndef __SHAKE_HXX__
 #define __SHAKE_HXX__
 
-#include "shake.h"
+#include <decaf/shake.h>
 #include <string>
 #include <sys/types.h>
 

src/shake.c

@@ -67,7 +67,7 @@ typedef struct keccak_sponge_s {
 } keccak_sponge_t[1];
 
 #define INTERNAL_SPONGE_STRUCT 1
-#include "shake.h"
+#include <decaf/shake.h>
 
 #define FLAG_ABSORBING 'A'
 #define FLAG_SQUEEZING 'Z'

src/utils.c

@@ -8,7 +8,7 @@
  * @brief Decaf utility functions.
  */
 
-#include "decaf_common.h"
+#include <decaf/common.h>
 
 void decaf_bzero (
     void *s,

test/bench_decaf.cxx

@@ -9,10 +9,9 @@
  * @brief C++ benchmarks, because that's easier.
  */
 
-#include "decaf.hxx"
-#include "shake.hxx"
-#include "shake.h"
-#include "decaf_crypto.h"
+#include <decaf.hxx>
+#include <decaf/shake.hxx>
+#include <decaf/crypto.h>
 #include <stdio.h>
 #include <sys/time.h>
 #include <assert.h>

test/shakesum.c

@@ -11,7 +11,7 @@
 #include <stdio.h>
 #include <unistd.h>
 #include <string.h>
-#include "shake.h"
+#include <decaf/shake.h>
 
 int main(int argc, char **argv) {
     (void)argc; (void)argv;

test/test_decaf.cxx

@@ -9,9 +9,9 @@
  * @brief C++ tests, because that's easier.
  */
 
-#include "decaf.hxx"
-#include "shake.hxx"
-#include "decaf_crypto.h"
+#include <decaf.hxx>
+#include <decaf/shake.hxx>
+#include <decaf/crypto.h>
 #include <stdio.h>