3 files changed, 140 insertions, 0 deletions

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