Skip to content

Commit 37dcf08

Browse files
author
gefeili
committed
Add java doc for Ascon
1 parent 8661366 commit 37dcf08

File tree

7 files changed

+113
-49
lines changed

7 files changed

+113
-49
lines changed

‎core/src/main/java/org/bouncycastle/crypto/digests/AsconBaseDigest.java‎

Lines changed: 10 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
import org.bouncycastle.crypto.DataLengthException;
66
import org.bouncycastle.crypto.ExtendedDigest;
77
import org.bouncycastle.crypto.OutputLengthException;
8-
import org.bouncycastle.util.Pack;
8+
import org.bouncycastle.util.Longs;
99

1010
abstract class AsconBaseDigest
1111
implements ExtendedDigest
@@ -20,24 +20,18 @@ abstract class AsconBaseDigest
2020
protected int ASCON_PB_ROUNDS = 12;
2121

2222
protected final ByteArrayOutputStream buffer = new ByteArrayOutputStream();
23-
24-
protected long ror(long x, int n)
25-
{
26-
return x >>> n | x << (64 - n);
27-
}
28-
29-
protected void round(long C)
23+
private void round(long C)
3024
{
3125
long t0 = x0 ^ x1 ^ x2 ^ x3 ^ C ^ (x1 & (x0 ^ x2 ^ x4 ^ C));
3226
long t1 = x0 ^ x2 ^ x3 ^ x4 ^ C ^ ((x1 ^ x2 ^ C) & (x1 ^ x3));
3327
long t2 = x1 ^ x2 ^ x4 ^ C ^ (x3 & x4);
3428
long t3 = x0 ^ x1 ^ x2 ^ C ^ ((~x0) & (x3 ^ x4));
3529
long t4 = x1 ^ x3 ^ x4 ^ ((x0 ^ x4) & x1);
36-
x0 = t0 ^ ror(t0, 19) ^ ror(t0, 28);
37-
x1 = t1 ^ ror(t1, 39) ^ ror(t1, 61);
38-
x2 = ~(t2 ^ ror(t2, 1) ^ ror(t2, 6));
39-
x3 = t3 ^ ror(t3, 10) ^ ror(t3, 17);
40-
x4 = t4 ^ ror(t4, 7) ^ ror(t4, 41);
30+
x0 = t0 ^ Longs.rotateRight(t0, 19) ^ Longs.rotateRight(t0, 28);
31+
x1 = t1 ^ Longs.rotateRight(t1, 39) ^ Longs.rotateRight(t1, 61);
32+
x2 = ~(t2 ^ Longs.rotateRight(t2, 1) ^ Longs.rotateRight(t2, 6));
33+
x3 = t3 ^ Longs.rotateRight(t3, 10) ^ Longs.rotateRight(t3, 17);
34+
x4 = t4 ^ Longs.rotateRight(t4, 7) ^ Longs.rotateRight(t4, 41);
4135
}
4236

4337
protected void p(int nr)
@@ -62,20 +56,11 @@ protected void p(int nr)
6256
round(0x4bL);
6357
}
6458

65-
protected long pad(int i)
66-
{
67-
return 0x01L << (i << 3);
68-
}
59+
protected abstract long pad(int i);
6960

70-
protected long loadBytes(final byte[] bytes, int inOff, int n)
71-
{
72-
return Pack.littleEndianToLong(bytes, inOff, n);
73-
}
61+
protected abstract long loadBytes(final byte[] bytes, int inOff, int n);
7462

75-
protected void setBytes(long w, byte[] bytes, int inOff, int n)
76-
{
77-
Pack.longToLittleEndian(w, bytes, inOff, n);
78-
}
63+
protected abstract void setBytes(long w, byte[] bytes, int inOff, int n);
7964

8065
@Override
8166
public int getDigestSize()

‎core/src/main/java/org/bouncycastle/crypto/digests/AsconCxof128.java‎

Lines changed: 25 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -4,13 +4,18 @@
44
import org.bouncycastle.crypto.OutputLengthException;
55
import org.bouncycastle.crypto.Xof;
66
import org.bouncycastle.util.Arrays;
7+
import org.bouncycastle.util.Pack;
78

89
/**
9-
* ASCON v1.2 XOF, https://ascon.iaik.tugraz.at/ .
10+
* Ascon-CXOF128 was introduced in NIST Special Publication (SP) 800-232
11+
* (Initial Public Draft).
1012
* <p>
11-
* https://csrc.nist.gov/CSRC/media/Projects/lightweight-cryptography/documents/finalist-round/updated-spec-doc/ascon-spec-final.pdf
12-
* <p>
13-
* ASCON v1.2 XOF with reference to C Reference Impl from: https://github.com/ascon/ascon-c .
13+
* Additional details and the specification can be found in:
14+
* <a href="https://csrc.nist.gov/pubs/sp/800/232/ipd">NIST SP 800-232 (Initial Public Draft)</a>.
15+
* For reference source code and implementation details, please see:
16+
* <a href="https://github.com/ascon/ascon-c">Reference, highly optimized, masked C and
17+
* ASM implementations of Ascon (NIST SP 800-232)</a>.
18+
* </p>
1419
*/
1520
public class AsconCxof128
1621
extends AsconBaseDigest
@@ -47,10 +52,25 @@ public AsconCxof128()
4752
reset();
4853
}
4954

55+
protected long pad(int i)
56+
{
57+
return 0x01L << (i << 3);
58+
}
59+
60+
protected long loadBytes(final byte[] bytes, int inOff, int n)
61+
{
62+
return Pack.littleEndianToLong(bytes, inOff, n);
63+
}
64+
65+
protected void setBytes(long w, byte[] bytes, int inOff, int n)
66+
{
67+
Pack.longToLittleEndian(w, bytes, inOff, n);
68+
}
69+
5070
@Override
5171
public String getAlgorithmName()
5272
{
53-
return "Ascon-XOF-128";
73+
return "Ascon-CXOF128";
5474
}
5575

5676
@Override

‎core/src/main/java/org/bouncycastle/crypto/digests/AsconHash256Digest.java‎

Lines changed: 26 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,17 @@
11
package org.bouncycastle.crypto.digests;
22

3+
import org.bouncycastle.util.Pack;
4+
35
/**
4-
* ASCON v1.2 Digest, https://ascon.iaik.tugraz.at/ .
5-
* <p>
6-
* https://csrc.nist.gov/CSRC/media/Projects/lightweight-cryptography/documents/finalist-round/updated-spec-doc/ascon-spec-final.pdf
6+
* Ascon-Hash256 was introduced in NIST Special Publication (SP) 800-232
7+
* (Initial Public Draft).
78
* <p>
8-
* ASCON v1.2 Digest with reference to C Reference Impl from: https://github.com/ascon/ascon-c .
9+
* Additional details and the specification can be found in:
10+
* <a href="https://csrc.nist.gov/pubs/sp/800/232/ipd">NIST SP 800-232 (Initial Public Draft)</a>.
11+
* For reference source code and implementation details, please see:
12+
* <a href="https://github.com/ascon/ascon-c">Reference, highly optimized, masked C and
13+
* ASM implementations of Ascon (NIST SP 800-232)</a>.
14+
* </p>
915
*/
1016
public class AsconHash256Digest
1117
extends AsconBaseDigest
@@ -15,10 +21,25 @@ public AsconHash256Digest()
1521
reset();
1622
}
1723

24+
protected long pad(int i)
25+
{
26+
return 0x01L << (i << 3);
27+
}
28+
29+
protected long loadBytes(final byte[] bytes, int inOff, int n)
30+
{
31+
return Pack.littleEndianToLong(bytes, inOff, n);
32+
}
33+
34+
protected void setBytes(long w, byte[] bytes, int inOff, int n)
35+
{
36+
Pack.longToLittleEndian(w, bytes, inOff, n);
37+
}
38+
1839
@Override
1940
public String getAlgorithmName()
2041
{
21-
return "Ascon Hash 256";
42+
return "Ascon-Hash256";
2243
}
2344

2445
@Override

‎core/src/main/java/org/bouncycastle/crypto/digests/AsconXof128.java‎

Lines changed: 24 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,18 @@
11
package org.bouncycastle.crypto.digests;
22

33
import org.bouncycastle.crypto.Xof;
4+
import org.bouncycastle.util.Pack;
45

56
/**
6-
* ASCON v1.2 XOF, https://ascon.iaik.tugraz.at/ .
7+
* Ascon-XOF128 was introduced in NIST Special Publication (SP) 800-232
8+
* (Initial Public Draft).
79
* <p>
8-
* https://csrc.nist.gov/CSRC/media/Projects/lightweight-cryptography/documents/finalist-round/updated-spec-doc/ascon-spec-final.pdf
9-
* <p>
10-
* ASCON v1.2 XOF with reference to C Reference Impl from: https://github.com/ascon/ascon-c .
11-
*
10+
* Additional details and the specification can be found in:
11+
* <a href="https://csrc.nist.gov/pubs/sp/800/232/ipd">NIST SP 800-232 (Initial Public Draft)</a>.
12+
* For reference source code and implementation details, please see:
13+
* <a href="https://github.com/ascon/ascon-c">Reference, highly optimized, masked C and
14+
* ASM implementations of Ascon (NIST SP 800-232)</a>.
15+
* </p>
1216
*/
1317
public class AsconXof128
1418
extends AsconBaseDigest
@@ -19,6 +23,21 @@ public AsconXof128()
1923
reset();
2024
}
2125

26+
protected long pad(int i)
27+
{
28+
return 0x01L << (i << 3);
29+
}
30+
31+
protected long loadBytes(final byte[] bytes, int inOff, int n)
32+
{
33+
return Pack.littleEndianToLong(bytes, inOff, n);
34+
}
35+
36+
protected void setBytes(long w, byte[] bytes, int inOff, int n)
37+
{
38+
Pack.longToLittleEndian(w, bytes, inOff, n);
39+
}
40+
2241
@Override
2342
public String getAlgorithmName()
2443
{

‎core/src/main/java/org/bouncycastle/crypto/engines/AsconAEAD128Engine.java‎

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,19 @@
88
import org.bouncycastle.crypto.params.ParametersWithIV;
99
import org.bouncycastle.util.Pack;
1010

11+
/**
12+
* Ascon-AEAD128 was introduced as part of the NIST Lightweight Cryptography
13+
* competition and described in the NIST Special Publication SP 800-232 (Initial
14+
* Public Draft).
15+
* For additional details, see:
16+
* <ul>
17+
* <li><a href="https://csrc.nist.gov/pubs/sp/800/232/ipd">NIST SP 800-232 (Initial Public Draft)</a></li>
18+
* <li><a href="https://github.com/ascon/ascon-c">Reference, highly optimized, masked C and
19+
* ASM implementations of Ascon (NIST SP 800-232)</a></li>
20+
* </ul>
21+
*
22+
* @version 1.3
23+
*/
1124
public class AsconAEAD128Engine
1225
extends AsconBaseEngine
1326
{
@@ -17,7 +30,7 @@ public AsconAEAD128Engine()
1730
CRYPTO_ABYTES = 16;
1831
ASCON_AEAD_RATE = 16;
1932
ASCON_IV = 0x00001000808c0001L;
20-
algorithmName = "Ascon-AEAD-128";
33+
algorithmName = "Ascon-AEAD128";
2134
nr = 8;
2235
m_bufferSizeDecrypt = ASCON_AEAD_RATE + CRYPTO_ABYTES;
2336
m_buf = new byte[m_bufferSizeDecrypt];

‎core/src/main/java/org/bouncycastle/crypto/engines/AsconBaseEngine.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -53,7 +53,7 @@ protected enum State
5353

5454
protected abstract void setBytes(long n, byte[] bs, int off);
5555

56-
protected void round(long C)
56+
private void round(long C)
5757
{
5858
long t0 = x0 ^ x1 ^ x2 ^ x3 ^ C ^ (x1 & (x0 ^ x2 ^ x4 ^ C));
5959
long t1 = x0 ^ x2 ^ x3 ^ x4 ^ C ^ ((x1 ^ x2 ^ C) & (x1 ^ x3));

‎core/src/main/java/org/bouncycastle/crypto/engines/AsconEngine.java‎

Lines changed: 13 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -9,14 +9,22 @@
99
import org.bouncycastle.util.Pack;
1010

1111
/**
12-
* ASCON AEAD v1.2, https://ascon.iaik.tugraz.at/
13-
* https://csrc.nist.gov/CSRC/media/Projects/lightweight-cryptography/documents/finalist-round/updated-spec-doc/ascon-spec-final.pdf
12+
* The {@code AsconEngine} class provides an implementation of ASCON AEAD version 1.2,
13+
* based on the official specification available at:
14+
* <a href="https://ascon.iaik.tugraz.at/">https://ascon.iaik.tugraz.at/</a> and the
15+
* updated specification document from the NIST competition:
16+
* <a href="https://csrc.nist.gov/CSRC/media/Projects/lightweight-cryptography/documents/finalist-round/updated-spec-doc/ascon-spec-final.pdf">
17+
* ASCON Specification (Finalist Round)
18+
* </a>.
1419
* <p>
15-
* ASCON AEAD v1.2 with reference to C Reference Impl from: https://github.com/ascon/ascon-c
16-
*
17-
* @deprecated Now superseded - please use AsconAead128Engine
20+
* This version references the C reference implementation provided by NIST, available at:
21+
* <a href="https://csrc.nist.gov/CSRC/media/Projects/lightweight-cryptography/documents/finalist-round/updated-submissions/ascon.zip">
22+
* ASCON C Reference Implementation (NIST Round 2)
23+
* </a>.
1824
* </p>
25+
* @deprecated Now superseded. Please refer to {@code AsconAEAD128Engine} for future implementations.
1926
*/
27+
2028
public class AsconEngine
2129
extends AsconBaseEngine
2230
{
@@ -29,8 +37,6 @@ public enum AsconParameters
2937

3038
private final AsconParameters asconParameters;
3139

32-
private final String algorithmName;
33-
3440
private long K2;
3541

3642
public AsconEngine(AsconParameters asconParameters)

0 commit comments

Comments
 (0)