From 9324dcae824b37edd61b370c6f41b5ea228888ec Mon Sep 17 00:00:00 2001 From: J08nY Date: Tue, 31 Oct 2017 23:22:39 +0100 Subject: Move docs to subfolder. --- CURVES.md | 15 ---------- FORMAT.md | 35 ----------------------- README.md | 6 ++-- TESTS.md | 90 ---------------------------------------------------------- docs/CURVES.md | 15 ++++++++++ docs/FORMAT.md | 35 +++++++++++++++++++++++ docs/TESTS.md | 90 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 7 files changed, 143 insertions(+), 143 deletions(-) delete mode 100644 CURVES.md delete mode 100644 FORMAT.md delete mode 100644 TESTS.md create mode 100644 docs/CURVES.md create mode 100644 docs/FORMAT.md create mode 100644 docs/TESTS.md diff --git a/CURVES.md b/CURVES.md deleted file mode 100644 index d1749df..0000000 --- a/CURVES.md +++ /dev/null @@ -1,15 +0,0 @@ -# Curves - -## anomalous - -## Brainpool - -## invalid - -## NIST - -## nonprime - -## SECG - -## wrong diff --git a/FORMAT.md b/FORMAT.md deleted file mode 100644 index b68db39..0000000 --- a/FORMAT.md +++ /dev/null @@ -1,35 +0,0 @@ -# Format -CSV based, little-endian hexadecimal values. - -## Curves -### Prime field -`p,a,b,gx,gy,n,h` - -### Binary field -`m,e1,e2,e3,a,b,gx,gy,n,h` - -## Key material -### Keypair -`wx,wy,s` - -### Public key -`wx,wy` - -### Private key -`s` - -# Notation - - `p` - prime F_p - - `m` - binary field exponent F_2^m - - `e1` - largest exponent of the field polynomial - - `e2` - middle exponenet of the field polynomial, or `0000` if field poly is a trinomial - - `e3` - smallest exponent (except zero) of the field polynomial, or `0000` if field poly is a trinomial - - `a` - a parameter in short Weierstrass curve equation - - `b` - b parameter in short Weierstrass curve equation - - `gx` - x coordinate of the curve base-point g - - `gy` - y coordinate of the curve base-point g - - `n` - the base-point order - - `h` - the base-point cofactor - - `wx` - the x coordinate of the public key - - `wy` - the y coordinate of th public key - - `s` - the private key value \ No newline at end of file diff --git a/README.md b/README.md index 82cb645..c48426e 100644 --- a/README.md +++ b/README.md @@ -73,14 +73,14 @@ See `java -jar ECTester.jar -h` for more. Exports the default curves (if any) that are preset on the card. Use with `-o / --output [out_file]` to output the curve parameters to a file. -For format of this file see [FORMAT](FORMAT.md). +For format of this file see [FORMAT](docs/FORMAT.md). #### Test `-t / --test [test_suite]` Perform support and performance tests of ECC. -For more info about the test suites see [TESTS](TESTS.md). +For more info about the test suites see [TESTS](docs/TESTS.md). #### Generate `-g / --generate [amount]` @@ -113,7 +113,7 @@ With the format: `category/name`. For example: `secg/secp192r1` identifies the SECG 192 bit prime field curve known as `secp192r1`. -For more info about the curves see [CURVES](CURVES.md). +For more info about the curves see [CURVES](docs/CURVES.md). ### Example diff --git a/TESTS.md b/TESTS.md deleted file mode 100644 index 21298dc..0000000 --- a/TESTS.md +++ /dev/null @@ -1,90 +0,0 @@ -# Tests - - - `default` - - `test-vectors` - - `wrong` - - `composite` - - `invalid` - -**NOTE: The `wrong`, `composite` and `invalid` test suites caused temporary DoS of some cards. These test suites prompt you for -confirmation before running, be cautious.** - -## Default -Tests the default curves present on the card. These might not be present or the card might not even support ECC. -Tests keypair allocation, generation, ECDH and ECDSA. ECDH is first tested with two valid generated keypairs, then a with a -public key that is corrupted in various ways, these tests should fail. - -This test suite is run if no argument is provided to `-t / --test`. - -Supports the `-nc / --named-curve` option so you can specify a category of curves or a curve to use if the card doesn't -have default curves preset. - -For example: -```bash -java -jar ECTester.jar -nc secg -a -fp -t -``` -tests all(`-a`), prime field(`-fp`) SECG curves, using the default test suite. - -```bash -java -jar ECTester.jar -u -a -f2m -t -``` -tests all(`-a`), binary field(`-f2m`), custom(`-u`) curves. - -```bash -java -jar ECTester.jar -b 128 -fp -t -``` -tests a 128 bit(`-b`), prime field(`-fp`) curve, (if a default one is present). - -## Test-Vectors -Tests using known test vectors provided by NIST/SECG/Brainpool: - -[SECG - GEC2](http://read.pudn.com/downloads168/doc/772358/TestVectorsforSEC%201-gec2.pdf) - -[NIST - ECCDH](http://csrc.nist.gov/groups/STM/cavp/component-testing.html#ECCCDH) - -[Brainpool - RFC6931](https://tools.ietf.org/html/rfc6932#appendix-A.1) - -[Brainpool - RFC7027](https://tools.ietf.org/html/rfc7027#appendix-A) - -For example: -```bash -java -jar ECTester.jar -t test-vectors -nc nist -a -f2m -``` -tests all(`-a`), binary field(`-f2m`) NIST curves for which test-vectors are provided. Although this test suite is better for general testing: -```bash -java -jar ECTester.jar -t test-vectors -a -``` -## Wrong -Tests using the default tests on a category of wrong curves. These curves are not really curves as they have: - - non-prime field in the prime-field case - - reducible polynomial as the field polynomial in the binary case - -These tests should fail generally. They are equivalent with `java -jar ECTester.jar -nc wrong -t`, the default tests over the `wrong` category -of curves. - -For example: -```bash -java -jar ECTester.jar -t wrong -b 521 -fp -``` -tests a 521 bit(`-b`), prime-field(`-fp`) wrong curve. - -## Composite -Tests using curves that don't have a prime order/nearly prime order. -These tests should generally fail, a success here implies the card **WILL** use a non-secure curve if such curve is set -by the applet. Operations over such curves are susceptible to small-subgroup attacks. - -For example: -```bash -java -jar ECTester.jar -t composite -b 160 -fp -``` - -## Invalid -Tests using known named curves from several categories(SECG/NIST/Brainpool) against pregenerated *invalid* public keys. -These tests should definitely fail, a success here implies the card is susceptible to invalid curve attacks. - - -For example: -```bash -java -jar ECTester.jar -t invalid -nc nist -a -fp -``` -tests using all(`-a`), prime-field(`-fp`) NIST curves and pregenerated *invalid* public keys for these curves. \ No newline at end of file diff --git a/docs/CURVES.md b/docs/CURVES.md new file mode 100644 index 0000000..d1749df --- /dev/null +++ b/docs/CURVES.md @@ -0,0 +1,15 @@ +# Curves + +## anomalous + +## Brainpool + +## invalid + +## NIST + +## nonprime + +## SECG + +## wrong diff --git a/docs/FORMAT.md b/docs/FORMAT.md new file mode 100644 index 0000000..b68db39 --- /dev/null +++ b/docs/FORMAT.md @@ -0,0 +1,35 @@ +# Format +CSV based, little-endian hexadecimal values. + +## Curves +### Prime field +`p,a,b,gx,gy,n,h` + +### Binary field +`m,e1,e2,e3,a,b,gx,gy,n,h` + +## Key material +### Keypair +`wx,wy,s` + +### Public key +`wx,wy` + +### Private key +`s` + +# Notation + - `p` - prime F_p + - `m` - binary field exponent F_2^m + - `e1` - largest exponent of the field polynomial + - `e2` - middle exponenet of the field polynomial, or `0000` if field poly is a trinomial + - `e3` - smallest exponent (except zero) of the field polynomial, or `0000` if field poly is a trinomial + - `a` - a parameter in short Weierstrass curve equation + - `b` - b parameter in short Weierstrass curve equation + - `gx` - x coordinate of the curve base-point g + - `gy` - y coordinate of the curve base-point g + - `n` - the base-point order + - `h` - the base-point cofactor + - `wx` - the x coordinate of the public key + - `wy` - the y coordinate of th public key + - `s` - the private key value \ No newline at end of file diff --git a/docs/TESTS.md b/docs/TESTS.md new file mode 100644 index 0000000..21298dc --- /dev/null +++ b/docs/TESTS.md @@ -0,0 +1,90 @@ +# Tests + + - `default` + - `test-vectors` + - `wrong` + - `composite` + - `invalid` + +**NOTE: The `wrong`, `composite` and `invalid` test suites caused temporary DoS of some cards. These test suites prompt you for +confirmation before running, be cautious.** + +## Default +Tests the default curves present on the card. These might not be present or the card might not even support ECC. +Tests keypair allocation, generation, ECDH and ECDSA. ECDH is first tested with two valid generated keypairs, then a with a +public key that is corrupted in various ways, these tests should fail. + +This test suite is run if no argument is provided to `-t / --test`. + +Supports the `-nc / --named-curve` option so you can specify a category of curves or a curve to use if the card doesn't +have default curves preset. + +For example: +```bash +java -jar ECTester.jar -nc secg -a -fp -t +``` +tests all(`-a`), prime field(`-fp`) SECG curves, using the default test suite. + +```bash +java -jar ECTester.jar -u -a -f2m -t +``` +tests all(`-a`), binary field(`-f2m`), custom(`-u`) curves. + +```bash +java -jar ECTester.jar -b 128 -fp -t +``` +tests a 128 bit(`-b`), prime field(`-fp`) curve, (if a default one is present). + +## Test-Vectors +Tests using known test vectors provided by NIST/SECG/Brainpool: + +[SECG - GEC2](http://read.pudn.com/downloads168/doc/772358/TestVectorsforSEC%201-gec2.pdf) + +[NIST - ECCDH](http://csrc.nist.gov/groups/STM/cavp/component-testing.html#ECCCDH) + +[Brainpool - RFC6931](https://tools.ietf.org/html/rfc6932#appendix-A.1) + +[Brainpool - RFC7027](https://tools.ietf.org/html/rfc7027#appendix-A) + +For example: +```bash +java -jar ECTester.jar -t test-vectors -nc nist -a -f2m +``` +tests all(`-a`), binary field(`-f2m`) NIST curves for which test-vectors are provided. Although this test suite is better for general testing: +```bash +java -jar ECTester.jar -t test-vectors -a +``` +## Wrong +Tests using the default tests on a category of wrong curves. These curves are not really curves as they have: + - non-prime field in the prime-field case + - reducible polynomial as the field polynomial in the binary case + +These tests should fail generally. They are equivalent with `java -jar ECTester.jar -nc wrong -t`, the default tests over the `wrong` category +of curves. + +For example: +```bash +java -jar ECTester.jar -t wrong -b 521 -fp +``` +tests a 521 bit(`-b`), prime-field(`-fp`) wrong curve. + +## Composite +Tests using curves that don't have a prime order/nearly prime order. +These tests should generally fail, a success here implies the card **WILL** use a non-secure curve if such curve is set +by the applet. Operations over such curves are susceptible to small-subgroup attacks. + +For example: +```bash +java -jar ECTester.jar -t composite -b 160 -fp +``` + +## Invalid +Tests using known named curves from several categories(SECG/NIST/Brainpool) against pregenerated *invalid* public keys. +These tests should definitely fail, a success here implies the card is susceptible to invalid curve attacks. + + +For example: +```bash +java -jar ECTester.jar -t invalid -nc nist -a -fp +``` +tests using all(`-a`), prime-field(`-fp`) NIST curves and pregenerated *invalid* public keys for these curves. \ No newline at end of file -- cgit v1.2.3-70-g09d2