RustCrypto / RustCrypto/AEADs

Lack of immediate access to GenericArray to view associated functions and trait impls leads to confusion and annoyance.

Open
#575 13 comments 2 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Rust
Stars
961
Forks
200
Avg merge
1h 30m
Merged PRs (30d)
6

Description

It's understandable that aes-gcm and aes-gcm-siv use generic_array's GenericArray's for the Nonce type. What's less understandable though is why this is left an opaque type and not either a wrapper with its own documentation of its methods custom to the uses of ges-gcm* or that GenericArray is not re-exported both for convenience as well as documentation. As a new user, I was really confused by the fact that I could not access the documentation for the underlying type to see what associated functions/methods it supports or even how to get one besides converting from a slice (as is demonstrated by the top-level crate documentation). Not everyone knows the generic_array crate and knows what GenericArray is and I had to look through the source to find the implementations of what I thought were a private type but turned out to be an import that is used on the front end by the user despite not only not being re-exported but there being no mention in the top-level crate documentation where this type comes from.

I would personally prefer turning Nonce into a newtype custom wrapper but I understand that this can be an issue due to the fact that it fundamentally introduces breaking changes.

The second best option is to simply re-export GenericArray. After all, aes-gcm-siv re-exports the entire aead crate just like aes-gcm which also re-exports aes in addition. I think this is by far the most uncontroversial option but the seemingly random re-export seems for some reason distasteful, I propose a third proposal:

This one is a compromise between the last two: create a new type called something like NonceWrapper that does exactly what I mentioned in the first proposal and then impl From for Nonce, unwrapping it. One could then have replace all instances of taking a Nonce type with impl Into. I can't see any breakage that would come of this but obviously it would still work even without the function refactors, just less convenient.

I would be willing to make a PR if and when a solution is agreed upon. I would love to hear others' thoughts.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reviewing how aes-gcm and aes-gcm-siv expose Nonce and how GenericArray is used, then read the issue discussion for an agreed API direction. Done means the maintainers choose and document one approach—re-exporting GenericArray, adding a wrapper, or another design—with compatibility and user-facing documentation addressed.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
cryptography
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.