Модуль Apache mod_ssl

Директива SSLCACertificateFile

SSLCACertificateFile file-path

Эта директива задаёт единый файл, в который можно поместить сертификаты центров сертификации (CA), с клиентами которых вы работаете. Они используются для аутентификации клиента. Такой файл представляет собой объединение нескольких файлов сертификатов в кодировке PEM, расположенных в порядке предпочтения. Этот способ можно использовать вместо SSLCACertificatePath и/или в дополнение к ней.

SSLCACertificateFile "/usr/local/apache2/conf/ssl.crt/ca-bundle-client.crt"

Директива SSLCACertificatePath

SSLCACertificatePath directory-path

Эта директива задаёт каталог, в котором хранятся сертификаты центров сертификации (CA), с клиентами которых вы работаете. Они используются для проверки клиентского сертификата при аутентификации клиента.

Файлы в этом каталоге должны быть в кодировке PEM; доступ к ним осуществляется по хешированным именам файлов. Поэтому обычно недостаточно просто поместить туда файлы сертификатов: необходимо также создать символические ссылки с именами hash-value.N. Всегда проверяйте, что в этом каталоге есть соответствующие символические ссылки.

SSLCACertificatePath "/usr/local/apache2/conf/ssl.crt/"

Директива SSLCADNRequestFile

SSLCADNRequestFile file-path

Когда mod_ssl запрашивает клиентский сертификат, во время SSL-рукопожатия клиенту отправляется список допустимых имён центров сертификации. Клиент может использовать эти имена, чтобы выбрать подходящий клиентский сертификат из имеющихся.

Если не заданы ни директива SSLCADNRequestPath, ни директива SSLCADNRequestFile, клиенту отправляются имена всех сертификатов CA, заданных директивами SSLCACertificateFile и SSLCACertificatePath; иными словами, имена CA, которые фактически будут использоваться для проверки клиентского сертификата.

В некоторых случаях полезно отправить набор допустимых имён CA, отличный от фактически используемых для проверки клиентского сертификата CA, например, если клиентские сертификаты подписаны промежуточными CA. В таких случаях можно использовать SSLCADNRequestPath и/или SSLCADNRequestFile; тогда допустимые имена CA берутся из полного набора сертификатов в каталоге и/или файле, заданном этими директивами.

SSLCADNRequestFile должна указывать на единый файл, содержащий объединённые сертификаты CA в кодировке PEM.

SSLCADNRequestFile "/usr/local/apache2/conf/ca-names.crt"

Директива SSLCADNRequestPath

SSLCADNRequestPath directory-path

Эту необязательную директиву можно использовать для задания набора допустимых имён CA, который будет отправлен клиенту при запросе клиентского сертификата. Подробности см. в описании директивы SSLCADNRequestFile.

Файлы в этом каталоге должны быть в кодировке PEM; доступ к ним осуществляется по хешированным именам файлов. Поэтому обычно недостаточно просто поместить туда файлы сертификатов: необходимо также создать символические ссылки с именами hash-value.N. Всегда проверяйте, что в этом каталоге есть соответствующие символические ссылки.

SSLCADNRequestPath "/usr/local/apache2/conf/ca-names.crt/"

Директива SSLCARevocationCheck

SSLCARevocationCheck chain|leaf|none [flags ...]

SSLCARevocationCheck none

Включает проверку списков отозванных сертификатов (CRL). Необходимо настроить как минимум один из параметров SSLCARevocationFile или SSLCARevocationPath. При значении chain (рекомендуемая настройка) проверяются CRL для всех сертификатов в цепочке; значение leaf ограничивает проверку конечным сертификатом.

Доступны следующие флаги:

• no_crl_for_cert_ok

  До версии 2.3.15 проверка CRL в mod_ssl также считалась успешной, если CRL для проверяемых сертификатов не были найдены ни в одном из расположений, заданных с помощью SSLCARevocationFile или SSLCARevocationPath.

  С появлением SSLCARevocationFile поведение изменилось: по умолчанию при использовании chain или leaf наличие CRL обязательно для успешной проверки; в противном случае проверка завершится ошибкой "unable to get certificate CRL".

  Флаг no_crl_for_cert_ok позволяет восстановить прежнее поведение.

SSLCARevocationCheck chain

SSLCARevocationCheck chain no_crl_for_cert_ok

Директива SSLCARevocationFile

SSLCARevocationFile file-path

Эта директива задаёт единый файл, в который можно поместить списки отозванных сертификатов (CRL) центров сертификации (CA), с клиентами которых вы работаете. Они используются для аутентификации клиента. Такой файл представляет собой объединение нескольких файлов CRL в кодировке PEM, расположенных в порядке предпочтения. Этот способ можно использовать вместо SSLCARevocationPath и/или в дополнение к ней.

SSLCARevocationFile "/usr/local/apache2/conf/ssl.crl/ca-bundle-client.crl"

Директива SSLCARevocationPath

SSLCARevocationPath directory-path

Эта директива задаёт каталог, в котором хранятся списки отозванных сертификатов (CRL) центров сертификации (CA), с клиентами которых вы работаете. Они используются для отзыва клиентского сертификата при аутентификации клиента.

Файлы в этом каталоге должны быть в кодировке PEM; доступ к ним осуществляется по хешированным именам файлов. Поэтому обычно недостаточно просто поместить туда файлы CRL. Необходимо также создать символические ссылки с именами hash-value.rN. Всегда проверяйте, что в этом каталоге есть соответствующие символические ссылки.

SSLCARevocationPath "/usr/local/apache2/conf/ssl.crl/"

Директива SSLCertificateChainFile

SSLCertificateChainFile file-path

Эта директива задаёт необязательный единый файл, в который можно поместить сертификаты центров сертификации (CA), образующих цепочку сертификатов сервера. Цепочка начинается с сертификата CA, выдавшего сертификат сервера, и может доходить до корневого сертификата CA. Такой файл представляет собой объединение нескольких файлов сертификатов CA в кодировке PEM, обычно расположенных в порядке цепочки сертификатов.

Эту директиву следует использовать вместо SSLCACertificatePath и/или в дополнение к ней для явного построения цепочки сертификатов сервера, которая отправляется браузеру вместе с сертификатом сервера. Это особенно полезно для предотвращения конфликтов с сертификатами CA при использовании аутентификации клиента. Хотя добавление сертификата CA из цепочки сертификатов сервера в SSLCACertificatePath даёт тот же результат при построении цепочки, это также приводит к побочному эффекту: при аутентификации клиента принимаются клиентские сертификаты, выданные тем же сертификатом CA.

Но будьте осторожны: предоставление цепочки сертификатов работает только при использовании одного сертификата сервера на основе RSA или DSA. Если используется связанная пара сертификатов RSA+DSA, этот способ сработает только в том случае, если для обоих сертификатов используется одна и та же цепочка сертификатов. В противном случае браузеры будут введены в заблуждение.

SSLCertificateChainFile "/usr/local/apache2/conf/ssl.crt/ca.crt"

Директива SSLCertificateFile

SSLCertificateFile file-path|certid

Эта директива указывает на файл с данными сертификата в формате PEM или на идентификатор сертификата, хранящегося в настроенном криптографическом токене. Если используется файл PEM, он должен содержать как минимум конечный сертификат (сертификат конечного узла). Директиву можно указывать несколько раз (с разными именами файлов), чтобы поддерживать несколько алгоритмов аутентификации сервера — обычно RSA, DSA и ECC. Число поддерживаемых алгоритмов зависит от версии OpenSSL, используемой mod_ssl: версия 1.0.0 и более поздние позволяют получить список поддерживаемых алгоритмов с помощью openssl list-public-key-algorithms. См. также приведённое ниже примечание об ограничениях версий OpenSSL до 1.0.2 и способах их обхода.

Файлы могут также содержать промежуточные сертификаты CA, упорядоченные от конечного к корневому. Эта возможность поддерживается в версии 2.4.8 и более поздних и заменяет SSLCertificateChainFile. При использовании OpenSSL 1.0.2 или более поздней версии это позволяет настраивать цепочку промежуточных CA отдельно для каждого сертификата.

Пользовательские параметры DH и имя кривой EC для эфемерных ключей также можно добавить в конец первого файла, заданного с помощью SSLCertificateFile. Эта возможность поддерживается в версии 2.4.7 и более поздних. Такие параметры можно создать с помощью команд openssl dhparam и openssl ecparam. Параметры можно добавить в конец первого файла сертификата без изменений. Пользовательские параметры можно указать только в первом файле, поскольку они применяются независимо от типа алгоритма аутентификации.

Наконец, закрытый ключ конечного сертификата можно добавить непосредственно в файл сертификата вместо использования отдельной директивы SSLCertificateKeyFile. Настоятельно не рекомендуется поступать таким образом. Если этот способ используется, файлы сертификатов со встроенным ключом необходимо настроить после сертификатов, для которых задан отдельный файл ключа. Если закрытый ключ зашифрован, при запуске будет запрошена парольная фраза.

Вместо хранения сертификатов и закрытых ключей в файлах можно использовать идентификатор сертификата, хранящегося в токене. В настоящее время идентификаторами сертификатов распознаются только URI PKCS#11; их можно использовать совместно с движком или провайдером OpenSSL pkcs11. Если SSLCertificateKeyFile не задан, сертификат и закрытый ключ можно загрузить с помощью единого идентификатора, указанного в SSLCertificateFile.

# Example using a PEM-encoded file.
SSLCertificateFile "/usr/local/apache2/conf/ssl.crt/server.crt"
# Example use of a certificate and private key from a PKCS#11 token:
SSLCertificateFile "pkcs11:token=My%20Token%20Name;id=45"

Директива SSLCertificateKeyFile

SSLCertificateKeyFile file-path|keyid

Эта директива указывает на файл закрытого ключа сервера в кодировке PEM или на идентификатор ключа, хранящегося в настроенном криптографическом токене. Если закрытый ключ зашифрован, при запуске будет запрошена парольная фраза.

Директиву можно указывать несколько раз (с разными именами файлов), чтобы поддерживать несколько алгоритмов аутентификации сервера. Для каждой директивы SSLCertificateKeyFile должна быть соответствующая директива SSLCertificateFile.

Закрытый ключ также можно объединить с сертификатом в файле, заданном директивой SSLCertificateFile, но настоятельно не рекомендуется поступать таким образом. Если этот способ используется, файлы сертификатов со встроенным ключом необходимо настроить после сертификатов, для которых задан отдельный файл ключа.

Вместо хранения закрытых ключей в файлах можно использовать идентификатор ключа, хранящегося в токене. В настоящее время идентификаторами закрытых ключей распознаются только URI PKCS#11; их можно использовать совместно с движком или провайдером OpenSSL pkcs11.

# To use a private key from a PEM-encoded file:
SSLCertificateKeyFile "/usr/local/apache2/conf/ssl.key/server.key"
# To use a private key from a PKCS#11 token:
SSLCertificateKeyFile "pkcs11:token=My%20Token%20Name;id=45"

Директива SSLCipherSuite

SSLCipherSuite [protocol] cipher-spec

SSLCipherSuite DEFAULT (depends on OpenSSL version)

Эта сложная директива использует разделённую двоеточиями строку cipher-spec, состоящую из спецификаций шифров OpenSSL, чтобы настроить набор шифров, который клиенту разрешено согласовать на этапе SSL-рукопожатия. Необязательный спецификатор протокола позволяет настроить набор шифров для определённой версии SSL. Возможные значения включают «SSL» для всех протоколов SSL вплоть до TLSv1.2 включительно.

Обратите внимание, что эту директиву можно использовать как в контексте отдельного сервера, так и в контексте отдельного каталога. В контексте отдельного сервера она применяется к стандартному SSL-рукопожатию при установлении соединения. В контексте отдельного каталога она принудительно запускает повторное SSL-согласование с перенастроенным набором шифров после чтения HTTP-запроса, но до отправки HTTP-ответа.

Если библиотека SSL поддерживает TLSv1.3 (OpenSSL 1.1.1 и новее), для настройки наборов шифров этого протокола можно использовать спецификатор протокола «TLSv1.3». Поскольку TLSv1.3 не поддерживает повторное согласование, указывать для него шифры в контексте каталога нельзя.

Список названий шифров TLSv1.3 см. в документации OpenSSL.

Спецификация SSL-шифра в cipher-spec состоит из 4 основных атрибутов и нескольких дополнительных второстепенных:

• Алгоритм обмена ключами:
  RSA, Диффи — Хеллман, Диффи — Хеллман на эллиптических кривых, Secure Remote Password
• Алгоритм аутентификации:
  RSA, Диффи — Хеллман, DSS, ECDSA или отсутствует.
• Алгоритм шифрования:
  AES, DES, Triple-DES, RC4, RC2, IDEA и т. д.
• Алгоритм хеширования MAC:
  MD5, SHA или SHA1, SHA256, SHA384.

SSL-шифр также может быть экспортным. Шифры SSLv2 больше не поддерживаются. Чтобы указать, какие шифры использовать, можно перечислить все шифры по одному или воспользоваться псевдонимами, задающими предпочтения и порядок шифров (см. таблицу 1). Фактически доступные шифры и псевдонимы зависят от используемой версии OpenSSL. В более новых версиях OpenSSL могут быть дополнительные шифры.

Интересно то, что эти значения можно комбинировать, чтобы задать желаемый порядок и набор шифров. Для ускорения настройки существуют также псевдонимы (SSLv3, TLSv1, EXP, LOW, MEDIUM, HIGH) для некоторых групп шифров. Эти теги можно объединять с префиксами, формируя cipher-spec. Доступны следующие префиксы:

• без префикса: добавить шифр в список
• +: переместить соответствующие шифры в текущую позицию в списке
• -: удалить шифр из списка (позже его можно добавить снова)
• !: полностью исключить шифр из списка (позже его нельзя будет добавить снова)

Более простой способ разобраться во всём этом — использовать команду «openssl ciphers -v», которая позволяет последовательно составить правильную строку cipher-spec. Строка cipher-spec по умолчанию зависит от версии используемых библиотек OpenSSL. Предположим, что это «RC4-SHA:AES128-SHA:HIGH:MEDIUM:!aNULL:!MD5», что означает следующее: поместить RC4-SHA и AES128-SHA в начало. Мы делаем это, поскольку эти шифры обеспечивают хороший компромисс между скоростью и безопасностью. Затем включить шифры с высокой и средней стойкостью. Наконец, удалить все шифры без аутентификации, то есть для SSL — шифры с анонимным обменом ключами Диффи — Хеллмана, а также все шифры, использующие MD5 в качестве алгоритма хеширования, поскольку его стойкость признана недостаточной.

$ openssl ciphers -v 'RC4-SHA:AES128-SHA:HIGH:MEDIUM:!aNULL:!MD5'
RC4-SHA                 SSLv3 Kx=RSA      Au=RSA  Enc=RC4(128)  Mac=SHA1
AES128-SHA              SSLv3 Kx=RSA      Au=RSA  Enc=AES(128)  Mac=SHA1
DHE-RSA-AES256-SHA      SSLv3 Kx=DH       Au=RSA  Enc=AES(256)  Mac=SHA1
...                     ...               ...     ...           ...
SEED-SHA                SSLv3 Kx=RSA      Au=RSA  Enc=SEED(128) Mac=SHA1
PSK-RC4-SHA             SSLv3 Kx=PSK      Au=PSK  Enc=RC4(128)  Mac=SHA1
KRB5-RC4-SHA            SSLv3 Kx=KRB5     Au=KRB5 Enc=RC4(128)  Mac=SHA1

Полный список отдельных шифров RSA и DH для SSL приведён в таблице 2.

SSLCipherSuite RSA:!EXP:!NULL:+HIGH:+MEDIUM:-LOW

Директива SSLCompression

SSLCompression on|off

SSLCompression off

Эта директива позволяет включить сжатие на уровне SSL.

Директива SSLCryptoDevice

SSLCryptoDevice engine

SSLCryptoDevice builtin

Эта директива включает использование аппаратной платы криптографического ускорителя для переноса на неё части нагрузки по обработке SSL. Эту директиву можно использовать, только если набор инструментов SSL собран с поддержкой «engine»; выпуски OpenSSL 0.9.7 и новее по умолчанию поддерживают «engine», а для OpenSSL 0.9.6 необходимо использовать отдельные выпуски «-engine».

Чтобы узнать, какие имена движков поддерживаются, выполните команду «openssl engine».

# For a Broadcom accelerator:
SSLCryptoDevice ubsec

В OpenSSL 3.0 и новее, если движок не указан, но ключ или сертификат заданы с помощью URI PKCS#11, будет предпринята попытка загрузить ключ и сертификат из провайдера OpenSSL. Используемый провайдер OpenSSL необходимо определить и настроить в файле конфигурации OpenSSL; он должен поддерживать метод STORE для URI PKCS#11.

Директива SSLEngine

SSLEngine on|off|optional

SSLEngine off

Эта директива включает или отключает использование обработчика протокола SSL/TLS. Её следует использовать внутри секции <VirtualHost>, чтобы включить SSL/TLS для этого виртуального хоста. По умолчанию обработчик протокола SSL/TLS отключён как для основного сервера, так и для всех настроенных виртуальных хостов.

<VirtualHost _default_:443>
SSLEngine on
#...
</VirtualHost>

В Apache 2.1 и новее для SSLEngine можно задать значение optional. Это включает поддержку RFC 2817 — перехода на TLS в рамках HTTP/1.1. В настоящее время ни один веб-браузер не поддерживает RFC 2817.

Директива SSLFIPS

SSLFIPS on|off

SSLFIPS off

Эта директива включает или отключает флаг FIPS_mode библиотеки SSL. Её необходимо задать в глобальном контексте сервера; задавать конфликтующие значения (например, SSLFIPS on, а затем SSLFIPS off) нельзя. Режим применяется ко всем операциям библиотеки SSL.

Если httpd был скомпилирован с библиотекой SSL, которая не поддерживает флаг FIPS_mode, директива SSLFIPS on завершится ошибкой. Конкретные требования для использования mod_ssl в режиме, одобренном по стандарту FIPS 140-2, см. в документе «Политика безопасности» библиотеки SSL-провайдера. Обратите внимание: сам mod_ssl не прошёл валидацию, однако его можно описать как использующий криптографический модуль, прошедший валидацию FIPS 140-2, если все компоненты собраны и работают в соответствии с рекомендациями применимой политики безопасности.

Директива SSLHonorCipherOrder

SSLHonorCipherOrder on|off

SSLHonorCipherOrder off

При выборе шифра во время рукопожатия SSLv3 или TLSv1 обычно учитываются предпочтения клиента. Если эта директива включена, вместо них будут использоваться предпочтения сервера.

SSLHonorCipherOrder on

Директива SSLInsecureRenegotiation

SSLInsecureRenegotiation on|off

SSLInsecureRenegotiation off

В исходной спецификации все версии протоколов SSL и TLS (вплоть до TLS/1.2 включительно) были уязвимы к атаке «человек посередине» (CVE-2009-3555) во время повторного согласования. Эта уязвимость позволяла злоумышленнику добавить выбранный открытый текст в начало HTTP-запроса, получаемого веб-сервером. Для устранения уязвимости было разработано расширение протокола, обеспечивающее защиту при его поддержке клиентом и сервером.

Если mod_ssl скомпонован с OpenSSL версии 0.9.8m или новее, по умолчанию повторное согласование поддерживается только для клиентов, поддерживающих новое расширение протокола. Если эта директива включена, повторное согласование будет разрешено и для старых (неисправленных) клиентов, хотя и с риском для безопасности.

SSLInsecureRenegotiation on

Переменную окружения SSL_SECURE_RENEG можно использовать в SSI- или CGI-сценарии, чтобы определить, поддерживается ли безопасное повторное согласование для данного SSL-соединения.

Директива SSLOCSPDefaultResponder

SSLOCSPDefaultResponder uri

Этот параметр задаёт ответчик OCSP по умолчанию. Если SSLOCSPOverrideResponder не включена, указанный URI будет использоваться только в том случае, если в проверяемом сертификате не задан URI ответчика.

Директива SSLOCSPEnable

SSLOCSPEnable on|leaf|off

SSLOCSPEnable off

Этот параметр включает проверку цепочки сертификатов клиента с помощью OCSP. Если параметр включён, сертификаты в цепочке сертификатов клиента будут проверены ответчиком OCSP после выполнения обычной проверки (включая проверки CRL). В режиме «leaf» проверяется только сам сертификат клиента.

Используемый ответчик OCSP извлекается из самого сертификата или определяется конфигурацией; см. директивы SSLOCSPDefaultResponder и SSLOCSPOverrideResponder.

SSLVerifyClient on
SSLOCSPEnable on
SSLOCSPDefaultResponder "http://responder.example.com:8888/responder"
SSLOCSPOverrideResponder on

Директива SSLOCSPNoverify

SSLOCSPNoverify on|off

SSLOCSPNoverify off

Пропускает проверку сертификатов ответчика OCSP; это может быть полезно при тестировании сервера OCSP.

Директива SSLOCSPOverrideResponder

SSLOCSPOverrideResponder on|off

SSLOCSPOverrideResponder off

Этот параметр принудительно задаёт использование настроенного ответчика OCSP по умолчанию при проверке сертификатов с помощью OCSP независимо от того, указан ли ответчик OCSP в проверяемом сертификате.

Директива SSLOCSPProxyURL

SSLOCSPProxyURL url

Этот параметр позволяет задать URL HTTP-прокси-сервера, который будет использоваться для всех запросов к ответчикам OCSP.

Директива SSLOCSPResponderCertificateFile

SSLOCSPResponderCertificateFile file

Задаёт список доверенных сертификатов ответчика OCSP, используемых при проверке сертификата ответчика OCSP. Предоставленные сертификаты считаются доверенными без дополнительной проверки. Обычно это используется, когда сертификат ответчика OCSP самоподписан или не включён в ответ OCSP.

Директива SSLOCSPResponderTimeout

SSLOCSPResponderTimeout seconds

SSLOCSPResponderTimeout 10

Этот параметр задаёт время ожидания ответов на запросы к ответчикам OCSP, когда включён параметр SSLOCSPEnable.

Директива SSLOCSPResponseMaxAge

SSLOCSPResponseMaxAge seconds

SSLOCSPResponseMaxAge -1

Этот параметр задаёт максимально допустимый возраст («свежесть») ответов OCSP. Значение по умолчанию (-1) не ограничивает максимальный возраст, а значит, ответы OCSP считаются действительными, пока их поле nextUpdate содержит дату в будущем.

Директива SSLOCSPResponseTimeSkew

SSLOCSPResponseTimeSkew seconds

SSLOCSPResponseTimeSkew 300

Этот параметр задаёт максимально допустимое расхождение времени для ответов OCSP (при проверке их полей thisUpdate и nextUpdate).

Директива SSLOCSPUseRequestNonce

SSLOCSPUseRequestNonce on|off

SSLOCSPUseRequestNonce on

Этот параметр определяет, должны ли запросы к ответчикам OCSP содержать nonce. По умолчанию nonce всегда используется в запросе и сверяется со значением в ответе. Если ответчик не использует nonce (например, Microsoft OCSP Responder), этот параметр следует выключить: off.

Директива SSLOpenSSLConfCmd

SSLOpenSSLConfCmd command-name command-value

Эта директива предоставляет mod_ssl доступ к API SSL_CONF OpenSSL, позволяя гибко настраивать параметры OpenSSL без необходимости реализовывать дополнительные директивы mod_ssl при добавлении новых функций в OpenSSL.

Набор доступных команд SSLOpenSSLConfCmd зависит от версии OpenSSL, используемой для mod_ssl (требуется версия не ниже 1.0.2). Список поддерживаемых имён команд см. в разделе Supported configuration file commands руководства SSL_CONF_cmd(3) для OpenSSL.

Некоторые команды SSLOpenSSLConfCmd можно использовать вместо существующих директив (например, SSLCipherSuite или SSLProtocol), однако следует учитывать, что синтаксис и допустимые значения параметров могут различаться.

SSLOpenSSLConfCmd Options -SessionTicket,ServerPreference
SSLOpenSSLConfCmd ECDHParameters brainpoolP256r1
SSLOpenSSLConfCmd ServerInfoFile "/usr/local/apache2/conf/server-info.pem"
SSLOpenSSLConfCmd Protocol "-ALL, TLSv1.2"
SSLOpenSSLConfCmd SignatureAlgorithms RSA+SHA384:ECDSA+SHA256

Директива SSLOptions

SSLOptions [+|-]option ...

Эта директива позволяет управлять различными параметрами среды выполнения отдельно для каждого каталога. Обычно, если к каталогу применимы несколько директив SSLOptions, полностью применяется наиболее специфичная из них; параметры не объединяются. Однако, если перед всеми параметрами директивы SSLOptions стоит знак плюс (+) или минус (-), параметры объединяются. Параметры, перед которыми стоит +, добавляются к действующим в данный момент параметрам, а параметры, перед которыми стоит -, удаляются из действующих в данный момент параметров.

Доступны следующие параметры:

• StdEnvVars

  Если этот параметр включён, создаётся стандартный набор переменных среды CGI/SSI, связанных с SSL. По умолчанию этот параметр отключён из соображений производительности, поскольку извлечение этой информации — довольно затратная операция. Поэтому обычно этот параметр включают только для запросов CGI и SSI.

• ExportCertData

  Если этот параметр включён, создаются дополнительные переменные среды CGI/SSI: SSL_SERVER_CERT, SSL_CLIENT_CERT и SSL_CLIENT_CERT_CHAIN_n (где n = 0,1,2,..). Они содержат сертификаты X.509 сервера и клиента для текущего HTTPS-соединения в кодировке PEM и могут использоваться скриптами CGI для более глубокой проверки сертификатов. Кроме того, предоставляются все остальные сертификаты из цепочки сертификатов клиента. Это немного увеличивает размер среды, поэтому данный параметр необходимо включать только при необходимости.

• FakeBasicAuth

  Если этот параметр включён, отличительное имя (DN) субъекта сертификата X509 клиента преобразуется в имя пользователя HTTP Basic Authorization. Это означает, что для управления доступом можно использовать стандартные методы аутентификации Apache. Именем пользователя является субъект сертификата X509 клиента (его можно определить с помощью команды OpenSSL openssl x509: openssl x509 -noout -subject -incertificate.crt). Обратите внимание, что пароль пользователя не запрашивается. Для каждой записи в файле пользователей нужен пароль ``xxj31ZMTZzkVA'' — DES-зашифрованная версия слова `password''. В системах, использующих шифрование на основе MD5 (например, FreeBSD или BSD/OS и т. д.), следует использовать следующий MD5-хеш того же слова: ``$1$OXLyS...$Owx8s2/m9/gfkcRVXzgoE/''.

  Обратите внимание, что директива AuthBasicFake в mod_auth_basic может использоваться как более общий механизм имитации базовой аутентификации, позволяющий управлять структурой имени пользователя и пароля.

• StrictRequire

  Этот параметр принудительно запрещает доступ, если SSLRequireSSL или SSLRequire успешно определили, что доступ должен быть запрещён. Обычно по умолчанию, если используется директива «Satisfy any», а другие ограничения доступа пройдены, запрет доступа из-за SSLRequireSSL или SSLRequire отменяется (поскольку именно так должен работать механизм Apache Satisfy). Однако для строгого ограничения доступа можно использовать SSLRequireSSL и/или SSLRequire вместе с «SSLOptions +StrictRequire». Тогда дополнительная директива «Satisfy Any» не сможет повлиять на решение mod_ssl запретить доступ.

• OptRenegotiate

  Этот параметр включает оптимизированную обработку повторного согласования SSL-соединения, если директивы SSL используются в контексте отдельного каталога. По умолчанию используется строгая схема, при которой каждая перенастройка параметров SSL для отдельного каталога приводит к полному рукопожатию повторного согласования SSL. При использовании этого параметра mod_ssl пытается избежать ненужных рукопожатий, выполняя более детальные (но по-прежнему безопасные) проверки параметров. Тем не менее такие детальные проверки иногда могут не соответствовать ожиданиям пользователя, поэтому включайте этот параметр только для отдельных каталогов.

• LegacyDNStringFormat

  Этот параметр влияет на форматирование значений переменных SSL_{CLIENT,SERVER}_{I,S}_DN. Начиная с версии 2.3.11, Apache HTTPD по умолчанию использует формат, совместимый с RFC 2253. В нём в качестве разделителей между атрибутами используются запятые, допускаются символы не ASCII (которые преобразуются в UTF8), различные специальные символы экранируются обратными косыми чертами, а атрибут "C" сортируется последним.

  Если задан LegacyDNStringFormat, будет использоваться старый формат: атрибут "C" сортируется первым, в качестве разделителей используются косые черты, а символы не ASCII и специальные символы обрабатываются непоследовательно.

SSLOptions +FakeBasicAuth -StrictRequire
<Files ~ "\.(cgi|shtml)$">
    SSLOptions +StdEnvVars -ExportCertData
</Files>

Директива SSLPassPhraseDialog

SSLPassPhraseDialog type

SSLPassPhraseDialog builtin

При запуске Apache необходимо прочитать различные файлы сертификатов (см. SSLCertificateFile) и закрытых ключей (см. SSLCertificateKeyFile) SSL-виртуальных серверов. Поскольку из соображений безопасности файлы закрытых ключей обычно зашифрованы, mod_ssl должен запросить у администратора парольную фразу для их расшифровки. Такой запрос можно выполнить двумя способами, которые задаются параметром type:

• builtin

  Это вариант по умолчанию: при запуске открывается интерактивный диалог в терминале, непосредственно перед тем как Apache отсоединится от терминала. Администратор должен вручную ввести парольную фразу для каждого зашифрованного файла закрытого ключа. Поскольку может быть настроено много виртуальных хостов с поддержкой SSL, для сокращения числа запросов используется следующая схема повторного использования: при зашифрованном файле закрытого ключа проверяются все известные парольные фразы (в начале их, конечно, нет). Если одна из известных парольных фраз подходит, для этого файла закрытого ключа диалог не открывается. Если ни одна не подошла, в терминале запрашивается ещё одна парольная фраза, которая сохраняется для следующей проверки (когда её, возможно, удастся повторно использовать).

  Эта схема обеспечивает mod_ssl максимальную гибкость (поскольку для N зашифрованных файлов закрытых ключей можно использовать N разных парольных фраз — но тогда, разумеется, придётся ввести их все) и одновременно сокращает число запросов в терминале (то есть если для всех N файлов закрытых ключей используется одна парольная фраза, она будет запрошена только один раз).

• |/path/to/program [args...]

  В этом режиме можно использовать внешнюю программу, работающую как канал к определённому устройству ввода. Программе передаётся стандартный текст запроса, используемый в режиме builtin, через stdin; ожидается, что строки с паролями она будет записывать в stdout. Если требуется несколько паролей (или введён неверный пароль), после возврата первого пароля будет выведен дополнительный текст запроса, и программе нужно будет передать следующие пароли.

• exec:/path/to/program

  Здесь настраивается внешняя программа, которая вызывается при запуске для каждого зашифрованного файла закрытого ключа. Она вызывается с двумя аргументами (первый имеет формат «servername:portnumber», второй — «RSA», «DSA», «ECC» или целочисленный индекс, начиная с 3, если настроено более трёх ключей); они указывают, для какого сервера и алгоритма требуется вывести соответствующую парольную фразу в stdout. В версиях 2.4.8 (не выпущена) и 2.4.9 ей передаётся один аргумент — строка формата «servername:portnumber:index» (где index — целое число, отсчитываемое с нуля), указывающая сервер, порт TCP и номер сертификата. Предполагается, что сначала эта внешняя программа выполняет проверки безопасности, чтобы убедиться, что система не скомпрометирована злоумышленником, и только после успешного прохождения этих проверок предоставляет парольную фразу.

  Эти проверки безопасности и способ определения парольной фразы могут быть сколь угодно сложными. Mod_ssl определяет только интерфейс: исполняемая программа, которая предоставляет парольную фразу в stdout. Ни больше ни меньше! Поэтому, если вы действительно крайне осторожны в вопросах безопасности, этот интерфейс для вас. Всё остальное остаётся на усмотрение администратора, поскольку требования к локальной безопасности могут сильно различаться.

  Здесь также используется описанный выше алгоритм повторного использования. Иными словами, внешняя программа вызывается только один раз для каждой уникальной парольной фразы.

SSLPassPhraseDialog "exec:/usr/local/apache/sbin/pp-filter"

Директива SSLProtocol

SSLProtocol [+|-]protocol ...

SSLProtocol all -SSLv3 (up to 2.4.16: all)

Эта директива позволяет управлять версиями протокола SSL/TLS, которые будут приниматься при новых соединениях.

Доступны следующие протоколы (регистр не учитывается):

• SSLv3

  Протокол Secure Sockets Layer (SSL), версия 3.0, разработанный корпорацией Netscape. Он пришёл на смену SSLv2, а затем был заменён TLSv1; в настоящее время его использование не рекомендуется согласно RFC 7568.

• TLSv1

  Протокол Transport Layer Security (TLS), версия 1.0. Он пришёл на смену SSLv3 и описан в RFC 2246. Его поддерживает почти каждый клиент.

• TLSv1.1 (при использовании OpenSSL 1.0.1 и более поздних версий)

  Пересмотренная версия протокола TLS 1.0, описанная в RFC 4346.

• TLSv1.2 (при использовании OpenSSL 1.0.1 и более поздних версий)

  Пересмотренная версия протокола TLS 1.1, описанная в RFC 5246.

• TLSv1.3 (при использовании OpenSSL 1.1.1 и более поздних версий)

  Новая версия протокола TLS, описанная в RFC 8446.

• all

  Это сокращение для «+SSLv3 +TLSv1» или — при использовании OpenSSL 1.0.1 и более поздних версий — «+SSLv3 +TLSv1 +TLSv1.1 +TLSv1.2» соответственно (за исключением версий OpenSSL, собранных с параметром конфигурации «no-ssl3», в которых all не включает +SSLv3).

SSLProtocol TLSv1

Директива SSLProxyCACertificateFile

SSLProxyCACertificateFile file-path

Эта директива задаёт единый файл, в котором можно объединить сертификаты центров сертификации (CA), с которыми работают ваши удалённые серверы. Они используются для аутентификации удалённых серверов. Такой файл представляет собой простое объединение различных файлов сертификатов в кодировке PEM, расположенных в порядке предпочтения. Его можно использовать вместо SSLProxyCACertificatePath и/или в дополнение к ней.

SSLProxyCACertificateFile "/usr/local/apache2/conf/ssl.crt/ca-bundle-remote-server.crt"

Директива SSLProxyCACertificatePath

SSLProxyCACertificatePath directory-path

Эта директива задаёт каталог, в котором хранятся сертификаты центров сертификации (CA), с которыми работают ваши удалённые серверы. Они используются для проверки сертификата удалённого сервера при его аутентификации.

Файлы в этом каталоге должны быть в кодировке PEM и доступны по именам, содержащим хеш. Поэтому обычно недостаточно просто поместить туда файлы сертификатов: нужно также создать символические ссылки с именами значение-хеша.N. Всегда проверяйте, что в этом каталоге есть соответствующие символические ссылки.

SSLProxyCACertificatePath "/usr/local/apache2/conf/ssl.crt/"

Директива SSLProxyCARevocationCheck

SSLProxyCARevocationCheck chain|leaf|none

SSLProxyCARevocationCheck none

Включает проверку списков отозванных сертификатов (CRL) для удалённых серверов, с которыми вы работаете. Должна быть настроена как минимум одна из директив SSLProxyCARevocationFile или SSLProxyCARevocationPath. При значении chain (рекомендуемая настройка) проверяются CRL для всех сертификатов в цепочке; значение leaf ограничивает проверку конечным сертификатом.

SSLProxyCARevocationCheck chain

Директива SSLProxyCARevocationFile

SSLProxyCARevocationFile file-path

Эта директива задаёт единый файл, в котором можно объединить списки отозванных сертификатов (CRL) центров сертификации (CA), с которыми работают ваши удалённые серверы. Они используются для аутентификации удалённых серверов. Такой файл представляет собой простое объединение различных файлов CRL в кодировке PEM, расположенных в порядке предпочтения. Его можно использовать вместо SSLProxyCARevocationPath и/или в дополнение к ней.

SSLProxyCARevocationFile "/usr/local/apache2/conf/ssl.crl/ca-bundle-remote-server.crl"

Директива SSLProxyCARevocationPath

SSLProxyCARevocationPath directory-path

Эта директива задаёт каталог, в котором хранятся списки отозванных сертификатов (CRL) центров сертификации (CA), с которыми работают ваши удалённые серверы. Они используются для отзыва сертификата удалённого сервера при его аутентификации.

Файлы в этом каталоге должны быть в кодировке PEM и доступны по именам, содержащим хеш. Поэтому обычно недостаточно просто поместить туда файлы CRL. Кроме того, нужно создать символические ссылки с именами значение-хеша.rN. Всегда проверяйте, что в этом каталоге есть соответствующие символические ссылки.

SSLProxyCARevocationPath "/usr/local/apache2/conf/ssl.crl/"

Директива SSLProxyCheckPeerCN

SSLProxyCheckPeerCN on|off

SSLProxyCheckPeerCN on

Эта директива задаёт, следует ли сравнивать поле CN сертификата удалённого сервера с именем хоста в URL запроса. Если они не совпадают, возвращается код состояния 502 (Bad Gateway). В выпуске 2.4.5 и более поздних версиях директику SSLProxyCheckPeerCN заменила директива SSLProxyCheckPeerName.

Во всех выпусках с 2.4.5 по 2.4.20 для включения такого поведения было достаточно задать SSLProxyCheckPeerName off (поскольку значением по умолчанию для SSLProxyCheckPeerCN было on). В этих выпусках, чтобы полностью отключить проверку имени в сертификате удалённого сервера, обе директивы нужно было задать как off. Многие пользователи считали это поведение весьма запутанным.

Начиная с выпуска 2.4.21, во всех конфигурациях, где включён хотя бы один из параметров SSLProxyCheckPeerName или SSLProxyCheckPeerCN, используется новое поведение SSLProxyCheckPeerName, а во всех конфигурациях, где отключён хотя бы один из параметров SSLProxyCheckPeerName или SSLProxyCheckPeerCN, подавляется вся проверка имени в сертификате удалённого сервера. Только следующая конфигурация запускает устаревшее сравнение CN сертификата в версии 2.4.21 и более поздних выпусках;

SSLProxyCheckPeerCN on
SSLProxyCheckPeerName off

Директива SSLProxyCheckPeerExpire

SSLProxyCheckPeerExpire on|off

SSLProxyCheckPeerExpire on

Эта директива задаёт, проверяется ли истечение срока действия сертификата удалённого сервера. Если проверка не пройдена, возвращается код состояния 502 (Bad Gateway).

SSLProxyCheckPeerExpire on

Директива SSLProxyCheckPeerName

SSLProxyCheckPeerName on|off

SSLProxyCheckPeerName on

Эта директива настраивает проверку имени хоста в сертификатах сервера, когда mod_ssl работает в качестве клиента SSL. Проверка считается успешной, если имя хоста из URI запроса совпадает с одним из атрибутов CN субъекта сертификата или с расширением subjectAltName. Если проверка не пройдена, SSL-запрос прерывается и возвращается код состояния 502 (Bad Gateway).

Подстановка символов-шаблонов поддерживается в определённых случаях: запись subjectAltName типа dNSName или атрибуты CN, начинающиеся с *., совпадают с любым именем хоста с таким же числом компонентов и тем же суффиксом. Например, *.example.org совпадает с foo.example.org, но не с foo.bar.example.org, поскольку соответствующие имена хостов содержат разное число компонентов.

Эта возможность появилась в версии 2.4.5 и заменила поведение директивы SSLProxyCheckPeerCN, которая проверяла только точное совпадение значения первого атрибута CN с именем хоста. Однако многих пользователей сбивало с толку поведение при раздельном использовании этих директив, поэтому в выпуске 2.4.21 было улучшено совместное поведение директив SSLProxyCheckPeerName и SSLProxyCheckPeerCN. Описание директивы SSLProxyCheckPeerCN содержит сведения об исходном поведении и подробности этих улучшений.

Директива SSLProxyCipherSuite

SSLProxyCipherSuite [protocol] cipher-spec

SSLProxyCipherSuite ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+EXP

Эквивалент директивы SSLCipherSuite, применяемый к соединению прокси. Дополнительные сведения см. в SSLCipherSuite.

Директива SSLProxyEngine

SSLProxyEngine on|off

SSLProxyEngine off

Эта директива включает или отключает работу протокольного механизма SSL/TLS для прокси. Обычно она используется внутри секции <VirtualHost>, чтобы включить SSL/TLS для прокси в определённом виртуальном хосте. По умолчанию протокольный механизм SSL/TLS для прокси отключён как на главном сервере, так и во всех настроенных виртуальных хостах.

Обратите внимание, что директиву SSLProxyEngine обычно не следует включать в виртуальный хост, который будет работать как прямой прокси (с использованием директив <Proxy> или ProxyRequests). Для того чтобы прямой прокси-сервер мог проксировать запросы SSL/TLS, SSLProxyEngine не требуется.

<VirtualHost _default_:443>
    SSLProxyEngine on
    #...
</VirtualHost>

Директива SSLProxyMachineCertificateChainFile

SSLProxyMachineCertificateChainFile filename

Эта директива задаёт единый файл, в котором хранится цепочка сертификатов для всех используемых клиентских сертификатов. Эта директива необходима, если удалённый сервер передаёт список сертификатов центров сертификации, которые не являются непосредственными подписантами ни одного из настроенных клиентских сертификатов.

Указанный файл представляет собой простое объединение различных файлов сертификатов в кодировке PEM. При запуске проверяется каждый настроенный клиентский сертификат и строится цепочка доверия.

SSLProxyMachineCertificateChainFile "/usr/local/apache2/conf/ssl.crt/proxyCA.pem"

Директива SSLProxyMachineCertificateFile

SSLProxyMachineCertificateFile filename

Эта директива задаёт единый файл, в котором хранятся сертификаты и ключи, используемые для аутентификации прокси-сервера на удалённых серверах.

Указанный файл представляет собой простое объединение различных файлов сертификатов в кодировке PEM. Используйте эту директиву вместо SSLProxyMachineCertificatePath или в дополнение к ней. Указанный файл может содержать любое количество пар клиентского сертификата и соответствующего закрытого ключа. Каждую пару можно указать в любом порядке: (сертификат, ключ) или (ключ, сертификат). Файл также может содержать сертификаты, не являющиеся конечными (CA); они обрабатываются так, как если бы были настроены с помощью SSLProxyMachineCertificateChainFile.

Когда удалённый сервер запрашивает клиентский сертификат, он должен передать в запросе список приемлемых имён центров сертификации. Если такой список не передан, mod_ssl использует первый настроенный клиентский сертификат/ключ. Если список имён CA передан, mod_ssl перебирает его и пытается найти настроенный клиентский сертификат, выданный непосредственно указанным центром сертификации или через любое количество промежуточных центров сертификации. Цепочку промежуточных сертификатов CA можно построить из включённых в файл сертификатов или настроить с помощью SSLProxyMachineCertificateChainFile. Затем в ответ на запрос будет передан первый настроенный сертификат, соответствующий условиям.

Если удалённый сервер передал список имён CA и подходящий клиентский сертификат найти не удалось, mod_ssl не предоставит клиентский сертификат, что, скорее всего, приведёт к сбою TLS-рукопожатия (в зависимости от конфигурации удалённого сервера).

SSLProxyMachineCertificateFile "/usr/local/apache2/conf/ssl.crt/proxy.pem"

Директива SSLProxyMachineCertificatePath

SSLProxyMachineCertificatePath directory

Эта директива задаёт каталог, в котором хранятся клиентские сертификаты и ключи, используемые для аутентификации прокси-сервера на удалённых серверах.

mod_ssl попытается загрузить каждый файл в указанном каталоге так, как если бы он был задан отдельно с помощью SSLProxyMachineCertificateFile.

SSLProxyMachineCertificatePath "/usr/local/apache2/conf/proxy.crt/"

Директива SSLProxyProtocol

SSLProxyProtocol [+|-]protocol ...

SSLProxyProtocol all -SSLv3 (up to 2.4.16: all)

Эта директива позволяет управлять версиями протокола SSL, которые mod_ssl должен использовать при настройке среды сервера для прокси-соединения. Подключение будет выполняться только к серверам, использующим один из указанных протоколов.

Дополнительные сведения см. в разделе SSLProtocol.

Директива SSLProxyVerify

SSLProxyVerify level

SSLProxyVerify none

Если прокси настроен на перенаправление запросов к удалённому SSL-серверу, эту директиву можно использовать для настройки проверки сертификата удалённого сервера.

Для уровня доступны следующие значения:

• none: сертификат удалённого сервера не требуется
• optional: удалённый сервер может предъявить действительный сертификат
• require: удалённый сервер должен предъявить действительный сертификат
• optional_no_ca: удалённый сервер может предъявить действительный сертификат,
  но его необязательно успешно проверять.

На практике представляют интерес только уровни none и require, поскольку уровень optional работает не со всеми серверами, а уровень optional_no_ca противоречит самой идее аутентификации (однако его можно использовать для создания тестовых страниц SSL и т. п.).

SSLProxyVerify require

Директива SSLProxyVerifyDepth

SSLProxyVerifyDepth number

SSLProxyVerifyDepth 1

Эта директива задаёт глубину проверки mod_ssl, после которой он решает, что сертификат удалённого сервера недействителен.

Глубина — это максимальное число промежуточных издателей сертификатов, то есть максимальное количество сертификатов центров сертификации, по которым разрешено пройти при проверке сертификата удалённого сервера. Глубина 0 означает, что принимаются только самоподписанные сертификаты удалённых серверов; глубина 1 по умолчанию означает, что сертификат удалённого сервера может быть самоподписанным или должен быть подписан центром сертификации, который непосредственно известен серверу (то есть сертификат центра сертификации находится в SSLProxyCACertificatePath), и т. д.

SSLProxyVerifyDepth 10

Директива SSLRandomSeed

SSLRandomSeed context source [bytes]

Эта директива настраивает один или несколько источников для начального заполнения генератора псевдослучайных чисел (PRNG) в OpenSSL при запуске (контекст — startup) и/или непосредственно перед установлением нового SSL-соединения (контекст — connect). Эту директиву можно использовать только в глобальном контексте сервера, поскольку PRNG является глобальным механизмом.

Доступны следующие варианты источника:

• builtin

  Это встроенный источник начального заполнения, доступный всегда. Во время работы он потребляет минимум процессорных ресурсов, поэтому его можно использовать постоянно без каких-либо недостатков. Источник данных для начального заполнения PRNG состоит из текущего времени, идентификатора текущего процесса и случайно выбранных 128 байт из стека. Недостаток заключается в том, что этот источник нельзя считать действительно надёжным, а при запуске (когда таблица состояния ещё недоступна) он даёт лишь несколько байтов энтропии. Поэтому при запуске всегда следует использовать дополнительный источник начального заполнения.

• file:/path/to/source

  Этот вариант использует внешний файл /path/to/source в качестве источника для начального заполнения PRNG. Если задано значение bytes, энтропию образуют только первые bytes байт файла (а значение bytes передаётся в /path/to/source как первый аргумент). Если значение bytes не задано, энтропию образует весь файл (а 0 передаётся в /path/to/source как первый аргумент). Используйте этот вариант, особенно при запуске, например, с доступными устройствами /dev/random и/или /dev/urandom (обычно они есть в современных системах на базе Unix, таких как FreeBSD и Linux).

  Однако будьте осторожны: обычно /dev/random предоставляет столько данных энтропии, сколько имеется в данный момент. Например, если запрошено 512 байт энтропии, а устройство располагает только 100 байтами, возможны два варианта: на некоторых платформах вы получите только 100 байт, а на других чтение будет заблокировано до появления достаточного количества байт (что может занять много времени). В этом случае лучше использовать имеющийся /dev/urandom, поскольку он никогда не блокирует работу и действительно выдаёт запрошенный объём данных. Недостаток лишь в том, что качество полученных данных может быть не самым высоким.

• exec:/path/to/program

  Этот вариант использует внешнюю исполняемую программу /path/to/program в качестве источника для начального заполнения PRNG. Если задано значение bytes, энтропию образуют только первые bytes байт содержимого её stdout. Если значение bytes не задано, энтропию образуют все данные, полученные из stdout. Используйте этот вариант только при запуске, когда требуется очень надёжное начальное заполнение с помощью внешней программы (например, как в приведённом выше примере с утилитой truerand из дистрибутива mod_ssl, основанной на библиотеке AT&T truerand). Использование этого варианта в контексте соединения, разумеется, слишком сильно замедляет работу сервера. Поэтому обычно следует избегать использования внешних программ в этом контексте.

• egd:/path/to/egd-socket (только Unix)

  Этот вариант использует доменный сокет Unix внешнего демона сбора энтропии (EGD) (см. http://www.lothar.com/tech /crypto/) для начального заполнения PRNG. Используйте его, если на вашей платформе нет устройства генерации случайных чисел.

SSLRandomSeed startup builtin
SSLRandomSeed startup "file:/dev/random"
SSLRandomSeed startup "file:/dev/urandom" 1024
SSLRandomSeed startup "exec:/usr/local/bin/truerand" 16
SSLRandomSeed connect builtin
SSLRandomSeed connect "file:/dev/random"
SSLRandomSeed connect "file:/dev/urandom" 1024

Директива SSLRenegBufferSize

SSLRenegBufferSize bytes

SSLRenegBufferSize 131072

Если требуется повторное согласование SSL в контексте отдельного расположения, например при использовании SSLVerifyClient в блоке Directory или Location, mod_ssl должен буферизовать тело HTTP-запроса в памяти до завершения нового рукопожатия SSL. Эту директиву можно использовать для задания объёма памяти, выделяемого под этот буфер.

SSLRenegBufferSize 262144

Директива SSLRequire

SSLRequire expression

Эта директива задаёт общее требование к доступу, которое должно выполняться для его разрешения. Это очень мощная директива, поскольку требование может представлять собой произвольно сложное логическое выражение с любым количеством проверок доступа.

Выражение должно соответствовать следующему синтаксису (записанному в нотации грамматики БНФ):

expr     ::= "true" | "false"
           | "!" expr
           | expr "&&" expr
           | expr "||" expr
           | "(" expr ")"
           | comp

comp     ::= word "==" word | word "eq" word
           | word "!=" word | word "ne" word
           | word "<"  word | word "lt" word
           | word "<=" word | word "le" word
           | word ">"  word | word "gt" word
           | word ">=" word | word "ge" word
           | word "in" "{" wordlist "}"
           | word "in" "PeerExtList(" word ")"
           | word "=~" regex
           | word "!~" regex

wordlist ::= word
           | wordlist "," word

word     ::= digit
           | cstring
           | variable
           | function

digit    ::= [0-9]+
cstring  ::= "..."
variable ::= "%{" varname "}"
function ::= funcname "(" funcargs ")"

Для varname можно использовать любые переменные, описанные в разделе Переменные среды. Доступные для funcname функции перечислены в документации ap_expr.

Выражение преобразуется во внутреннее машинное представление при загрузке конфигурации, а затем вычисляется во время обработки запроса. В контексте .htaccess выражение разбирается и выполняется каждый раз, когда при обработке запроса встречается файл .htaccess.

SSLRequire (    %{SSL_CIPHER} !~ m/^(EXP|NULL)-/                   \
            and %{SSL_CLIENT_S_DN_O} eq "Snake Oil, Ltd."          \
            and %{SSL_CLIENT_S_DN_OU} in {"Staff", "CA", "Dev"}    \
            and %{TIME_WDAY} -ge 1 and %{TIME_WDAY} -le 5          \
            and %{TIME_HOUR} -ge 8 and %{TIME_HOUR} -le 20       ) \
           or %{REMOTE_ADDR} =~ m/^192\.76\.162\.[0-9]+$/

Функция PeerExtList(object-ID) ищет в сертификате клиента ноль или более экземпляров расширения сертификата X.509, определяемого заданным идентификатором объекта (OID). Выражение считается истинным, если строка слева точно совпадает со значением расширения с этим OID. (Если присутствует несколько расширений с одинаковым OID, должно совпасть хотя бы одно из них.)

SSLRequire "foobar" in PeerExtList("1.2.3.4.5.6")

См. также

• Переменные среды в Apache HTTP Server — дополнительные примеры.
• Require expr
• Общий синтаксис выражений в Apache HTTP Server

Директива SSLRequireSSL

Эта директива запрещает доступ, если для текущего соединения не включён HTTP поверх SSL (то есть HTTPS). Она очень удобна внутри виртуального хоста с включённым SSL или каталогов, чтобы защититься от ошибок конфигурации, из-за которых могут стать доступными данные, требующие защиты. При наличии этой директивы все запросы без использования SSL отклоняются.

SSLRequireSSL

Директива SSLSessionCache

SSLSessionCache type

SSLSessionCache none

Эта директива настраивает тип хранилища глобального/межпроцессного кэша сеансов SSL. Этот кэш является необязательным механизмом, который ускоряет параллельную обработку запросов. Для запросов к одному и тому же процессу сервера (через HTTP keep-alive) OpenSSL уже кэширует сведения о сеансах SSL локально. Однако современные клиенты запрашивают встроенные изображения и другие данные параллельно (обычно одновременно выполняется до четырёх запросов), и эти запросы обслуживаются разными предварительно созданными процессами сервера. Межпроцессный кэш помогает избежать ненужных рукопожатий сеанса.

В настоящее время поддерживаются следующие пять типов хранилища:

• none

  Отключает глобальный/межпроцессный кэш сеансов. Это заметно снизит производительность и может вызвать проблемы при использовании некоторых браузеров, особенно если включены клиентские сертификаты. Эта настройка не рекомендуется.

• nonenotnull

  Отключает любой глобальный/межпроцессный кэш сеансов. Однако OpenSSL принудительно отправляет ненулевой идентификатор сеанса, чтобы поддержать некорректно работающие клиенты, которым он необходим.

• dbm:/path/to/datafile

  Использует хеш-файл DBM на локальном диске для синхронизации локальных кэшей памяти OpenSSL процессов сервера. При высокой нагрузке в работе этого кэша сеансов могут возникать проблемы с надёжностью. Для его использования убедитесь, что загружен mod_socache_dbm.

• shmcb:/path/to/datafile [(размер)]

  Использует высокопроизводительный циклический буфер (приблизительно размер байт) в сегменте разделяемой оперативной памяти (создаваемом с помощью /path/to/datafile) для синхронизации локальных кэшей памяти OpenSSL процессов сервера. Это рекомендуемый кэш сеансов. Для его использования убедитесь, что загружен mod_socache_shmcb.

• dc:UNIX:/path/to/socket

  Использует библиотеки распределённого кэширования сеансов distcache. Аргумент должен указывать расположение используемого сервера или прокси-сервера в синтаксисе адресов distcache; например, UNIX:/path/to/socket указывает доменный сокет UNIX (обычно локальный прокси dc_client); IP:server.example.com:9001 указывает IP-адрес. Для использования убедитесь, что загружен mod_socache_dc.

SSLSessionCache "dbm:/usr/local/apache/logs/ssl_gcache_data"
SSLSessionCache "shmcb:/usr/local/apache/logs/ssl_gcache_data(512000)"

Мьютекс ssl-cache используется для сериализации доступа к кэшу сеансов и предотвращения его повреждения. Этот мьютекс можно настроить с помощью директивы Mutex.

Директива SSLSessionCacheTimeout

SSLSessionCacheTimeout seconds

SSLSessionCacheTimeout 300

Эта директива задаёт время ожидания в секундах для данных, хранящихся в глобальном/межпроцессном кэше сеансов SSL и внутреннем кэше памяти OpenSSL, а также для сеансов, возобновляемых с помощью механизма возобновления сеансов TLS (RFC 5077). Для тестирования значение можно уменьшить до 15, но в реальных условиях следует использовать более высокие значения, например 300.

SSLSessionCacheTimeout 600

Директива SSLSessionTicketKeyFile

SSLSessionTicketKeyFile file-path

Эта необязательная директива задаёт секретный ключ для шифрования и расшифрования билетов сеансов TLS, определённых в RFC 5077. В первую очередь подходит для кластерных сред, где сведения о сеансах TLS должны быть общими для нескольких узлов. Для конфигураций httpd с одним экземпляром рекомендуется не задавать файл ключа билета, а вместо этого использовать ключи, которые mod_ssl генерирует при запуске (случайным образом).

Файл ключа билета должен содержать 48 байт случайных данных, предпочтительно полученных из источника с высокой энтропией. В Unix-подобной системе файл ключа билета можно создать следующим образом:

dd if=/dev/random of=/path/to/file.tkey bs=1 count=48

Ключи билетов следует регулярно менять, поскольку это единственный способ аннулировать существующие билеты сеансов: в настоящее время OpenSSL не позволяет задавать срок действия билетов. Новый ключ билета начинает использоваться только после перезапуска веб-сервера. После перезапуска все существующие билеты сеансов становятся недействительными.

Директива SSLSessionTickets

SSLSessionTickets on|off

SSLSessionTickets on

Эта директива позволяет включить или отключить использование билетов сеансов TLS (RFC 5077).

Директива SSLSRPUnknownUserSeed

SSLSRPUnknownUserSeed secret-string

Эта директива задаёт начальное значение, используемое для подстановки параметров пользователя SRP для неизвестных пользователей, чтобы не раскрывать, существует ли указанный пользователь. Укажите секретную строку. Если директива не используется, Apache будет возвращать клиентам, указавшим неизвестное имя пользователя, оповещение UNKNOWN_PSK_IDENTITY.

SSLSRPUnknownUserSeed "secret"

Директива SSLSRPVerifierFile

SSLSRPVerifierFile file-path

Эта директива включает TLS-SRP и задаёт путь к файлу верификаторов OpenSSL SRP (Secure Remote Password), содержащему имена пользователей TLS-SRP, верификаторы, соли и параметры групп.

SSLSRPVerifierFile "/path/to/file.srpv"

Файл верификаторов можно создать с помощью утилиты командной строки openssl:

openssl srp -srpvfile passwd.srpv -userinfo "some info" -add username

Значение, указанное с необязательным параметром -userinfo, доступно в переменной среды запроса SSL_SRP_USERINFO.

Директива SSLStaplingCache

SSLStaplingCache type

Настраивает кэш для хранения ответов OCSP, включаемых в рукопожатие TLS, если включена SSLUseStapling. Для OCSP-штампования настройка кэша обязательна. За исключением none и nonenotnull, поддерживаются те же типы хранилища, что и для SSLSessionCache.

Директива SSLStaplingErrorCacheTimeout

SSLStaplingErrorCacheTimeout seconds

SSLStaplingErrorCacheTimeout 600

Задаёт время ожидания в секундах до истечения срока действия недействительных ответов в кэше OCSP-штампования (настраиваемом с помощью SSLStaplingCache). Чтобы задать время хранения действительных ответов в кэше, см. SSLStaplingStandardCacheTimeout.

Директива SSLStaplingFakeTryLater

SSLStaplingFakeTryLater on|off

SSLStaplingFakeTryLater on

Если эта директива включена и запрос к ответчику OCSP для целей штампования завершается ошибкой, mod_ssl сформирует для клиента ответ "tryLater". Действует только при включённой SSLStaplingReturnResponderErrors.

Директива SSLStaplingForceURL

SSLStaplingForceURL uri

Эта директива переопределяет URI ответчика OCSP, полученный из расширения authorityInfoAccess (AIA) сертификата. Один из возможных вариантов использования — обращение через прокси-сервер для получения запросов OCSP.

Директива SSLStaplingResponderTimeout

SSLStaplingResponderTimeout seconds

SSLStaplingResponderTimeout 10

Этот параметр задаёт время ожидания ответов на запросы к ответчикам OCSP, когда включена SSLUseStapling и mod_ssl запрашивает ответчика для целей OCSP-штампования.

Директива SSLStaplingResponseMaxAge

SSLStaplingResponseMaxAge seconds

SSLStaplingResponseMaxAge -1

Этот параметр задаёт максимально допустимый возраст («свежесть») ответов OCSP при их использовании для штампования, то есть когда включена SSLUseStapling. Значение по умолчанию (-1) не ограничивает максимальный возраст, поэтому ответы OCSP считаются действительными, пока их поле nextUpdate указывает на будущее время.

Директива SSLStaplingResponseTimeSkew

SSLStaplingResponseTimeSkew seconds

SSLStaplingResponseTimeSkew 300

Этот параметр задаёт максимально допустимое расхождение времени при проверке mod_ssl полей thisUpdate и nextUpdate ответов OCSP, включаемых в рукопожатие TLS (OCSP-штампование). Применяется только при включённой SSLUseStapling.

Директива SSLStaplingReturnResponderErrors

SSLStaplingReturnResponderErrors on|off

SSLStaplingReturnResponderErrors on

Если эта директива включена, mod_ssl будет передавать клиенту ответы на неудачные запросы OCSP, связанные со штампованием (например, ответы с общим статусом, отличным от "successful", ответы со статусом сертификата, отличным от "good", просроченные ответы и т. д.). Если задано значение off, в рукопожатие TLS будут включаться только ответы, указывающие на статус сертификата "good".

Директива SSLStaplingStandardCacheTimeout

SSLStaplingStandardCacheTimeout seconds

SSLStaplingStandardCacheTimeout 3600

Задаёт время в секундах, по истечении которого ответы в кэше OCSP stapling (настраиваемом с помощью SSLStaplingCache) теряют силу. Эта директива применяется к действительным ответам, тогда как SSLStaplingErrorCacheTimeout используется для управления временем хранения недействительных/недоступных ответов.

Директива SSLStrictSNIVHostCheck

SSLStrictSNIVHostCheck on|off

SSLStrictSNIVHostCheck off

Эта директива задаёт, разрешён ли клиенту без поддержки SNI доступ к виртуальному хосту на основе имени. Если в виртуальном хосте по умолчанию, использующем имя, задано значение on, клиенты без поддержки SNI не смогут получить доступ ни к одному виртуальному хосту, относящемуся к этой комбинации IP-адреса и порта. Если в любом другом виртуальном хосте задано значение on, клиенты без поддержки SNI не смогут получить доступ к этому виртуальному хосту.

SSLStrictSNIVHostCheck on

Директива SSLUserName

SSLUserName varname

Эта директива задаёт поле «user» в объекте запроса Apache. Нижестоящие модули используют его для идентификации пользователя в виде символьной строки. В частности, это может привести к установке переменной окружения REMOTE_USER. В качестве varname можно указать любую из переменных окружения SSL.

Обратите внимание, что эта директива не действует, если используется параметр FakeBasicAuth (см. SSLOptions).

SSLUserName SSL_CLIENT_S_DN_CN

Директива SSLUseStapling

SSLUseStapling on|off

SSLUseStapling off

Этот параметр включает OCSP stapling, определённый расширением TLS «Certificate Status Request», описанным в RFC 6066. Если этот параметр включён (и клиент отправил соответствующий запрос), mod_ssl включит ответ OCSP для собственного сертификата в рукопожатие TLS. Для включения OCSP stapling необходимо настроить SSLStaplingCache.

OCSP stapling избавляет клиента от необходимости самостоятельно обращаться к серверу OCSP, однако следует учитывать, что согласно спецификации RFC 6066 ответ CertificateStatus сервера может содержать ответ OCSP только для одного сертификата. Поэтому для сертификатов сервера, цепочка которых содержит промежуточные сертификаты ЦС (что обычно встречается в наши дни), текущая реализация stapling лишь частично достигает заявленной цели — «сокращения числа обменов данными и расхода ресурсов». См. также RFC 6961 (расширение TLS для статусов нескольких сертификатов).

При включённом OCSP stapling мьютекс ssl-stapling используется для управления доступом к кэшу OCSP stapling и предотвращения его повреждения, а мьютекс sss-stapling-refresh — для управления обновлением ответов OCSP. Эти мьютексы можно настроить с помощью директивы Mutex.

Директива SSLVerifyClient

SSLVerifyClient level

SSLVerifyClient none

Эта директива задаёт уровень проверки сертификата для аутентификации клиента. Обратите внимание, что директиву можно использовать как в контексте сервера, так и в контексте каталога. В контексте сервера она применяется к процессу аутентификации клиента, выполняемому во время стандартного рукопожатия SSL при установлении соединения. В контексте каталога она принудительно запускает повторное согласование SSL с перенастроенным уровнем проверки клиента после чтения HTTP-запроса, но до отправки HTTP-ответа.

Для параметра level доступны следующие значения:

• none: сертификат клиента не требуется
• optional: клиент может предоставить действительный сертификат
• require: клиент должен предоставить действительный сертификат
• optional_no_ca: клиент может предоставить действительный сертификат,
  но его проверка может завершиться неудачей. На этот параметр нельзя полагаться при аутентификации клиента.

SSLVerifyClient require

Директива SSLVerifyDepth

SSLVerifyDepth number

SSLVerifyDepth 1

Эта директива задаёт глубину проверки, до которой mod_ssl будет проверять сертификат, прежде чем решить, что у клиента нет действительного сертификата. Обратите внимание, что директиву можно использовать как в контексте сервера, так и в контексте каталога. В контексте сервера она применяется к процессу аутентификации клиента, выполняемому во время стандартного рукопожатия SSL при установлении соединения. В контексте каталога она принудительно запускает повторное согласование SSL с перенастроенной глубиной проверки клиента после чтения HTTP-запроса, но до отправки HTTP-ответа.

Фактически глубина — это максимальное количество промежуточных издателей сертификатов, то есть максимальное количество сертификатов ЦС, по которым разрешено пройти при проверке сертификата клиента. Глубина 0 означает, что принимаются только самоподписанные сертификаты клиента; глубина 1, заданная по умолчанию, означает, что сертификат клиента может быть самоподписанным или должен быть подписан ЦС, непосредственно известным серверу (то есть сертификат ЦС находится в SSLCACertificatePath), и так далее.

SSLVerifyDepth 10