repo: gemini-site
action: commit
revision: 
path_from: 
revision_from: fecc424d1bbaa66e9de6b3d2c6a50e37d52e9f5c:
path_to: 
revision_to: 

commit fecc424d1bbaa66e9de6b3d2c6a50e37d52e9f5c
Author: Anna “CyberTailor” 
Date:   Mon Mar 29 06:44:00 2021 +0200

    docs/ru: add "Resources for beginners" translation

    Signed-off-by: Solderpunk 

diff --git a/docs/ru/cheatsheet.gmi b/docs/ru/cheatsheet.gmi
new file mode 100644
index 0000000000000000000000000000000000000000..ba7f035587f8b9c044b9dcc6897195d3f68a5d66
--- /dev/null
+++ b/docs/ru/cheatsheet.gmi
@@ -0,0 +1,34 @@
+# Шпаргалка по Gemtext
+
+Перечислим основы того, как работает текст в Gemtext:
+
+* Длинные строки переносятся клиентом, чтобы помещаться в экран
+* Короткие строки *не* соединяются вместе
+* Параграфы пишутся как отдельные длинные строки
+* Пустые строки отрисовываются точь-в-точь
+
+Есть три уровня заголовков:
+
+```
+# Заголовок
+
+## Подзаголовок
+
+### Подподзаголовок
+```
+
+Есть один вид списков, причём они не могут быть вложенными:
+
+```
+* Меркурий
+* Джемини
+* Аполлон
+```
+
+А вот цитата Мацея Цегловского:
+
+```
+> Я утверждаю, что ваш сайт, если он текстовый, не должен превышать в файловом размере главные работы русской литературы.
+```
+
+Строки, которые начинаются с ```, переключают клиент с нормального режима рендеринга на вывод преформатированного текста и обратно.  В режиме преформатированного текста синтаксис Gemtext игнорируется, то  есть ссылки и всё прочее не будет отрисовано особым образом, а текст будет напечатан моноширинным шрифтом.
diff --git a/docs/ru/gemtext.gmi b/docs/ru/gemtext.gmi
new file mode 100644
index 0000000000000000000000000000000000000000..33c6b1a0096324372cc5aff8a04e18e0819ade2e
--- /dev/null
+++ b/docs/ru/gemtext.gmi
@@ -0,0 +1,98 @@
+# Быстрое введение в язык разметки "gemtext"
+
+Общепринятый способ передавать текстовое содержимое через Gemini - не простым текстом, как в Gopher, а с помощью лёгкого языка разметки под названием "Gemtext" (который раздаётся с неофициальным MIME-типом text/gemini).  Данный документ служит быстрым введением в этот язык разметки.  Gemtext имеет поверхностное сходство с Markdown, что делает его изучение простым, если вы уже знаете MD, но они также имеют и ряд отличий.
+
+После того, как вы прочитаете этот документ, вы можете время от времени освежить свою память, обращаясь к шпаргалке.
+
+=> cheatsheet.gmi Шпаргалка по Gemtext
+
+## Текст
+
+Текст в документах Gemtext пишется с помощью "длинных строк", то есть вы (или ваш редактор) не должны вставлять символы переноса строки каждые 80 символов или около того.  Вместо этого, оставьте задачу переноса строк клиенту Gemini на принимающей стороне, чтобы он подогнал содержимое под ширину экрана и предпочтения пользователя.  Таким образом, контент Gemtext выглядит красиво и удобочитаемо на мониторах компьютеров, экранах ноутбуков, планшетов и смартфонов.
+
+Учтите, что хотя клиенты Gemini переносят строки текста, которые не помещаются в экран пользователя, они не объединяют короткие строки вместе, как происходит в Markdown, HTML или LaTeX.  Это значит, что, к примеру, списки или стихи с намеренно короткими строками будут отображаться правильно без необходимости для автора делать дополнительную работу или для клиента быть умнее, чтобы распознавать и обрабатывать такой вид содержимого корректно.
+
+Для большинства "повседневного" письма такой подход будет означать, что вам нужно писать каждый параграф отдельной строкой.
+
+Учтите, что пустые строки выводятся точь-в-точь, то есть если вы вставляете две или три пустых строки между параграфами, читатель увидит две или три пустых строки.
+
+## Ссылки
+
+Как Gopher (и в отличие от Markdown и HTML), Gemtext позволяет размещать ссылки на другие документы только на отдельной строке.  Вы не сможете сделать ссылкой одно слово посреди предложения.  К этому надо привыкнуть, но зато ссылки крайне легко найти, а клиенты могут по-разному их стилизовать (например, дать ясно понять, какой протокол они используют, или отображать доменное имя, чтобы помочь пользователям решить, хотят ли они переходить по ним или нет), не испортив при этом удобочитаемость вашего текста.
+
+Строки ссылок выглядят так:
+
+```
+=> https://example.com    Крутой вебсайт
+=> gopher://example.com   Ещё более крутой gopher-сайт
+=> gemini://example.com   Невероятно крутая капсула Gemini
+=> sftp://example.com
+```
+
+А именно:
+
+* Они начинаются с двух символов =>,
+* после которых идут один либо несколько пробелов или табуляций,
+* после которых идёт URL (имеющий любой протокол).
+* Они могут заканчиваться прямо здесь, если вы так хотите, как с примером sftp выше!
+* Или после может быть хотя бы один пробел или табуляция,
+* А потом понятная человеку подпись, которая может быть любой длины
+
+В примере выше все URL и подписи к ним выровнены, потому что автор был педантичным.  Но Gemini всё равно, и так тоже можно:
+
+```
+=>https://example.com Крутой вебсайт
+=>gopher://example.com      Ещё более крутой gopher-сайт
+=> gemini://example.com Невероятно крутая капсула Gemini
+=>   sftp://example.com
+```
+
+## Заголовки
+
+Gemtext поддерживает три уровня заголовков.  Заголовки ограничены одной строкой и начинаются с одного, двух или трёх символов #, после которых обязательно следует один пробел:
+
+```
+# Заголовок
+
+## Подзаголовок
+
+### Подподзаголовок
+```
+
+Это единственный поддерживаемый синтаксис заголовков.  Подчёркивания заголовков символами - и = в стиле Markdown не имеют никакого эффекта.
+
+Для клиентов придавать какое-либо специальное значение заголовкам строго опционально.  Многие клиенты будут распознавать их и использовать крупный шрифт, или другой цвет, или ещё какой-нибудь особый стиль, но некоторые не будут и просто воспримут и выведут их как обычные строки текста.  Это нормально, потому что заголовки предназначены не для того, чтобы контролировать внешний вид содержимого, а чтобы предоставлять важную семантическую информацию о структуре содержимого.  Некоторые клиенты будут использовать заголовки, чтобы автоматически генерировать оглавление, которое может пригодиться пользователю для навигации по большим документам.  Программы для генерации лент Atom и RSS могут использовать заголовки, чтобы автоматически определять наименования постов гемлога.
+
+## Списки
+
+Gemtext поддерживает маркированные списки.  Каждый элемент в списке пишется как одна длинная линия, которая начинается с одного символа *, за которым обязательно следует один пробел:
+
+```
+* Меркурий
+* Джемини
+* Аполлон
+```
+
+Это единственный поддерживаемый синтаксис списков.  Использование - вместо * в стиле Markdown не имеет никакого эффекта.  Вложенные списки не поддерживаются.
+
+Для клиентов делать что-либо особое с элементами списков строго опционально, и некоторые клиенты будут воспринимать их как любую другую строку текста.  Единственная причина, по которой они определены, заключается в том, что более функциональные клиенты могут заменить символ * на более красивый маркер, а когда элементы списка слишком длинные, чтобы уместиться в ширину экрана, и разбиваются на несколько строк, вторая и последующие строки могут смещаться от края на то же расстояние, что занимает символ маркера.  Это просто типографическая утончённость.
+
+## Цитаты
+
+Gemtext поддерживает цитаты.  Цитированное содержимое пишется одной длинной строкой, которая начинается с одного символа >:
+
+```
+> Gemtext поддерживает цитаты.  Цитированное содержимое пишется одной длинной строкой, которая начинается с одного символа >
+```
+
+Для клиентов делать что-либо особое с цитатами строго опционально, и некоторые клиенты будут воспринимать их как любую другую строку текста.  Как и в случае со списками, они определены исключительно для того, чтобы позволить более претенциозным клиентам отрисовывать более красивую типографию.
+
+## Преформатированный текст
+
+Gemtext тщательно спроектирован быть очень-очень простым для парсинга и рендеринга.  Клиенты Gemini обрабатывают Gemtext по одной строке за раз, выводя каждую строку независимо от любых строк до и после неё, просто смотря на первые несколько символов строки, чтобы найти там что-то вроде =>, # , * , и т.д.
+
+Строка, начинающаяся с ``` (то есть с трёх обратных апострофов), говорит клиенту переключиться между его обычным режимом парсинга и "преформатированным режимом". В режиме преформатированного текста клиенты не проверяют, является ли строка ссылкой, или заголовком, или чем-либо ещё.  Она просто выводится как есть.  Также, в то время как клиенты могут использовать разные шрифты для всего другого обычного текста, в преформатированном режиме клиенты должны использовать моноширинный шрифт.  Таким образом, пара строк ``` служит для того же, что и теги 
 и 
 в HTML.
+
+Преформатированный текст можно использовать, чтобы включать в документ Gemtext ASCII-арт, исходный код или подобное содержимое, а клиенты не будут по ошибке воспринимать строки как заголовки, элементы списка и так далее.  Также его можно использовать, чтобы писать документы как этот, где объясняется синтаксис Gemtext с примерами - вы можете видеть примеры синтаксиса выше, потому что ваш клиент не интерпретирует их как он делает в норме, ведь они отрисованы в режиме преформатированного текста.
+
+Всё, что идёт после символов ``` на строке, которая *включает* режим преформатированного текста (то есть первая, третья, пятая и т.д. такая строка в документе), может быть распознано как "альтернативный текст" для преформатированного содержимого.  В общем случае, вы не должны рассчитывать на то, что его увидит пользователь, но, к примеру, поисковые движки могут его индексировать, а программы для чтения с экрана могут озвучить это пользователям, чтобы помочь им решить, нужно ли читать преформатированный текст вслух (чего, например, с ASCII-артом происходить не должно, а с исходным кодом должно).  Пока нет общепринятого соглашения насчёт того, как должен быть отформатирован альтернативный текст.
diff --git a/docs/ru/index.gmi b/docs/ru/index.gmi
new file mode 100644
index 0000000000000000000000000000000000000000..3305171c24243f2501078c7e29fce0ce5d28e6dc
--- /dev/null
+++ b/docs/ru/index.gmi
@@ -0,0 +1,7 @@
+# Документация протокола Gemini
+
+## Ресурсы для начинающих
+
+=> gemtext.gmi		Быстрое введение в язык разметки "gemtext"
+=> cheatsheet.gmi	Шпаргалка по Gemtext
+=> tls-tutorial.gmi	Краткое, Gemini-центричное руководство по TLS-сертификатам
diff --git a/docs/ru/tls-tutorial.gmi b/docs/ru/tls-tutorial.gmi
new file mode 100644
index 0000000000000000000000000000000000000000..b766684205cb2d403e5d94830359ecb8b4d2a807
--- /dev/null
+++ b/docs/ru/tls-tutorial.gmi
@@ -0,0 +1,77 @@
+# TLS, клиентские сертификаты, TOFU и всё такое
+
+Этот документ находится в процессе создания!
+
+## Введение
+
+Gemini делает обязательным защиту соединения с помощью TLS.  Кроме того, он поддерживает использование клиентских сертификатов и альтернативных схем подтверждения подлинности сертификатов, что для многих людей непривычно.  Для множества потенциальных разработчиков и разработчиц Gemini это самая сложная часть из всех.  Этот документ нацелен предоставить краткое введение в значимые концепции.  Он не слишком детальный или точный: целью является позволить людям понять и осмыслить то, как эта штука работает на уровне абстракции поверх всех криптографических подробностей.
+
+Но это не разбор полностью "с нуля".  Этот документ предполагает, что вы знакомы с некоторыми базовыми концептами асимметричной (использующей "публичные ключи") криптотграфии; не с математическими формулами и тем, как и почему всё это работает, а с абстракцией, общей картиной происходящего.  В сущности, вы должны уверенно себя чувствовать с идеями:
+
+* Пар ключей, то есть соответствующих друг другу публичного и приватного ключей, которые имеют такое свойство: то, что зашифровано первым, может быть расшифровано только вторым
+* Цифровых подписей, то есть того, что люди используют свой приватный ключ, чтобы "подписывать" некоторое цифровое содержимое таким способом, что остальные могут проверить его на подлинность, используя их публичный ключ; что эти подписи не могут быть подделаны и что они защищают подписанное содержимое от модификации
+
+## Основы сертификатов
+
+### Что такое сертификат TLS?
+
+Для наших целей, вы можете думать о TLS-сертификате как о комбинации следующих вещей:
+
+* Публичный ключ
+* Некоторые метаданные о стороне, которая утверждает, что владеет этим публичным ключом - так называемый "субъект" сертификата
+* Цифровая подпись всего сертификата
+* Некоторые метаданные о стороне, которая подписала сертификат - так называемый "эмитент" сертификата
+* Период действия
+
+Метаданные о субъекте и эмитенте имеют одинаковую структуру.  Сертификат содержит "Distinguished Name" (DN) субъекта и эмитента.  DN имеет несколько полей, но самое важное из них - так называемое "Common Name" (CN).  Оно не обязано являться, но в типичном реальном сценарии использования почти всегда является именем узла, например `paypal.com`.
+
+В сертификате может быть, и на практике так оно и есть, больше того, чем упомянуто, но это основные особенности, которые нужны вам для того, чтобы понимать остальной текст этой статьи.  Большую часть времени вы можете забыть о периоде действия и думать о сертификате просто как о публичном ключе, наименовании того, кто утверждает, что владеет им, и наименовании и подписи того, кто заверяет подлинность этого утверждения.
+
+### Каков типичный сценарий использования TLS-сертификата?
+
+Предположим, что вы легитимный оператор сервера `example.com`. "Нормальный" способ использовать TLS - это связаться с надёжной третьей стороной, называемой "Certificate Authority" (CA), и сказать "Привет, CA, мой DN - бла-бла-бла, и в частности мой CN - example.com.  Этот набор байтов вот здесь - мой собственный публичный ключ". CA "делает что-то", чтобы убедиться, что это действительно вы, легитимный оператор example.com, и затем они используют свой приватный ключ, чтобы подписать сертификат, в которым указан ваш DN (как субъекта), их собственный DN (как эмитента), плюс период действия.  Затем вы настраиваете вебсервер, почтовый сервер или ещё что-нибудь, чтобы раздавать этот сертификат, когда клиенты делают TLS-запросы к серверу.
+
+На стороне клиента веб-браузеры и/или операционная система обычно поставляется с огромной кучей публичных ключей для распознавания предустановленных CA.  Когда клиенты подключаются к вашему вебсерверу и получают ваш сертификат, они могут использовать DN вашего CA, чтобы найти публичный ключ в своей куче, а затем проверить на подлинность цифровую подпись вашего сертификата.  Если подпись подлинна, это говорит им о том, что действительно конкретный добропорядочный CA сделал что-то, чтобы убедиться, что публичный ключ в этом сертификате действительно принадлежит example.com.  Так как клиенты доверяют CA, они принимают за истину, что этот публичный ключ подлинный и (предполагая, что период действия не истёк) всё хорошо: клиент и сервер используют удостоверенный публичный ключ, чтобы создать защищённый канал через замысловатый процесс, который на самом деле делает с сертификатом кое-что ещё.
+
+### Почему всё это необходимо?
+
+Предположим, что когда клиент устанавливает соединение с example.com, сервер отправляет по линии только публичный ключ вместо сертификата.  Клиент всё ещё может использовать этот ключ, чтобы шифровать информацию, которую он отправляет на сервер, и эта информация будет защищена от посторонних глаз.  Но есть риск того, что будет некто, кто может не просто прослушивать соединение, но и вмешиваться более активными способами - например, это может быть провайдер клиента либо сервера или кто-то, сумевший обмануть DNS-провайдера пользователя разрешать имя example.com в их собственный сервер - они могут действовать как так называемый "человек посередине" или "Man in the Middle" (MitM).  Когда клиент пытается установить соединение с сервером, атакующие отправляют клиенту *их собственный* публичный ключ вместо ключа сервера.  В то же самое время они подключаются к запрошенному серверу, получая настоящий публичный ключ.  Атакующие используют их собственный приватный ключ, чтобы расшифровать данные, полученные от клиента, а затем снова зашифровывают их публичным ключом сервера перед отправкой данных на сервер - и наоборот в противоположном направлении.  Клиент и сервер всё ещё могут общаться друг с другом, и всё кажется работающим, но атакующие могут прослушивать соединение даже несмотря на то, что клиент и сервер всё зашифровали.
+
+Чтобы предотвратить это, клиент должен знать, что какой бы публичный ключ он ни получил по линии, он действительно принадлежит example.com, а не каким-нибудь злоумышленникам, которые перехватили соединение и подменили ключ на свой.  Будьте уверены, это очень сложная проблема.  Существует множество возможных решений, все со своими плюсами и минусами.  Мейнстримное решение в сегодняшнем интернете - использовать сертификаты, подписанные CA.  Оно по сути делегирует эту трудную задачу установления того, кто взаправду каким ключом владеет, небольшому (относительно числу компьютеров в интернете) количеству доверенных лиц (CA), от которых ожидается хорошо выполнять свою работу.
+
+Так, если вы отдалитесь от технических подробностей того, что находится *внутри* TLS-сертификата и что делают с ними компьютеры, а вместо этого подумаете о *роли*, которую они играют, TLS-сертификаты - это способ для одной стороны (эмитент) поручиться за действительность утверждения другой стороны (заявление субъекта "этот ключ мой") таким образом, который убедит каждого, кто имеет уже существующие доверительные отношения с эмитентом (имея публичный ключ эмитента и, следовательно, имея возможность проверить его цифровую подпись).
+
+### Хорошо, то есть с системой CA проблема MitM решена?
+
+Ну, и да и нет.
+
+Некоторые люди не очень довольны уровнем безопасности, предоставляемым системой CA.  Если только не нагромоздить дополнительных штук поверх простой процедуры подтверждения, обрисованной выше, *любой* CA, чей публичный ключ предустановлен в вашем браузере или операционной системе, может подписать сертификат для *любого* узла, и ваша система с радостью примет его.  Это может быть список из буквально сотен CA, принадлежащим компаниям или государствам по всему миру, которые могут в действительности иметь сильно расходящиеся уровни доверия (в реальности, вы не слышали и не взаимодействовали ранее с большинством из них). Если ваша система будет принимать сертификаты с любого из них, вся система настолько же защищена, как и самый уязвимый CA: тот CA, который наименее тщательно проверяет утверждения о владении публичным ключом, или же CA с наихудшей интернет-безопасностью, чьи приватные ключи оказываются украдены, или же CA с наиболее подкупными сотрудниками, или же CA, чьё правительство имеет наибольшую правовую силу вынудить их подписать поддельный сертификат под угрозой тюремного заключения или ещё чего похуже.  Самый уязвимый CA может быть действительно таким слабым, и если обнаружится, что некоторый CA "вышел из-под контроля", уйдёт много работы и займёт много времени удалить его публичный ключ из каждого устройства, на котором он был установлен.
+
+Некоторые люди не так озабочены уровнем безопасности, предоставляемым системой CA, а вместо этого недовольны по политическим или философским причинам тем, что целая система основана в первую очередь на относительно небольшом количестве частных коммерческих корпораций, обслуживающих дорогую централизованную инфраструктуру и берущих с конечных пользователей деньги (иногда много денег) за сертификаты.
+
+### Что такое самовыданный и самоподписанный сертификат?
+
+Сертификат называется "самовыданным", когда субъект и эмитент - одно и то же лицо, а "самоподписанным" - если он подписан приватным ключом, соответствующим содержащемуся в нём публичному ключу.  Сертификат может быть самовыданным и при этом не самоподписанным, и наоборот, но в самом распространённом случае (в том самом, который большинство людей имеют в виду, когда говорят о "самоподписанных сертификатах") сертификат имеет оба эти свойства.
+
+Самоподписанные сертификаты несовместимы с типичным использованием сертификатов: они не функционируют таким образом, который позволял бы заверить владение публичным ключом, потому что отсутствует третья сторона, такая как CA, которой клиент уже доверяет и которой сервер доказал свою подлинность.  Любой может создать самоподписанный сертификат с таким CN, который душе угодно.  Если вы используете самоподписанный сертификат для своего сервера, клиент не в состоянии отличить его от подделанного злоумышленником для MitM-атаки - как минимум не просто просмотрев сертификат и проверив подпись.  В этом причина того, что самоподписанные сертификаты обычно признаются небезопасными.
+
+Это немаленькая проблема, но важно понимать, что разница между самоподписанным сертификатом и тем, что был подписан CA, только в возможности установить, лишь изучив сертификат, что содержащийся в нём публичный ключ принадлежит содержащемуся в нём имени узла.  Содержащийся публичный ключ сам по себе не отличается и ничем не хуже публичного ключа в подписанном CA сертификате, и не будет никакой разницы в силе криптографического шифрования, полученного при использовании этого ключа.  Это значит, что в ситуациях где:
+
+* вы можете установить, что ключ взаправду принадлежит имени узла каким-то иным способом, или
+* проверять, кто владеет ключом, на самом деле не нужно
+
+самоподписанные сертификаты абсолютно нормально использовать.
+
+Вы можете спросить: в чём ценность использования самоподписанных сертификатов вместо использования одних лишь публичных ключей?  Ответ: фактически никакая, и существует множество безопасных протоколов, которые используют публичные ключи без сертификатов.  Но TLS построен полностью вокруг концепта подписанных CA сертификатов и не предоставляет способа использовать публичные ключи отдельно.  Вы можете думать о самоподписанных сертификатах как о "хаке", чтобы обойти эту систему: они позволяют использовать уже существующий стек технологий TLS, но отказаться от системы CA.
+
+## Клиентские сертификаты
+
+Скоро появится.
+
+## TOFU
+
+Скоро появится.
+
+## Практические вопросы
+
+Скоро появится.

-----END OF PAGE-----