docs: update for OctKey.import_key

Author: lepture

docs/guide/algorithms.rst

@@ -65,7 +65,7 @@ algorithms either by the ``algorithms`` parameter, or ``registry`` parameter.
     from joserfc import jws
     from joserfc.jwk import OctKey
 
-    key = OctKey.import_key("secret")
+    key = OctKey.import_key("your-secret-key")
     # HS384 is a non-recommended algorithm
     jws.serialize_compact({"alg": "HS384"}, b"payload", key, algorithms=["HS384"])
 

docs/guide/index.rst

@@ -11,12 +11,11 @@ Encode and decode JWT
 
 .. code-block:: python
 
-    >>> from joserfc import jwt
-    >>> from joserfc.jwk import OctKey
-    >>> key = OctKey.import_key("secret")
-    >>> encoded_jwt = jwt.encode({"alg": "HS256"}, {"key": "value"}, key)
+    >>> from joserfc import jwt, jwk
+    >>> key = jwk.import_key("your-secret-key", "oct")
+    >>> encoded_jwt = jwt.encode({"alg": "HS256"}, {"k": "value"}, key)
     >>> encoded_jwt
-    'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ2YWx1ZSJ9.FG-8UppwHaFp1LgRYQQeS6EDQF7_6-bMFegNucHjmWg'
+    'eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJrIjoidmFsdWUifQ._M8ViO_GK6TnZ9G9eqdlS7IpNWzhoGwaYYDQ3hEwwmA'
     >>> token = jwt.decode(encoded_jwt, key)
     >>> token.header
     {'alg': 'HS256', 'typ': 'JWT'}

docs/guide/jwk.rst

@@ -46,17 +46,17 @@ You can import an ``OctKey`` from string, bytes and a JWK (in dict).
     OctKey.import_key(b"a-random-bytes-as-key")
     OctKey.import_key({
       "kty": "oct",
-      "k": "Zm9v",
+      "k": "eW91ci1zZWNyZXQta2V5",
     })
 
 When importing a key, you can add extra parameters into a key:
 
 .. code-block:: python
 
     >>> from joserfc.jwk import OctKey
-    >>> key = OctKey.import_key("foo", {"use": "sig"})
+    >>> key = OctKey.import_key("your-secret-key", {"use": "sig"})
     >>> key.as_dict()
-    {'k': 'Zm9v', 'use': 'sig', 'kty': 'oct'}
+    {'k': 'eW91ci1zZWNyZXQta2V5', 'use': 'sig', 'kty': 'oct'}
 
 .. _RSAKey:
 
@@ -354,12 +354,12 @@ Call this method to make sure the key contains a ``kid``. If the key has no
 .. code-block:: python
 
     >>> from joserfc.jwk import OctKey
-    >>> key = OctKey.import_key("foo")
+    >>> key = OctKey.import_key("your-secret-key")
     >>> key.kid
     None
     >>> key.ensure_kid()
     >>> key.kid
-    '8-e-qGDS2nDpfZzOPtD8Sb7NkifUbw70MeqOKIqyaRw'
+    'IGfff6pETIMRgwAOHtzIQ_Sflgv5wzWl6SYZlcZ_JDU'
 
 ``as_dict``
 ~~~~~~~~~~~

docs/guide/jws.rst

@@ -45,10 +45,10 @@ You can call :meth:`jws.serialize_compact` to construct a compact JWS serializat
     from joserfc import jws
     from joserfc.jwk import OctKey
 
-    key = OctKey.import_key("secret")
+    key = OctKey.import_key("your-secret-key")
     protected = {"alg": "HS256"}
     jws.serialize_compact(protected, "hello", key)
-    # => 'eyJhbGciOiJIUzI1NiJ9.aGVsbG8.UYmO_lPAY5V0Wf4KZsfhiYs1SxqXPhxvjuYqellDV5A'
+    # => 'eyJhbGciOiJIUzI1NiJ9.aGVsbG8.i_RrfHeMxwHrhk5Xi3J_bU9B9O-gjkMaQtagtqiCndM'
 
 A compact JWS is constructed by protected header, payload and a private key. In the above
 example, ``protected`` is the "protected header" part, `"hello"` is the payload part, and
@@ -65,8 +65,8 @@ serialization with a public key.
     from joserfc import jws
     from joserfc.jwk import OctKey
 
-    text = "eyJhbGciOiJIUzI1NiJ9.aGVsbG8.UYmO_lPAY5V0Wf4KZsfhiYs1SxqXPhxvjuYqellDV5A"
-    key = OctKey.import_key("secret")
+    text = "eyJhbGciOiJIUzI1NiJ9.aGVsbG8.i_RrfHeMxwHrhk5Xi3J_bU9B9O-gjkMaQtagtqiCndM"
+    key = OctKey.import_key("your-secret-key")
     obj = jws.deserialize_compact(text, key)
     # obj.protected => {"alg": "HS256"}
     # obj.payload => b"hello"
@@ -298,7 +298,7 @@ either by the ``algorithms`` parameter, or ``registry`` parameter.
 
     >>> from joserfc import jws
     >>> from joserfc.jwk import OctKey
-    >>> key = OctKey.import_key("secret")
+    >>> key = OctKey.import_key("your-secret-key")
     >>> jws.serialize_compact({"alg": "HS384"}, b"payload", key, algorithms=["HS384"])
     'eyJhbGciOiJIUzM4NCJ9.cGF5bG9hZA.TJEvlp74g89hNRNGNZxCQvB7YDEAWP5vFAjgu1O9Qr5BLMj0NtvbxvYkVYPGp-xQ'
 
@@ -309,7 +309,7 @@ of using :ref:`registry`.
 
     >>> from joserfc import jws
     >>> from joserfc.jwk import OctKey
-    >>> key = OctKey.import_key("secret")
+    >>> key = OctKey.import_key("your-secret-key")
     >>> registry = jws.JWSRegistry(algorithms=["HS384"])
     >>> jws.serialize_compact({"alg": "HS384"}, b"payload", key, registry=registry)
     'eyJhbGciOiJIUzM4NCJ9.cGF5bG9hZA.TJEvlp74g89hNRNGNZxCQvB7YDEAWP5vFAjgu1O9Qr5BLMj0NtvbxvYkVYPGp-xQ'
@@ -332,7 +332,7 @@ Here are examples demonstrating the usage of the ``b64`` option:
     from joserfc.jws import serialize_compact, deserialize_compact
     from joserfc.jwk import OctKey
 
-    key = OctKey.import_key("secret")
+    key = OctKey.import_key("your-secret-key")
     protected = {"alg": "HS256", "b64": False, "crit": ["b64"]}
     value = serialize_compact(protected, "hello", key)
     # => 'eyJhbGciOiJIUzI1NiIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19.hello.mdPbZLtc3tqQ6NCV1pKF-qfEx-3jtR6rv109phKAc4I'
@@ -351,10 +351,10 @@ characters, the compact serialization will detach the payload:
     from joserfc.jws import serialize_compact, deserialize_compact
     from joserfc.jwk import OctKey
 
-    key = OctKey.import_key("secret")
+    key = OctKey.import_key("your-secret-key")
     protected = {"alg": "HS256", "b64": False, "crit": ["b64"]}
     value = serialize_compact(protected, "$.02", key)
-    # => 'eyJhbGciOiJIUzI1NiIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..GbtzAD3Cwe6snTZnaAxapwQz5QftEz7agx_6aMtZ4w0'
+    # => 'eyJhbGciOiJIUzI1NiIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..6iWgAK_TZLgwzk1mhtxs6Imw-dJM1cRstsOKVQ5MjFQ'
     # since the payload is detached, you need to specify the
     # payload when calling deserialize_compact
     deserialize_compact(value, key, payload="$.02")

docs/guide/jwt.rst

@@ -30,7 +30,7 @@ It encodes the payload with the given ``alg`` in header:
 
     header = {"alg": "HS256"}
     claims = {"iss": "https://authlib.org"}
-    key = OctKey.import_key("secret")
+    key = OctKey.import_key("your-secret-key")
     text = jwt.encode(header, claims, key)
 
 The returned value of ``text`` in above example is:
@@ -451,7 +451,7 @@ this algorithm:
     >>> from joserfc import jwt, jwk
     >>> header = {"alg": "HS384"}
     >>> claims = {"iss": "https://authlib.org"}
-    >>> key = jwk.OctKey.import_key("secret")
+    >>> key = jwk.OctKey.import_key("your-secret-key")
     >>> jwt.encode(header, claims, key, algorithms=["HS384"])
 
 If not specifying the ``algorithms`` parameter, the ``encode`` method will
@@ -474,7 +474,7 @@ be raised.
     >>> import uuid
     >>> from joserfc import jwt, jwk
     >>>
-    >>> key = jwk.OctKey.import_key("secret")
+    >>> key = jwk.OctKey.import_key("your-secret-key")
     >>> claims = {"sub": uuid.uuid4()}
     >>> jwt.encode({"alg": "HS256"}, claims, key)
     Traceback (most recent call last):
@@ -512,7 +512,7 @@ To resolve this issue, you can pass a custom ``JSONEncoder`` using the ``encoder
                 return str(o)
             return super().default(o)
 
-    key = jwk.OctKey.import_key("secret")
+    key = jwk.OctKey.import_key("your-secret-key")
     claims = {"sub": uuid.uuid4()}
     jwt.encode({"alg": "HS256"}, claims, key, encoder_cls=MyEncoder)
 

docs/guide/registry.rst

@@ -69,7 +69,7 @@ the value type.
 
     >>> from joserfc import jws
     >>> from joserfc.jwk import OctKey
-    >>> key = OctKey.import_key("secret")
+    >>> key = OctKey.import_key("your-secret-key")
     >>> jws.serialize_compact({"alg": "HS256", "kid": 123}, "hello", key)
     Traceback (most recent call last):
       File "<stdin>", line 1, in <module>
@@ -95,7 +95,7 @@ indicating that they must be present. For example:
 
     >>> from joserfc import jws
     >>> from joserfc.jwk import OctKey
-    >>> key = OctKey.import_key("secret")
+    >>> key = OctKey.import_key("your-secret-key")
     >>> jws.serialize_compact({"alg": "HS256", "crit": ["kid"]}, "hello", key)
     Traceback (most recent call last):
       File "<stdin>", line 1, in <module>
@@ -120,7 +120,7 @@ Any additional header beyond those supported by the algorithm will result in an
 
     >>> from joserfc import jws
     >>> from joserfc.jwk import OctKey
-    >>> key = OctKey.import_key("secret")
+    >>> key = OctKey.import_key("your-secret-key")
     >>> jws.serialize_compact({"alg": "HS256", "custom": "hi"}, "hello", key)
     Traceback (most recent call last):
       File "<stdin>", line 1, in <module>
@@ -143,7 +143,7 @@ to recognize and validate those parameters instead of raising an error.
     from joserfc.registry import HeaderParameter
     from joserfc.jwk import OctKey
 
-    key = OctKey.import_key("secret")
+    key = OctKey.import_key("your-secret-key")
 
     additional_header_registry = {
         "custom": HeaderParameter("Custom message", "str", required=True),

docs/index.rst

@@ -17,12 +17,11 @@ A quick and simple JWT encoding and decoding would look something like this:
 
 .. code-block:: python
 
-    >>> from joserfc import jwt
-    >>> from joserfc.jwk import OctKey
-    >>> key = OctKey.import_key("secret")
+    >>> from joserfc import jwt, jwk
+    >>> key = jwk.import_key("your-secret-key", "oct")
     >>> encoded = jwt.encode({"alg": "HS256"}, {"k": "value"}, key)
     >>> encoded
-    'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrIjoidmFsdWUifQ.ni-MJXnZHpFB_8L9P9yllj3RNDfzmD4yBKAyefSctMY'
+    'eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJrIjoidmFsdWUifQ._M8ViO_GK6TnZ9G9eqdlS7IpNWzhoGwaYYDQ3hEwwmA'
     >>> token = jwt.decode(encoded, key)
     >>> token.header
     {'alg': 'HS256', 'typ': 'JWT'}

docs/migrations/authlib.rst

@@ -24,7 +24,7 @@ In both libraries, you can encode a JWT using the ``jwt.encode(header, payload,
 
     from authlib.jose import jwt
 
-    jwt.encode({"alg": "HS256"}, {"iss": "https://jose.authlib.org"}, "secret")
+    jwt.encode({"alg": "HS256"}, {"iss": "https://jose.authlib.org"}, "your-secret-key")
 
 
 .. code-block:: python
@@ -33,7 +33,7 @@ In both libraries, you can encode a JWT using the ``jwt.encode(header, payload,
     from joserfc import jwt
     from joserfc.jwk import OctKey
 
-    key = OctKey.import_key("secret")
+    key = OctKey.import_key("your-secret-key")
     jwt.encode({"alg": "HS256"}, {"iss": "https://jose.authlib.org"}, key)
 
 jwt.decode
@@ -86,16 +86,16 @@ follow these steps:
 
     protected = {'alg': 'HS256'}
     payload = b"example"
-    value = jws.serialize_compact(protected, payload, "secret")
-    jws.deserialize_compact(value, "secret")
+    value = jws.serialize_compact(protected, payload, "your-secret-key")
+    jws.deserialize_compact(value, "your-secret-key")
 
 .. code-block:: python
     :caption: joserfc
 
     from joserfc import jws
     from joserfc.jwk import OctKey
 
-    key = OctKey.import_key("secret")
+    key = OctKey.import_key("your-secret-key")
     protected = {"alg': 'HS256"}
     payload = b"example"
     value = jws.serialize_compact(protected, payload, key)

docs/migrations/pyjwt.rst

@@ -18,15 +18,15 @@ structure differs between the two libraries.
 
     import jwt
     # jwt.encode(payload, key, algorithm)
-    encoded_jwt = jwt.encode({"some": "payload"}, "secret", algorithm="HS256")
+    encoded_jwt = jwt.encode({"some": "payload"}, "your-secret-key", algorithm="HS256")
 
 .. code-block:: python
     :caption: joserfc
 
     from joserfc import jwt
     from joserfc.jwk import OctKey
 
-    key = OctKey.import_key("secret")  # use an explicit key
+    key = OctKey.import_key("your-secret-key")  # use an explicit key
     # jwt.encode(header, payload, key)
     encoded_jwt = jwt.encode({"alg": "HS256"}, {"some": "payload"}, key)
 
@@ -39,7 +39,7 @@ but the parameter structure differs.
 .. code-block:: python
     :caption: PyJWT
 
-    token = jwt.decode(encoded_jwt, "secret", algorithms=["HS256"])
+    token = jwt.decode(encoded_jwt, "your-secret-key", algorithms=["HS256"])
     # => {"some": "payload"}
 
 .. code-block:: python
@@ -48,7 +48,7 @@ but the parameter structure differs.
     from joserfc import jwt
     from joserfc.jwk import OctKey
 
-    key = OctKey.import_key("secret")
+    key = OctKey.import_key("your-secret-key")
     token = jwt.decode(encoded_jwt, key)
     # => token.header : {"alg": "HS256"}
     # => token.claims : {"some": "payload"}

docs/migrations/python-jose.rst

@@ -24,8 +24,8 @@ and ``jws.deserialize_compact`` for deserialization.
 
     from jose import jws
 
-    signed = jws.sign({'a': 'b'}, 'secret', algorithm='HS256')
-    jws.verify(signed, 'secret', algorithms='HS256')
+    signed = jws.sign({'a': 'b'}, 'your-secret-key', algorithm='HS256')
+    jws.verify(signed, 'your-secret-key', algorithms='HS256')
     # the verify only returns the payload
 
 .. code-block:: python
@@ -35,7 +35,7 @@ and ``jws.deserialize_compact`` for deserialization.
     from joserfc import jws
     from joserfc.jwk import OctKey
 
-    key = OctKey.import_key("secret")
+    key = OctKey.import_key("your-secret-key")
     protected = {"alg": "HS256"}
     signed = jws.serialize_compact(protected, json.dumps({'a': 'b'}), key)
     obj = jws.deserialize_compact(text, key)
@@ -94,8 +94,8 @@ differ significantly in terms of structure and flexibility.
 
     from jose import jwt
 
-    encoded = jwt.encode({'a': 'b'}, 'secret', algorithm='HS256')
-    jwt.decode(encoded, 'secret', algorithms='HS256')
+    encoded = jwt.encode({'a': 'b'}, 'your-secret-key', algorithm='HS256')
+    jwt.decode(encoded, 'your-secret-key', algorithms='HS256')
     # => {'a': 'b'}
 
 .. code-block:: python
@@ -104,7 +104,7 @@ differ significantly in terms of structure and flexibility.
     from joserfc import jwt
     from joserfc.jwk import OctKey
 
-    key = OctKey.import_key("secret")
+    key = OctKey.import_key("your-secret-key")
     # jwt.encode(header, payload, key)
     encoded = jwt.encode({"alg": "HS256"}, {'a': 'b'}, key)
     token = jwt.decode(encoded, key)