More documentation

Author: rohe

doc/jws.rst

@@ -9,3 +9,52 @@ or Message Authentication Codes (MACs) using JSON-based data structures.
 It's assumed that you know all you need to know about key handling if not
 please spend some time reading keyhandling_ .
 
+When it comes to JWS there are basically 2 things you want to be able to do: sign some data and verify that a
+signature over some data is correct. I'll deal with them in that order.
+
+Signing a document
+------------------
+
+There are few steps you have to go through. Let us start with an example and then break it into its parts::
+
+    >>> from cryptojwt.jwk.hmac import SYMKey
+    >>> from cryptojwt.jws.jws import JWS
+
+    >>> key = SYMKey(key=b'My hollow echo chamber', alg="HS512")
+    >>> payload = "Please take a moment to register today"
+    >>> _signer = JWS(payload, alg="HS512")
+    >>> _jws = _signer.sign_compact([key])
+
+The steps:
+
+    1. You need keys, one of more. If you provide more then one the software will pick one that has all the necessary
+       qualifications. The keys *MUST* be instances of :py:class:`cryptojwt.jwk.JWK` or of sub classes of that class.
+    2. You need the information that are to be signed. It must be in the form of a string.
+    3. You initiate the signer, providing it with the message and other needed information.
+    4. You sign using the compact or the JSON method as described in section 7 of RFC7515_ .
+
+
+Verifying a signature
+---------------------
+
+Verifying a signature works like this::
+
+    >>> from cryptojwt.jwk.hmac import SYMKey
+    >>> from cryptojwt.jws.jws import JWS
+
+    >>> key = SYMKey(key=b'My hollow echo chamber', alg="HS512")
+    >>> _verifier = JWS(alg="HS512")
+    >>> _msg = _verifier.verify_compact([key])
+    >>> print(_msg)
+    "Please take a moment to register today"
+
+The steps:
+
+    1. As with signing, you need a set of keys that can be used to verify the signature. If you provider more then
+       one possible, then the default is to use then one by one until one works or the list is empty.
+    2. Initiate the verifier. If you have a reason to expect that a particular signing algorithm is to be used you
+       should give that information to the verifier as shown here. If you don't know you can leave it out.
+    3. Verify, using the compact or JSON method.
+
+
+.. _RFC7515: https://tools.ietf.org/html/rfc7515

tests/test_06_jws.py

@@ -10,6 +10,7 @@
 
 from cryptojwt.jws.exception import FormatError
 from cryptojwt.jws.exception import NoSuitableSigningKeys
+from cryptojwt.jws.exception import SignerAlgError
 from cryptojwt.jws.rsa import RSASigner
 from cryptojwt.jws.utils import left_hash
 from cryptojwt.jws.utils import parse_rsa_algorithm
@@ -344,6 +345,20 @@ def test_jws_2():
     assert _jws2.key == key
 
 
+def test_jws_mm():
+    msg = {"iss": "joe", "exp": 1300819380, "http://example.com/is_root": True}
+    key = SYMKey(key=intarr2bin(HMAC_KEY))
+    _jws = JWS(msg, cty="JWT", alg="HS256", jwk=key.serialize())
+    res = _jws.sign_compact()
+
+    _jws2 = JWS(alg="HS512")
+
+    with pytest.raises(SignerAlgError):
+        _jws2.verify_compact(res, keys=[key])
+
+
+
+
 @pytest.mark.parametrize("ec_func,alg", [
     (ec.SECP256R1, "ES256"),
     (ec.SECP384R1, "ES384"),
@@ -783,3 +798,12 @@ def test_extra_headers_2():
     sjwt = _jws.sign_compact(keys)
     _jwt = factory(sjwt)
     assert set(_jwt.jwt.headers.keys()) == {'alg', 'foo'}
+
+
+def test_mismatch_alg_and_key():
+    pkey = import_private_rsa_key_from_file(full_path("./size2048.key"))
+    payload = "Please take a moment to register today"
+    keys = [RSAKey(priv_key=pkey)]
+    _jws = JWS(payload, alg='ES256')
+    with pytest.raises(NoSuitableSigningKeys):
+        _jws.sign_compact(keys)