Internal Documentation¶

See also: Module Index

serles.create_app()¶

initialize web app

This function should be passed to the WSGI server.

class serles.backends.ejbca.EjbcaBackend(config)¶

Serles Backend for EJBCA (Community edition compatible)

Uses the EJBCA SOAP API to request certificates. Recommended setup on the EJBCA side:

A Certificate Profile for ACME-issued certificates, e.g. “ACMEServerProfile”. Must have an Extended Key Usage of “Server Authentication”. Should have relatively short Validity duration.
An End Entity Profile, e.g. “ACMEEndIdentityProfile”. Uses the Server Certificate Profile mentioned above and should allow for a number of DNS Name Subject Alternative Names.

To connect to the API, the following setup is used:

A Certificate Profile for authenticating EjbcaBackend with EJBCA’s SOAP API, e.g. “APIClientProfile”. Must have an Extended Key Usage of “Client Authentication”.
An End Entity Profile for client authentication, e.g. “APIClientIdentityProfile”. Uses the Client Certificate Profile mentioned above.
A concrete End Entity for EjbcaBackend, e.g. “client01”. Uses the Client Entity Profile mentioned above. Should have its common name same as its user name.
A certificate must be issued for this entity and its location stored in config.ini.
An Administrator Role for API clients, e.g. “ACMEUser”. From advanced mode, requires access to the Rules (<> denote variables)
- /administrator
- /ca_functionality/create_certificate
- /ra_functionality/create_end_entity
- /ra_functionality/edit_end_entity
- /ca/<NAME_OF_CA> (e.g. /ca/ACMECA)
- /endentityprofilesrules/<END_ENTITY_PROFILE>/create_end_entity (e.g. /endentityprofilesrules/ACMEEndIdentityProfile/create_end_entity/)
- /endentityprofilesrules/<END_ENTITY_PROFILE>/edit_end_entity (e.g. /endentityprofilesrules/ACMEEndIdentityProfile/edit_end_entity/)
Ensure the client entity is in the correct Administrator Role (e.g. via CN).

serles.backends.ejbca.pkcs7_to_pem_chain(pkcs7_input)¶

Converts a PKCS#7 cert chain to PEM format.

Parameters:: pkcs7_input (bytes) – the PKCS#7 chain as stored in the database.
Returns:: PEM encoded certificate chain as expected by ACME clients.
Return type:: str

class serles.backends.base.Backend(config)¶

Abstract Base Backend

Inherit from this and implement sign(), and optionally __init__() to use this.

class serles.backends.certbot.Backend(config)¶

Serles Backend for certbot

Backend will pass the certificate signing request to an already configured certbot installation.

Example use cases:

Want actual trusted certs without using an internal CA (you want it to work in browsers/etc. out of the box)
Don’t want the services externally exposed (internal services/development only)
Don’t want the internal services having control over your external DNS (random developers/users)
Have an intermediate server running serles that you are willing to grant external DNS update rights to.

This allows any internal entity to transparently use serles ACME CA with http-01 validation, but the actual signing requests are delegated to external ACME CA.

Contributed by Nathan Neulinger.

class serles.models.Account(**kwargs)¶

To avoid having to send the large public key for each request, a client registers an Account and identifies itself using the key id. With Let’s Encrypt, accounts persist over a long time, and some clients will try to keep using it. Certbot is especially bad at this, as it fails when the account it expects doesn’t exist. This object also stores an optional contact email address, which we pass to the backend (e.g. for notifications regarding certificate expiry).

query: t.ClassVar[Query]¶: A SQLAlchemy query for a model. Equivalent to db.session.query(Model). Can be customized per-model by overriding query_class.

Warning

The query interface is considered legacy in SQLAlchemy. Prefer using session.execute(select()) instead.

class serles.models.AccountStatus(*values)¶: RFC 8555 § 7.1.6

class serles.models.Authorization(**kwargs)¶

For each Identifier (domain name) the client requested in an Order, there is a Authorization. To obtain a certificate, the client must satisfy all of them. To satisfy an Authorization, the client can solve any one of the Challenges within (i.e., only 1 Challenge per Authorization is required).

query: t.ClassVar[Query]¶: A SQLAlchemy query for a model. Equivalent to db.session.query(Model). Can be customized per-model by overriding query_class.

Warning

The query interface is considered legacy in SQLAlchemy. Prefer using session.execute(select()) instead.

class serles.models.AuthzStatus(*values)¶: RFC 8555 § 7.1.6 (Fig.2)

class serles.models.Certificate(**kwargs)¶

Pretty much what it says on the tin. Stored in the database for the short time between the client requesting finalization of their order and them fetching the cert from us.

query: t.ClassVar[Query]¶: A SQLAlchemy query for a model. Equivalent to db.session.query(Model). Can be customized per-model by overriding query_class.

Warning

The query interface is considered legacy in SQLAlchemy. Prefer using session.execute(select()) instead.

class serles.models.Challenge(**kwargs)¶

A completed Challenge satisfies an Authorization. We support the HTTP-01 challenge type, which requires the client to temporarily serve a short text string on a location we decide.

query: t.ClassVar[Query]¶: A SQLAlchemy query for a model. Equivalent to db.session.query(Model). Can be customized per-model by overriding query_class.

Warning

The query interface is considered legacy in SQLAlchemy. Prefer using session.execute(select()) instead.

class serles.models.ChallengeStatus(*values)¶: RFC 8555 § 7.1.6 (Fig.1)

class serles.models.ChallengeTypes(*values)¶

class serles.models.Identifier(**kwargs)¶

An Identifier is essentially a domain name and some metadata.

query: t.ClassVar[Query]¶: A SQLAlchemy query for a model. Equivalent to db.session.query(Model). Can be customized per-model by overriding query_class.

Warning

The query interface is considered legacy in SQLAlchemy. Prefer using session.execute(select()) instead.

class serles.models.IdentifierTypes(*values)¶

class serles.models.Nonces(**kwargs)¶

To avoid replay attacks, each HTTP POST request must come with a nonce we issued.

classmethod check(value)¶: returns True iff the nonce is valid (not yet used)

query: t.ClassVar[Query]¶: A SQLAlchemy query for a model. Equivalent to db.session.query(Model). Can be customized per-model by overriding query_class.

Warning

The query interface is considered legacy in SQLAlchemy. Prefer using session.execute(select()) instead.

class serles.models.Order(**kwargs)¶

In ACME lingo, an Order identifies a client’s request for a certificate. It keeps a list of Identifiers (domain names) requested from the client, a list of Authorizations (see below), and (once we decided to issue one) the certificate.

query: t.ClassVar[Query]¶: A SQLAlchemy query for a model. Equivalent to db.session.query(Model). Can be customized per-model by overriding query_class.

Warning

The query interface is considered legacy in SQLAlchemy. Prefer using session.execute(select()) instead.

class serles.models.OrderStatus(*values)¶: RFC 8555 § 7.1.6 (Fig.3)

class serles.models.UTCDateTime(*args: Any, **kwargs: Any)¶

SQLite stores datetimes without TZ info, and SQLAlchemy then returns TZ-less datetimes. This breaks calculating timedeltas. So this wrapper converts incoming timestamps to UTC before storing and adds the TZ (utc) back on retrieval.

cache_ok = True¶

Indicate if statements using this ExternalType are “safe to cache”.

The default value None will emit a warning and then not allow caching of a statement which includes this type. Set to False to disable statements using this type from being cached at all without a warning. When set to True, the object’s class and selected elements from its state will be used as part of the cache key. For example, using a TypeDecorator:

class MyType(TypeDecorator):
    impl = String

    cache_ok = True

    def __init__(self, choices):
        self.choices = tuple(choices)
        self.internal_only = True

The cache key for the above type would be equivalent to:

>>> MyType(["a", "b", "c"])._static_cache_key
(<class '__main__.MyType'>, ('choices', ('a', 'b', 'c')))

The caching scheme will extract attributes from the type that correspond to the names of parameters in the __init__() method. Above, the “choices” attribute becomes part of the cache key but “internal_only” does not, because there is no parameter named “internal_only”.

The requirements for cacheable elements is that they are hashable and also that they indicate the same SQL rendered for expressions using this type every time for a given cache value.

To accommodate for datatypes that refer to unhashable structures such as dictionaries, sets and lists, these objects can be made “cacheable” by assigning hashable structures to the attributes whose names correspond with the names of the arguments. For example, a datatype which accepts a dictionary of lookup values may publish this as a sorted series of tuples. Given a previously un-cacheable type as:

class LookupType(UserDefinedType):
    """a custom type that accepts a dictionary as a parameter.

    this is the non-cacheable version, as "self.lookup" is not
    hashable.

    """

    def __init__(self, lookup):
        self.lookup = lookup

    def get_col_spec(self, **kw):
        return "VARCHAR(255)"

    def bind_processor(self, dialect): ...  # works with "self.lookup" ...

Where “lookup” is a dictionary. The type will not be able to generate a cache key:

>>> type_ = LookupType({"a": 10, "b": 20})
>>> type_._static_cache_key
<stdin>:1: SAWarning: UserDefinedType LookupType({'a': 10, 'b': 20}) will not
produce a cache key because the ``cache_ok`` flag is not set to True.
Set this flag to True if this type object's state is safe to use
in a cache key, or False to disable this warning.
symbol('no_cache')

If we did set up such a cache key, it wouldn’t be usable. We would get a tuple structure that contains a dictionary inside of it, which cannot itself be used as a key in a “cache dictionary” such as SQLAlchemy’s statement cache, since Python dictionaries aren’t hashable:

>>> # set cache_ok = True
>>> type_.cache_ok = True

>>> # this is the cache key it would generate
>>> key = type_._static_cache_key
>>> key
(<class '__main__.LookupType'>, ('lookup', {'a': 10, 'b': 20}))

>>> # however this key is not hashable, will fail when used with
>>> # SQLAlchemy statement cache
>>> some_cache = {key: "some sql value"}
Traceback (most recent call last): File "<stdin>", line 1,
in <module> TypeError: unhashable type: 'dict'

The type may be made cacheable by assigning a sorted tuple of tuples to the “.lookup” attribute:

class LookupType(UserDefinedType):
    """a custom type that accepts a dictionary as a parameter.

    The dictionary is stored both as itself in a private variable,
    and published in a public variable as a sorted tuple of tuples,
    which is hashable and will also return the same value for any
    two equivalent dictionaries.  Note it assumes the keys and
    values of the dictionary are themselves hashable.

    """

    cache_ok = True

    def __init__(self, lookup):
        self._lookup = lookup

        # assume keys/values of "lookup" are hashable; otherwise
        # they would also need to be converted in some way here
        self.lookup = tuple((key, lookup[key]) for key in sorted(lookup))

    def get_col_spec(self, **kw):
        return "VARCHAR(255)"

    def bind_processor(self, dialect): ...  # works with "self._lookup" ...

Where above, the cache key for LookupType({"a": 10, "b": 20}) will be:

>>> LookupType({"a": 10, "b": 20})._static_cache_key
(<class '__main__.LookupType'>, ('lookup', (('a', 10), ('b', 20))))

Added in version 1.4.14: - added the cache_ok flag to allow some configurability of caching for TypeDecorator classes.

Added in version 1.4.28: - added the ExternalType mixin which generalizes the cache_ok flag to both the TypeDecorator and UserDefinedType classes.