.. hazmat::

Asymmetric Utilities
====================

.. currentmodule:: cryptography.hazmat.primitives.asymmetric.utils


.. function:: decode_dss_signature(signature)

    Takes in signatures generated by the DSA/ECDSA signers and returns a
    tuple ``(r, s)``. These signatures are ASN.1 encoded ``Dss-Sig-Value``
    sequences (as defined in :rfc:`3279`)

    :param bytes signature: The signature to decode.

    :returns: The decoded tuple ``(r, s)``.

    :raises ValueError: Raised if the signature is malformed.

.. function:: encode_dss_signature(r, s)

    Creates an ASN.1 encoded ``Dss-Sig-Value`` (as defined in :rfc:`3279`) from
    raw ``r`` and ``s`` values.

    :param int r: The raw signature value ``r``.

    :param int s: The raw signature value ``s``.

    :return bytes: The encoded signature.

.. function:: encode_ec_point(curve, x, y)

    .. versionadded:: 1.1

    Encodes an elliptic curve point to a byte string as described in
    _`SEC 1 v2.0` section 2.3.3. This function only supports uncompressed
    points.

    :param curve: A :class:`EllipticCurve` provider.

    :param x: The x value of the point.

    :type: int or None

    :param int y: The y value of the point.

    :return bytes: The encoded point.

    :raises TypeError: Raised when curve is not an :class:`EllipticCurve`.

.. function:: decode_ec_point(key_length, data)

    .. versionadded:: 1.1

    Decodes a byte string as described in _`SEC 1 v2.0` section 2.3.3 to the
    ``x`` and ``y`` integer values. This function only supports uncompressed
    points.

    :param curve: A :class:`EllipticCurve` provider.

    :param bytes data: The serialized point byte string.

    :returns: The decoded tuple ``(x, y)``.

    :raises ValueError: Raised on invalid point type or data length.

    :raises TypeError: Raised when curve is not an :class:`EllipticCurve`.


.. _`SEC 1 v2.0`: http://www.secg.org/sec1-v2.pdf