cyclonedx.model.signature
=========================

.. py:module:: cyclonedx.model.signature

.. autoapi-nested-parse::

   JSF (JSON Signature Format) signature-related classes.

   .. note::
       JSON-only. There is no XSD/XML equivalent for JSF signatures in CycloneDX.

   .. note::
       Introduced in CycloneDX v1.4

   .. note::
       See the JSF specification: https://cyberphone.github.io/doc/security/jsf.html
       See the CycloneDX Schema reference: https://cyclonedx.org/docs/1.4/json/#signature



Classes
-------

.. autoapisummary::

   cyclonedx.model.signature.JsfAlgorithm
   cyclonedx.model.signature.JsfKeyType
   cyclonedx.model.signature.JsfPublicKey
   cyclonedx.model.signature.JsfSignature
   cyclonedx.model.signature.JsfSimpleSignature
   cyclonedx.model.signature.JsfSignatureSigners
   cyclonedx.model.signature.JsfSignatureChain


Module Contents
---------------

.. py:class:: JsfAlgorithm

   Bases: :py:obj:`str`, :py:obj:`enum.Enum`


   Recognized JWA [RFC7518] and RFC8037 asymmetric/symmetric key algorithms for JSF signatures.

   Note: Unlike RFC8037, JSF requires explicit Ed* algorithm names instead of "EdDSA".

   For proprietary algorithms, pass a URI string directly — the ``algorithm`` field on
   :class:`JsfSignature`, :class:`JsfSignatureSigners`, and :class:`JsfSignatureChain`
   accepts both :class:`JsfAlgorithm` enum values and arbitrary strings.


   .. py:attribute:: RS256
      :value: 'RS256'



   .. py:attribute:: RS384
      :value: 'RS384'



   .. py:attribute:: RS512
      :value: 'RS512'



   .. py:attribute:: PS256
      :value: 'PS256'



   .. py:attribute:: PS384
      :value: 'PS384'



   .. py:attribute:: PS512
      :value: 'PS512'



   .. py:attribute:: ES256
      :value: 'ES256'



   .. py:attribute:: ES384
      :value: 'ES384'



   .. py:attribute:: ES512
      :value: 'ES512'



   .. py:attribute:: ED25519
      :value: 'Ed25519'



   .. py:attribute:: ED448
      :value: 'Ed448'



   .. py:attribute:: HS256
      :value: 'HS256'



   .. py:attribute:: HS384
      :value: 'HS384'



   .. py:attribute:: HS512
      :value: 'HS512'



.. py:class:: JsfKeyType

   Bases: :py:obj:`str`, :py:obj:`enum.Enum`


   Key type indicator for a JSF public key.


   .. py:attribute:: EC
      :value: 'EC'



   .. py:attribute:: OKP
      :value: 'OKP'



   .. py:attribute:: RSA
      :value: 'RSA'



.. py:class:: JsfPublicKey(*, kty: JsfKeyType, crv: Optional[str] = None, x: Optional[str] = None, y: Optional[str] = None, n: Optional[str] = None, e: Optional[str] = None)

   Public key object as defined by the JSF standard.

   Supports three key types (determined by ``kty``):

   - **EC**: requires ``crv``, ``x``, ``y``
   - **OKP**: requires ``crv``, ``x``
   - **RSA**: requires ``n``, ``e``


   .. py:attribute:: kty


   .. py:attribute:: crv
      :value: None



   .. py:attribute:: x
      :value: None



   .. py:attribute:: y
      :value: None



   .. py:attribute:: n
      :value: None



   .. py:attribute:: e
      :value: None



.. py:class:: JsfSignature

   JSF (JSON Signature Format) signature object — abstract base class.

   The JSF specification defines three mutually exclusive signature modes, each represented by
   a separate concrete class:

   - **Simple signature** (``signaturecore``): :class:`JsfSimpleSignature`: a single signature
     with required ``algorithm`` and ``value``, plus optional ``key_id``, ``public_key``,
     ``certificate_path``, and ``excludes``
   - **Multiple signers** (``multisignature``): :class:`JsfSignatureSigners`: contains a
     ``signers`` list of :class:`JsfSimpleSignature`
   - **Signature chain** (``signaturechain``): :class:`JsfSignatureChain`: contains a
     ``chain`` list of :class:`JsfSimpleSignature`

   .. note::
       JSON-only. There is no XSD/XML equivalent in any CycloneDX schema version.

   .. note::
       Introduced in CycloneDX v1.4


.. py:class:: JsfSimpleSignature(*, algorithm: Union[JsfAlgorithm, str], value: str, key_id: Optional[str] = None, public_key: Optional[JsfPublicKey] = None, certificate_path: Optional[list[str]] = None, excludes: Optional[list[str]] = None)

   Bases: :py:obj:`JsfSignature`


   JSF simple signature object: ``signaturecore`` mode.

   Represents a single signature with required ``algorithm`` and ``value``, plus optional
   ``key_id``, ``public_key``, ``certificate_path``, and ``excludes``.


   .. py:attribute:: algorithm


   .. py:attribute:: value


   .. py:attribute:: key_id
      :value: None



   .. py:attribute:: public_key
      :value: None



   .. py:attribute:: certificate_path


   .. py:attribute:: excludes


.. py:class:: JsfSignatureSigners(*, signers: list[JsfSimpleSignature])

   Bases: :py:obj:`JsfSignature`


   Multiple-signers JSF signature: ``multisignature`` in the JSF schema.

   Contains a list of :class:`JsfSimpleSignature` objects serialized under the ``signers`` key.


   .. py:attribute:: signers


.. py:class:: JsfSignatureChain(*, chain: list[JsfSimpleSignature])

   Bases: :py:obj:`JsfSignature`


   Signature-chain JSF signature: ``signaturechain`` in the JSF schema.

   Contains a list of :class:`JsfSimpleSignature` objects serialized under the ``chain`` key.


   .. py:attribute:: chain