Пишем техническую документацию: руководство для непрофессионала

[namikiri]

Про сообщения об ошибках хочется всё же добавить. Если для веб-сервиса ещё хоть как-то допустима формулировка «у нас что-то сломалось, приходите завтра», то для приложений, работающих на устройствах пользователя, это, на мой взгляд, недопустимо. Яркий пример — приложение ВК для Android. Если оно не может загрузить или выгрузить фотографию, оно пишет «Ошибка, проверьте подключение к сети». Какая ошибка? Что за ней стоит? Нет доступа? Сервер не отвечает? Может, у меня в телефоне закончилась память для кэша? В чём причина ошибки? Возможно, это малозначительно и «напугает» большинство, но я умоляю, давайте пользователю знать, что именно пошло не так. Пусть даже для этого нужно будет сделать дополнительный клик по «Подробнее», только не кидайте меня на сайт с базой знаний. Мне было бы удобнее знать, что доступ к фотографии ограничен, или телефон не смог отрезолвить имя сервера, чем видеть тупое «Ошибка» без комментариев.

[CryptoPirate]

На всякий случай, есть небольшое исключение из правила «сообщение об ошибке должно объяснить что конкретно пошло не так». Это исключение для всяких правил безопасности и тесно связанных с безопасностью вещей. Небольшая разница в сообщениях об ошибке может послужить средством для проникновения в систему (или чтобы выудить из системы секретную информацию).
Пример: Если сообщение зашифровано и при этом используется аутентификация (скажем, MAC), то нужно и в слечае неправильной расшифровки (invalid padding), и в случае неправильного MAC вернуть одинаковое сообщение об ошибке. В противном слечае может получится что-то типа «Bleichenbacher’s attack».

[UnclShura]

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

Нет (я даже повторю: нет!) причин не показывать абсолютно всю информацию об ошибке. Да хоть регистры показываете. Это никак не должно влиять на безопасность приложения. Если влияет — приложение или middleware — говно.

[CryptoPirate]

«А вот да!» Попробую ещё раз обяснить. Если вы напишете библиотеку для шифрования, а потом ей будуте пользоваться и пользователям присылать разные сообщения в случае если дополнение (padding) не правильное и в случае если контрольная сумма не правильная (та, которая MAC)… то тогда я с радостью вытащу из вашего сервера всю необходимую мне информацию с помощью одной очень простой разновидности «Bleichenbacher’s attack». Если быть более точным: я смогу «заставить» ваш сервер расшифровать сообщения которыми он с другими пользователями обменивается.
При этом, сам протокол и все алгоритмы в полном порядке, атака использует разницу в ошибках (кодах), которые сервер возвращает на «неправиьное» сообщение.

[UnclShura]

Ну хорошо частично могу согласиться. Но с «Bleichenbacher’s attack» никто-же не обязывает вообще считать ошибкой несовпадение MAC равно как и его наличие. В данном случае это скорее требование алгоритма — не раскрывать факт правильной расшифровки. И кстати алгоритм не в порядке, если допускает такого рода атаку. Речь не о RSA, а об алгоритме авторизации или выработки сессионного ключа.

Я вообще-то говорил про стеки вызовов, версии софта и тому подобное, что пытаются от пользователя скрыть. Сидишь теперь и втыкаешь на «Oops».

[telobezumnoe]

это им наших ГОСТов не хватает, и нормоконтроля)) сразу бы не возникало вопросов как и что написать

[aleksandr-s-zelenin]

Отличная статья, спасибо!

P. S. Хабр со временем растерял часть изображений, вот тут есть копия статьи, но с картинками: https://www.pvsm.ru/dokumentatsiya/290673