diff --git a/doc/jwe.rst b/doc/jwe.rst index d78fb2ad..731c10b6 100644 --- a/doc/jwe.rst +++ b/doc/jwe.rst @@ -6,7 +6,7 @@ JSON Web Encryption (JWE) JSON Web Encryption (JWE) represents encrypted content using JSON-based data structures. -It's assumed that you know all you need to know about key handling if not +It is assumed that you know all you need to know about key handling if not please spend some time reading keyhandling_ . When it comes to JWE there are basically 2 things you want to be able to do: @@ -17,7 +17,7 @@ Encrypting a document --------------------- This is the high level way of doing things. -There are few steps you have to go through. Let us start with an example and then break it into its parts:: +There are a few steps you have to go through. Let us start with an example and then break it into its parts:: >>> from cryptojwt.jwk.rsa import RSAKey >>> from cryptojwt.jwe.jwe import JWE @@ -31,9 +31,9 @@ There are few steps you have to go through. Let us start with an example and the The steps: - 1. You need an encryption key. The key *MUST* be instances of + 1. You need an encryption key. The key *MUST* be an instance of :py:class:`cryptojwt.jwk.JWK`. - 2. You need the information that are to be signed. It must be in the form of a string. + 2. You need the information that is to be signed. It must be in the form of a string. 3. You initiate the encryptor, provide it with the message and other needed information. 4. And then you encrypt as described in RFC7516_ . @@ -74,4 +74,4 @@ or if you know what you're doing:: -.. _RFC7516: https://tools.ietf.org/html/rfc7516 \ No newline at end of file +.. _RFC7516: https://tools.ietf.org/html/rfc7516 diff --git a/doc/jws.rst b/doc/jws.rst index 324d5731..b345ce8a 100644 --- a/doc/jws.rst +++ b/doc/jws.rst @@ -6,7 +6,7 @@ JSON Web Signature (JWS) JSON Web Signature (JWS) represents content secured with digital signatures 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 +It is 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 @@ -27,9 +27,9 @@ There are few steps you have to go through. Let us start with an example and the 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. + 1. You need keys, one or more. If you provide more than one the software will pick one that has all the necessary + qualifications. The keys *MUST* be an instance of :py:class:`cryptojwt.jwk.JWK` or of a sub class of that class. + 2. You need the information that is 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_ . @@ -50,10 +50,10 @@ Verifying a signature works like this (_jws comes from the first signing example 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. + 1. As with signing, you need a set of keys that can be used to verify the signature. If you provide more than + one key, the default is to use them 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. + 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. Or slightly different:: @@ -89,4 +89,4 @@ If you have Key Jar instead of a simple set of keys you can do (not showing how This is a trick that is used in :py:class:`cryptojwt.jwt.JWT` -.. _RFC7515: https://tools.ietf.org/html/rfc7515 \ No newline at end of file +.. _RFC7515: https://tools.ietf.org/html/rfc7515 diff --git a/doc/keyhandling.rst b/doc/keyhandling.rst index c798c7e4..fd5ae2a8 100644 --- a/doc/keyhandling.rst +++ b/doc/keyhandling.rst @@ -56,7 +56,7 @@ mechanism. You can use this to acquire a byte array of the appropriate length When you have a key in a file on your hard drive ................................................ -If you already has a key, like if you have a PEM encoded private RSA key in +If you already have a key, like if you have a PEM encoded private RSA key in a file on your machine you can load it this way:: >>> from cryptojwt.jwk.rsa import RSAKey @@ -96,7 +96,7 @@ Exporting keys .............. When it comes to exporting keys, a :py:class:`cryptojwt.jwk.JWK` instance -only know how to serialize into the format described in JWK_. +only knows how to serialize into the format described in JWK_. >>> from cryptojwt.jwk.rsa import new_rsa_key >>> rsa_key = new_rsa_key() @@ -234,12 +234,12 @@ keys in the key bundle:: >>> len(_keys) 2 -It turns out the key bundle now contains 2 keys. Both the keys that are in the +It turns out the key bundle now contains 2 keys; both the keys that are in the file. If the change is that one key is removed then something else happens. -Assume we add one key and remove one of the ones that was there before. -The file now contain 2 keys, and you might expect the key bundle to do the +Assume we add one key and remove one of the keys that was there before. +The file now contains 2 keys, and you might expect the key bundle to do the same:: >>> _keys = kb.keys() @@ -278,7 +278,7 @@ Creating a key jar with your own newly minted keys you would do: **Note** also that different RSA keys are minted for signing and for encryption. You can also use :py:func:`cryptojwt.keyjar.init_key_jar` which will -load keys from disc if they are there and if not mint new.:: +load keys from disk if they are there and if not mint new.:: >>> from cryptojwt.key_jar import build_keyjar >>> import os @@ -318,8 +318,8 @@ The last line can also be expressed as:: >>> keyjar[''] = kb -**Note** both variants adds a key bundle to the list of key bundles that -belongs to '', it does not overwrite anything that was already there. +**Note** both variants add a key bundle to the list of key bundles that +belong to '', it does not overwrite anything that was already there. Adding a JWKS is such a common thing that there is a simpler way to do it:: @@ -346,7 +346,7 @@ When dealing with signed and/or encrypted JSON Web Tokens :py:class:`cryptojwt.key_jar.KeyJar` has these nice methods. get_jwt_verify_keys - :py:func:`cryptojwt.key_jar.KeyJar.get_jwt_verify_keys` takes an + :py:func:`cryptojwt.key_jar.KeyJar.get_jwt_verify_keys` takes a signed JWT as input and returns a set of keys that can be used to verify the signature. The set you get back is a best estimate and might not contain **the** key. How good the estimate is