# -*- coding: utf-8 -*-
from setuptools import setup

packages = \
['pyasice']

package_data = \
{'': ['*'], 'pyasice': ['templates/*']}

install_requires = \
['asn1crypto', 'cryptography>=5', 'lxml>=4,<5', 'oscrypto', 'requests>=2.20']

setup_kwargs = {
    'name': 'pyasice',
    'version': '1.0.4',
    'description': 'Manipulate ASiC-E containers and XAdES/eIDAS signatures for Estonian e-identity services',
    'long_description': '# pyasice - ASiC-E (BDOC) and XAdES Manipulation Library\n\n[![pypi Package](https://badge.fury.io/py/pyasice.png)](https://badge.fury.io/py/pyasice)\n[![Build Status](https://app.travis-ci.com/thorgate/pyasice.svg?branch=main)](https://app.travis-ci.com/thorgate/pyasice)\n[![Coverage Status](https://coveralls.io/repos/github/thorgate/pyasice/badge.svg?branch=main)](https://coveralls.io/github/thorgate/pyasice?branch=main)\n\nThe `pyasice` library is designed to:\n* create, read, and verify XAdES/XMLDsig/eIDAS electronic signatures,\n* validate signers\' certificates with OCSP,\n* confirm these signatures with TimeStamping, \n* create and manipulate [ASiC-E](https://en.wikipedia.org/wiki/Associated_Signature_Containers) or BDoc 2.1 containers, \nwhich are based on the XAdES/eIDAS stack.  \n\n## Contents\n\n* [Quickstart](#quickstart)\n* * [ASiC-E/BDOC Container File Manipulation](#asic-ebdoc-container-file-manipulation)\n* * [Signing Flow Utilities](#signing-flow-utilities)\n* [Normative References](#normative-references)\n* [Module Layout](#module-layout)\n* [Technology Stack](#technology-stack)\n* [Build the XAdES XML Signature meta-file](#build-the-xades-xml-signature-meta-file)\n* * [SignedInfo](#signedinfo)\n* * [SignatureValue](#signaturevalue)\n* * [KeyInfo](#keyinfo)\n* * [SignedProperties](#signedproperties)\n* [Secondary Services](#secondary-services)\n* * [OCSP](#ocsp)\n* * [Timestamping Service](#timestamping-service)\n\n## Quickstart\n\n### ASiC-E/BDOC Container File Manipulation\n\nCreate a new container:\n```python\nfrom pyasice import Container, XmlSignature\n\nxmlsig = XmlSignature.create().add_document(\'test.txt\', b\'Test data\', \'application/pdf\')\n# ... here goes the signing, confirming and timestamping part ... \n\ncontainer = Container()\ncontainer\\\n    .add_file(\'test.txt\', b\'Test data\', \'application/pdf\')\\\n    .add_signature(xmlsig)\\\n    .save(\'test.asice\')\n\n# container is a context manager:\nwith Container() as container:\n    container.add_file(\'a\', b\'b\', \'c\').save(\'path/to\')\n\n# Open an existing container:\ncontainer = Container.open(\'test.asice\')\n\n# Verify container. Raises pyasice.SignatureVerificationError on failure\ncontainer.verify_signatures()\n\n# Read files in the container\nwith container.open_file(\'test.txt\') as f:\n    assert f.read() == b\'Test data\'\n\n# Iterate over signatures\nfor xmlsig in container.iter_signatures():\n    xmlsig.get_signing_time()\n```\n\n### Signing Flow Utilities\n\n```python\nfrom pyasice import Container, finalize_signature\n\n# get this from an external service, ID card, or elsewhere\nuser_certificate = b\'user certificate in DER/PEM format\'\n\ncontainer = Container()\ncontainer.add_file("test.txt", b\'Test\', "text/plain")\n\nxml_sig = container.prepare_signature(user_certificate)\n\n# Use an external service, or ID card, or a private key from elsewhere\n# to sign the XML signature structure\nsignature_value = externally.sign(xml_sig.signed_data())\nxml_sig.set_signature_value(signature_value)\n\n# Get issuer certificate from the ID service provider, e.g. sk.ee. \n# Here we use the user certificate\'s `issuer.common_name` field to identify the issuer cert,\n# and find the cert in the `esteid-certificates` PyPI package. \nissuer_cert_name = xml_sig.get_certificate_issuer_common_name()\nimport esteid_certificates\nissuer_certificate = esteid_certificates.get_certificate(issuer_cert_name)\n\n# Complete the XML signature with OCSP and optionally Timestamping\nfinalize_signature(xml_sig, ocsp_url="https://ocsp.server.url", tsa_url="https://tsa.server.url")\n\ncontainer.add_signature(xml_sig)\n\ncontainer.save("path/to/file.asice")\n```\n\n\n## Normative References\n\nThe main document this library is based on:\nthe [BDOC 2.1.2 spec](https://www.id.ee/wp-content/uploads/2020/06/bdoc-spec212-eng.pdf).\n\nThe specific standards outlined in that document:\n\n* [ETSI TS 101 903 v1.4.2](https://www.etsi.org/deliver/etsi_ts/101900_101999/101903/01.04.02_60/ts_101903v010402p.pdf) \n  – XML Advanced Electronic Signatures (XAdES) and its Baseline Profile ETSI TS 103 171;\n* ITU-T Recommendation X.509;\n* [RFC 3161](https://tools.ietf.org/html/rfc3161) – PKIX Time-Stamp protocol;\n* [RFC 6960](https://tools.ietf.org/html/rfc6960) – Online Certificate Status Protocol;\n* ETSI TS 102 918 v1.2.1 - Associated Signature Containers (ASiC) and its\n  Baseline Profile ETSI TS 103 174.\n\nThe difference between ASiC-E and BDOC is almost exclusively in terminology.\n\nThe [BDOC 2.1.2 spec](https://www.id.ee/wp-content/uploads/2020/06/bdoc-spec212-eng.pdf) states:\n\n> The BDOC file format is based on ASiC standard which is in turn profiled by ASiC BP.\n> BDOC packaging is a ASiC-E XAdES type ZIP container ...\n\nSo with a moderate risk of confusion, we can accept that ASiC-E and BDOC refer to the same thing.\n\n## Module Layout\n\n* [container.py](container.py) -- the `Container` class, that deals with ASiC-E (BDOC v.2.1) container format \n* [xmlsig.py](xmlsig.py) -- the `XmlSignature` class, that deals with XAdES/XMLDSig XML structures\n* [ocsp.py](ocsp.py) -- the `OCSP` class that deals with OCSP requests and responses\n* [tsa.py](tsa.py) -- the `TSA` class that deals with TimeStamping service requests and responses\n* [signature_verifier.py](signature_verifier.py) -- the `verify` function, to verify signatures against a certificate.\n\n## Technology Stack\n\nDealing with the subject involves, at least:\n* public key cryptography (RSA, ECDSA);\n* ASN.1 encoding;\n* XML processing;\n* Zip archives;\n* and also requests to various services (obtaining signer\'s certificate and the signature,\n  validating the certificate through OCSP, time-stamping the signature).\n\nThe [asn1crypto](https://github.com/wbond/asn1crypto) library and its higher-level complement \n[oscrypto](https://github.com/wbond/oscrypto)\nallow handling certificates and ASN.1 structures quite easily.\n\nThe [cryptography](https://cryptography.io/en/latest) library is by far the most powerful python library \nfor dealing with public key cryptography algorithms.\n\n\n## Build the XAdES XML Signature meta-file\n\nThe structure of the XAdES XML signature file looks like this:\n```xml\n<asic:XAdESSignatures xmlns:asic="http://uri.etsi.org/02918/v1.2.1#" xmlns:ds="http://www.w3.org/2000/09/xmldsig#"\n                      xmlns:xades="http://uri.etsi.org/01903/v1.3.2#">\n    <ds:Signature Id="S0">\n        <ds:SignedInfo Id="S0-SignedInfo">...</ds:SignedInfo>\n        <ds:SignatureValue Id="S0-SIG">...</ds:SignatureValue>\n        <ds:KeyInfo Id="S0-KeyInfo">...</ds:KeyInfo>\n        <ds:Object Id="S0-object-xades">\n            <xades:QualifyingProperties Id="S0-QualifyingProperties" Target="#S0">\n                <xades:SignedProperties Id="S0-SignedProperties">\n                    <xades:SignedSignatureProperties Id="S0-SignedSignatureProperties">\n                        <xades:SigningTime>2019-06-07T14:03:50Z</xades:SigningTime>\n                        <xades:SigningCertificate>...</xades:SigningCertificate>\n                        <xades:SignaturePolicyIdentifer>...</xades:SignaturePolicyIdentifer>\n                    </xades:SignedSignatureProperties>\n                </xades:SignedProperties>\n            </xades:QualifyingProperties>\n        </ds:Object>\n    </ds:Signature>\n</asic:XAdESSignatures>\n```\n\nWe\'ll go over each section below.\n\n* [SignedInfo](#signedinfo)\n* [SignatureValue](#signaturevalue)\n* [KeyInfo](#keyinfo)\n* [SignedProperties](#signedproperties)\n\n### SignedInfo\n\nThe `SignedInfo` node is the source of the data being signed. The XML content of the node, canonicalized\nusing the `CanonicalizationMethod` as per the respective child node, is hashed using an algorithm defined in\nthe `SignatureMethod` child node, and this hash is fed to a signing service (ID card, SmartID etc.) \n\n```xml\n<ds:SignedInfo Id="S0-SignedInfo">\n    <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2006/12/xml-c14n11"></ds:CanonicalizationMethod>\n    <ds:SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha256"></ds:SignatureMethod>\n    <ds:Reference Id="S0-ref-0" URI="test.pdf">\n        <ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"></ds:DigestMethod>\n        <ds:DigestValue>...</ds:DigestValue>\n    </ds:Reference>\n    <ds:Reference Id="S0-ref-sp" Type="http://uri.etsi.org/01903#SignedProperties" URI="#S0-SignedProperties">\n        <ds:Transforms>\n            <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>\n        </ds:Transforms>\n        <ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"></ds:DigestMethod>\n        <ds:DigestValue>...</ds:DigestValue>\n    </ds:Reference>\n</ds:SignedInfo>\n```\n\nThe `Reference` fields are different in purpose and formation.\n\nThe first `Reference` field is about the signed document and as such, has an `URI` attribute of the document\'s file name.\nIts child `DigestValue` element is the SHA256 hash of the document, it is, incidentally, the very hash that is sent to the SmartID API for signing.\n\nThe second `Reference` is built on the basis of some fields defined later in the [SignedProperties](#SignedProperties) section.\nIts child `DigestValue` is calculated as a SHA256 hash of the canonicalized XML output of the  `SignedProperties` tag, after that one is formed:\nThe `URI` attribute of this `Reference` tag is the `#`-prefixed `Id` attribute of the `SignedProperties` tag.\n\n```python\nimport base64\nimport hashlib\nfrom lxml import etree\n\nbuf = etree.tostring(el, method=\'c14n\', exclusive=True or False)  # NOTE below\ndigest_value = base64.b64encode(hashlib.sha256(buf).digest())\n```\n(Assuming the `el` here to be the XML `<SignedProperties>` element)\n\n#### Canonicalization\n\nThe `exclusive` kwarg controls whether the namespace declarations of ancestor tags should be included in the resulting canonical representation, or _excluded_.\nWhether to use `exclusive=True` depends on the canonicalization tag\'s `Algorithm` attribute: \n* `http://www.w3.org/2001/10/xml-exc-c14n#`, uses `exclusive=True`,  \n* the two others, the required `http://www.w3.org/TR/2001/REC-xml-c14n-20010315`, or `http://www.w3.org/2006/12/xml-c14n11`, are not exclusive.\n\nThe aforementioned `<ds:CanonicalizationMethod>` tag controls the c14n of the `SignedInfo` node before feeding its digest to the signature service. \nThe c14n of `SignedProperties` prior to getting its digest is determined by the `ds:Transform` tag within this `ds:Reference` node. \nIf it\'s not present, then the default, ie. not exclusive, c14n is used.  \n\n### KeyInfo\n\nThis section contains the base64-encoded user certificate value, e.g. the SmartID API response\'s `cert.value`,\nor the certificate obtained from an ID card:\n```xml\n<ds:KeyInfo Id="S0-KeyInfo">\n    <ds:X509Data>\n        <ds:X509Certificate>MIIGJDCCBAygAwIBAgIQBNsLtTIpnmNbbE4+laSLaTANBgkqhkiG9w0BAQsFADBr...</ds:X509Certificate>\n    </ds:X509Data>\n</ds:KeyInfo>\n```\nMore details about the certificate in the [SigningCertificate](#SigningCertificate) subsection.\n \n### SignedProperties\n\nThe XML section of `SignedProperties` consists of, [at least](https://www.w3.org/TR/XAdES/#IDAEAD1B), \nthe `SigningTime`, `SigningCertificate` and `SignaturePolicyIdentifer` elements.\n\n:question: The signatures returned by e.g. [Dokobit](https://dokobit.ee), \ndo not contain the `SignaturePolicyIdentifer` node.\n\n#### SigningTime\n\nA timestamp in ISO 8601 format.\n\n#### SignaturePolicyIdentifier \n\nThis appears to be a static^1 XML chunk referencing the BDOC 2.1 Specifications document:\n```xml\n<xades:SignaturePolicyIdentifier>\n    <xades:SignaturePolicyId>\n        <xades:SigPolicyId>\n            <xades:Identifier Qualifier="OIDAsURN">urn:oid:1.3.6.1.4.1.10015.1000.3.2.1</xades:Identifier>\n        </xades:SigPolicyId>\n        <xades:SigPolicyHash>\n            <ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256">\n            </ds:DigestMethod>\n            <ds:DigestValue>3Tl1oILSvOAWomdI9VeWV6IA/32eSXRUri9kPEz1IVs=</ds:DigestValue>\n        </xades:SigPolicyHash>\n        <xades:SigPolicyQualifiers>\n            <xades:SigPolicyQualifier>\n                <xades:SPURI>https://www.sk.ee/repository/bdoc-spec21.pdf</xades:SPURI>\n            </xades:SigPolicyQualifier>\n        </xades:SigPolicyQualifiers>\n    </xades:SignaturePolicyId>\n</xades:SignaturePolicyIdentifier>\n```\n\n[1] The DigestValue is the hash value of the document referenced by `SPURI`, encoded in base64. \nRefer to [BDOC 2.1:2014 Specification](https://www.id.ee/public/bdoc-spec212-eng.pdf) for more information.\n\n#### SigningCertificate\n\nThe user certificate is a base64-encoded DER certificate which can be loaded as follows:\n```python\nimport base64\nfrom cryptography import x509\nfrom cryptography.hazmat.backends import default_backend\ncert_asn1 = base64.b64decode(cert_value)\ncert = x509.load_der_x509_certificate(base64.b64decode(cert_asn1), default_backend())\n```\nor with `pyopenssl`:\n```python\nimport base64\nfrom OpenSSL.crypto import load_certificate, FILETYPE_ASN1\ncert_asn1 = base64.b64decode(cert_value)\nopenssl_cert = load_certificate(FILETYPE_ASN1, base64.b64decode(cert_asn1))\n```\nThese objects expose a slightly different but similar API.\n\nWhat we need is the issuer name and certificate serial number:\n```python\nassert openssl_cert.get_serial_number() == cert.sertial_number == \'6454262457486410408874311107672836969\'\nassert cert.issuer.rfc4514_string() == \'C=EE,O=AS Sertifitseerimiskeskus,2.5.4.97=NTREE-10747013,CN=TEST of ESTEID-SK 2015\'\nassert openssl_cert.issuer.get_components() == [(b\'C\', b\'EE\'), (b\'O\', b\'AS Sertifitseerimiskeskus\'), (b\'organizationIdentifier\', b\'NTREE-10747013\'), (b\'CN\', b\'ESTEID-SK 2015\')]  \n```\n\nAlso we need a SHA256 digest value of the certificate:\n```python\ncert_digest = base64.b64encode(hashlib.sha256(cert_asn1).digest())\n```\n\nWith these values we can build the certificate information entry of the SignedProperties:\n```xml\n<xades:SigningCertificate>\n    <xades:Cert>\n        <xades:CertDigest>\n            <ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"></ds:DigestMethod>\n            <ds:DigestValue>hdsLTm4aaFKaGMwF6fvH5vWmiMBBnTCH3kba+TjY+pE=</ds:DigestValue>\n        </xades:CertDigest>\n        <xades:IssuerSerial>\n            <ds:X509IssuerName>C=EE,O=AS Sertifitseerimiskeskus,2.5.4.97=NTREE-10747013,CN=TEST of EID-SK 2016</ds:X509IssuerName>\n            <ds:X509SerialNumber>98652662091042892833248946646759285960</ds:X509SerialNumber>\n        </xades:IssuerSerial>\n    </xades:Cert>\n</xades:SigningCertificate>\n```\n\n:question: Does `X509IssuerName` content need to be a `cert.issuer.rfc4514_string()` or can it be anything else?\n\nSo, in the end, we get a `<xades:SignedProperties>` element which we then canonicalize and calculate a sha256 hash of this string,\nto place it in the appropriate `<ds:Reference>` element.\n\n### SignatureValue\n\n```xml\n<ds:SignatureValue Id="SIG-{SIGNATURE_ID}"><!-- Base64-encoded SIGNATURE_VALUE, gotten externally --></ds:SignatureValue>\n```\n\nA base64-encoded value of the signature calculated over the signed data. \nThe signed data is the `ds:SignedInfo` section, as [described above](#signedinfo).\n\nWhen using SmartID/MobileID, this is taken from the `signature.value` field of the response.\n\n### KeyInfo\n\nContains the base64-encoded certificate, as gotten from the SmartID response.\n```xml\n<ds:KeyInfo Id="S0-KeyInfo">\n    <ds:X509Data>\n        <ds:X509Certificate>...</ds:X509Certificate>\n    </ds:X509Data>\n</ds:KeyInfo>\n```\n\n## Secondary Services\n\n### OCSP\n\nOCSP ([Online Certificate Status Protocol](https://en.wikipedia.org/wiki/Online_Certificate_Status_Protocol)) \nis designed to check that the signing certificate is valid at the point of signing. It is a binary protocol, and uses ASN.1 encoding in both request and response payload.\nTo deal with it, we\'re using the `asn1crypto` library.\n\nThe OCSP request should be made immediately after signing, and the base64-encoded response is embedded in the XAdES signature as a `xades:UnsignedSignatureProperties` descendant node,\nnamely `xades:EncapsulatedOCSPValue`.\n\n#### Estonian eID\n\nURLs for OCSP services:\n* Demo: `http://demo.sk.ee/ocsp`\n* Production: `http://ocsp.sk.ee/`\n\nMore detail on the [sk.ee OCSP page](https://www.sk.ee/en/services/validity-confirmation-services/technical-information/)\n\n\n### Timestamping service\n\nThe [TimeStamp protocol](https://en.wikipedia.org/wiki/Time_stamp_protocol) is also a binary protocol, for getting a Long-Term Validity Timestamp for a signature. \nAlso handled with the help of the `asn1crypto` library.\n\nThe TSA request should be made immediately after OCSP validity confirmation, and the base64-encoded response is embedded in the XAdES signature as a `xades:UnsignedSignatureProperties` descendant node,\nnamely `xades:EncapsulatedTimeStamp`.\n\n#### Estonian eID\n\nURLs for timestamping services:\n* Demo: `http://demo.sk.ee/tsa/`\n* Production: `http://tsa.sk.ee`\n\nMore detail on the [sk.ee TSA page](https://www.sk.ee/en/services/time-stamping-service/)\n',
    'author': 'Thorgate',
    'author_email': 'info@thorgate.eu',
    'maintainer': 'Jyrno Ader',
    'maintainer_email': 'jyrno42@gmail.com',
    'url': 'https://github.com/thorgate/pyasice',
    'packages': packages,
    'package_data': package_data,
    'install_requires': install_requires,
    'python_requires': '>=3.6,<4.0',
}


setup(**setup_kwargs)
