1JOSEPY(1) josepy JOSEPY(1)
2
6 josepy - josepy Documentation
7 Javascript Object Signing and Encryption (JOSE).
9 This package is a Python implementation of the standards developed by
11 IETF Javascript Object Signing and Encryption (Active WG), in particu‐
12 lar the following RFCs:
13 • JSON Web Algorithms (JWA)
15 • JSON Web Key (JWK)
17 • JSON Web Signature (JWS)
19 Originally developed as part of the ACME protocol implementation.
21
23 JOSE Base64 is defined as:
24 • URL-safe Base64
26 • padding stripped
28 josepy.b64.b64encode(data: bytes) -> bytes
30 JOSE Base64 encode.
31 Parameters
33 data (bytes) -- Data to be encoded.
34 Returns
36 JOSE Base64 string.
37 Return type
39 bytes
40 Raises TypeError -- if data is of incorrect type
42 josepy.b64.b64decode(data: Union[bytes, str]) -> bytes
44 JOSE Base64 decode.
45 Parameters
47 data (bytes or unicode) -- Base64 string to be decoded.
48 If it's unicode, then only ASCII characters are allowed.
49 Returns
51 Decoded data.
52 Return type
54 bytes
55 Raises
57 • TypeError -- if input is of incorrect type
59 • ValueError -- if input is unicode with non-ASCII char‐
61 acters
62
64 JOSE errors.
65 exception josepy.errors.Error
67 Generic JOSE Error.
68 exception josepy.errors.DeserializationError
70 JSON deserialization error.
71 exception josepy.errors.SerializationError
73 JSON serialization error.
74 exception josepy.errors.UnrecognizedTypeError(typ: str, jobj: Any)
76 Unrecognized type error.
77 Variables
79 • typ (str) -- The unrecognized type of the JSON object.
81 • jobj -- Full JSON object.
83
85 JOSE interfaces.
86 class josepy.interfaces.JSONDeSerializable
88 Interface for (de)serializable JSON objects.
89 Please recall, that standard Python library implements json.JSO‐
91 NEncoder and json.JSONDecoder that perform translations based on
92 respective conversion tables that look pretty much like the one
93 below (for complete tables see relevant Python documentation):
94 ┌───────┬────────┐
96 │JSON │ Python │
97 ├───────┼────────┤
98 │object │ dict │
99 ├───────┼────────┤
100 │... │ ... │
101 └───────┴────────┘
102 While the above conversion table is about translation of JSON
104 documents to/from the basic Python types only,
105 JSONDeSerializable introduces the following two concepts:
106 serialization
108 Turning an arbitrary Python object into Python object
109 that can be encoded into a JSON document. Full serial‐
110 ization produces a Python object composed of only ba‐
111 sic types as required by the conversion table. Partial
112 serialization (accomplished by to_partial_json()) pro‐
113 duces a Python object that might also be built from
114 other JSONDeSerializable objects.
115 deserialization
117 Turning a decoded Python object (necessarily one of
118 the basic types as required by the conversion table)
119 into an arbitrary Python object.
120 Serialization produces serialized object ("partially serialized
122 object" or "fully serialized object" for partial and full seri‐
123 alization respectively) and deserialization produces deserial‐
124 ized object, both usually denoted in the source code as jobj.
125 Wording in the official Python documentation might be confusing
127 after reading the above, but in the light of those definitions,
128 one can view json.JSONDecoder.decode() as decoder and deserial‐
129 izer of basic types, json.JSONEncoder.default() as serializer of
130 basic types, json.JSONEncoder.encode() as serializer and en‐
131 coder of basic types.
132 One could extend json to support arbitrary object (de)serializa‐
134 tion either by:
135 • overriding json.JSONDecoder.decode() and json.JSONEn‐
137 coder.default() in subclasses
138 • or passing object_hook argument (or object_hook_pairs) to
140 json.load()/json.loads() or default argument for
141 json.dump()/json.dumps().
142 Interestingly, default is required to perform only partial seri‐
144 alization, as json.dumps() applies default recursively. This is
145 the idea behind making to_partial_json() produce only partial
146 serialization, while providing custom json_dumps() that dumps
147 with default set to json_dump_default().
148 To make further documentation a bit more concrete, please, con‐
150 sider the following imaginatory implementation example:
151 class Foo(JSONDeSerializable):
153 def to_partial_json(self):
154 return 'foo'
155 @classmethod
157 def from_json(cls, jobj):
158 return Foo()
159 class Bar(JSONDeSerializable):
161 def to_partial_json(self):
162 return [Foo(), Foo()]
163 @classmethod
165 def from_json(cls, jobj):
166 return Bar()
167 abstract to_partial_json() -> Any
169 Partially serialize.
170 Following the example, partial serialization means the
172 following:
173 assert isinstance(Bar().to_partial_json()[0], Foo)
175 assert isinstance(Bar().to_partial_json()[1], Foo)
176 # in particular...
178 assert Bar().to_partial_json() != ['foo', 'foo']
179 Raises josepy.errors.SerializationError -- in case of any
181 serialization error.
182 Returns
184 Partially serializable object.
185 to_json() -> Any
187 Fully serialize.
188 Again, following the example from before, full serializa‐
190 tion means the following:
191 assert Bar().to_json() == ['foo', 'foo']
193 Raises josepy.errors.SerializationError -- in case of any
195 serialization error.
196 Returns
198 Fully serialized object.
199 abstract classmethod from_json(jobj: Any) -> josepy.inter‐
201 faces.GenericJSONDeSerializable
202 Deserialize a decoded JSON document.
203 Parameters
205 jobj -- Python object, composed of only other ba‐
206 sic data types, as decoded from JSON document. Not
207 necessarily dict (as decoded from "JSON object"
208 document).
209 Raises josepy.errors.DeserializationError -- if decoding
211 was unsuccessful, e.g. in case of unparseable X509
212 certificate, or wrong padding in JOSE base64 en‐
213 coded string, etc.
214 classmethod json_loads(json_string: Union[str, bytes]) ->
216 josepy.interfaces.GenericJSONDeSerializable
217 Deserialize from JSON document string.
218 json_dumps(**kwargs: Any) -> str
220 Dump to JSON string using proper serializer.
221 Returns
223 JSON document string.
224 Return type
226 str
227 json_dumps_pretty() -> str
229 Dump the object to pretty JSON document string.
230 Return type
232 str
233 classmethod json_dump_default(python_object: josepy.inter‐
235 faces.JSONDeSerializable) -> Any
236 Serialize Python object.
237 This function is meant to be passed as default to
239 json.dump() or json.dumps(). They call default(python_ob‐
240 ject) only for non-basic Python types, so this function
241 necessarily raises TypeError if python_object is not an
242 instance of IJSONSerializable.
243 Please read the class docstring for more information.
245
247 JSON (de)serialization framework.
248 The framework presented here is somewhat based on Go's "json" package
250 (especially the omitempty functionality).
251 josepy.json_util.field(json_name: str, default: Optional[Any] = None,
253 omitempty: bool = False, decoder: Optional[Callable[[Any], Any]] =
254 None, encoder: Optional[Callable[[Any], Any]] = None) -> Any
255 Convenient function to declare a Field with proper type annota‐
256 tions.
257 This function allows to write the following code:
259 import josepy class JSON(josepy.JSONObjectWithFields):
261 typ: str = josepy.field('type')
262 def other_type(self) -> str:
264 return self.typ
265 class josepy.json_util.Field(json_name: str, default: Optional[Any] =
267 None, omitempty: bool = False, decoder: Optional[Callable[[Any], Any]]
268 = None, encoder: Optional[Callable[[Any], Any]] = None)
269 JSON object field.
270 Field is meant to be used together with JSONObjectWithFields.
272 encoder (decoder) is a callable that accepts a single parameter,
274 i.e. a value to be encoded (decoded), and returns the serialized
275 (deserialized) value. In case of errors it should raise Serial‐
276 izationError (DeserializationError).
277 Note, that decoder should perform partial serialization only.
279 Variables
281 • json_name (str) -- Name of the field when encoded to
283 JSON.
284 • default -- Default value (used when not present in JSON
286 object).
287 • omitempty (bool) -- If True and the field value is
289 empty, then it will not be included in the serialized
290 JSON object, and default will be used for deserializa‐
291 tion. Otherwise, if False, field is considered as re‐
292 quired, value will always be included in the serialized
293 JSON objected, and it must also be present when deseri‐
294 alizing.
295 omit(value: Any) -> bool
297 Omit the value in output?
298 decoder(fdec: Callable[[Any], Any]) -> josepy.json_util.Field
300 Descriptor to change the decoder on JSON object field.
301 encoder(fenc: Callable[[Any], Any]) -> josepy.json_util.Field
303 Descriptor to change the encoder on JSON object field.
304 decode(value: Any) -> Any
306 Decode a value, optionally with context JSON object.
307 encode(value: Any) -> Any
309 Encode a value, optionally with context JSON object.
310 classmethod default_decoder(value: Any) -> Any
312 Default decoder.
313 Recursively deserialize into immutable types (
315 josepy.util.frozendict instead of dict(), tuple() instead
316 of list()).
317 classmethod default_encoder(value: Any) -> Any
319 Default (passthrough) encoder.
320 class josepy.json_util.JSONObjectWithFieldsMeta(name: str, bases:
322 List[str], namespace: Dict[str, Any])
323 Metaclass for JSONObjectWithFields and its subclasses.
324 It makes sure that, for any class cls with __metaclass__ set to
326 JSONObjectWithFieldsMeta:
327 1. All fields (attributes of type Field) in the class definition
329 are moved to the cls._fields dictionary, where keys are field
330 attribute names and values are fields themselves.
331 2. cls.__slots__ is extended by all field attribute names (i.e.
333 not Field.json_name). Original cls.__slots__ are stored in
334 cls._orig_slots.
335 In a consequence, for a field attribute name some_field,
337 cls.some_field will be a slot descriptor and not an instance of
338 Field. For example:
339 some_field = Field('someField', default=())
341 class Foo:
343 __metaclass__ = JSONObjectWithFieldsMeta
344 __slots__ = ('baz',)
345 some_field = some_field
346 assert Foo.__slots__ == ('some_field', 'baz')
348 assert Foo._orig_slots == ()
349 assert Foo.some_field is not Field
350 assert Foo._fields.keys() == ['some_field']
352 assert Foo._fields['some_field'] is some_field
353 As an implementation note, this metaclass inherits from
355 abc.ABCMeta (and not the usual type) to mitigate the metaclass
356 conflict (ImmutableMap and JSONDeSerializable, parents of
357 JSONObjectWithFields, use abc.ABCMeta as its metaclass).
358 class josepy.json_util.JSONObjectWithFields(**kwargs: Any)
360 JSON object with fields.
361 Example:
363 class Foo(JSONObjectWithFields):
365 bar = Field('Bar')
366 empty = Field('Empty', omitempty=True)
367 @bar.encoder
369 def bar(value):
370 return value + 'bar'
371 @bar.decoder
373 def bar(value):
374 if not value.endswith('bar'):
375 raise errors.DeserializationError('No bar suffix!')
376 return value[:-3]
377 assert Foo(bar='baz').to_partial_json() == {'Bar': 'bazbar'}
379 assert Foo.from_json({'Bar': 'bazbar'}) == Foo(bar='baz')
380 assert (Foo.from_json({'Bar': 'bazbar', 'Empty': '!'})
381 == Foo(bar='baz', empty='!'))
382 assert Foo(bar='baz').bar == 'baz'
383 encode(name: str) -> Any
385 Encode a single field.
386 Parameters
388 name (str) -- Name of the field to be encoded.
389 Raises
391 • errors.SerializationError -- if field cannot be
393 serialized
394 • errors.Error -- if field could not be found
396 fields_to_partial_json() -> Dict[str, Any]
398 Serialize fields to JSON.
399 to_partial_json() -> Dict[str, Any]
401 Partially serialize.
402 Following the example, partial serialization means the
404 following:
405 assert isinstance(Bar().to_partial_json()[0], Foo)
407 assert isinstance(Bar().to_partial_json()[1], Foo)
408 # in particular...
410 assert Bar().to_partial_json() != ['foo', 'foo']
411 Raises josepy.errors.SerializationError -- in case of any
413 serialization error.
414 Returns
416 Partially serializable object.
417 classmethod fields_from_json(jobj: Mapping[str, Any]) -> Any
419 Deserialize fields from JSON.
420 classmethod from_json(jobj: Mapping[str, Any]) ->
422 josepy.json_util.GenericJSONObjectWithFields
423 Deserialize a decoded JSON document.
424 Parameters
426 jobj -- Python object, composed of only other ba‐
427 sic data types, as decoded from JSON document. Not
428 necessarily dict (as decoded from "JSON object"
429 document).
430 Raises josepy.errors.DeserializationError -- if decoding
432 was unsuccessful, e.g. in case of unparseable X509
433 certificate, or wrong padding in JOSE base64 en‐
434 coded string, etc.
435 josepy.json_util.encode_b64jose(data: bytes) -> str
437 Encode JOSE Base-64 field.
438 Parameters
440 data (bytes) --
441 Return type
443 str
444 josepy.json_util.decode_b64jose(data: str, size: Optional[int] = None,
446 minimum: bool = False) -> bytes
447 Decode JOSE Base-64 field.
448 Parameters
450 • data (unicode) --
452 • size (int) -- Required length (after decoding).
454 • minimum (bool) -- If True, then size will be treated as
456 minimum required length, as opposed to exact equality.
457 Return type
459 bytes
460 josepy.json_util.encode_hex16(value: bytes) -> str
462 Hexlify.
463 Parameters
465 value (bytes) --
466 Return type
468 unicode
469 josepy.json_util.decode_hex16(value: str, size: Optional[int] = None,
471 minimum: bool = False) -> bytes
472 Decode hexlified field.
473 Parameters
475 • value (unicode) --
477 • size (int) -- Required length (after decoding).
479 • minimum (bool) -- If True, then size will be treated as
481 minimum required length, as opposed to exact equality.
482 Return type
484 bytes
485 josepy.json_util.encode_cert(cert: josepy.util.ComparableX509) -> str
487 Encode certificate as JOSE Base-64 DER.
488 Return type
490 unicode
491 josepy.json_util.decode_cert(b64der: str) -> josepy.util.ComparableX509
493 Decode JOSE Base-64 DER-encoded certificate.
494 Parameters
496 b64der (unicode) --
497 Return type
499 OpenSSL.crypto.X509 wrapped in ComparableX509
500 josepy.json_util.encode_csr(csr: josepy.util.ComparableX509) -> str
502 Encode CSR as JOSE Base-64 DER.
503 Return type
505 unicode
506 josepy.json_util.decode_csr(b64der: str) -> josepy.util.ComparableX509
508 Decode JOSE Base-64 DER-encoded CSR.
509 Parameters
511 b64der (unicode) --
512 Return type
514 OpenSSL.crypto.X509Req wrapped in ComparableX509
515 class josepy.json_util.TypedJSONObjectWithFields(**kwargs: Any)
517 JSON object with type.
518 typ: str = NotImplemented
520 Type of the object. Subclasses must override.
521 type_field_name: str = 'type'
523 Field name used to distinguish different object types.
524 Subclasses will probably have to override this.
526 TYPES: Dict[str, Type] = NotImplemented
528 Types registered for JSON deserialization
529 classmethod register(type_cls: Type[josepy.json_util.Generic‐
531 TypedJSONObjectWithFields], typ: Optional[str] = None) ->
532 Type[josepy.json_util.GenericTypedJSONObjectWithFields]
533 Register class for JSON deserialization.
534 classmethod get_type_cls(jobj: Mapping[str, Any]) ->
536 Type[josepy.json_util.TypedJSONObjectWithFields]
537 Get the registered class for jobj.
538 to_partial_json() -> Dict[str, Any]
540 Get JSON serializable object.
541 Returns
543 Serializable JSON object representing ACME typed
544 object. validate() will almost certainly not
545 work, due to reasons explained in josepy.inter‐
546 faces.IJSONSerializable.
547 Return type
549 dict
550 classmethod from_json(jobj: Mapping[str, Any]) ->
552 josepy.json_util.TypedJSONObjectWithFields
553 Deserialize ACME object from valid JSON object.
554 Raises josepy.errors.UnrecognizedTypeError -- if type of
556 the ACME object has not been registered.
557
559 JSON Web Algorithms.
560 https://tools.ietf.org/html/draft-ietf-jose-json-web-algorithms-40
562 class josepy.jwa.JWA
564 JSON Web Algorithm.
565 class josepy.jwa.JWASignature(name: str)
567 Base class for JSON Web Signature Algorithms.
568 classmethod register(signature_cls: josepy.jwa.JWASignature) ->
570 josepy.jwa.JWASignature
571 Register class for JSON deserialization.
572 to_partial_json() -> Any
574 Partially serialize.
575 Following the example, partial serialization means the
577 following:
578 assert isinstance(Bar().to_partial_json()[0], Foo)
580 assert isinstance(Bar().to_partial_json()[1], Foo)
581 # in particular...
583 assert Bar().to_partial_json() != ['foo', 'foo']
584 Raises josepy.errors.SerializationError -- in case of any
586 serialization error.
587 Returns
589 Partially serializable object.
590 classmethod from_json(jobj: Any) -> josepy.jwa.JWASignature
592 Deserialize a decoded JSON document.
593 Parameters
595 jobj -- Python object, composed of only other ba‐
596 sic data types, as decoded from JSON document. Not
597 necessarily dict (as decoded from "JSON object"
598 document).
599 Raises josepy.errors.DeserializationError -- if decoding
601 was unsuccessful, e.g. in case of unparseable X509
602 certificate, or wrong padding in JOSE base64 en‐
603 coded string, etc.
604 abstract sign(key: Any, msg: bytes) -> bytes
606 Sign the msg using key.
607 abstract verify(key: Any, msg: bytes, sig: bytes) -> bool
609 Verify the msg and sig using key.
610 josepy.jwa.HS256 = HS256
612 HMAC using SHA-256
613 josepy.jwa.HS384 = HS384
615 HMAC using SHA-384
616 josepy.jwa.HS512 = HS512
618 HMAC using SHA-512
619 josepy.jwa.RS256 = RS256
621 RSASSA-PKCS-v1_5 using SHA-256
622 josepy.jwa.RS384 = RS384
624 RSASSA-PKCS-v1_5 using SHA-384
625 josepy.jwa.RS512 = RS512
627 RSASSA-PKCS-v1_5 using SHA-512
628 josepy.jwa.PS256 = PS256
630 RSASSA-PSS using SHA-256 and MGF1 with SHA-256
631 josepy.jwa.PS384 = PS384
633 RSASSA-PSS using SHA-384 and MGF1 with SHA-384
634 josepy.jwa.PS512 = PS512
636 RSASSA-PSS using SHA-512 and MGF1 with SHA-512
637 josepy.jwa.ES256 = ES256
639 ECDSA using P-256 and SHA-256
640 josepy.jwa.ES384 = ES384
642 ECDSA using P-384 and SHA-384
643 josepy.jwa.ES512 = ES512
645 ECDSA using P-521 and SHA-512
646
648 JSON Web Key.
649 class josepy.jwk.JWK(**kwargs: Any)
651 JSON Web Key.
652 cryptography_key_types: Tuple[Type[Any], ...] = ()
654 Subclasses should override.
655 required: Sequence[str] = NotImplemented
657 Required members of public key's representation as de‐
658 fined by JWK/JWA.
659 thumbprint(hash_function: typing.Callable[[], cryptography.haz‐
661 mat.primitives.hashes.HashAlgorithm] = <class 'cryptography.haz‐
662 mat.primitives.hashes.SHA256'>) -> bytes
663 Compute JWK Thumbprint.
664 https://tools.ietf.org/html/rfc7638
666 Returns
668 bytes
669 abstract public_key() -> josepy.jwk.JWK
671 Generate JWK with public key.
672 For symmetric cryptosystems, this would return self.
674 classmethod load(data: bytes, password: Optional[bytes] = None,
676 backend: Optional[Any] = None) -> josepy.jwk.JWK
677 Load serialized key as JWK.
678 Parameters
680 • data (str) -- Public or private key serialized
682 as PEM or DER.
683 • password (str) -- Optional password.
685 • backend -- A PEMSerializationBackend and DERSe‐
687 rializationBackend provider.
688 Raises errors.Error -- if unable to deserialize, or un‐
690 supported JWK algorithm
691 Returns
693 JWK of an appropriate type.
694 Return type
696 JWK
697 class josepy.jwk.JWKOct(**kwargs: Any)
699 Symmetric JWK.
700 fields_to_partial_json() -> Dict[str, str]
702 Serialize fields to JSON.
703 classmethod fields_from_json(jobj: Mapping[str, Any]) ->
705 josepy.jwk.JWKOct
706 Deserialize fields from JSON.
707 public_key() -> josepy.jwk.JWKOct
709 Generate JWK with public key.
710 For symmetric cryptosystems, this would return self.
712 class josepy.jwk.JWKRSA(*args: Any, **kwargs: Any)
714 RSA JWK.
715 Variables
717 key -- RSAPrivateKey or RSAPublicKey wrapped in Compara‐
718 bleRSAKey
719 public_key() -> josepy.jwk.JWKRSA
721 Generate JWK with public key.
722 For symmetric cryptosystems, this would return self.
724 classmethod fields_from_json(jobj: Mapping[str, Any]) ->
726 josepy.jwk.JWKRSA
727 Deserialize fields from JSON.
728 fields_to_partial_json() -> Dict[str, Any]
730 Serialize fields to JSON.
731 class josepy.jwk.JWKEC(*args: Any, **kwargs: Any)
733 EC JWK.
734 Variables
736 key -- EllipticCurvePrivateKey or EllipticCurvePublicKey
737 wrapped in ComparableECKey
738 fields_to_partial_json() -> Dict[str, Any]
740 Serialize fields to JSON.
741 classmethod fields_from_json(jobj: Mapping[str, Any]) ->
743 josepy.jwk.JWKEC
744 Deserialize fields from JSON.
745 public_key() -> josepy.jwk.JWKEC
747 Generate JWK with public key.
748 For symmetric cryptosystems, this would return self.
750
752 JSON Web Signature.
753 class josepy.jws.MediaType
755 MediaType field encoder/decoder.
756 PREFIX = 'application/'
758 MIME Media Type and Content Type prefix.
759 classmethod decode(value: str) -> str
761 Decoder.
762 classmethod encode(value: str) -> str
764 Encoder.
765 class josepy.jws.Header(**kwargs: Any)
767 JOSE Header.
768 WARNING:
770 This class supports only Registered Header Parameter Names
771 (as defined in section 4.1 of the protocol). If you need Pub‐
772 lic Header Parameter Names (4.2) or Private Header Parameter
773 Names (4.3), you must subclass and override from_json() and
774 to_partial_json() appropriately.
775 WARNING:
777 This class does not support any extensions through the "crit"
778 (Critical) Header Parameter (4.1.11) and as a conforming im‐
779 plementation, from_json() treats its occurrence as an error.
780 Please subclass if you seek for a different behaviour.
781 Variables
783 • x5tS256 -- "x5t#S256"
785 • typ (str) -- MIME Media Type, inc. MediaType.PREFIX.
787 • cty (str) -- Content-Type, inc. MediaType.PREFIX.
789 not_omitted() -> Dict[str, josepy.json_util.Field]
791 Fields that would not be omitted in the JSON object.
792 find_key() -> josepy.jwk.JWK
794 Find key based on header.
795
797 Supports only "jwk" header parameter lookup.
798 Returns
800 (Public) key found in the header.
801 Return type
803 .JWK
804 Raises josepy.errors.Error -- if key could not be found
806 class josepy.jws.Signature(**kwargs: Any)
808 JWS Signature.
809 Variables
811 • combined -- Combined Header (protected and unprotected,
813 Header).
814 • protected (unicode) -- JWS protected header (Jose
816 Base-64 decoded).
817 • header -- JWS Unprotected Header (Header).
819 • signature (str) -- The signature.
821 header_cls
823 alias of josepy.jws.Header
824 verify(payload: bytes, key: Optional[josepy.jwk.JWK] = None) ->
826 bool
827 Verify.
828 Parameters
830 • payload (bytes) -- Payload to verify.
832 • key (JWK) -- Key used for verification.
834 classmethod sign(payload: bytes, key: josepy.jwk.JWK, alg:
836 josepy.jwa.JWASignature, include_jwk: bool = True, protect:
837 FrozenSet = frozenset({}), **kwargs: Any) -> josepy.jws.Signa‐
838 ture
839 Sign.
840 Parameters
842 • payload (bytes) -- Payload to sign.
844 • key (JWK) -- Key for signature.
846 • alg (JWASignature) -- Signature algorithm to use
848 to sign.
849 • include_jwk (bool) -- If True, insert the JWK
851 inside the signature headers.
852 • protect (FrozenSet) -- List of headers to pro‐
854 tect.
855 fields_to_partial_json() -> Dict[str, Any]
857 Serialize fields to JSON.
858 classmethod fields_from_json(jobj: Mapping[str, Any]) ->
860 Dict[str, Any]
861 Deserialize fields from JSON.
862 class josepy.jws.JWS(**kwargs: Any)
864 JSON Web Signature.
865 Variables
867 • payload (str) -- JWS Payload.
869 • signature (str) -- JWS Signatures.
871 signature_cls
873 alias of josepy.jws.Signature
874 verify(key: Optional[josepy.jwk.JWK] = None) -> bool
876 Verify.
877 classmethod sign(payload: bytes, **kwargs: Any) ->
879 josepy.jws.JWS
880 Sign.
881 property signature: josepy.jws.Signature
883 Get a singleton signature.
884 Return type
886 JWS.signature_cls
887 to_compact() -> bytes
889 Compact serialization.
890 Return type
892 bytes
893 classmethod from_compact(compact: bytes) -> josepy.jws.JWS
895 Compact deserialization.
896 Parameters
898 compact (bytes) --
899 to_partial_json(flat: bool = True) -> Dict[str, Any]
901 Partially serialize.
902 Following the example, partial serialization means the
904 following:
905 assert isinstance(Bar().to_partial_json()[0], Foo)
907 assert isinstance(Bar().to_partial_json()[1], Foo)
908 # in particular...
910 assert Bar().to_partial_json() != ['foo', 'foo']
911 Raises josepy.errors.SerializationError -- in case of any
913 serialization error.
914 Returns
916 Partially serializable object.
917 classmethod from_json(jobj: Mapping[str, Any]) -> josepy.jws.JWS
919 Deserialize a decoded JSON document.
920 Parameters
922 jobj -- Python object, composed of only other ba‐
923 sic data types, as decoded from JSON document. Not
924 necessarily dict (as decoded from "JSON object"
925 document).
926 Raises josepy.errors.DeserializationError -- if decoding
928 was unsuccessful, e.g. in case of unparseable X509
929 certificate, or wrong padding in JOSE base64 en‐
930 coded string, etc.
931 class josepy.jws.CLI
933 JWS CLI.
934 classmethod sign(args: argparse.Namespace) -> None
936 Sign.
937 classmethod verify(args: argparse.Namespace) -> bool
939 Verify.
940 classmethod run(args: Optional[List[str]] = None) -> Op‐
942 tional[bool]
943 Parse arguments and sign/verify.
944
946 Internal class delegating to a module, and displaying warnings when at‐
947 tributes related to the deprecated "abstractclassmethod" attributes in
948 the josepy.util module.
949 class josepy.util.ComparableX509(wrapped: Union[OpenSSL.crypto.X509,
951 OpenSSL.crypto.X509Req])
952 Wrapper for OpenSSL.crypto.X509** objects that supports __eq__.
953 Variables
955 wrapped -- Wrapped certificate or certificate request.
956 class josepy.util.ComparableKey(wrapped: Union[cryptography.haz‐
958 mat.primitives.asymmetric.rsa.RSAPrivateKey, cryptography.hazmat.primi‐
959 tives.asymmetric.rsa.RSAPublicKey, cryptography.hazmat.primitives.asym‐
960 metric.ec.EllipticCurvePrivateKey, cryptography.hazmat.primitives.asym‐
961 metric.ec.EllipticCurvePublicKey])
962 Comparable wrapper for cryptography keys.
963 See https://github.com/pyca/cryptography/issues/2122.
965 public_key() -> josepy.util.ComparableKey
967 Get wrapped public key.
968 class josepy.util.ComparableRSAKey(wrapped: Union[cryptography.haz‐
970 mat.primitives.asymmetric.rsa.RSAPrivateKey, cryptography.hazmat.primi‐
971 tives.asymmetric.rsa.RSAPublicKey, cryptography.hazmat.primitives.asym‐
972 metric.ec.EllipticCurvePrivateKey, cryptography.hazmat.primitives.asym‐
973 metric.ec.EllipticCurvePublicKey])
974 Wrapper for cryptography RSA keys.
975 Wraps around:
977 • RSAPrivateKey
979 • RSAPublicKey
981 class josepy.util.ComparableECKey(wrapped: Union[cryptography.haz‐
983 mat.primitives.asymmetric.rsa.RSAPrivateKey, cryptography.hazmat.primi‐
984 tives.asymmetric.rsa.RSAPublicKey, cryptography.hazmat.primitives.asym‐
985 metric.ec.EllipticCurvePrivateKey, cryptography.hazmat.primitives.asym‐
986 metric.ec.EllipticCurvePublicKey])
987 Wrapper for cryptography RSA keys. Wraps around: - Elliptic‐
988 CurvePrivateKey - EllipticCurvePublicKey
989 class josepy.util.ImmutableMap(**kwargs: Any)
991 Immutable key to value mapping with attribute access.
992 update(**kwargs: Any) -> josepy.util.GenericImmutableMap
994 Return updated map.
995 class josepy.util.frozendict(*args: Any, **kwargs: Any)
997 Frozen dictionary.
998
1000 1.13.0 (2022-03-10)
1001 • Support for Python 3.6 has been deprecated and will be removed in the
1002 next scheduled release.
1003 • Corrected some type annotations.
1005 1.12.0 (2022-01-11)
1007 • Corrected some type annotations.
1008 • Dropped support for cryptography<1.5.
1010 • Added the top level attributes josepy.JWKEC, josepy.JWKOct, and
1012 josepy.ComparableECKey for convenience and consistency.
1013 1.11.0 (2021-11-17)
1015 • Added support for Python 3.10.
1016 • We changed the PGP key used to sign the packages we upload to PyPI.
1018 Going forward, releases will be signed with one of three different
1019 keys. All of these keys are available on major key servers and signed
1020 by our previous PGP key. The fingerprints of these new keys are:
1021 • BF6BCFC89E90747B9A680FD7B6029E8500F7DB16
1023 • 86379B4F0AF371B50CD9E5FF3402831161D1D280
1025 • 20F201346BF8F3F455A73F9A780CC99432A28621
1027 1.10.0 (2021-09-27)
1029 • josepy is now compliant with PEP-561: type checkers will fetch types
1030 from the inline types annotations when josepy is installed as a de‐
1031 pendency in a Python project.
1032 • Added a field function to assist in adding type annotations for
1034 Fields in classes. If the field function is used to define a Field
1035 in a JSONObjectWithFields based class without a type annotation, an
1036 error will be raised.
1037 • josepy's tests can no longer be imported under the name josepy, how‐
1039 ever, they are still included in the package and you can run them by
1040 installing josepy with "tests" extras and running python -m pytest.
1041 1.9.0 (2021-09-09)
1043 • Removed pytest-cache testing dependency.
1044 • Fixed a bug that sometimes caused incorrect padding to be used when
1046 serializing Elliptic Curve keys as JSON Web Keys.
1047 1.8.0 (2021-03-15)
1049 • Removed external mock dependency.
1050 • Removed dependency on six.
1052 • Deprecated the module josepy.magic_typing.
1054 • Fix JWS/JWK generation with EC keys when keys or signatures have
1056 leading zeros.
1057 1.7.0 (2021-02-11)
1059 • Dropped support for Python 2.7.
1060 • Added support for EC keys.
1062 1.6.0 (2021-01-26)
1064 • Deprecated support for Python 2.7.
1065 1.5.0 (2020-11-03)
1067 • Added support for Python 3.9.
1068 • Dropped support for Python 3.5.
1070 • Stopped supporting running tests with python setup.py test which is
1072 deprecated in favor of python -m pytest.
1073 1.4.0 (2020-08-17)
1075 • Deprecated support for Python 3.5.
1076 1.3.0 (2020-01-28)
1078 • Deprecated support for Python 3.4.
1079 • Officially add support for Python 3.8.
1081 1.2.0 (2019-06-28)
1083 • Support for Python 2.6 and 3.3 has been removed.
1084 • Known incompatibilities with Python 3.8 have been resolved.
1086 1.1.0 (2018-04-13)
1088 • Deprecated support for Python 2.6 and 3.3.
1089 • Use the sign and verify methods when they are available in cryptogra‐
1091 phy instead of the deprecated methods signer and verifier.
1092 1.0.1 (2017-10-25)
1094 Stop installing mock as part of the default but only as part of the
1095 testing dependencies.
1096 1.0.0 (2017-10-13)
1098 First release after moving the josepy package into a standalone li‐
1099 brary.
1100 • genindex
1102 • modindex
1104 • search
1106
1108 Let's Encrypt Project
1109
1111 2015-2022, Let's Encrypt Project
11121.13 Mar 10, 2022 JOSEPY(1)