typos, format updates, missing references, etc.

Author: tomato42

README.md

@@ -27,11 +27,11 @@ over prime fields.
 
 This library uses only Python and the 'six' package. It is compatible with
 Python 2.6, 2.7 and 3.3+. It also supports execution on the alternative
-implementaions like pypy and pypy3
+implementations like pypy and pypy3
 
-To run the OpenSSL compatibility tests, the 'openssl' tool must be on your
-$PATH. This release has been tested successfully against both OpenSSL 0.9.8o
-and 1.0.0a .
+To run the OpenSSL compatibility tests, the 'openssl' tool must be in your
+`PATH`. This release has been tested successfully against OpenSSL 0.9.8o,
+1.0.0a, 1.0.2f and 1.1.1d (among others).
 
 ## Speed
 
@@ -110,56 +110,61 @@ a system where os.urandom() is weak.
 
 ## Usage
 
-You start by creating a SigningKey. You can use this to sign data, by passing
-in a data string and getting back the signature (also a string). You can also
-ask a SigningKey to give you the corresponding VerifyingKey. The VerifyingKey
-can be used to verify a signature, by passing it both the data string and the
-signature string: it either returns True or raises BadSignatureError.
+You start by creating a `SigningKey`. You can use this to sign data, by passing
+in data as a byte string and getting back the signature (also a byte string).
+You can also ask a `SigningKey` to give you the corresponding `VerifyingKey`.
+The `VerifyingKey` can be used to verify a signature, by passing it both the
+data string and the signature byte string: it either returns True or raises
+`BadSignatureError`.
 
 ```python
 from ecdsa import SigningKey
 sk = SigningKey.generate() # uses NIST192p
-vk = sk.get_verifying_key()
+vk = sk.verifying_key
 signature = sk.sign(b"message")
 assert vk.verify(signature, b"message")
 ```
 
-Each SigningKey/VerifyingKey is associated with a specific curve, like
+Each `SigningKey`/`VerifyingKey` is associated with a specific curve, like
 NIST192p (the default one). Longer curves are more secure, but take longer to
 use, and result in longer keys and signatures.
 
 ```python
 from ecdsa import SigningKey, NIST384p
 sk = SigningKey.generate(curve=NIST384p)
-vk = sk.get_verifying_key()
-signature = sk.sign("message")
-assert vk.verify(signature, "message")
+vk = sk.verifying_key
+signature = sk.sign(b"message")
+assert vk.verify(signature, b"message")
 ```
 
-The SigningKey can be serialized into several different formats: the shortest
+The `SigningKey` can be serialized into several different formats: the shortest
 is to call `s=sk.to_string()`, and then re-create it with
 `SigningKey.from_string(s, curve)` . This short form does not record the
-curve, so you must be sure to tell from_string() the same curve you used for
-the original key. The short form of a NIST192p-based signing key is just 24
+curve, so you must be sure to pass to `from_string()` the same curve you used
+for the original key. The short form of a NIST192p-based signing key is just 24
 bytes long. If a point encoding is invalid or it does not lie on the specified
-curve, `from_string()` will raise MalformedPointError.
+curve, `from_string()` will raise `MalformedPointError`.
 
 ```python
 from ecdsa import SigningKey, NIST384p
 sk = SigningKey.generate(curve=NIST384p)
 sk_string = sk.to_string()
 sk2 = SigningKey.from_string(sk_string, curve=NIST384p)
-# sk and sk2 are the same key
+print(sk_string.hex())
+print(sk2.to_string().hex())
 ```
 
+Note: while the methods are called `to_string()` the type they return is
+actually `bytes`, the "string" part is leftover from Python 2.
+
 `sk.to_pem()` and `sk.to_der()` will serialize the signing key into the same
 formats that OpenSSL uses. The PEM file looks like the familiar ASCII-armored
 `"-----BEGIN EC PRIVATE KEY-----"` base64-encoded format, and the DER format
 is a shorter binary form of the same data.
 `SigningKey.from_pem()/.from_der()` will undo this serialization. These
 formats include the curve name, so you do not need to pass in a curve
 identifier to the deserializer. In case the file is malformed `from_der()`
-and `from_pem()` will raise UnexpectedDER or MalformedPointError.
+and `from_pem()` will raise `UnexpectedDER` or` MalformedPointError`.
 
 ```python
 from ecdsa import SigningKey, NIST384p
@@ -169,52 +174,53 @@ sk2 = SigningKey.from_pem(sk_pem)
 # sk and sk2 are the same key
 ```
 
-Likewise, the VerifyingKey can be serialized in the same way:
+Likewise, the `VerifyingKey` can be serialized in the same way:
 `vk.to_string()/VerifyingKey.from_string()`, `to_pem()/from_pem()`, and
-`to_der()/from_der()`. The same curve= argument is needed for
+`to_der()/from_der()`. The same `curve=` argument is needed for
 `VerifyingKey.from_string()`.
 
 ```python
 from ecdsa import SigningKey, VerifyingKey, NIST384p
 sk = SigningKey.generate(curve=NIST384p)
-vk = sk.get_verifying_key()
+vk = sk.verifying_key
 vk_string = vk.to_string()
 vk2 = VerifyingKey.from_string(vk_string, curve=NIST384p)
 # vk and vk2 are the same key
 
 from ecdsa import SigningKey, VerifyingKey, NIST384p
 sk = SigningKey.generate(curve=NIST384p)
-vk = sk.get_verifying_key()
+vk = sk.verifying_key
 vk_pem = vk.to_pem()
 vk2 = VerifyingKey.from_pem(vk_pem)
 # vk and vk2 are the same key
 ```
 
 There are a couple of different ways to compute a signature. Fundamentally,
 ECDSA takes a number that represents the data being signed, and returns a
-pair of numbers that represent the signature. The hashfunc= argument to
+pair of numbers that represent the signature. The `hashfunc=` argument to
 `sk.sign()` and `vk.verify()` is used to turn an arbitrary string into
 fixed-length digest, which is then turned into a number that ECDSA can sign,
 and both sign and verify must use the same approach. The default value is
-hashlib.sha1, but if you use NIST256p or a longer curve, you can use
-hashlib.sha256 instead.
+`hashlib.sha1`, but if you use NIST256p or a longer curve, you can use
+`hashlib.sha256` instead.
 
 There are also multiple ways to represent a signature. The default
 `sk.sign()` and `vk.verify()` methods present it as a short string, for
 simplicity and minimal overhead. To use a different scheme, use the
 `sk.sign(sigencode=)` and `vk.verify(sigdecode=)` arguments. There are helper
-funcions in the "ecdsa.util" module that can be useful here.
+functions in the `ecdsa.util` module that can be useful here.
 
-It is also possible to create a SigningKey from a "seed", which is
+It is also possible to create a `SigningKey` from a "seed", which is
 deterministic. This can be used in protocols where you want to derive
 consistent signing keys from some other secret, for example when you want
 three separate keys and only want to store a single master secret. You should
-start with a uniformly-distributed unguessable seed with about curve.baselen
-bytes of entropy, and then use one of the helper functions in ecdsa.util to
+start with a uniformly-distributed unguessable seed with about `curve.baselen`
+bytes of entropy, and then use one of the helper functions in `ecdsa.util` to
 convert it into an integer in the correct range, and then finally pass it
 into `SigningKey.from_secret_exponent()`, like this:
 
 ```python
+import os
 from ecdsa import NIST384p, SigningKey
 from ecdsa.util import randrange_from_seed__trytryagain
 
@@ -226,7 +232,9 @@ seed = os.urandom(NIST384p.baselen) # or other starting point
 sk1a = make_key(seed)
 sk1b = make_key(seed)
 # note: sk1a and sk1b are the same key
-sk2 = make_key("2-"+seed)  # different key
+assert sk1a.to_string() == sk1b.to_string()
+sk2 = make_key(b"2-"+seed)  # different key
+assert sk1a.to_string() != sk2.to_string()
 ```
 
 ## OpenSSL Compatibility