doc: Add ExternalDependencies.md

[alistair23]

Pull Request Overview

This adds a document that describes some of the requirements of adding external crates.

Once this is accepted the idea is then to add an external crate with #3092

Testing Strategy

TODO or Help Wanted

Documentation Updated

• Updated the relevant files in /docs, or no updates are required.

Formatting

• Ran make prepush.

[hudson-ayers]

I added this as an agenda item for tomorrow's call

[hudson-ayers]

We ended up not having much time to discuss this on the call.

I made one comment on the call which I wanted to try to summarize here:

Having dependencies which use unsafe internally directly in capsules violates Tock's written threat model for capsules. I am of the opinion that even relatively high quality dependencies are more likely to have soundness bugs than Rust's core library -- especially once we are using a stable compiler -- and these are not equivalent cases. That said, I realize it is important that some capsules be able to call code (e.g. crypto code) that will be defined in external dependencies.

I proposed that all dependencies should be hidden in a top-level directory named external. This top-level directory would not itself be a crate (like boards/, for instance), but would hold a collection of crates, with each crate having a single external dependency. For the ghash example, there would be a ghash-tock crate in the external folder. This crate would implement a trait which should be defined in capsules. For the ghash example, this trait might look like:

trait Hash {
    fn update_padded(&self, &'static mut [u8]);
    fn finalize(&self); 
    // etc. 
}

and the ghash-tock crate would define a struct which would implement this trait using the external dependency. The capsule (e.g. aes_gcm) would be generic over this trait, and accept an instance of it when created. Accordingly, the board using the capsule would be responsible for passing a GhashTock struct into the aes_gcm capsule in main.rs. Thus it is the board author explicitly choosing to use the ghash-tock crate, a crate clearly marked as containing an external dependency, and doing this mapping itself.

The upsides of this approach:

1. capsules does not itself gain any external dependencies, and all dependencies on potentially unsafe crates are expressed directly from the board repo, as is currently the case.
2. This works well to express situations where a given interface might be implemented by a trusted, high quality software library or by an accelerator, since the trait could be implemented for either and used equivalently (with some potential problems dealing with async vs. sync interfaces...)
3. The way that code can interact with the dependency is very clearly defined in this external interface crate, as opposed to the alternative approach where auditing the use of the external dependency requires tracking down every place that ghash::x is called throughout all of capsules.
4. Boards not using the individual capsules which require external dependencies do not have to compile those dependencies. This is nice because of a problem with external dependencies directly in capsules: even boards that do not need the dependency at all will be forced to compile them. Compiling external crates with large dependency trees can be quite slow, and compiling external crates could lead to the execution of build.rs files or procedural macros that themselves represent potential security vulnerabilities.

---

I also realize that this approach has a size and ergonomics overhead relative to direct use of the dependency. It also may be difficult to incorporate certain dependencies behind traits (procedural macro support traits being one such example). If this turns out to be impractical, I am sympathetic to that. Regardless, I think we should try to find a solution that addresses my final point above. So if this trait-based separation approach is impractical, I think that we should still create a seperate crate or crates for capsules with dependencies, we could just call it external-capsules or something, and that way boards that do not want to compile dependencies are not forced to.

[alistair23]

So if this trait-based separation approach is impractical, I think that we should still create a seperate crate or crates for capsules with dependencies, we could just call it external-capsules or something, and that way boards that do not want to compile dependencies are not forced to.

I agree with your 4 advantages, and I like the idea of trying to isolate external dependencies as much as possible. I do worry that it will add a lot of overhead. In terms of possible code size, but mostly development time, re-writing another level of abstraction. The ghash is a simple case, but for more complex functionality I think this will balloon into a lot of code overhead.

I do like the external-capsules idea a lot though. We could basically just move this capsule into an external-capsules directory (not itself a crate) and then allow board authors to add that. That means we will still expose HILs, so the implementations can be easily swapped out with others if desired.

[bradjc]

I somehow missed Hudson's comment before doing this, but I did a pass updating the doc. My main changes:

1. I specified we only do external deps for crypto from https://github.com/RustCrypto.
2. I specified one approach Hudson mentioned, specifically that all dependencies are included from a specific crate.
3. I wrote down what we talked about before with board crates having more latitude to use external dependencies.

I'm not overly attached to item 2, but I do like the idea that it would be easily grep-able.

[bradjc]

Having dependencies which use unsafe internally directly in capsules violates Tock's written threat model for capsules.

Right, do we treat external dependencies like unaudited capsule code, or like highly managed code (like the kernel crate)? I think I end up on the side of like highly managed code. This is more consistent with the ethos that we should be very selective of our external dependencies, and really we are just adding a convenience layer versus creating a vendor-specific copy in the tock repo itself.

Thus it is the board author explicitly choosing to use the ghash-tock crate, a crate clearly marked as containing an external dependency, and doing this mapping itself.

In my view, this is how board-specific dependencies should (and would be forced to) work. For core dependencies like cryptographic libraries, I find it dissonant that we are including external crates to promote secure code, but then falling back to trusting board authors to do the right thing. I view the external dependency inclusion process as the audit that the dependency is ok, and we do not want board authors overriding that choice.

Now, I do understand the SE challenge of allowing SW or HW implementations. But I think that comes at a different layer, using HILs, and not with a new collection of capsule interfaces.

[hudson-ayers]

For crypto crates that will ultimately need to be used by the core kernel, this makes sense to me -- it is inevitable that those crates will need to be compiled by all boards unless we want to rely on some hacky conditional includes that will be a mess to maintain.

For external dependencies which are only needed by individual capsules, I think things look a little different -- we really don't want to force all boards to compile those external crates if they are not using those capsules, so I think any such capsules should exist in stand-alone crates rather than inside the capsules crate.

ghash is an interesting example because currently it is only needed in capsules, but my understanding is that the plan is to eventually use it as part of the kernel app verification workflow (is this correct, @phil-levis ?), which would require the kernel to depend on it anyway. So I don't know that we need to move Alistair's capsule into a standalone crate.

[bradjc]

What's the right place to put the separation? I worry that we could be including fine-grained slicing before it's clear we need to. Does anyone care if the first build takes a couple seconds longer? I agree that once it's minutes then that is a lot of overhead, but perhaps we cross that bridge when we get there.

We also could look at separating capsules in to multiple crates, which could address this issue as well. Or put all capsules-with-dependencies in their own crate.

[alistair23]

ghash isn't specifically for app signing. The idea with the ghash crate is that we can expose AES-GCM on all platforms that have any AES hardware. The goal here would be to support all AES block ciphers (GCM, CCM, CTR, CBC and ECB) on any platform that supports AES. That way we can rely on all implementations existing and expose them all to userspace and the kernel.

Basically CTR, CBC and ECB are commonly supported in hardware, and the other two can be built with software on top of the hardware.

In the longer run though, I think it would be worth supporting crypto operations (AES, RSA, ECC) on all platforms with software fallbacks. The goal there is to allow loading signed/encrypted applications on all Tock platforms. As a secure operating system, it seems very useful for Tock to be able to do that.

I do agree with Brad. It does seem like we are worrying about something that isn't a problem yet. In terms of crypto crates we only ever expect to include a handful. We can also do the external-capsules direction, but I feel like the crypto ones might end up being included all the time anyway

[phil-levis]

Yeah, ghash isn't needed for application credentials. However, public key signatures (RSA, ECDSA, DH, etc.) will need to use tested-and-true software implementations (existing crates).

[hudson-ayers]

I think that I am happy with the current text of the document, modulo my one comment

[hudson-ayers]

We talked about this on the core call last week, some people read the updated version of this for the first time. The conclusion was that if we are gonna do this, we should go ahead and restructure the capsules directory to not be a crate, and instead have a few crates contained within it. I opened #3346 to propose a division, and will implement whatever consensus is reached there

[hudson-ayers]

Update: we reached a consensus in #3346, but I have not had a chance to implement the division (it is mostly just a large mechanical refactor). If someone else has a chance to implement it before me please feel free.

[alistair23]

Ok! Now that #3346 is fixed and #3396 is merged we can get back to this.

Is the plan to have a extern crate that contains all of the capsules that have external dependencies? Or do we want a individual crate per external capsule?

[bradjc]

I updated the document with a first pass based on the call. @lschuermann please revise as needed.

[lschuermann]

Thanks @bradjc! I restructured those sections a little, to reflect the proposed policy around the various capsule-crates.

While our previous discussions really only focused on adding dependencies to the capsule-crates, they did not explicitly consider board-specific external dependencies. However, those seem even less controversial, given a board can simply choose to depend on a capsule-crate which has external dependencies.

Finally, I'd appreciate some input on my comment regarding core external dependencies. I recall that there was a lot of pushback against that, which is why we converged on the capsule-crate based approach in the first place. The document may look inconsistent as of now, given that it establishes a policy around core external dependencies (which judging from the discussions we might not even want right now, at least not without concrete motivating examples), but not a process for including these.

It should be noted that the motivating example for this PR (#3092) could be resolved by, for instance, a crypto capsule crate.

[lschuermann]

We may want to emphasize that, while we don't force external crates to be hidden behind traits to make them accessible to Tock, this approach may still be preferred for additional flexibility. If possible (for a specific dependency), this can be a low-effort way to promote code-reuse and a cohesive crate structure. If not, splitting it out into an external crate is a good escape hatch.

[lschuermann]

I added a paragraph about this to the board-specific external dependencies section.

[lschuermann]

I recall from our discussions that we did deliberately punt on deciding over "core external dependencies". We converged on the capsule-crates restructuring to allow for using external dependencies where (arguably) they'd be needed the most right now, and to avoid forcing all Tock boards to use an external dependency.

In those discussions, there was significant pushback against such "core" external dependencies, specifically ones in kernel/ and arch/. I didn't want to outright remove it from the document with my edit. Nonetheless, given the current use-cases of external dependencies, IIRC adding them to a capsules-crate was deemed sufficient for now.

To reflect that, I added that we simply do not have an established process for introducing core external dependencies yet. This might be weird, given the document does specify a policy around them.

[hudson-ayers]

Items from the call:

• We should clarify that this document only applies to things that will end up in the kernel binary
• Would be good to lighten the language about cargo in the intro
• Move the "specific approach motivation" down to the end of the doc, and possibly rename that section

[bradjc]

I updated based on Amit's comment of the discussion.

Is this ready to merge?

[hudson-ayers]

I think this is ready!

[hudson-ayers]

bors r+

[bors]

Build succeeded!

The publicly hosted instance of bors-ng is deprecated and will go away soon.

If you want to self-host your own instance, instructions are here.
For more help, visit the forum.

If you want to switch to GitHub's built-in merge queue, visit their help page.

• ci-build (macos-latest)
• ci-build (ubuntu-latest)
• ci-format (ubuntu-latest)
• ci-qemu
• ci-tests (macos-latest)
• ci-tests (ubuntu-latest)