Debian Codegraph @

PKG-INFO

raw
1 Metadata-Version: 2.1
2 Name: asn1crypto
3 Version: 1.5.1
4 Summary: Fast ASN.1 parser and serializer with definitions for private keys, public keys, certificates, CRL, OCSP, CMS, PKCS#3, PKCS#7, PKCS#8, PKCS#12, PKCS#5, X.509 and TSP
5 Home-page: https://github.com/wbond/asn1crypto
6 Author: wbond
7 Author-email: [email protected]
8 License: MIT
9 Description: # asn1crypto
10
11 A fast, pure Python library for parsing and serializing ASN.1 structures.
12
13 - [Features](#features)
14 - [Why Another Python ASN.1 Library?](#why-another-python-asn1-library)
15 - [Related Crypto Libraries](#related-crypto-libraries)
16 - [Current Release](#current-release)
17 - [Dependencies](#dependencies)
18 - [Installation](#installation)
19 - [License](#license)
20 - [Security Policy](#security-policy)
21 - [Documentation](#documentation)
22 - [Continuous Integration](#continuous-integration)
23 - [Testing](#testing)
24 - [Development](#development)
25 - [CI Tasks](#ci-tasks)
26
27 [![GitHub Actions CI](https://github.com/wbond/asn1crypto/workflows/CI/badge.svg)](https://github.com/wbond/asn1crypto/actions?workflow=CI)
28 [![CircleCI](https://circleci.com/gh/wbond/asn1crypto.svg?style=shield)](https://circleci.com/gh/wbond/asn1crypto)
29 [![PyPI](https://img.shields.io/pypi/v/asn1crypto.svg)](https://pypi.org/project/asn1crypto/)
30
31 ## Features
32
33 In addition to an ASN.1 BER/DER decoder and DER serializer, the project includes
34 a bunch of ASN.1 structures for use with various common cryptography standards:
35
36 | Standard | Module | Source |
37 | ---------------------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
38 | X.509 | [`asn1crypto.x509`](asn1crypto/x509.py) | [RFC 5280](https://tools.ietf.org/html/rfc5280) |
39 | CRL | [`asn1crypto.crl`](asn1crypto/crl.py) | [RFC 5280](https://tools.ietf.org/html/rfc5280) |
40 | CSR | [`asn1crypto.csr`](asn1crypto/csr.py) | [RFC 2986](https://tools.ietf.org/html/rfc2986), [RFC 2985](https://tools.ietf.org/html/rfc2985) |
41 | OCSP | [`asn1crypto.ocsp`](asn1crypto/ocsp.py) | [RFC 6960](https://tools.ietf.org/html/rfc6960) |
42 | PKCS#12 | [`asn1crypto.pkcs12`](asn1crypto/pkcs12.py) | [RFC 7292](https://tools.ietf.org/html/rfc7292) |
43 | PKCS#8 | [`asn1crypto.keys`](asn1crypto/keys.py) | [RFC 5208](https://tools.ietf.org/html/rfc5208) |
44 | PKCS#1 v2.1 (RSA keys) | [`asn1crypto.keys`](asn1crypto/keys.py) | [RFC 3447](https://tools.ietf.org/html/rfc3447) |
45 | DSA keys | [`asn1crypto.keys`](asn1crypto/keys.py) | [RFC 3279](https://tools.ietf.org/html/rfc3279) |
46 | Elliptic curve keys | [`asn1crypto.keys`](asn1crypto/keys.py) | [SECG SEC1 V2](http://www.secg.org/sec1-v2.pdf) |
47 | PKCS#3 v1.4 | [`asn1crypto.algos`](asn1crypto/algos.py) | [PKCS#3 v1.4](ftp://ftp.rsasecurity.com/pub/pkcs/ascii/pkcs-3.asc) |
48 | PKCS#5 v2.1 | [`asn1crypto.algos`](asn1crypto/algos.py) | [PKCS#5 v2.1](http://www.emc.com/collateral/white-papers/h11302-pkcs5v2-1-password-based-cryptography-standard-wp.pdf) |
49 | CMS (and PKCS#7) | [`asn1crypto.cms`](asn1crypto/cms.py) | [RFC 5652](https://tools.ietf.org/html/rfc5652), [RFC 2315](https://tools.ietf.org/html/rfc2315) |
50 | TSP | [`asn1crypto.tsp`](asn1crypto/tsp.py) | [RFC 3161](https://tools.ietf.org/html/rfc3161) |
51 | PDF signatures | [`asn1crypto.pdf`](asn1crypto/pdf.py) | [PDF 1.7](http://wwwimages.adobe.com/content/dam/Adobe/en/devnet/pdf/pdfs/PDF32000_2008.pdf) |
52
53 ## Why Another Python ASN.1 Library?
54
55 Python has long had the [pyasn1](https://pypi.org/project/pyasn1/) and
56 [pyasn1_modules](https://pypi.org/project/pyasn1-modules/) available for
57 parsing and serializing ASN.1 structures. While the project does include a
58 comprehensive set of tools for parsing and serializing, the performance of the
59 library can be very poor, especially when dealing with bit fields and parsing
60 large structures such as CRLs.
61
62 After spending extensive time using *pyasn1*, the following issues were
63 identified:
64
65 1. Poor performance
66 2. Verbose, non-pythonic API
67 3. Out-dated and incomplete definitions in *pyasn1-modules*
68 4. No simple way to map data to native Python data structures
69 5. No mechanism for overridden universal ASN.1 types
70
71 The *pyasn1* API is largely method driven, and uses extensive configuration
72 objects and lowerCamelCase names. There were no consistent options for
73 converting types of native Python data structures. Since the project supports
74 out-dated versions of Python, many newer language features are unavailable
75 for use.
76
77 Time was spent trying to profile issues with the performance, however the
78 architecture made it hard to pin down the primary source of the poor
79 performance. Attempts were made to improve performance by utilizing unreleased
80 patches and delaying parsing using the `Any` type. Even with such changes, the
81 performance was still unacceptably slow.
82
83 Finally, a number of structures in the cryptographic space use universal data
84 types such as `BitString` and `OctetString`, but interpret the data as other
85 types. For instance, signatures are really byte strings, but are encoded as
86 `BitString`. Elliptic curve keys use both `BitString` and `OctetString` to
87 represent integers. Parsing these structures as the base universal types and
88 then re-interpreting them wastes computation.
89
90 *asn1crypto* uses the following techniques to improve performance, especially
91 when extracting one or two fields from large, complex structures:
92
93 - Delayed parsing of byte string values
94 - Persistence of original ASN.1 encoded data until a value is changed
95 - Lazy loading of child fields
96 - Utilization of high-level Python stdlib modules
97
98 While there is no extensive performance test suite, the
99 `CRLTests.test_parse_crl` test case was used to parse a 21MB CRL file on a
100 late 2013 rMBP. *asn1crypto* parsed the certificate serial numbers in just
101 under 8 seconds. With *pyasn1*, using definitions from *pyasn1-modules*, the
102 same parsing took over 4,100 seconds.
103
104 For smaller structures the performance difference can range from a few times
105 faster to an order of magnitude or more.
106
107 ## Related Crypto Libraries
108
109 *asn1crypto* is part of the modularcrypto family of Python packages:
110
111 - [asn1crypto](https://github.com/wbond/asn1crypto)
112 - [oscrypto](https://github.com/wbond/oscrypto)
113 - [csrbuilder](https://github.com/wbond/csrbuilder)
114 - [certbuilder](https://github.com/wbond/certbuilder)
115 - [crlbuilder](https://github.com/wbond/crlbuilder)
116 - [ocspbuilder](https://github.com/wbond/ocspbuilder)
117 - [certvalidator](https://github.com/wbond/certvalidator)
118
119 ## Current Release
120
121 1.5.0 - [changelog](changelog.md)
122
123 ## Dependencies
124
125 Python 2.6, 2.7, 3.2, 3.3, 3.4, 3.5, 3.6, 3.7, 3.8, 3.9, 3.10 or pypy. *No third-party
126 packages required.*
127
128 ## Installation
129
130 ```bash
131 pip install asn1crypto
132 ```
133
134 ## License
135
136 *asn1crypto* is licensed under the terms of the MIT license. See the
137 [LICENSE](LICENSE) file for the exact license text.
138
139 ## Security Policy
140
141 The security policies for this project are covered in
142 [SECURITY.md](https://github.com/wbond/asn1crypto/blob/master/SECURITY.md).
143
144 ## Documentation
145
146 The documentation for *asn1crypto* is composed of tutorials on basic usage and
147 links to the source for the various pre-defined type classes.
148
149 ### Tutorials
150
151 - [Universal Types with BER/DER Decoder and DER Encoder](docs/universal_types.md)
152 - [PEM Encoder and Decoder](docs/pem.md)
153
154 ### Reference
155
156 - [Universal types](asn1crypto/core.py), `asn1crypto.core`
157 - [Digest, HMAC, signed digest and encryption algorithms](asn1crypto/algos.py), `asn1crypto.algos`
158 - [Private and public keys](asn1crypto/keys.py), `asn1crypto.keys`
159 - [X509 certificates](asn1crypto/x509.py), `asn1crypto.x509`
160 - [Certificate revocation lists (CRLs)](asn1crypto/crl.py), `asn1crypto.crl`
161 - [Online certificate status protocol (OCSP)](asn1crypto/ocsp.py), `asn1crypto.ocsp`
162 - [Certificate signing requests (CSRs)](asn1crypto/csr.py), `asn1crypto.csr`
163 - [Private key/certificate containers (PKCS#12)](asn1crypto/pkcs12.py), `asn1crypto.pkcs12`
164 - [Cryptographic message syntax (CMS, PKCS#7)](asn1crypto/cms.py), `asn1crypto.cms`
165 - [Time stamp protocol (TSP)](asn1crypto/tsp.py), `asn1crypto.tsp`
166 - [PDF signatures](asn1crypto/pdf.py), `asn1crypto.pdf`
167
168 ## Continuous Integration
169
170 Various combinations of platforms and versions of Python are tested via:
171
172 - [macOS, Linux, Windows](https://github.com/wbond/asn1crypto/actions/workflows/ci.yml) via GitHub Actions
173 - [arm64](https://circleci.com/gh/wbond/asn1crypto) via CircleCI
174
175 ## Testing
176
177 Tests are written using `unittest` and require no third-party packages.
178
179 Depending on what type of source is available for the package, the following
180 commands can be used to run the test suite.
181
182 ### Git Repository
183
184 When working within a Git working copy, or an archive of the Git repository,
185 the full test suite is run via:
186
187 ```bash
188 python run.py tests
189 ```
190
191 To run only some tests, pass a regular expression as a parameter to `tests`.
192
193 ```bash
194 python run.py tests ocsp
195 ```
196
197 ### PyPi Source Distribution
198
199 When working within an extracted source distribution (aka `.tar.gz`) from
200 PyPi, the full test suite is run via:
201
202 ```bash
203 python setup.py test
204 ```
205
206 ### Package
207
208 When the package has been installed via pip (or another method), the package
209 `asn1crypto_tests` may be installed and invoked to run the full test suite:
210
211 ```bash
212 pip install asn1crypto_tests
213 python -m asn1crypto_tests
214 ```
215
216 ## Development
217
218 To install the package used for linting, execute:
219
220 ```bash
221 pip install --user -r requires/lint
222 ```
223
224 The following command will run the linter:
225
226 ```bash
227 python run.py lint
228 ```
229
230 Support for code coverage can be installed via:
231
232 ```bash
233 pip install --user -r requires/coverage
234 ```
235
236 Coverage is measured by running:
237
238 ```bash
239 python run.py coverage
240 ```
241
242 To change the version number of the package, run:
243
244 ```bash
245 python run.py version {pep440_version}
246 ```
247
248 To install the necessary packages for releasing a new version on PyPI, run:
249
250 ```bash
251 pip install --user -r requires/release
252 ```
253
254 Releases are created by:
255
256 - Making a git tag in [PEP 440](https://www.python.org/dev/peps/pep-0440/#examples-of-compliant-version-schemes) format
257 - Running the command:
258
259 ```bash
260 python run.py release
261 ```
262
263 Existing releases can be found at https://pypi.org/project/asn1crypto/.
264
265 ## CI Tasks
266
267 A task named `deps` exists to download and stage all necessary testing
268 dependencies. On posix platforms, `curl` is used for downloads and on Windows
269 PowerShell with `Net.WebClient` is used. This configuration sidesteps issues
270 related to getting pip to work properly and messing with `site-packages` for
271 the version of Python being used.
272
273 The `ci` task runs `lint` (if flake8 is available for the version of Python) and
274 `coverage` (or `tests` if coverage is not available for the version of Python).
275 If the current directory is a clean git working copy, the coverage data is
276 submitted to codecov.io.
277
278 ```bash
279 python run.py deps
280 python run.py ci
281 ```
282
283 Keywords: asn1 crypto pki x509 certificate rsa dsa ec dh
284 Platform: UNKNOWN
285 Classifier: Development Status :: 5 - Production/Stable
286 Classifier: Intended Audience :: Developers
287 Classifier: License :: OSI Approved :: MIT License
288 Classifier: Programming Language :: Python
289 Classifier: Programming Language :: Python :: 2
290 Classifier: Programming Language :: Python :: 2.6
291 Classifier: Programming Language :: Python :: 2.7
292 Classifier: Programming Language :: Python :: 3
293 Classifier: Programming Language :: Python :: 3.2
294 Classifier: Programming Language :: Python :: 3.3
295 Classifier: Programming Language :: Python :: 3.4
296 Classifier: Programming Language :: Python :: 3.5
297 Classifier: Programming Language :: Python :: 3.6
298 Classifier: Programming Language :: Python :: 3.7
299 Classifier: Programming Language :: Python :: 3.8
300 Classifier: Programming Language :: Python :: 3.9
301 Classifier: Programming Language :: Python :: 3.10
302 Classifier: Programming Language :: Python :: Implementation :: CPython
303 Classifier: Programming Language :: Python :: Implementation :: PyPy
304 Classifier: Topic :: Security :: Cryptography
305 Description-Content-Type: text/markdown