diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 074bdccac..98f8bb6cc 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -8,6 +8,9 @@ - [Emulator](core/emulator/index.md) - [Apps](core/src/apps.md) - [Tests](core/tests/index.md) + - [Miscellaneous](core/misc/index.md) + - [SLIP-39](core/misc/slip0039.md) + - [Exceptions usage](core/misc/exceptions.md) - [Legacy](legacy/index.md) - [Python](python/index.md) - [trezorlib](python/trezorlib.md) diff --git a/docs/core/misc/exceptions.md b/docs/core/misc/exceptions.md new file mode 100644 index 000000000..fee69090d --- /dev/null +++ b/docs/core/misc/exceptions.md @@ -0,0 +1,36 @@ +# Exceptions in Core + +From version 2.3.0 we try to follow few rules about how we use exceptions. All new +code MUST follow these. + +## Usage + +You MAY use any exceptions in Core's logic. Exceptions from `wire.errors` SHOULD be +the final exceptions that are thrown and SHOULD NOT be caught. Note that `wire.Error` +is a type of exception that is intended to be sent out over the wire. It should only +be used in contexts where that behavior is appropriate. + +Custom exception type hierarchies SHOULD always be derived directly from Exception. +They SHOULD NOT be derived from other built-in exceptions (such as ValueError, +TypeError, etc.) + +Deriving a custom exception type signals an intention to catch and handle it +somewhere in the code. For this reason, custom exception types SHOULD NOT be derived +from wire.Error and subclasses. + +Exception strings, including in internal exceptions, SHOULD only be used in cases +where the text is intended to be shown on the host. Exception strings MUST NOT +contain any sensitive information. An explanation of an internal exception MAY be +placed as a comment on the raise statement, to aid debugging. If an exception is +thrown with no arguments, the exception class SHOULD be thrown instead of a new +object, i.e., `raise CustomError` instead of `raise CustomError()`. + +## Tl;dr + +- Do not use `wire.errors` for `try-catch` statements, use other exceptions. +- Use `wire.errors` solely as a way to communicate errors to the Host, do not include +them somewhere deep in the stack. +- Do not put sensitive information in exception's message. If you are not sure, do not +add any message and provide a comment next to the `raise` statement. +- Use `raise CustomError` instead of `raise CustomError()` if you are omitting the +exception message. diff --git a/docs/core/misc/index.md b/docs/core/misc/index.md index 4576fedb7..aa505ad1f 100644 --- a/docs/core/misc/index.md +++ b/docs/core/misc/index.md @@ -1 +1,6 @@ # Miscellaneous + +Topics that do not fit elsewhere: + +- [SLIP-39 in Core](core/misc/slip0039.md) +- [Exceptions usage](core/misc/exceptions.md) diff --git a/docs/index.md b/docs/index.md index acc751009..60f62b5df 100644 --- a/docs/index.md +++ b/docs/index.md @@ -30,3 +30,8 @@ Also please have a look at the docs, either in the `docs` folder or at [docs.tr ## Security vulnerability disclosure Please report suspected security vulnerabilities in private to [security@satoshilabs.com](mailto:security@satoshilabs.com), also see [the disclosure section on the Trezor.io website](https://trezor.io/security/). Please do NOT create publicly viewable issues for suspected security vulnerabilities. + +## Note on terminology + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", +"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119).