Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

COSE Encryption Functionality (with HPKE-based key distribution) #46

Closed
wants to merge 3 commits into from
Closed

COSE Encryption Functionality (with HPKE-based key distribution) #46

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
aac45fd
Initial version of the COSE encryption functionality
Feb 23, 2022
2a513b8
Fix whitespace errors
tamasban Apr 8, 2022
c78ca24
Utilizing crypto adaptation layer.
tamasban Apr 8, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion CMakeLists.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ add_definitions(${thirdparty_def})

if(MBEDTLS)

set(T_COSE_SOURCE crypto_adapters/t_cose_psa_crypto.c src/t_cose_sign1_sign.c src/t_cose_parameters.c src/t_cose_sign1_verify.c src/t_cose_util.c)
set(T_COSE_SOURCE crypto_adapters/t_cose_psa_crypto.c src/t_cose_sign1_sign.c src/t_cose_parameters.c src/t_cose_sign1_verify.c src/t_cose_util.c src/t_cose_encrypt_enc.c src/t_cose_encrypt_dec.c)
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is getting long enough that it might make sense to break this into multiple lines.


add_definitions(-DT_COSE_USE_PSA_CRYPTO=1)

Expand Down
20 changes: 13 additions & 7 deletions Makefile.psa
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@
#
# Copyright (c) 2019-2021, Laurence Lundblade. All rights reserved.
# Copyright (c) 2020, Michael Eckel, Fraunhofer SIT.
# Copyright (c) 2022, Arm Limited. All rights reserved.
#
# SPDX-License-Identifier: BSD-3-Clause
#
Expand Down Expand Up @@ -64,11 +65,11 @@ INC=-I inc -I test -I src
ALL_INC=$(INC) $(CRYPTO_INC) $(QCBOR_INC)
CFLAGS=$(CMD_LINE) $(ALL_INC) $(C_OPTS) $(TEST_CONFIG_OPTS) $(CRYPTO_CONFIG_OPTS)

SRC_OBJ=src/t_cose_sign1_verify.o src/t_cose_sign1_sign.o src/t_cose_util.o src/t_cose_parameters.o
SRC_OBJ=src/t_cose_sign1_verify.o src/t_cose_encrypt_enc.o src/t_cose_encrypt_dec.o src/t_cose_sign1_sign.o src/t_cose_util.o src/t_cose_parameters.o

.PHONY: all install install_headers install_so uninstall clean

all: libt_cose.a t_cose_test t_cose_basic_example_psa
all: libt_cose.a t_cose_test t_cose_basic_example_psa t_cose_encryption_example_psa

libt_cose.a: $(SRC_OBJ) $(CRYPTO_OBJ)
ar -r $@ $^
Expand All @@ -86,6 +87,8 @@ t_cose_test: main.o $(TEST_OBJ) libt_cose.a
t_cose_basic_example_psa: examples/t_cose_basic_example_psa.o libt_cose.a
cc -o $@ $^ $(QCBOR_LIB) $(CRYPTO_LIB)

t_cose_encryption_example_psa: examples/t_cose_encryption_example_psa.o libt_cose.a
cc -o $@ $^ $(QCBOR_LIB) $(CRYPTO_LIB)

# ---- Installation ----
ifeq ($(PREFIX),)
Expand All @@ -102,6 +105,8 @@ install_headers: $(PUBLIC_INTERFACE)
install -m 644 inc/t_cose/q_useful_buf.h $(DESTDIR)$(PREFIX)/include/t_cose
install -m 644 inc/t_cose/t_cose_sign1_sign.h $(DESTDIR)$(PREFIX)/include/t_cose
install -m 644 inc/t_cose/t_cose_sign1_verify.h $(DESTDIR)$(PREFIX)/include/t_cose
install -m 644 inc/t_cose/t_cose_encrypt_enc.h $(DESTDIR)$(PREFIX)/include/t_cose
install -m 644 inc/t_cose/t_cose_encrypt_dec.h $(DESTDIR)$(PREFIX)/include/t_cose

# The shared library is not installed by default because of platform variability.
install_so: libt_cose.so install_headers
Expand All @@ -116,18 +121,18 @@ uninstall: libt_cose.a $(PUBLIC_INTERFACE)
libt_cose.a libt_cose.so libt_cose.so.1 libt_cose.so.1.0.0)

clean:
rm -f $(SRC_OBJ) $(TEST_OBJ) $(CRYPTO_OBJ) t_cose_basic_example_psa t_cose_test libt_cose.a libt_cose.so examples/*.o main.o

rm -f $(SRC_OBJ) $(TEST_OBJ) $(CRYPTO_OBJ) t_cose_encryption_example_psa t_cose_basic_example_psa t_cose_test libt_cose.a libt_cose.so examples/*.o main.o

# ---- public headers -----
PUBLIC_INTERFACE=inc/t_cose/t_cose_common.h inc/t_cose/t_cose_sign1_sign.h inc/t_cose/t_cose_sign1_verify.h
PUBLIC_INTERFACE=inc/t_cose/t_cose_common.h inc/t_cose/t_cose_sign1_sign.h inc/t_cose/t_cose_sign1_verify.h inc/t_cose/t_cose_encrypt_enc.h inc/t_cose/t_cose_encrypt_dec.h

# ---- source dependecies -----
src/t_cose_util.o: src/t_cose_util.h src/t_cose_standard_constants.h inc/t_cose/t_cose_common.h src/t_cose_crypto.h
src/t_cose_sign1_verify.o: inc/t_cose/t_cose_sign1_verify.h src/t_cose_crypto.h src/t_cose_util.h src/t_cose_parameters.h inc/t_cose/t_cose_common.h src/t_cose_standard_constants.h
src/t_cose_parameters.o: src/t_cose_parameters.h src/t_cose_standard_constants.h inc/t_cose/t_cose_sign1_verify.h inc/t_cose/t_cose_common.h
src/t_cose_sign1_sign.o: inc/t_cose/t_cose_sign1_sign.h src/t_cose_standard_constants.h src/t_cose_crypto.h src/t_cose_util.h inc/t_cose/t_cose_common.h

src/t_cose_sign1_sign.o: inc/t_cose/t_cose_sign1_sign.h src/t_cose_standard_constants.h src/t_cose_crypto.h src/t_cose_util.h inc/t_cose/t_cose_common.h
src/t_cose_encrypt_enc.o: inc/t_cose/t_cose_encrypt_enc.h src/t_cose_standard_constants.h src/t_cose_crypto.h src/t_cose_util.h inc/t_cose/t_cose_common.h
src/t_cose_encrypt_dec.o: inc/t_cose/t_cose_encrypt_dec.h src/t_cose_standard_constants.h src/t_cose_crypto.h src/t_cose_util.h inc/t_cose/t_cose_common.h

# ---- test dependencies -----
test/t_cose_test.o: test/t_cose_test.h test/t_cose_make_test_messages.h src/t_cose_crypto.h $(PUBLIC_INTERFACE)
Expand All @@ -141,3 +146,4 @@ crypto_adapters/t_cose_psa_crypto.o: src/t_cose_crypto.h inc/t_cose/t_cose_commo

# ---- example dependencies ----
examples/t_cose_basic_example_psa.o: $(PUBLIC_INTERFACE)
examples/t_cose_encryption_example_psa.o: $(PUBLIC_INTERFACE)
92 changes: 60 additions & 32 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,22 @@
# t_cose

t_cose implements COSE_Sign1 of [COSE, RFC 8152]
(https://tools.ietf.org/html/rfc8152).

# t_cose
- [CBOR Web Token,RFC 8392]
(https://tools.ietf.org/html/rfc8392)
- [Entity Attestation Token (EAT)]
(https://tools.ietf.org/html/draft-ietf-rats-eat-01).

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).
Furthermore, an initial implementation of COSE_Encrypt and
COSE_Encrypt0 is provided. For key distribution direct key distribution
and the Hybrid Public Key Encryption (HPKE)-based key agreement is
provided. Direct key distribution assumes that the Content Encryption
Key (CEK) is negotiated out-of-band. Key agreement with HPKE for use
with COSE is defined in
https://datatracker.ietf.org/doc/draft-ietf-cose-hpke/ while HPKE itself
is specified in https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hpke.
(Note: HPKE and COSE-HPKE are work in progress.)

## New Version Using Spiffy Decode
**A major new version of t_cose implemented with QCBOR's new**
Expand All @@ -22,37 +34,51 @@ See Memory Use section below for discussion on the new code size.

## 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. Except for
some minor configuration for the cryptographic library, no #ifdefs or
compiler options need to be set for it to run correctly.
**Implemented in C with minimal dependency** – There are three main
dependencies:

1) [QCBOR](https://github.com/laurencelundblade/QCBOR),

2) For signature generation and verification a cryptographic library
for ECDSA and SHA-2 is required. For encryption/decryption functionality
it is necessary to additionally support encryption algorithms, such as
AES-GCM, and [HPKE](https://github.com/hannestschofenig/mbedtls/tree/hpke)
if the HPKE-based key distribution mechanism is utilized. HPKE has its
own dependencies, such as the HKDF key derivation function.

3) C99, <stdint.h>, <stddef.h>, <stdbool.h> and <string.h>.

The cryptographic library is intended to be highly portable to different HW,
OS's and cryptographic libraries. Except for some minor configuration for
the cryptographic library, 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
the OpenSSL and ARM Mbed TLS (PSA Cryptography API) cryptographic libraries
are included.
**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 the OpenSSL and Arm
Mbed TLS (PSA Cryptography API) cryptographic libraries are included.

**Secure coding style** – Uses a construct called UsefulBuf / q_useful_buf as a
discipline for very safe coding and handling of binary data.
**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. Besides the
cryptographic library and payload buffer, about 600 bytes of heap/stack is needed
for signing and 1500 bytes for verifying. The caller supplies the output buffer
and context structures so the caller has control over memory usage making it
useful for embedded implementations that have to run in small fixed memory.
cryptographic library and payload buffer, about 600 bytes of heap/stack
is needed for signing and 1500 bytes for verifying. The caller supplies
the output buffer and context structures so the caller has control over
memory usage making it useful for embedded implementations that have to
run in small fixed memory.


## Code Status

As of December 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)
and for [Arm MBed Crypto](https://github.com/ARMmbed/mbed-crypto).
As of December 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) and for [Arm Mbed Crypto]
(https://github.com/ARMmbed/mbed-crypto).

This version requires a QCBOR library that supports Spiffy Decode.
This version requires a QCBOR library that supports Spiffy Decode.


## Building and Dependencies
Expand Down Expand Up @@ -276,10 +302,11 @@ enough.

### Mixed code style
QCBOR uses camelCase and t_cose follows
[Arm's coding guidelines](https://git.trustedfirmware.org/TF-M/trusted-firmware-m.git/tree/docs/contributing/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.
[Arm's coding guidelines]
(https://git.trustedfirmware.org/TF-M/trusted-firmware-m.git/tree/docs/contributing/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

Expand All @@ -301,8 +328,9 @@ just have different names.
## Credit

* Ken Takayama for the bulk of the detached content implementation.
* 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.
* 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.
* Michael Eckel for makefile fixes.

## Copyright and License
Expand Down
Loading