# XML Signature checking

PSKC files can contain embedded XML signatures that allow integrity and authenticity checks of the transmitted information. This signature typically covers the whole PSKC file while MAC checking only covers the encrypted parts.

    >>> pskc = PSKC('somefile.pskcxml')
    >>> pskc.signature.verify()
    >>> pskc = pskc.signature.signed_pskc

When using XML signatures it is important to use the `signed_pskc` attribute after verification because that `PSKC` instance will only contain the signed information.

To create a signed PSKC file build up a `PSKC` instance as usual, configure the signature and save it:

    >>> pskc.signature.sign(key, certificate)
    >>> pskc.write('output.pskcxml')

## The Signature class

class pskc.signature.Signature
  is_signed

    A boolan value that indicates whether an XML signature is present in the PSKC file. This property does not indicate whether the signature is validated.

  algorithm

    A URI of the signing algorithm used. Assigned values to this attribute will be converted to the canonical URI for the algorithm if it is known.

  canonicalization_method

    A URI that is used to identify the XML canonicalization method used.

  digest_algorithm

    A URI that identifies that hashing algorithm that is used to construct the signature.

  issuer

    A distinguished name of the issuer of the certificate that belongs to the key that is used for the signature.

  serial

    A serial number of the certificate that belongs to the key that is used for the signature.

  key

    A PEM encoded key that will be used to create the signed PSKC file.

  certificate

    A PEM encoded certificate that is embedded inside the signature that can be used to validate the signature.

  signed_pskc

    A `PSKC` instance that contains the signed contents of the PSKC file. It is usually required to call `verify()` before accessing this attribute without raising an exception.

  verify(certificate=None, ca_pem_file=None)

    Verify the validity of the embedded XML signature. This function will raise an exception when the validation fails.

    Parameters

      - certificate (bytes) – a PEM encoded certificate that is used for verification

      - ca_pem_file (str) – the name of a file that contains a CA certificate

    The signature can be verified in three ways:

    - The signature was made with a key that has a certificate that is signed by a CA that is configured in the system CA store. In this case neither certificate or ca_pem_file need to be specified (but a certificate needs to be embedded inside the PSKC file).

    - The signature was made with a key and a certificate for the key was transmitted out-of-band. In this case the certificate argument needs to be present.

    - The signature was made with a key and has a certificate that is signed by a specific CA who’s certificate was transmitted out-of-band. In this case the ca_pem_file is used to point to a CA certificate file (but a certificate needs to be embedded inside the PSKC file).

    After calling this function a verified version of the PSKC file will be present in the `signed_pskc` attribute.

  sign(key, certificate=None)

    Set up a key and optionally a certificate that will be used to create an embedded XML signature when writing the file.

    Parameters

      - key (bytes) – PEM encoded key used for signing

      - certificate (bytes) – PEM encoded certificate that will be embedded

    This is a utility function that is used to configure the properties needed to create a signed PSKC file.