Skip to content

TLS

TlsBlock pydantic-model

Bases: BindBaseModel

TLS configuration block for BIND.

Grammar: tls { ca-file ; cert-file ; cipher-suites ; ciphers ; dhparam-file ; key-file ; prefer-server-ciphers ; protocols { ; ... }; remote-hostname ; session-tickets ; }; // may occur multiple times

Blocks: topmost Tags: security

"ephemeral" and "none" are reserved tls_id values used to reference a TLS configuration in-line (e.g. tls ephemeral; on a listener, or the tls field of a remote-servers/server entry) - passed as a plain string wherever a tls_id_BIND is expected. They cannot be defined via a tls <name> { ... }; clause: named-checkconf rejects that unconditionally, even with an empty body, as "tls clause name '' is reserved for internal use".

Show JSON schema: 
{
  "description": "TLS configuration block for BIND.\n\nGrammar:\ntls <string> {\n    ca-file <quoted_string>;\n    cert-file <quoted_string>;\n    cipher-suites <string>;\n    ciphers <string>;\n    dhparam-file <quoted_string>;\n    key-file <quoted_string>;\n    prefer-server-ciphers <boolean>;\n    protocols { <string>; ... };\n    remote-hostname <quoted_string>;\n    session-tickets <boolean>;\n}; // may occur multiple times\n\nBlocks: topmost\nTags: security\n\n\"ephemeral\" and \"none\" are reserved tls_id values used to *reference* a TLS\nconfiguration in-line (e.g. `tls ephemeral;` on a listener, or the `tls`\nfield of a remote-servers/server entry) - passed as a plain string wherever\na tls_id_BIND is expected. They cannot be *defined* via a `tls <name> { ...\n};` clause: named-checkconf rejects that unconditionally, even with an\nempty body, as \"tls clause name '<name>' is reserved for internal use\".",
  "properties": {
    "comment": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional comment for this block",
      "title": "Comment"
    },
    "name": {
      "description": "Name of the TLS configuration",
      "title": "Name",
      "type": "string"
    },
    "key_file": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Path to private TLS key file",
      "title": "Key File"
    },
    "cert_file": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Path to TLS certificate file",
      "title": "Cert File"
    },
    "ca_file": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Path to trusted CA certificates file",
      "title": "Ca File"
    },
    "dhparam_file": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Path to Diffie-Hellman parameters file",
      "title": "Dhparam File"
    },
    "ciphers": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Allowed ciphers for TLSv1.2/TLSv1.3 (OpenSSL format)",
      "title": "Ciphers"
    },
    "protocols": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Allowed TLS protocol versions",
      "title": "Protocols"
    },
    "prefer_server_ciphers": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "string"
        },
        {
          "type": "integer"
        },
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Prefer server ciphers over client ones",
      "title": "Prefer Server Ciphers"
    },
    "session_tickets": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "string"
        },
        {
          "type": "integer"
        },
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Enable TLS session tickets (RFC 5077)",
      "title": "Session Tickets"
    },
    "remote_hostname": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Expected hostname in remote server certificate",
      "title": "Remote Hostname"
    }
  },
  "required": [
    "name"
  ],
  "title": "TlsBlock",
  "type": "object"
}

Fields:

Validators:

name pydantic-field 

name: string_BIND

Name of the TLS configuration

key_file pydantic-field 

key_file: quoted_string_BIND | None = None

Path to private TLS key file

cert_file pydantic-field 

cert_file: quoted_string_BIND | None = None

Path to TLS certificate file

ca_file pydantic-field 

ca_file: quoted_string_BIND | None = None

Path to trusted CA certificates file

dhparam_file pydantic-field 

dhparam_file: quoted_string_BIND | None = None

Path to Diffie-Hellman parameters file

ciphers pydantic-field 

ciphers: string_BIND | None = None

Allowed ciphers for TLSv1.2/TLSv1.3 (OpenSSL format)

protocols pydantic-field 

protocols: list[string_BIND] | None = None

Allowed TLS protocol versions

prefer_server_ciphers pydantic-field 

prefer_server_ciphers: boolean_BIND | None = None

Prefer server ciphers over client ones

session_tickets pydantic-field 

session_tickets: boolean_BIND | None = None

Enable TLS session tickets (RFC 5077)

remote_hostname pydantic-field 

remote_hostname: quoted_string_BIND | None = None

Expected hostname in remote server certificate

validate_protocols pydantic-validator 

validate_protocols(
    v: list[string_BIND] | None,
) -> list[string_BIND] | None

Validate allowed TLS protocol versions.

validate_configuration_requirements pydantic-validator 

validate_configuration_requirements() -> TlsBlock

Validate configuration requirements.

cert-file/key-file are only required together, not unconditionally: a tls block used purely for client-side connections (forwarders, primaries, remote-servers) is commonly just ca-file/remote-hostname with no certificate of its own to present, and BIND9 accepts that (including a completely empty tls { }; block). named-checkconf only rejects the case where exactly one of cert-file/key-file is given ("must both be specified, or both omitted").