1JOSEPY(1)                           josepy                           JOSEPY(1)
2
3
4

NAME

6       josepy - josepy Documentation
7
8       Javascript Object Signing and Encryption (JOSE).
9
10       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
14       · JSON Web Algorithms (JWA)
15
16       · JSON Web Key (JWK)
17
18       · JSON Web Signature (JWS)
19
20       Originally developed as part of the ACME protocol implementation.
21

JOSE BASE64

23       JOSE Base64 is defined as:
24
25          · URL-safe Base64
26
27          · padding stripped
28
29       josepy.b64.b64encode(data)
30              JOSE Base64 encode.
31
32              Parameters
33                     data (bytes) -- Data to be encoded.
34
35              Returns
36                     JOSE Base64 string.
37
38              Return type
39                     bytes
40
41              Raises TypeError -- if data is of incorrect type
42
43       josepy.b64.b64decode(data)
44              JOSE Base64 decode.
45
46              Parameters
47                     data  (bytes  or unicode) -- Base64 string to be decoded.
48                     If it's unicode, then only ASCII characters are allowed.
49
50              Returns
51                     Decoded data.
52
53              Return type
54                     bytes
55
56              Raises
57
58                     · TypeError -- if input is of incorrect type
59
60                     · ValueError -- if input is unicode with non-ASCII  char‐
61                       acters
62

ERRORS

64       JOSE errors.
65
66       exception josepy.errors.Error
67              Bases: Exception
68
69              Generic JOSE Error.
70
71       exception josepy.errors.DeserializationError
72              Bases: josepy.errors.Error
73
74              JSON deserialization error.
75
76       exception josepy.errors.SerializationError
77              Bases: josepy.errors.Error
78
79              JSON serialization error.
80
81       exception josepy.errors.UnrecognizedTypeError(typ, jobj)
82              Bases: josepy.errors.DeserializationError
83
84              Unrecognized type error.
85
86              Variables
87
88                     · typ (str) -- The unrecognized type of the JSON object.
89
90                     · jobj -- Full JSON object.
91

INTERFACES

93       JOSE interfaces.
94
95       class josepy.interfaces.JSONDeSerializable
96              Bases: object
97
98              Interface for (de)serializable JSON objects.
99
100              Please recall, that standard Python library implements json.JSO‐
101              NEncoder and json.JSONDecoder that perform translations based on
102              respective  conversion tables that look pretty much like the one
103              below (for complete tables see relevant Python documentation):
104
105                                     ┌───────┬────────┐
106                                     │JSON   │ Python │
107                                     ├───────┼────────┤
108                                     │object │ dict   │
109                                     ├───────┼────────┤
110                                     │...    │ ...    │
111                                     └───────┴────────┘
112
113              While the above conversion table is about  translation  of  JSON
114              documents    to/from    the    basic    Python    types    only,
115              JSONDeSerializable introduces the following two concepts:
116
117                 serialization
118                        Turning an arbitrary Python object into Python  object
119                        that can be encoded into a JSON document. Full serial‐
120                        ization produces a  Python  object  composed  of  only
121                        basic  types as required by the conversion table. Par‐
122                        tial serialization (accomplished by to_partial_json())
123                        produces a Python object that might also be built from
124                        other JSONDeSerializable objects.
125
126                 deserialization
127                        Turning a decoded Python object  (necessarily  one  of
128                        the  basic  types as required by the conversion table)
129                        into an arbitrary Python object.
130
131              Serialization produces serialized object ("partially  serialized
132              object"  or "fully serialized object" for partial and full seri‐
133              alization respectively) and deserialization  produces  deserial‐
134              ized object, both usually denoted in the source code as jobj.
135
136              Wording  in the official Python documentation might be confusing
137              after reading the above, but in the light of those  definitions,
138              one  can view json.JSONDecoder.decode() as decoder and deserial‐
139              izer of basic types, json.JSONEncoder.default() as serializer of
140              basic   types,   json.JSONEncoder.encode()   as  serializer  and
141              encoder of basic types.
142
143              One could extend json to support arbitrary object (de)serializa‐
144              tion either by:
145
146                 · overriding   json.JSONDecoder.decode()   and   json.JSONEn‐
147                   coder.default() in subclasses
148
149                 · or passing object_hook argument (or  object_hook_pairs)  to
150                   json.load()/json.loads()    or    default    argument   for
151                   json.dump()/json.dumps().
152
153              Interestingly, default is required to perform only partial seri‐
154              alization,  as json.dumps() applies default recursively. This is
155              the idea behind making to_partial_json()  produce  only  partial
156              serialization,  while  providing  custom json_dumps() that dumps
157              with default set to json_dump_default().
158
159              To make further documentation a bit more concrete, please,  con‐
160              sider the following imaginatory implementation example:
161
162                 class Foo(JSONDeSerializable):
163                     def to_partial_json(self):
164                         return 'foo'
165
166                     @classmethod
167                     def from_json(cls, jobj):
168                         return Foo()
169
170                 class Bar(JSONDeSerializable):
171                     def to_partial_json(self):
172                         return [Foo(), Foo()]
173
174                     @classmethod
175                     def from_json(cls, jobj):
176                         return Bar()
177
178              abstract to_partial_json()
179                     Partially serialize.
180
181                     Following  the  example,  partial serialization means the
182                     following:
183
184                        assert isinstance(Bar().to_partial_json()[0], Foo)
185                        assert isinstance(Bar().to_partial_json()[1], Foo)
186
187                        # in particular...
188                        assert Bar().to_partial_json() != ['foo', 'foo']
189
190                     Raises josepy.errors.SerializationError -- in case of any
191                            serialization error.
192
193                     Returns
194                            Partially serializable object.
195
196              to_json()
197                     Fully serialize.
198
199                     Again, following the example from before, full serializa‐
200                     tion means the following:
201
202                        assert Bar().to_json() == ['foo', 'foo']
203
204                     Raises josepy.errors.SerializationError -- in case of any
205                            serialization error.
206
207                     Returns
208                            Fully serialized object.
209
210              abstract classmethod from_json(jobj)
211                     Deserialize a decoded JSON document.
212
213                     Parameters
214                            jobj  --  Python  object,  composed  of only other
215                            basic data types, as decoded from  JSON  document.
216                            Not   necessarily  dict  (as  decoded  from  "JSON
217                            object" document).
218
219                     Raises josepy.errors.DeserializationError -- if  decoding
220                            was unsuccessful, e.g. in case of unparseable X509
221                            certificate,  or  wrong  padding  in  JOSE  base64
222                            encoded string, etc.
223
224              classmethod json_loads(json_string)
225                     Deserialize from JSON document string.
226
227              json_dumps(**kwargs)
228                     Dump to JSON string using proper serializer.
229
230                     Returns
231                            JSON document string.
232
233                     Return type
234                            str
235
236              json_dumps_pretty()
237                     Dump the object to pretty JSON document string.
238
239                     Return type
240                            str
241
242              classmethod json_dump_default(python_object)
243                     Serialize Python object.
244
245                     This  function  is  meant  to  be  passed  as  default to
246                     json.dump()     or      json.dumps().      They      call
247                     default(python_object)  only  for non-basic Python types,
248                     so  this  function  necessarily   raises   TypeError   if
249                     python_object is not an instance of IJSONSerializable.
250
251                     Please read the class docstring for more information.
252

JSON UTILITIES

254       JSON (de)serialization framework.
255
256       The  framework  presented here is somewhat based on Go's "json" package
257       (especially the omitempty functionality).
258
259       class josepy.json_util.Field(json_name, default=None,  omitempty=False,
260       decoder=None, encoder=None)
261              Bases: object
262
263              JSON object field.
264
265              Field is meant to be used together with JSONObjectWithFields.
266
267              encoder (decoder) is a callable that accepts a single parameter,
268              i.e. a value to be encoded (decoded), and returns the serialized
269              (deserialized)  value. In case of errors it should raise Serial‐
270              izationError (DeserializationError).
271
272              Note, that decoder should perform partial serialization only.
273
274              Variables
275
276                     · json_name (str) -- Name of the field  when  encoded  to
277                       JSON.
278
279                     · default -- Default value (used when not present in JSON
280                       object).
281
282                     · omitempty (bool) -- If True  and  the  field  value  is
283                       empty,  then  it will not be included in the serialized
284                       JSON object, and default will be used for  deserializa‐
285                       tion.  Otherwise,  if  False,  field  is  considered as
286                       required, value will always be included in the  serial‐
287                       ized  JSON  objected,  and it must also be present when
288                       deserializing.
289
290              classmethod _empty(value)
291                     Is the provided value considered "empty" for this field?
292
293                     This is useful for subclasses that might want to override
294                     the  definition of being empty, e.g. for some more exotic
295                     data types.
296
297              omit(value)
298                     Omit the value in output?
299
300              decoder(fdec)
301                     Descriptor to change the decoder on JSON object field.
302
303              encoder(fenc)
304                     Descriptor to change the encoder on JSON object field.
305
306              decode(value)
307                     Decode a value, optionally with context JSON object.
308
309              encode(value)
310                     Encode a value, optionally with context JSON object.
311
312              classmethod default_decoder(value)
313                     Default decoder.
314
315                     Recursively   deserialize   into   immutable   types    (
316                     josepy.util.frozendict instead of dict(), tuple() instead
317                     of list()).
318
319              classmethod default_encoder(value)
320                     Default (passthrough) encoder.
321
322       class josepy.json_util.JSONObjectWithFieldsMeta
323              Bases: abc.ABCMeta
324
325              Metaclass for JSONObjectWithFields and its subclasses.
326
327              It makes sure that, for any class cls with __metaclass__ set  to
328              JSONObjectWithFieldsMeta:
329
330              1. All fields (attributes of type Field) in the class definition
331                 are moved to the cls._fields dictionary, where keys are field
332                 attribute names and values are fields themselves.
333
334              2. cls.__slots__  is extended by all field attribute names (i.e.
335                 not Field.json_name). Original cls.__slots__  are  stored  in
336                 cls._orig_slots.
337
338              In  a  consequence,  for  a  field  attribute  name  some_field,
339              cls.some_field will be a slot descriptor and not an instance  of
340              Field. For example:
341
342                 some_field = Field('someField', default=())
343
344                 class Foo(object):
345                     __metaclass__ = JSONObjectWithFieldsMeta
346                     __slots__ = ('baz',)
347                     some_field = some_field
348
349                 assert Foo.__slots__ == ('some_field', 'baz')
350                 assert Foo._orig_slots == ()
351                 assert Foo.some_field is not Field
352
353                 assert Foo._fields.keys() == ['some_field']
354                 assert Foo._fields['some_field'] is some_field
355
356              As   an   implementation  note,  this  metaclass  inherits  from
357              abc.ABCMeta (and not the usual type) to mitigate  the  metaclass
358              conflict   (ImmutableMap   and  JSONDeSerializable,  parents  of
359              JSONObjectWithFields, use abc.ABCMeta as its metaclass).
360
361       class josepy.json_util.JSONObjectWithFields(**kwargs)
362              Bases: josepy.util.ImmutableMap, josepy.interfaces.JSONDeSerial‐
363              izable
364
365              JSON object with fields.
366
367              Example:
368
369                 class Foo(JSONObjectWithFields):
370                     bar = Field('Bar')
371                     empty = Field('Empty', omitempty=True)
372
373                     @bar.encoder
374                     def bar(value):
375                         return value + 'bar'
376
377                     @bar.decoder
378                     def bar(value):
379                         if not value.endswith('bar'):
380                             raise errors.DeserializationError('No bar suffix!')
381                         return value[:-3]
382
383                 assert Foo(bar='baz').to_partial_json() == {'Bar': 'bazbar'}
384                 assert Foo.from_json({'Bar': 'bazbar'}) == Foo(bar='baz')
385                 assert (Foo.from_json({'Bar': 'bazbar', 'Empty': '!'})
386                         == Foo(bar='baz', empty='!'))
387                 assert Foo(bar='baz').bar == 'baz'
388
389              classmethod _defaults()
390                     Get default fields values.
391
392              encode(name)
393                     Encode a single field.
394
395                     Parameters
396                            name (str) -- Name of the field to be encoded.
397
398                     Raises
399
400                            · errors.SerializationError  -- if field cannot be
401                              serialized
402
403                            · errors.Error -- if field could not be found
404
405              fields_to_partial_json()
406                     Serialize fields to JSON.
407
408              to_partial_json()
409                     Partially serialize.
410
411                     Following the example, partial  serialization  means  the
412                     following:
413
414                        assert isinstance(Bar().to_partial_json()[0], Foo)
415                        assert isinstance(Bar().to_partial_json()[1], Foo)
416
417                        # in particular...
418                        assert Bar().to_partial_json() != ['foo', 'foo']
419
420                     Raises josepy.errors.SerializationError -- in case of any
421                            serialization error.
422
423                     Returns
424                            Partially serializable object.
425
426              classmethod fields_from_json(jobj)
427                     Deserialize fields from JSON.
428
429              classmethod from_json(jobj)
430                     Deserialize a decoded JSON document.
431
432                     Parameters
433                            jobj -- Python  object,  composed  of  only  other
434                            basic  data  types, as decoded from JSON document.
435                            Not  necessarily  dict  (as  decoded  from   "JSON
436                            object" document).
437
438                     Raises josepy.errors.DeserializationError  -- if decoding
439                            was unsuccessful, e.g. in case of unparseable X509
440                            certificate,  or  wrong  padding  in  JOSE  base64
441                            encoded string, etc.
442
443       josepy.json_util.encode_b64jose(data)
444              Encode JOSE Base-64 field.
445
446              Parameters
447                     data (bytes) --
448
449              Return type
450                     unicode
451
452       josepy.json_util.decode_b64jose(data, size=None, minimum=False)
453              Decode JOSE Base-64 field.
454
455              Parameters
456
457                     · data (unicode) --
458
459                     · size (int) -- Required length (after decoding).
460
461                     · minimum (bool) -- If True, then size will be treated as
462                       minimum required length, as opposed to exact equality.
463
464              Return type
465                     bytes
466
467       josepy.json_util.encode_hex16(value)
468              Hexlify.
469
470              Parameters
471                     value (bytes) --
472
473              Return type
474                     unicode
475
476       josepy.json_util.decode_hex16(value, size=None, minimum=False)
477              Decode hexlified field.
478
479              Parameters
480
481                     · value (unicode) --
482
483                     · size (int) -- Required length (after decoding).
484
485                     · minimum (bool) -- If True, then size will be treated as
486                       minimum required length, as opposed to exact equality.
487
488              Return type
489                     bytes
490
491       josepy.json_util.encode_cert(cert)
492              Encode certificate as JOSE Base-64 DER.
493
494              Return type
495                     unicode
496
497       josepy.json_util.decode_cert(b64der)
498              Decode JOSE Base-64 DER-encoded certificate.
499
500              Parameters
501                     b64der (unicode) --
502
503              Return type
504                     OpenSSL.crypto.X509 wrapped in ComparableX509
505
506       josepy.json_util.encode_csr(csr)
507              Encode CSR as JOSE Base-64 DER.
508
509              Return type
510                     unicode
511
512       josepy.json_util.decode_csr(b64der)
513              Decode JOSE Base-64 DER-encoded CSR.
514
515              Parameters
516                     b64der (unicode) --
517
518              Return type
519                     OpenSSL.crypto.X509Req wrapped in ComparableX509
520
521       class josepy.json_util.TypedJSONObjectWithFields(**kwargs)
522              Bases: josepy.json_util.JSONObjectWithFields
523
524              JSON object with type.
525
526              typ = NotImplemented
527                     Type of the object. Subclasses must override.
528
529              type_field_name = 'type'
530                     Field name used to distinguish different object types.
531
532                     Subclasses will probably have to override this.
533
534              TYPES = NotImplemented
535                     Types registered for JSON deserialization
536
537              classmethod register(type_cls, typ=None)
538                     Register class for JSON deserialization.
539
540              classmethod get_type_cls(jobj)
541                     Get the registered class for jobj.
542
543              to_partial_json()
544                     Get JSON serializable object.
545
546                     Returns
547                            Serializable JSON object representing  ACME  typed
548                            object.   validate()  will  almost  certainly  not
549                            work, due to reasons  explained  in  josepy.inter‐
550                            faces.IJSONSerializable.
551
552                     Return type
553                            dict
554
555              classmethod from_json(jobj)
556                     Deserialize ACME object from valid JSON object.
557
558                     Raises josepy.errors.UnrecognizedTypeError  -- if type of
559                            the ACME object has not been registered.
560

JSON WEB ALGORITHMS

562       JSON Web Algorithms.
563
564       https://tools.ietf.org/html/draft-ietf-jose-json-web-algorithms-40
565
566       class josepy.jwa.JWA
567              Bases: josepy.interfaces.JSONDeSerializable
568
569              JSON Web Algorithm.
570
571       class josepy.jwa.JWASignature(name)
572              Bases: josepy.jwa.JWA, collections.abc.Hashable
573
574              Base class for JSON Web Signature Algorithms.
575
576              classmethod register(signature_cls)
577                     Register class for JSON deserialization.
578
579              to_partial_json()
580                     Partially serialize.
581
582                     Following the example, partial  serialization  means  the
583                     following:
584
585                        assert isinstance(Bar().to_partial_json()[0], Foo)
586                        assert isinstance(Bar().to_partial_json()[1], Foo)
587
588                        # in particular...
589                        assert Bar().to_partial_json() != ['foo', 'foo']
590
591                     Raises josepy.errors.SerializationError -- in case of any
592                            serialization error.
593
594                     Returns
595                            Partially serializable object.
596
597              classmethod from_json(jobj)
598                     Deserialize a decoded JSON document.
599
600                     Parameters
601                            jobj -- Python  object,  composed  of  only  other
602                            basic  data  types, as decoded from JSON document.
603                            Not  necessarily  dict  (as  decoded  from   "JSON
604                            object" document).
605
606                     Raises josepy.errors.DeserializationError  -- if decoding
607                            was unsuccessful, e.g. in case of unparseable X509
608                            certificate,  or  wrong  padding  in  JOSE  base64
609                            encoded string, etc.
610
611              abstract sign(key, msg)
612                     Sign the msg using key.
613
614              abstract verify(key, msg, sig)
615                     Verify the msg and sig using key.
616
617       class josepy.jwa._JWAHS(name, hash_)
618              Bases: josepy.jwa.JWASignature
619
620              kty    alias of josepy.jwk.JWKOct
621
622              sign(key, msg)
623                     Sign the msg using key.
624
625              verify(key, msg, sig)
626                     Verify the msg and sig using key.
627
628       class josepy.jwa._JWARS(name, hash_)
629              Bases: josepy.jwa._JWARSA, josepy.jwa.JWASignature
630
631       class josepy.jwa._JWAPS(name, hash_)
632              Bases: josepy.jwa._JWARSA, josepy.jwa.JWASignature
633
634       class josepy.jwa._JWAES(name)
635              Bases: josepy.jwa.JWASignature
636
637              sign(key, msg)
638                     Sign the msg using key.
639
640              verify(key, msg, sig)
641                     Verify the msg and sig using key.
642
643       josepy.jwa.HS256 = HS256
644              HMAC using SHA-256
645
646       josepy.jwa.HS384 = HS384
647              HMAC using SHA-384
648
649       josepy.jwa.HS512 = HS512
650              HMAC using SHA-512
651
652       josepy.jwa.RS256 = RS256
653              RSASSA-PKCS-v1_5 using SHA-256
654
655       josepy.jwa.RS384 = RS384
656              RSASSA-PKCS-v1_5 using SHA-384
657
658       josepy.jwa.RS512 = RS512
659              RSASSA-PKCS-v1_5 using SHA-512
660
661       josepy.jwa.PS256 = PS256
662              RSASSA-PSS using SHA-256 and MGF1 with SHA-256
663
664       josepy.jwa.PS384 = PS384
665              RSASSA-PSS using SHA-384 and MGF1 with SHA-384
666
667       josepy.jwa.PS512 = PS512
668              RSASSA-PSS using SHA-512 and MGF1 with SHA-512
669
670       josepy.jwa.ES256 = ES256
671              ECDSA using P-256 and SHA-256
672
673       josepy.jwa.ES384 = ES384
674              ECDSA using P-384 and SHA-384
675
676       josepy.jwa.ES512 = ES512
677              ECDSA using P-521 and SHA-512
678

JSON WEB KEY

680       JSON Web Key.
681
682       class josepy.jwk.JWK(**kwargs)
683              Bases: josepy.json_util.TypedJSONObjectWithFields
684
685              JSON Web Key.
686
687              cryptography_key_types = ()
688                     Subclasses should override.
689
690              required = NotImplemented
691                     Required  members  of  public  key's  representation   as
692                     defined by JWK/JWA.
693
694              thumbprint(hash_function=<class      'cryptography.hazmat.primi‐
695              tives.hashes.SHA256'>)
696                     Compute JWK Thumbprint.
697
698                     https://tools.ietf.org/html/rfc7638
699
700                     Returns
701                            bytes
702
703              abstract public_key()
704                     Generate JWK with public key.
705
706                     For symmetric cryptosystems, this would return self.
707
708              classmethod load(data, password=None, backend=None)
709                     Load serialized key as JWK.
710
711                     Parameters
712
713                            · data (str) -- Public or private  key  serialized
714                              as PEM or DER.
715
716                            · password (str) -- Optional password.
717
718                            · backend  -- A PEMSerializationBackend and DERSe‐
719                              rializationBackend provider.
720
721                     Raises errors.Error  --  if  unable  to  deserialize,  or
722                            unsupported JWK algorithm
723
724                     Returns
725                            JWK of an appropriate type.
726
727                     Return type
728                            JWK
729
730       class josepy.jwk.JWKES(**kwargs)
731              Bases: josepy.jwk.JWK
732
733              ES JWK.
734
735              WARNING:
736                 This is not yet implemented!
737
738              fields_to_partial_json()
739                     Serialize fields to JSON.
740
741              classmethod fields_from_json(jobj)
742                     Deserialize fields from JSON.
743
744              public_key()
745                     Generate JWK with public key.
746
747                     For symmetric cryptosystems, this would return self.
748
749       class josepy.jwk.JWKOct(**kwargs)
750              Bases: josepy.jwk.JWK
751
752              Symmetric JWK.
753
754              fields_to_partial_json()
755                     Serialize fields to JSON.
756
757              classmethod fields_from_json(jobj)
758                     Deserialize fields from JSON.
759
760              public_key()
761                     Generate JWK with public key.
762
763                     For symmetric cryptosystems, this would return self.
764
765       class josepy.jwk.JWKRSA(*args, **kwargs)
766              Bases: josepy.jwk.JWK
767
768              RSA JWK.
769
770              Variables
771                     key  -- RSAPrivateKey or RSAPublicKey wrapped in Compara‐
772                     bleRSAKey
773
774              classmethod _encode_param(data)
775                     Encode Base64urlUInt.
776
777                     Return type
778                            unicode
779
780              classmethod _decode_param(data)
781                     Decode Base64urlUInt.
782
783              public_key()
784                     Generate JWK with public key.
785
786                     For symmetric cryptosystems, this would return self.
787
788              classmethod fields_from_json(jobj)
789                     Deserialize fields from JSON.
790
791              fields_to_partial_json()
792                     Serialize fields to JSON.
793

JSON WEB SIGNATURE

795       JSON Web Signature.
796
797       class josepy.jws.MediaType
798              Bases: object
799
800              MediaType field encoder/decoder.
801
802              PREFIX = 'application/'
803                     MIME Media Type and Content Type prefix.
804
805              classmethod decode(value)
806                     Decoder.
807
808              classmethod encode(value)
809                     Encoder.
810
811       class josepy.jws.Header(**kwargs)
812              Bases: josepy.json_util.JSONObjectWithFields
813
814              JOSE Header.
815
816              WARNING:
817                 This class supports only Registered  Header  Parameter  Names
818                 (as defined in section 4.1 of the protocol). If you need Pub‐
819                 lic Header Parameter Names (4.2) or Private Header  Parameter
820                 Names  (4.3),  you must subclass and override from_json() and
821                 to_partial_json() appropriately.
822
823              WARNING:
824                 This class does not support any extensions through the "crit"
825                 (Critical)  Header  Parameter  (4.1.11)  and  as a conforming
826                 implementation,  from_json()  treats  its  occurrence  as  an
827                 error. Please subclass if you seek for a different behaviour.
828
829              Variables
830
831                     · x5tS256 -- "x5t#S256"
832
833                     · typ (str) -- MIME Media Type, inc. MediaType.PREFIX.
834
835                     · cty (str) -- Content-Type, inc. MediaType.PREFIX.
836
837              not_omitted()
838                     Fields that would not be omitted in the JSON object.
839
840              find_key()
841                     Find key based on header.
842

TODO

844       Supports only "jwk" header parameter lookup.
845
846              Returns
847                     (Public) key found in the header.
848
849              Return type
850                     JWK
851
852              Raises josepy.errors.Error -- if key could not be found
853
854       class josepy.jws.Signature(**kwargs)
855              Bases: josepy.json_util.JSONObjectWithFields
856
857              JWS Signature.
858
859              Variables
860
861                     · combined -- Combined Header (protected and unprotected,
862                       Header).
863
864                     · protected  (unicode)  --  JWS  protected  header  (Jose
865                       Base-64 decoded).
866
867                     · header -- JWS Unprotected Header (Header).
868
869                     · signature (str) -- The signature.
870
871              header_cls
872                     alias of Header
873
874              verify(payload, key=None)
875                     Verify.
876
877                     Parameters
878                            key (JWK) -- Key used for verification.
879
880              classmethod   sign(payload,  key,  alg,  include_jwk=True,  pro‐
881              tect=frozenset({}), **kwargs)
882                     Sign.
883
884                     Parameters
885                            key (JWK) -- Key for signature.
886
887              fields_to_partial_json()
888                     Serialize fields to JSON.
889
890              classmethod fields_from_json(jobj)
891                     Deserialize fields from JSON.
892
893       class josepy.jws.JWS(**kwargs)
894              Bases: josepy.json_util.JSONObjectWithFields
895
896              JSON Web Signature.
897
898              Variables
899
900                     · payload (str) -- JWS Payload.
901
902                     · signature (str) -- JWS Signatures.
903
904              signature_cls
905                     alias of Signature
906
907              verify(key=None)
908                     Verify.
909
910              classmethod sign(payload, **kwargs)
911                     Sign.
912
913              property signature
914                     Get a singleton signature.
915
916                     Return type
917                            JWS.signature_cls
918
919              to_compact()
920                     Compact serialization.
921
922                     Return type
923                            bytes
924
925              classmethod from_compact(compact)
926                     Compact deserialization.
927
928                     Parameters
929                            compact (bytes) --
930
931              to_partial_json(flat=True)
932                     Partially serialize.
933
934                     Following the example, partial  serialization  means  the
935                     following:
936
937                        assert isinstance(Bar().to_partial_json()[0], Foo)
938                        assert isinstance(Bar().to_partial_json()[1], Foo)
939
940                        # in particular...
941                        assert Bar().to_partial_json() != ['foo', 'foo']
942
943                     Raises josepy.errors.SerializationError -- in case of any
944                            serialization error.
945
946                     Returns
947                            Partially serializable object.
948
949              classmethod from_json(jobj)
950                     Deserialize a decoded JSON document.
951
952                     Parameters
953                            jobj -- Python  object,  composed  of  only  other
954                            basic  data  types, as decoded from JSON document.
955                            Not  necessarily  dict  (as  decoded  from   "JSON
956                            object" document).
957
958                     Raises josepy.errors.DeserializationError  -- if decoding
959                            was unsuccessful, e.g. in case of unparseable X509
960                            certificate,  or  wrong  padding  in  JOSE  base64
961                            encoded string, etc.
962
963       class josepy.jws.CLI
964              Bases: object
965
966              JWS CLI.
967
968              classmethod sign(args)
969                     Sign.
970
971              classmethod verify(args)
972                     Verify.
973
974              classmethod run(args=None)
975                     Parse arguments and sign/verify.
976

UTILITIES

978       JOSE utilities.
979
980       class josepy.util.abstractclassmethod(target)
981              Bases: classmethod
982
983              Descriptor for an abstract classmethod.
984
985              It augments the abc framework with an abstract classmethod. This
986              is implemented as abc.abstractclassmethod in the standard Python
987              library starting with version 3.2.
988
989              This particular implementation, allegedly based  on  Python  3.3
990              source           code,          is          stolen          from
991              http://stackoverflow.com/questions/11217878/python-2-7-combine-abc-abstractmethod-and-classmethod.
992
993       class josepy.util.ComparableX509(wrapped)
994              Bases: object
995
996              Wrapper for OpenSSL.crypto.X509** objects that supports __eq__.
997
998              Variables
999                     wrapped -- Wrapped certificate or certificate request.
1000
1001              _dump(filetype=2)
1002                     Dumps  the object into a buffer with the specified encod‐
1003                     ing.
1004
1005                     Parameters
1006                            filetype (int) -- The desired encoding. Should  be
1007                            one        of        OpenSSL.crypto.FILETYPE_ASN1,
1008                            OpenSSL.crypto.FILETYPE_PEM,                    or
1009                            OpenSSL.crypto.FILETYPE_TEXT.
1010
1011                     Returns
1012                            Encoded X509 object.
1013
1014                     Return type
1015                            str
1016
1017       class josepy.util.ComparableKey(wrapped)
1018              Bases: object
1019
1020              Comparable wrapper for cryptography keys.
1021
1022              See https://github.com/pyca/cryptography/issues/2122.
1023
1024              public_key()
1025                     Get wrapped public key.
1026
1027       class josepy.util.ComparableRSAKey(wrapped)
1028              Bases: josepy.util.ComparableKey
1029
1030              Wrapper for cryptography RSA keys.
1031
1032              Wraps around:
1033
1034              · RSAPrivateKey
1035
1036              · RSAPublicKey
1037
1038       class josepy.util.ImmutableMap(**kwargs)
1039              Bases: collections.abc.Mapping, collections.abc.Hashable
1040
1041              Immutable key to value mapping with attribute access.
1042
1043              update(**kwargs)
1044                     Return updated map.
1045
1046       class josepy.util.frozendict(*args, **kwargs)
1047              Bases: collections.abc.Mapping, collections.abc.Hashable
1048
1049              Frozen dictionary.
1050

CHANGELOG

1052   1.2.0 (2019-06-28)
1053       · Support for Python 2.6 and 3.3 has been removed.
1054
1055       · Known incompatibilities with Python 3.8 have been resolved.
1056
1057   1.1.0 (2018-04-13)
1058       · Deprecated support for Python 2.6 and 3.3.
1059
1060       · Use the sign and verify methods when they are available in cryptogra‐
1061         phy instead of the deprecated methods signer and verifier.
1062
1063   1.0.1 (2017-10-25)
1064       Stop installing mock as part of the default but only  as  part  of  the
1065       testing dependencies.
1066
1067   1.0.0 (2017-10-13)
1068       First  release  after  moving  the  josepy  package  into  a standalone
1069       library.
1070
1071       · genindex
1072
1073       · modindex
1074
1075       · search
1076

AUTHOR

1078       Let's Encrypt Project
1079
1081       2015-2019, Let's Encrypt Project
1082
1083
1084
1085
10861.2                              Jul 26, 2019                        JOSEPY(1)
Impressum