AIS2.py¶

AIS.py: a Python interface for the Swisscom All-in Signing Service (aka AIS).

AIS2.py is a fork created to get rid of the licensing woes affected itext dependency and replace it with pyHanko. Furthermore the API was slightly adjusted to be more flexible, so buffers can be passed around rather than files that need to exist on the filesystem.

Release v2.2.1.

AIS2.py works like this:

>>> from AIS import AIS, PDF
>>> client = AIS('alice', 'a_secret', 'a.crt', 'a.key')
>>> pdf = PDF('source.pdf')
>>> ais.sign_one_pdf(pdf)
>>> with open('target.pdf', 'wb') as fp:
...     fp.write(pdf.out_stream.getvalue())
...

AIS is a webservice for electronic signatures offered by Swisscom. You can check out the corporate page and the reference guide of the service.

To use the webservice you have to send an appropriate digest of the file. The service returns a PKCS#7 detached signature that can be send alongside the original file.

To validate a detached signature, the digest of the original file can be computed again.

In the case of PDF files, the signature is integrated in the PDF itself and it needs to be extracted to be verified.

A complication in that case is that during verification you must be able to compute the same digest that was used to generate the signature with the original file, but the original file is not available anymore, and the signed file has clearly a different digest.

Thus, the procedure is the following:

The original PDF file is prepared by adding an empty signature block. This includes a ByteRange object.
The digest is computed only in the part specified by the ByteRange, so it excludes the empty signature.
The digest is sent to the AIS webservice.
The detached signature is included in the placeholder.

AIS.py takes care of all this, delegating everything except step 3 to pyHanko.

Installation¶

Make sure you have Python 3.7, 3.8, 3.9, 3.11 or a recent Pypy then:

$ pip install AIS2.py

This will pull Python dependencies, you don’t need to install anything other than Python.

Tests¶

A few tests are found in the tests/ directory. Integration tests use the real webservice, and HTTP requests/responses are recorded with the vcrpy library as cassettes. This means that you can run all the tests on your machine without real credentials to AIS. The sensible part of the request (i.e. the login and password) is hidden automatically from the cassette file. This also allows the tests to run on GitHub Actions.

To run the tests locally, enter the directory you cloned and:

$ pip install tox
$ tox

Tox will automatically create a virtualenv for each Python version, install the package and run the tests.

If you prefer to do this manually for one Python version:

$ python -m virtualenv env
$ source env/bin/activate
$ pip install -e .
$ py.test

Status¶

AIS2.py is already functional for its main use case, but a few things could be improved:

Allow to request only a trusted timestamp instead of a signature.
Allow to choose a different digest algorithm than SHA256.
Handle second factor authentication in addition to static certificates.
Find a way to check PDF signatures programmatically in the tests.
Document all parameters and return values in the docstrings (i.e. improve the API reference).

API Reference¶

This section describes classes and exceptions.

API

Release History¶

2.2.1 (2022-09-02)¶

Gracefully handles empty batches

2.2.0 (2022-07-14)¶

Switches to AIS API Profile 1.1

2.1.2 (2022-07-14)¶

Actually fixes batch signing

2.1.1 (2022-07-14)¶

Fix batch signing

2.1.0 (2022-04-19)¶

Clean up project structure
Clean up PDF API
Clean up docs

2.0.0 (2022-04-12)¶

Creation of AIS2.py fork
Replaced Travis CI with GitHub Actions.

0.3.0-beta (2021-11-04)¶

Remove Python 2.7, 3.4, 3.5, 3.6 support
Replace PyPDF2 and itext with pyHanko
Remove support for signing prepared PDFs

0.2.2 (2018-10-22)¶

Store the last created request_id on the AIS instance
Use a proper test matrix on Travis to test various Python releases
Add Python 3.6 to test matrix

0.2.1 (2016-06-16)¶

Return in batch mode timestamp and revocation information with the signature.
Fix python3 bugs.
Refactoring.

0.2.0 (2016-05-19)¶

Documentation

Added sections for introduction, installation, testing, project status, API reference.

0.1 (2016-05-17)¶

Initial release. It is possible to start with a batch of pdf files that do not yet have a prepared signature, and sign them.

Contributors¶

AIS.py is written by:

Leonardo Pistone (Camptocamp).
Cyril Gaudin (Camptocamp).

AIS2.py fork was created by:

David Salvisberg (Seantis GmbH)

License¶

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.