From 9eb59094fead5ce3210f14455a828cd4f0701cb9 Mon Sep 17 00:00:00 2001 From: J08nY Date: Wed, 27 Dec 2017 19:35:16 +0100 Subject: Update README, fix cli option mismatch. --- !uploader/ectester.cap | Bin 16008 -> 15192 bytes README.md | 105 ++++++++++++++++++++---- docs/LIBS.md | 31 ++++--- src/cz/crcs/ectester/reader/ECTesterReader.java | 8 +- 4 files changed, 110 insertions(+), 34 deletions(-) diff --git a/!uploader/ectester.cap b/!uploader/ectester.cap index b883965..8077260 100644 Binary files a/!uploader/ectester.cap and b/!uploader/ectester.cap differ diff --git a/README.md b/README.md index 9dbffc3..d68deb9 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,5 @@ # ECTester +[![Build status](https://api.travis-ci.org/crocs-muni/ECTester.svg?branch=master)](https://travis-ci.org/crocs-muni/ECTester) [![GitHub release](https://img.shields.io/github/release/crocs-muni/ECTEster.svg)](https://github.com/crocs-muni/ECTester/releases) [![license](https://img.shields.io/github/license/crocs-muni/ECTester.svg)](https://github.com/crocs-muni/ECTester/blob/master/LICENSE) Tests support and behavior of elliptic curve cryptography implementations on JavaCards (`TYPE_EC_FP` and `TYPE_EC_F2M`) and on selected software libraries. @@ -6,14 +7,14 @@ Tests support and behavior of elliptic curve cryptography implementations on Jav ECTester uses ant. There are three parts of ECTester, the JavaCard applet used for testing, the reader app which controls it and the standalone app which tests software libraries. ```bash -ant -f build-reader.xml package # To build the reader tool (jar). -ant -f build-standalone.xml package # To build the standalone tool (jar). -ant -f build-applet.xml build # To build the applet (cap). +ant -f build-reader.xml package # To build the reader tool (jar) -> "dist/ECTesterReader.jar" +ant -f build-standalone.xml package # To build the standalone tool (jar) -> "dist/ECTesterStandalone.jar" +ant -f build-applet.xml build # To build the applet (cap) -> "!uploader/ectester.cap". ``` +Build produces both a lightweight version of the JARs and a full version of the JARs with dependencies included, the latter has the `*-dist.jar` suffix. +The standalone build tries building test binaries for all the supported libraries, and silently fails if the library is not properly supported. -## Usage - -### JavaCard testing +## JavaCard testing 1. Upload `!uploader/ectester.cap` using your favorite tool (e.g., [GlobalPlatformPro tool](https://github.com/martinpaljak/GlobalPlatform)) 2. Run `java -jar dist/ECTesterReader.jar -t -a` @@ -29,23 +30,31 @@ Following operations are tested: See `java -jar ECTesterReader.jar -h` for more. -#### Options +### Options ``` - -ln,--list-named Print the list of supported named - curves and keys. -dsa,--ecdsa Sign data with ECDSA, [count] times. - -t,--test Test ECC support. - -dh,--ecdh Do ECDH, [count] times. + -t,--test Test ECC support. [test_suite]: + - default: + - invalid: + - wrong: + - composite: + - test-vectors: + -dh,--ecdh Do EC KeyAgreement (ECDH...), [count] + times. -e,--export Export the defaut curve parameters of the card(if any). - -g,--generate Generate [amount] of EC keys. + -V,--version Print version info. + -ln,--list-named Print the list of supported named + curves and keys. -h,--help Print help. - -dhc,--ecdhc Do ECDHC, [count] times. + -a,--all Test all curve sizes. -b,--bit-size Set curve size. + -fp,--prime-field Use a prime field. -f2m,--binary-field Use a binary field. + -c,--curve Use curve from file (field,a,b,gx,gy,r,k). -nc,--named-curve Use a named curve, from CurveDB: @@ -61,20 +70,25 @@ See `java -jar ECTesterReader.jar -h` for more. -k,--key Use keyPair from file  (wx,wy,s). -nk,--named-key Use keyPair from KeyDB: + -i,--input Input from file , for ECDSA signing. -o,--output Output into file . -l,--log Log output into file [log_file]. -v,--verbose Turn on verbose logging. - --format Output format to use. + --format Output format to use. One of: + text,yml,xml. -f,--fresh Generate fresh keys (set domain parameters before every generation). -s,--simulate Simulate a card with jcardsim instead of using a terminal. -y,--yes Accept all warnings and prompts. + -ka,--ka-type Set KeyAgreement object [type], corresponds to JC.KeyAgreement - constants. + constants. + -sig,--sig-type Set Signature object [type], + corresponds to JC.Signature constants. ``` ### Actions @@ -101,10 +115,10 @@ Use with `-o / --output [out_file]` to output the generated keys to a file. #### ECDH `-dh / --ecdh [count]` -`-dhc / --ecdhc [count]` Performs ECDH. Use with `-o / --output [out_file]` to output into a file. +Respects the KeyAgreement type specified in `-ka / --ka-type [type]`. #### ECDSA `-dsa / --ecdsa [count]` @@ -112,6 +126,7 @@ Use with `-o / --output [out_file]` to output into a file. Performs ECDSA. Useful with `-i / --input [in_file]` to sign the contents of a file. Use with `-o / --output [out_file]` to output into a file. +Respects the Signature type specified in `-sig / --sig-type [type]`. #### List named curves `-ln / --list-named []` @@ -149,6 +164,62 @@ For more info about the curves see [CURVES](docs/CURVES.md). *Explanation: ALG_EC_FP with 256b curve was tested. Is supported by card (KeyPair object allocation: OK), don't have preset default curve (Generate key with def curve: fail), custom curve can be set (Set valid custom curve: OK), new keypair can be generated (Generate key with valid curve: OK), ECDH key agreement failed to execute (ECDH agreement with valid point: fail) although it was supposed to succeed (log line is therefore marked with !!), ECDH wil fail (expected behavior) if invalid point is provided (ECDH agreement with invalid point: fail), ECDSA signature worked and verified correctly (ECDSA signature on random data: OK), anomalous curve can be set (Set anomalous custom curve: OK), however generating a key on it will fail (Generate key with anomalous curve: fail), ECDH with small-order public key provided will fail as intended (ECDH agreement with small order point: fail), invalid custom curve could be set (Set invalid custom curve: OK), new keypair cannot be generated with invalid curve (Generate key with invalid curve: fail), invalid field (non-prime) could be set (Set invalid field: OK), however a key could not be generated (Generate key with invalid field: fail).* - If you are interested in testing support for other JavaCard algorithms, please visit JCAlgTester project: https://github.com/crocs-muni/JCAlgTest + +## Standalone library testing + +Currently supported libraries include: + - BouncyCastle + - SunEC + - libtomcrypt + - botan + + +``` +usage: ECTesterStandalone.jar [-V] [-h] [ (ecdh [-t ] [-n ] [-b ] [-nc ]) | +(ecdsa [-t ] [-n ] [-b ] [-nc ] [-f ]) | +(export [-t ] [-b ]) | (generate [-nc ] [-n ] [-t +] [-b ]) | (list-data [what]) | (list-libs) | (test [-gt ] +[-kt ] [-st ] [-b ] [-nc ]) ] [lib] + + -V,--version Print version info. + -h,--help Print help. + [lib] What library to use. + + ecdh: + -t,--type Set KeyAgreement object [type]. + -n,--amount Do ECDH [amount] times. + -b,--bits What size of curve to use. + -nc,--named-curve Use a named curve, from CurveDB: + + ecdsa: + -t,--type Set Signature object [type]. + -n,--amount Do ECDSA [amount] times. + -b,--bits What size of curve to use. + -nc,--named-curve Use a named curve, from CurveDB: + -f,--file Input [file] to sign. + + export: + -t,--type Set KeyPair object [type]. + -b,--bits What size of curve to use. + + generate: + -nc,--named-curve Use a named curve, from CurveDB: + -n,--amount Generate [amount] of EC keys. + -t,--type Set KeyPairGenerator object [type]. + -b,--bits What size of curve to use. + + list-data: + [what] what to list. + + list-libs: + + test: + -gt,--kpg-type Set the KeyPairGenerator object [type]. + -kt,--ka-type Set the KeyAgreement object [type]. + -st,--sig-type Set the Signature object [type]. + -b,--bits What size of curve to use. + -nc,--named-curve Use a named curve, from CurveDB: + +``` \ No newline at end of file diff --git a/docs/LIBS.md b/docs/LIBS.md index 3635fef..4fac57b 100644 --- a/docs/LIBS.md +++ b/docs/LIBS.md @@ -1,26 +1,31 @@ -# Libraries +# Libraries with ECC Libraries with at least some ECC support: + - [Crypto++](https://cryptopp.com/) + - [libgcrypt](https://www.gnupg.org/related_software/libgcrypt/) + + - [mbedTLS](https://tls.mbed.org/) + - [Nettle](http://www.lysator.liu.se/~nisse/nettle/) + - [OpenSSL](https://www.openssl.org/) + - [OpenSSL (FIPS mode)](https://www.openssl.org/docs/fipsnotes.html) + + - [Microsoft CNG](https://msdn.microsoft.com/en-us/library/windows/desktop/aa376210(v=vs.85).aspx) + - [Microsoft .NET crypto](https://docs.microsoft.com/en-us/dotnet/standard/security/cryptography-model) + +# Supported libraries + - [BouncyCastle](https://bouncycastle.org/java.html) - Java - - [Botan](https://botan.randombit.net/) + - [Sun EC](https://docs.oracle.com/javase/7/docs/technotes/guides/security/SunProviders.html#SunEC) + - Java + C + - [Botan](https://botan.randombit.net/), since 2.4.0 (unreleased) - C++ - Uses blinded(randomized) Montgomery ladder. - https://hyperelliptic.org/EFD/g1p/auto-shortw-jacobian-3.html#addition-add-1998-cmo-2 - https://hyperelliptic.org/EFD/g1p/auto-shortw-jacobian-3.html#doubling-dbl-1986-cc - https://eprint.iacr.org/2015/657 - - [Crypto++](https://cryptopp.com/) - - [libgcrypt](https://www.gnupg.org/related_software/libgcrypt/) - [libtomcrypt](http://www.libtom.net/LibTomCrypt/) - C - Uses Jacobian coordinates. - - Sliding window scalar multiplication algorithm. - - [mbedTLS](https://tls.mbed.org/) - - [Nettle](http://www.lysator.liu.se/~nisse/nettle/) - - [OpenSSL](https://www.openssl.org/) - - [OpenSSL (FIPS mode)](https://www.openssl.org/docs/fipsnotes.html) - - [Sun EC](https://docs.oracle.com/javase/7/docs/technotes/guides/security/SunProviders.html#SunEC) - - Java + C - - [Microsoft CNG](https://msdn.microsoft.com/en-us/library/windows/desktop/aa376210(v=vs.85).aspx) - - [Microsoft .NET crypto](https://docs.microsoft.com/en-us/dotnet/standard/security/cryptography-model) \ No newline at end of file + - Sliding window scalar multiplication algorithm. \ No newline at end of file diff --git a/src/cz/crcs/ectester/reader/ECTesterReader.java b/src/cz/crcs/ectester/reader/ECTesterReader.java index 4e62f3f..215afbd 100644 --- a/src/cz/crcs/ectester/reader/ECTesterReader.java +++ b/src/cz/crcs/ectester/reader/ECTesterReader.java @@ -263,7 +263,7 @@ public class ECTesterReader { actions.addOption(Option.builder("e").longOpt("export").desc("Export the defaut curve parameters of the card(if any).").build()); actions.addOption(Option.builder("g").longOpt("generate").desc("Generate [amount] of EC keys.").hasArg().argName("amount").optionalArg(true).build()); actions.addOption(Option.builder("t").longOpt("test").desc("Test ECC support. [test_suite]:\n- default:\n- invalid:\n- wrong:\n- composite:\n- test-vectors:").hasArg().argName("test_suite").optionalArg(true).build()); - actions.addOption(Option.builder("ka").longOpt("ecka").desc("Do EC KeyAgreement (ECDH...), [count] times.").hasArg().argName("count").optionalArg(true).build()); + actions.addOption(Option.builder("dh").longOpt("ecdh").desc("Do EC KeyAgreement (ECDH...), [count] times.").hasArg().argName("count").optionalArg(true).build()); actions.addOption(Option.builder("dsa").longOpt("ecdsa").desc("Sign data with ECDSA, [count] times.").hasArg().argName("count").optionalArg(true).build()); opts.addOptionGroup(actions); @@ -782,7 +782,7 @@ public class ECTesterReader { return false; } - } else if (cli.hasOption("ecka")) { + } else if (cli.hasOption("ecdh")) { if (primeField == binaryField) { System.err.print("Need to specify field with -fp or -f2m. (not both)"); return false; @@ -792,9 +792,9 @@ public class ECTesterReader { return false; } - ECKACount = Integer.parseInt(cli.getOptionValue("ecka", "1")); + ECKACount = Integer.parseInt(cli.getOptionValue("ecdh", "1")); if (ECKACount <= 0) { - System.err.println("ECKA count cannot be <= 0."); + System.err.println("ECDH count cannot be <= 0."); return false; } -- cgit v1.3.1