python-jose¶
A JOSE implementation in Python
The JavaScript Object Signing and Encryption (JOSE) technologies - JSON Web Signature (JWS), JSON Web Encryption (JWE), JSON Web Key (JWK), and JSON Web Algorithms (JWA) - collectively can be used to encrypt and/or sign content using a variety of algorithms. While the full set of permutations is extremely large, and might be daunting to some, it is expected that most applications will only use a small set of algorithms to meet their needs.
Contents¶
JSON Web Signature¶
JSON Web Signatures (JWS) are used to digitally sign a JSON encoded object and represent it as a compact URL-safe string.
Supported Algorithms¶
The following algorithms are currently supported.
Algorithm Value | Digital Signature or MAC Algorithm |
---|---|
HS256 | HMAC using SHA-256 hash algorithm |
HS384 | HMAC using SHA-384 hash algorithm |
HS512 | HMAC using SHA-512 hash algorithm |
RS256 | RSASSA using SHA-256 hash algorithm |
RS384 | RSASSA using SHA-384 hash algorithm |
RS512 | RSASSA using SHA-512 hash algorithm |
ES256 | ECDSA using SHA-256 hash algorithm |
ES384 | ECDSA using SHA-384 hash algorithm |
ES512 | ECDSA using SHA-512 hash algorithm |
Examples¶
Signing tokens¶
>>> from jose import jws
>>> signed = jws.sign({'a': 'b'}, 'secret', algorithm='HS256')
'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhIjoiYiJ9.jiMyrsmD8AoHWeQgmxZ5yq8z0lXS67_QGs52AzC8Ru8'
Verifying token signatures¶
>>> jws.verify(signed, 'secret', algorithms=['HS256'])
{'a': 'b'}
JSON Web Token¶
JSON Web Tokens (JWT) are a JWS with a set of reserved claims to be used in a standardized manner.
JWT Reserved Claims¶
Claim | Name | Format | Usage |
---|---|---|---|
‘exp’ | Expiration | int | The time after which the token is invalid. |
‘nbf’ | Not Before | int | The time before which the token is invalid. |
‘iss’ | Issuer | str | The principal that issued the JWT. |
‘aud’ | Audience | str or list(str) | The recipient that the JWT is intended for. |
‘iat’ | Issued At | int | The time at which the JWT was issued. |
JSON Web Key¶
JSON Web Keys (JWK) are a JSON data structure representing a cryptographic key.
Examples¶
Verifying token signatures¶
>>> from jose import jwk
>>> from jose.utils import base64url_decode
>>>
>>> token = "eyJhbGciOiJIUzI1NiIsImtpZCI6IjAxOGMwYWU1LTRkOWItNDcxYi1iZmQ2LWVlZjMxNGJjNzAzNyJ9.SXTigJlzIGEgZGFuZ2Vyb3VzIGJ1c2luZXNzLCBGcm9kbywgZ29pbmcgb3V0IHlvdXIgZG9vci4gWW91IHN0ZXAgb250byB0aGUgcm9hZCwgYW5kIGlmIHlvdSBkb24ndCBrZWVwIHlvdXIgZmVldCwgdGhlcmXigJlzIG5vIGtub3dpbmcgd2hlcmUgeW91IG1pZ2h0IGJlIHN3ZXB0IG9mZiB0by4.s0h6KThzkfBBBkLspW1h84VsJZFTsPPqMDA7g1Md7p0"
>>> hmac_key = {
"kty": "oct",
"kid": "018c0ae5-4d9b-471b-bfd6-eef314bc7037",
"use": "sig",
"alg": "HS256",
"k": "hJtXIZ2uSN5kbQfbtTNWbpdmhkV8FJG-Onbc6mxCcYg"
}
>>>
>>> key = jwk.construct(hmac_key)
>>>
>>> message, encoded_sig = token.rsplit('.', 1)
>>> decoded_sig = base64url_decode(encoded_sig)
>>> key.verify(message, decoded_sig)
Note¶
python-jose requires the use of public keys, as opposed to X.509 certificates. If you have an X.509 certificate that you would like to convert to a public key that python-jose can consume, you can do so with openssl.
> openssl x509 -pubkey -noout < cert.pem
Principles¶
This is a JOSE implementation that is fully compatible with Google App Engine which requires the use of the PyCrypto library.