aboutsummaryrefslogtreecommitdiff
path: root/lib/ext/t_cose/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'lib/ext/t_cose/README.md')
-rw-r--r--lib/ext/t_cose/README.md138
1 files changed, 138 insertions, 0 deletions
diff --git a/lib/ext/t_cose/README.md b/lib/ext/t_cose/README.md
new file mode 100644
index 0000000000..57d9f71271
--- /dev/null
+++ b/lib/ext/t_cose/README.md
@@ -0,0 +1,138 @@
+
+
+# t_cose
+
+t_cose implements enough of COSE to support [CBOR Web Token, RFC 8392](https://tools.ietf.org/html/rfc8392)
+and [Entity Attestation Token (EAT)](https://tools.ietf.org/html/draft-ietf-rats-eat-01).
+This is the COSE_Sign1 part of [COSE, RFC 8152](https://tools.ietf.org/html/rfc8152).
+
+## Characteristics
+
+**Implemented in C with minimal dependency** – There are three main
+dependencies: 1) [QCBOR](https://github.com/laurencelundblade/QCBOR), 2) A
+cryptographic library for ECDSA and SHA-2, 3) C99, <stdint.h>, <stddef.h>,
+<stdbool.h> and <string.h>. It is intended to be highly portable to different HW, OS's and
+cryptographic libraries. No #ifdefs or compiler options need to be set for it to run correctly.
+
+**Crypto Library Integration Layer** – t_cose can work with different cryptographic
+libraries via a simple integration layer. The integration layer is kept small and simple,
+just enough for the use cases, so that integration is simpler. An integration layer for
+Openssl is included (not complete yet).
+
+**Secure coding style** – Uses a construct called UsefulBuf / q_useful_buf as a
+discipline for very safe coding and handling of binary data.
+
+**Small simple memory model** – Malloc is not needed. The signing
+context is less than 100 bytes. Stack use is light and
+there is no recursion. The caller supplies the memory to hold the
+completed COSE_Sign1 and encode/decode contexts so caller has full control
+of memory usage making it good for embedded implementations that
+have to run in small fixed memory.
+
+## Code Status
+
+As of October 2019, the code is in reasonable working order and the public interface is
+fairly stable. There is a crypto adaptaion layer for [OpenSSL](https://www.openssl.org).
+
+### The to-do list:
+* Add some more tests, particular test vectors from C_COSE or such
+* General documentation clean up, spelling checks and formatting.
+
+## Building and Dependencies
+
+There is a simple makefile.
+
+[QCBOR](https://github.com/laurencelundblade/QCBOR) is required
+
+### Crypto Library
+Some cryptographic library that supports ECDSA and at least SHA-256 is required.
+
+#### Test Crypto
+Out of the box, this compiles, links and runs with no additional crypto library, but only in
+a test mode. This allows for quickly geting started. This mode allows more than half the tests to run.
+It is however not good for real commercial use as it doesn't do real public key signing and
+verification.
+
+For this test mode a bundled SHA-256 hash implementation is used, the ECDSA signing
+is stubbed to do nothing and the test short-circuit signing is used.
+
+#### OpenSSL Crypto
+This OpenSSL integration supports SHA-256, SHA-384 and SHA-512 with ECDSA to support
+the COSE algorithms ES256, ES384 and ES512.
+
+To enable this:
+* #define T_COSE_USE_OPENSSL_CRYPTO
+* Make with crypto_adapters/t_cose_openssl_crypto.c
+* Define the include path to OpenSSL headers in your build environment
+* Link with the OpenSSL libary
+
+#### PSA Crypto
+
+
+
+## Memory Usage
+
+### Code
+
+These are approximate numbers for 64-bit x86 code optimized for size
+
+* Common to signing and verifying: 515
+* Signing: 920 (742)
+* Verify: 1596
+* OpenSSL adaptor layer: 609
+* Total: 3710
+* Signing only total: 1813
+* Verify only total: 2509
+
+### Heap and stack
+Malloc is not used.
+
+Stack usage is less than 1KB for signing and for encryption.
+
+The design is such that only one copy of the COSE_Sign1 need be in memory. It makes
+use of special features in QCBOR to accomplish this.
+
+The payload to sign must be in one contiguous buffer and be passed in. It can be allocated
+however the caller wishes, even in ROM, since it is only read.
+
+A buffer to hold the signed COSE result must be passed in. It must be about 100 bytes
+larger than the combined size of the payload and key id for ECDSA 256. It can be
+allocated however the caller wishes.
+
+### Crypto library memory usage
+In addition to the above memory usage, the crypto library will use some stack and / or
+heap memory. This will vary quite a bit by crypto library. Some may use malloc. Some may
+not.
+
+So far no support for RSA is available, but since the keys and signatures are much bigger,
+it will up the memory usage a lot and may require use of malloc.
+
+The OpenSSL library does use malloc, even with ECDSA. Another implementation of ECDSA
+might not use malloc, as the keys are small enough.
+
+### Mixed code style
+QCBOR uses camelCase and t_cose follows
+[Arm's coding guidelines](https://git.trustedfirmware.org/trusted-firmware-m.git/tree/docs/coding_guide.rst)
+resulting in code with mixed styles. For better or worse, an Arm-style version of UsefulBuf
+is created and used and so there is a duplicate of UsefulBuf. The two are identical. They
+just have different names.
+
+## Limitations
+* The payload input and output and the signed structure input and output must be in
+contiguous memory.
+* Doesn't handle COSE string algorithm IDs. Only COSE integer algorithm IDs are handled.
+Thus far no string algorithm IDs have been assigned by IANA.
+* No way to add custom headers when creating signed messages or process them during
+verification.
+* Only ECDSA is supported so far (facilities are available to add others).
+* Does not handle CBOR indefinite length strings (indefinite length maps and arrays are handled).
+* Counter signatures are not supported.
+
+## Credit
+
+* Tamas Ban for lots code review comments, design ideas and porting to ARM PSA.
+* Rob Coombs, Shebu Varghese Kuriakose and other ARM folks for sponsorship.
+
+## Copyright and License
+
+t_cose is available under the 3-Clause BSD License.