forked from XKCP/XKCP
-
Notifications
You must be signed in to change notification settings - Fork 0
/
HOWTO-customize.build
111 lines (71 loc) · 6.55 KB
/
HOWTO-customize.build
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
<?xml version="1.0"?>
<!--
The eXtended Keccak Code Package (XKCP)
https://github.com/XKCP/XKCP
Implementation by Gilles Van Assche and Ronny Van Keer, hereby denoted as "the implementer".
For more information, feedback or questions, please refer to the Keccak Team website:
https://keccak.team/
To the extent possible under law, the implementer has waived all copyright
and related or neighboring rights to the source code in this file.
http://creativecommons.org/publicdomain/zero/1.0/
-->
<group>
<!--
# Introduction
We here explain how to create a custom build target in the XKCP. Some examples, which can be found below, illustrate the process.
Note that this file is included from Makefile.build, so the examples and anything tried here are accessible "for real" from make.
# Step 1: create a new target
First, choose a target name and add the corresponding XML tag. For the moment, we leave the inherits attribute empty:
<target name="chosenName" inherits=""/>
The name can be anything. If it ends with .a, make will attempt to build a static library with that name. If it ends with .so (resp. with .dylib), make will build a dynamic library for Linux (resp. macOS). Otherwise, it will build a standalone executable. In all cases, one can add ".pack" when invoking make (but not in the target name) to get a tarball with the source files, instead of building it.
# Step 2: select the high-level services
In a second step, select the desired cryptographic functions and add the corresponding fragment keywords to the inherits attribute (separated by a space).
Please refer to lib/HighLevel.build for the list of supported cryptographic functions.
# Step 3: identify the required low-level services
Then, identify the permutations that the chosen cryptographic functions need.
Each cryptographic function implemented in the XKCP depends on a given permutation. It interacts with the permutation through an interface called SnP. Some functions further can take advantage of a parallel implementation of the permutation, in which case the interface is called PlSnP. The choice of high-level services therefore determines what we need as low-level services:
* Those that require Keccak-p[200]: Ketje Jr, Keccak{Sponge, Duplex, PRG} with rate + capacity = 200
* Those that require Keccak-p[400]: Ketje Sr, Keccak{Sponge, Duplex, PRG} with rate + capacity = 400
* Those that require Keccak-p[800]: Ketje Minor, River Keyak, Keccak{Sponge, Duplex, PRG} with rate + capacity = 800
* Those that require Keccak-p[1600]: Ketje Major, {Lake, Sea, Ocean} Keyak, Kravatte, KangarooTwelve, FIPS202, SP800-185, Keccak{Sponge, Duplex, PRG} with rate + capacity = 1600
* Those that require Xoodoo: Xoofff, Xoodyak
The following targets additionally require an implementation of parallel instances of Keccak-p[1600]. The parallel implementation may be a fall-back stub (i.e., 1600timesXonY).
* SeaKeyak requires Keccak-p[1600]×2
* OceanKeyak requires Keccak-p[1600]×4
* LunarKeyak requires Keccak-p[1600]×8.
For KangarooTwelve, SP800-185, Kravatte and Xoofff, the use of parallel implementations is recommended for best performances, but they can work without these.
# Step 4: select the implementation of the low-level services
Finally, for each of the required permutation (or parallel implementation thereof) identified in the previous step, select one implementation and add the corresponding fragment keywords to the inherits attribute (separated by a space).
Please refer to the file lib/LowLevel.build for the list of supported implementations.
If Ketje is used, we still need to add an additional fragment keyword, see lib/LowLevel.build for more details.
-->
<!-- Examples -->
<!-- Type "make PRG-AVR8.pack" to get a tarball with the sources needed to compile a pseudo-random number generator on top of Keccak-f[200] for AVR8. -->
<target name="PRG-AVR8" inherits="KeccakPRG K200-AVR8"/>
<!-- Type "make KetjeJr-compact8.pack" to get a tarball with the sources needed to compile KetjeJr generically optimized for 8-bit platforms. -->
<target name="KetjeJr-compact8" inherits="Ketje Ket-SnP K200-compact"/>
<!-- Type "make libKeccak-16bits.a" to compile a library with Keccak sponge, duplex and PRG on top of Keccak-f[400], using plain reference code. Add ".pack" when invoking make to get a tarball with the source files instead. -->
<target name="libKeccak-16bits.a" inherits="KeccakSponge KeccakDuplex KeccakPRG K400-ref"/>
<!-- Type "make Xoodyak-ARMv7M.pack" to get a tarball with the sources needed to compile Xoodyak on ARMv7M. -->
<target name="Xoodyak-ARMv7M" inherits="Xoodyak Xoodoo-ARMv7M"/>
<!-- Type "make libRiverKeyak-generic32.a" to get a library with River Keyak generically optimized for 32-bit platforms. Add ".pack" when invoking make to get a tarball with the source files instead. -->
<target name="libRiverKeyak-generic32.a" inherits="Keyak K800-plain-lcu2"/>
<!-- Same as above, but we add a PRG and we use a compact implementation instead. -->
<target name="libRiverKeyak-PRG-compact32.a" inherits="Keyak KeccakPRG K800-compact"/>
<!-- Type "make libK12-AVX2.a" to build a library with KangarooTwelve with AVX2 code. Add ".pack" when invoking make to get a tarball with the source files instead. -->
<target name="libK12-AVX2.a" inherits="KangarooTwelve K1600-AVX2 K1600x2-SSSE3-u2 K1600x4-AVX2-u12"/>
<!-- Same as above, but using a 32-bit implementation and not exploiting any parallelism. -->
<target name="libK12-32bits.a" inherits="KangarooTwelve K1600-plain-32bits-inplace"/>
<!-- Type "make FIPS202-opt64.pack" to get a tarball with the sources needed to compile the FIPS 202 functions generically optimized for 64-bit platforms. -->
<target name="FIPS202-opt64" inherits="FIPS202 K1600-plain-64bits-ua"/>
<!-- Type "make MyUnitTests" to build an executable that runs the unit tests on a restricted set of functionality.
In this example, the functionality is KangarooTwelve, with AVX2 code.
-->
<target name="MyUnitTests" inherits="KangarooTwelve K1600-AVX2 K1600x2-SSSE3-u2 K1600x4-AVX2-u12 UT"/>
<!-- Type "make MyBenchmarks" to build an executable that benchmarks a restricted set of functionality.
In this example, the functionality is Xoofff, with AVX2 code.
-->
<target name="MyBenchmarks" inherits="Xoofff Xoodoo-SSE2 Xoodoox4-SSSE3 Xoodoox8-AVX2 BM"/>
<!-- Type "make libK12-AVX512.dylib" to build a dynamic library for macOS with KangarooTwelve with AVX512 code. -->
<target name="libK12-AVX512.dylib" inherits="KangarooTwelve K1600-AVX512 K1600x2-AVX512-u12 K1600x4-AVX512-u12 K1600x8-AVX512-u12"/>
</group>