Django-ca

> [!NOTE]
> django-ca 1.27.0 introduced a major change in how subjects are parsed on the command-line. Please see [RFC 4514 subjects](https://django-ca.readthedocs.io/en/latest/update.html#update-126-rfc4514-subjects) for migration information.

> [!NOTE]
> **Docker Compose users:** The PostgreSQL version was updated to PostgreSQL 16. See [PostgreSQL update](https://django-ca.readthedocs.io/en/latest/quickstart_docker_compose.html#postgresql-update) for update instructions.

Major changes

* Add support for `Django~=5.0`, `cryptography~=42`, `acme==2.8.0` and `acme==2.9.0`.
* **Docker Compose:** The PostgreSQL version was updated to PostgreSQL 16. See [PostgreSQL update](https://django-ca.readthedocs.io/en/latest/quickstart_docker_compose.html#postgresql-update) for update instructions.
* `pydantic>=2.5` is now a required dependency.
* Preparations for support for using Hardware Security Modules, "Key backend support" below.
* The `CA_FILE_STORAGE` and `CA_FILE_STORAGE_KWARGS` settings are deprecated in favor of [CA_KEY_BACKENDS](https://django-ca.readthedocs.io/en/latest/settings.html#settings-ca-key-backends) and will be removed in `django-ca==2.0`. Installations [as Django app](https://django-ca.readthedocs.io/en/latest/quickstart_as_app.html) must add a `"django-ca"` storage alias in their configuration.
* The [CA_PASSWORDS](https://django-ca.readthedocs.io/en/latest/settings.html#settings-ca-passwords) setting is now consistently used whenever required.
* Private keys (for CAs and OCSP responder certificates) are now stored as DER keys to improve loading speed.
* The admin interface now presents lists of general names (e.g. in the Subject Alternative Name extension) as a list of order-able key/value pairs when adding certificates.
* Extensions added by the CA when signing new certificates can now have the same complexity as when giving the extensions directly when signing the certificate:
* The `--sign-ca-issuer`, `--sign-ocsp-responder` and `--sign-issuer-alternative-name` options to `manage.py sign_cert` etc. now support any general name type and giving multiple general names.
* The CRL Distribution Points extension added to certificates may now be marked as critical via `--sign-crl-distribution-points-critical`.
* When editing a CA, the admin interface presents these fields in the same way as when signing a
certificate.
* Remove the option to add the Common Name to the Subject Alternative Name extension, as the result is unpredictable:
* The `manage.py sign_cert` `--cn-in-san` option was removed.
* The checkbox in the admin interface was removed.
* The profile option no longer has any effect and issues a warning.
* Add [Pydantic models for cryptography classes](https://django-ca.readthedocs.io/en/latest/python/pydantic.html). These are required for the REST API, but are also used internally for various places where serialization of objects is required.
* Support for configuring absolute paths for OCSP responder certificates in manual OCSP views was removed. This was a left over, it was deprecated and issued a warning since 2019.
* Fixed bash shortcut if installing from source to allow spaces (fixes 123).

Key backend support

This version adds support for "key backends", allowing you to store and use private keys in different places,
for example the file system or a Hardware Security Module (HSM). At present, the only backend available uses
the Django file storage API, usually storing private keys on the file system.

Future versions will add support for other ways to handle private keys, including HSMs.

REST API changes

> [!NOTE]
> The [REST API](https://django-ca.readthedocs.io/en/latest/rest_api.html) is still experimental and endpoints will change without notice.

The update to django-ninja 1.1 and Pydantic brings a general update on how extensions are represented. Any
code using the API will have to be updated.

* Update to `django-ninja==1.1.0`, including a full migration to Pydantic 2.
* The format of extensions now includes a `type` parameter indicating the extension type.
* Extension objects are now more in line with [RFC 5280](https://datatracker.ietf.org/doc/html/rfc5280) and no longer use arbitrary abbreviations.
* Extensions are now represented as a list.
* General names are now represented as an object, instead of string that has to be parsed.

Backwards incompatible changes

* **Docker Compose:** The PostgreSQL version was updated to PostgreSQL 16. See [PostgreSQL update](https://django-ca.readthedocs.io/en/latest/quickstart_docker_compose.html#postgresql-update) for update instructions.
* Drop support for `Django~=3.2`, `acme==1.26.0` and `Alpine~=3.16`.
* `django_ca.extensions.serialize_extension()` is removed and replaced by [Pydantic serialization](https://django-ca.readthedocs.io/en/latest/python/pydantic.html).

Deprecation notices

* This is the last release to support Python 3.8, `cryptography~=41.0`, `acme~=2.7.0` and `acme~=2.8.0`.
* The default subject format will switch from OpenSSL-style to RFC 4514 in django-ca 2.0.
* Support for OpenSSL-style subjects will be removed in django-ca 2.2.
* `django_ca.extensions.parse_extension()` is deprecated and should not longer be used. Use Pydantic models instead.
* The `manage.py convert_timestamps` command will be removed in `django-ca==2.0`.
* The `CA_FILE_STORAGE` and `CA_FILE_STORAGE_KWARGS` settings are deprecated in favor of [CA_KEY_BACKENDS](https://django-ca.readthedocs.io/en/latest/settings.html#settings-ca-key-backends) and will be removed in `django-ca==2.0`.

**NOTE:** django-ca 1.27.0 introduced a major change in how subjects are parsed on the command-line. Please see
[RFC 4514 subjects](https://django-ca.readthedocs.io/en/1.27.0/update.html#update-126-rfc4514-subjects) for migration information.

* Add support for Python 3.12 and acme 2.7.0.
* Update the Docker image to use Alpine Linux 3.18 with Python 3.12.
* Add support for passing subjects in RFC 4514 format when creating certificate authorities and certificates via the `--subject-format=rfc4514` option. This format will become the default in django-ca 2.0.
* Support for subjects in OpenSSL-style format when creating certificate authorities and certificates is deprecated and will issue a warning. Support for this format will be removed in django-ca 2.2.
* [CA_DEFAULT_SUBJECT](https://django-ca.readthedocs.io/en/1.27.0/settings.html#settings-ca-default-subject), [subjects in profiles](https://django-ca.readthedocs.io/en/1.27.0/profiles.html#profiles-subject) and [CA_DEFAULT_NAME_ORDER](https://django-ca.readthedocs.io/en/1.27.0/settings.html#settings-ca-default-name-order) now also support a dotted string to include arbitrary object identifiers.
* [CA_DEFAULT_NAME_ORDER](https://django-ca.readthedocs.io/en/1.27.0/settings.html#settings-ca-default-name-order) can now be configured in YAML files.
* Do not implicitly sort the subject of new certificate authorities according to [CA_DEFAULT_NAME_ORDER](https://django-ca.readthedocs.io/en/1.27.0/settings.html#settings-ca-default-name-order). The user is expected to supply the correct order.
* When signing certificates via the command line, implicitly sort the subject only when the profile defines a subject and/or the CommonName is not given and added via the SubjectAlternativeName extension. If neither is the case, the user is expected to supply the correct order.

Backwards incompatible changes

* Removed support for the old `--issuer-url`, `--issuer-alt-name`, `--crl-url` and `--ocsp-url` options for `manage.py init_ca`, `manage.py edit_ca` and `manage.py import_ca` in favor of `--sign-ca-issuer`, `--sign-issuer-alternative-name`, `--sign-crl-full-name` and `--sign-ocsp-responder`.
* Support for non-standard algorithm names in profile settings was removed.
* Drop support for `Django==4.1`, `cryptography==40.x`, `acme==1.25.0` and `celery==5.2.x`.

Deprecation notices

* The default subject format will switch from OpenSSL-style to RFC 4514 in django-ca 2.0.
* Support for OpenSSL-style subjects will be removed in django-ca 2.2.
* This is the last release to support Django 3.2.
* This is the last release to support acme 2.6.0.
* This is the last release to support Alpine 3.16.

REST API changes

**NOTE:** The [REST API](https://django-ca.readthedocs.io/en/1.27.0/rest_api.html) is still experimental and endpoints will change without notice.

* Certificate issuance is now asynchronous, similar to how certificates are issued via ACME. This enables using CAs where the private key is not directly available to the web server.
* The REST API must now be enabled explicitly for each certificate authority. This can be done via the admin interface or the `--enable-api` flag for `manage.py init_ca`, `manage.py edit_ca` and `manage.py import_ca`.

* Support for `cryptography==39` and `acme==2.4.0` (other versions may removed depending on release time).
* Support for using `ECC` and `EdDSA` as key type. Use `EC` and `Ed25519` instead.
* The `--pathlen` and `--no-pathlen` parameters to `manage.py init_ca` will be removed. Use `--path-length` and `--no-path-length` instead.
* Support for coma-separated lists in `--key-usage`, `--extended-key-usage` and `--tls-feature`. Use lists instead (e.g. `--key-usage keyAgreement keyEncipherment` instead of `--key usagekeyAgreement,keyEncipherment`.
* Support for non-standard TLS feature names "OCSPMustStaple" and "MultipleCertStatusRequest". Use `status_request` and `status_request_v2` instead.

* This is the last release to support acme 2.3.0 and cryptography 38 (cryptography 37 is still supported, see [Warning: cryptography version 38](https://django-ca.readthedocs.io/en/1.24.0/quickstart_as_app.html#cryptography-38-warning)).
* Support for the `CA_DIGEST_ALGORITHM` setting, use `CA_DEFAULT_SIGNATURE_HASH_ALGORITHM` instead.
* Support for the `CA_DEFAULT_ECC_CURVE` setting, use `CA_DEFAULT_ELLIPTIC_CURVE` instead.
* Support for non-standard algorithm names (e.g. `sha512`, use `SHA-512` instead).
* Support for non-standard elliptic key curve names (e.g. `SECP384R1`, use `secp384r1` instead).

Warnings

* **Django app or source users:** Changes in cryptography 38 make it incompatible with common versions of certbot. See [Warning: cryptography version 38](https://django-ca.readthedocs.io/en/1.24.0/quickstart_as_app.html#cryptography-38-warning).
* **docker or source users that do *not* use PostgreSQL:** The [USE_TZ](https://docs.djangoproject.com/en/4.2/ref/settings/#std-setting-USE_TZ) setting was switched to `True` in the Django project. See [Switch to USE_TZ=True by default](https://django-ca.readthedocs.io/en/1.24.0/update.html#switch-use-tz) for update information.

General changes

* Add support for cryptography 40.0, django 4.2 and acme 2.4.0 and 2.5.0.
* Use Django's timezone support by default by enabling `USE_TZ=True`. See [Switch to USE_TZ=True by default](https://django-ca.readthedocs.io/en/1.24.0/update.html#switch-use-tz) for update information.
* Make the default order of subjects configurable via [CA_DEFAULT_NAME_ORDER](https://django-ca.readthedocs.io/en/1.24.0/settings.html#settings-ca-default-name-order).
* Certificates for OCSP responders now include the OCSPNoCheck extension by default.
* Certificates for OCSP responders now use a commonName designating the certificate as OCSP responder as subject, other fields from the CAs subject are discarded.
* A profile can now ignore [CA_DEFAULT_SUBJECT](https://django-ca.readthedocs.io/en/1.24.0/settings.html#settings-ca-default-subject) by setting subject to False.
* Copy all extensions when using `manage.py resign_cert`.
* Add support for multiple OCSP responder and CA Issuer entries when creating a certificate authority.
* Add typehints when installing as wheel.

Command-line interface
======================

Continuing the standardization effort started in 1.23.0, some options have been replaced and/or use a
different syntax. See the [update notes](https://django-ca.readthedocs.io/en/1.24.0/update.html#cli-1-24-0-updates) for more detailed instructions.

* The `--pathlen` and `--no-pathlen` parameters for `manage.py init_ca` were renamed to `--path-length` and `--no-path-length`.
* The `--key-usage` option was changed to/split into `--key-usage` and `--key-usage-non-critical`. `--key-usage` takes multiple option values instead of a single coma-separated list.
* The `--ext-key-usage` option was changed to/split into `--extended-key-usage` and `--extended-key-usage-critical`. `--extended-key-usage` takes multiple option values instead of a single coma-separated list.
* The `--tls-feature` option was changed to/split into `--tls-feature` and `--tls-feature-critical`. `--tls-feature` takes multiple option values instead of a single coma-separated list.
* Add support for specifying a custom Key Usage extension when using `manage.py init_ca`.
* Add support for adding the Inhibit anyPolicy, Policy Constraints and TLS feature extensions when using `manage.py init_ca`.
* Add support for adding the OCSP No Check extension in when issuing certificates with `manage.py sign_cert` or `manage.py resign_cert`.
* Add support for specifying a date when the certificate was compromised when revoking a certificate with `manage.py revoke_cert`.

Backwards incompatible changes

* The `--ext-key-usage` flag to `manage.py sign_cert` was replaced with `--extended-key-usage`.
* The critical flag for the Key Usage, Extended Key Usage and TLS Feature is now set with dedicated options, with the recommended value being the default. See above and the [update notes](https://django-ca.readthedocs.io/en/1.24.0/update.html#cli-1-24-0-updates) for details.
* The `pre_issue_cert` was removed. Use the [pre_sign_cert](https://django-ca.readthedocs.io/en/1.24.0/signals.html#django_ca.signals.pre_sign_cert) signal instead.

Deprecation notices

WARNING

1. **docker compose users:** Update from 1.20 or earlier? See [the update notes](https://django-ca.readthedocs.io/en/1.22.0/update.html#update-121-docker-compose) to switch to named volumes.
2. **Django app or source users:** Changes in cryptography 38 make it incompatible with common versions of certbot. See [Warning: cryptography 38](https://django-ca.readthedocs.io/en/1.22.0/quickstart_as_app.html#cryptography-38-warning).

Changes

* Add support for Python 3.11, Alpine 3.17, Django 4.1, cryptography 38.0 and acme 2.0.
* Support for MD5 and SHA1 hashes is removed, as they are no longer supported in upcoming releases of cryptography.
* New signals [pre_sign_cert](https://django-ca.readthedocs.io/en/1.22.0/signals.html#django_ca.signals.pre_sign_cert) and [post_sign_cert](https://django-ca.readthedocs.io/en/1.22.0/signals.html#django_ca.signals.post_sign_cert) that receive the values as passed to the cryptography library.
* Add the ability to force inclusion/exclusion of the IssuingDistributionPoint extension in CRLs.
* Ensure that CRLs are regenerated periodically before the cache expires.
* Switch to the Djangos `built in Redis cache <https://docs.djangoproject.com/en/4.1/topics/cache/#redis>`_ in the docker compose setup.

Admin interface

* Almost all extensions used in end entity certificates can now be modified when creating new certificates. The following additional extensions are now modifiable: Authority Information Access, CRL Distribution Points, Freshest CRL, Issuer Alternative Name, OCSP No Check and TLS Feature.

**Limitations:**

* The CRL Distribution Points and Freshest CRL extensions can only modify the first distribution point. If the selected profile defines more then one distribution point, they are added after the one from the admin interface.
* The Certificate Policies extension cannot yet be modified. If the selected profile defines this extension, it is still added to the certificate.

* Initial values for the Authority Information Access, CRL Distribution Points and Issuer Alternative Name extensions are set based on information from the default certificate authority. Values may be masked by the default profile.
* Selecting a certificate authority will automatically update the Authority Information Access, CRL Distribution Points and Issuer Alternative Name extensions based on the configuration.
* Because the the user can now modify the extensions directly, the `add_*` directives for a profile now have no effect when issuing a certificate through the admin interface.

ACMEv2 support

* Handle clients that do not send the `termsOfService` field during registration.
* Improve error handling when the CSR cannot be parsed.
* An ACME account is now considered usable if it never agreed to the terms of service *and* the certificate authority does not define any terms of service. Certain versions of certbot (at least version 1.31.0) never ask the user to agree to the terms of service if there are none to agree to.
* Allow clients to agree to the terms of service when updating the account.

Minor changes

* The Docker image is now based on `python:3.11-alpine3.17`.
* Access Descriptions in the Authority Information Access extension will now always order OCSP URLs before CA Issuers, inverting the previous behavior. The order of values does not matter in practice.

Backwards incompatible changes

* The docker-compose setup requires at least docker-compose 1.27.0.
* The docker-compose setup now uses Redis 7.
* Drop support for cryptography 35.0.
* Drop support for acme 1.23, 1.24, 1.25 and 1.26.
* Drop support for Celery 5.0.
* Require django-object-actions 4.0 or higher.
* Remove the `--ca-crl` parameter in `manage.py dump_crl` (this was a left over and has been marked as deprecated since 1.12.0).
* Drop `django-redis-cache` from the `redis` extra, as the project is abandoned. Please switch to the [built in redis cache]( https://docs.djangoproject.com/en/4.1/topics/cache/#redis) instead. If you still use Django 3.2, please manually install the backend.
* `ExtendedKeyUsageOID.KERBEROS_CONSTRAINED_DELEGATION` was removed, use the identical `ExtendedKeyUsageOID.KERBEROS_PKINIT_KDC` instead.

Deprecation notices

* This is the last release to support for Python 3.7.
* This is the last release to support Django 4.0.
* This is the last release to support cryptography 36.0.
* This is the last release to support acme 1.27.0, 1.28.0 and 1.29.0, 1.30.0, 1.31.0 and 2.0.0.
* This is the last release to support Alpine 3.14 and 3.15.
* The `acme` extra will be removed in in the next release.
* The `pre_issue_cert` is deprecated and will be removed in `django_ca==1.24.0`. Use the new [pre_sign_cert](https://django-ca.readthedocs.io/en/1.22.0/signals.html#django_ca.signals.pre_sign_cert) signal instead.
* The subject wrapper class `django_ca.subject.Subject` is deprecated and will be removed in `django-ca==1.24.0`.
* Extension wrapper classes in `django_ca.extensions` are deprecated and will be removed in `django_ca==1.24.0`.