Skip to content

use type definitions to represent different attestation encodings - #13

Merged
nickpell merged 5 commits into
mainfrom
nick/types
Dec 11, 2025
Merged

nickpell merged 5 commits into
mainfrom
nick/types

Conversation

@nickpell

@nickpell nickpell commented Dec 10, 2025 •

Copy link
Copy Markdown
Member

Summary

Add type definitions for COSE attestation data with encoding/decoding methods to improve type safety and provide a complete reference implementation for third parties.

  • Add AttestationCOSE, AttestationCOSEBase64, AttestationCOSEURLBase64, and AttestationCOSEGzip types
  • Implement encoding/decoding/compression methods on attestation types
  • Maintain compatibility with JSON marshaling

Changes

New Types

  1. AttestationCOSE - Raw COSE_Sign1 bytes from AWS Nitro Enclaves

    • EncodeBase64() → AttestationCOSEBase64
    • EncodeURLSafe() → AttestationCOSEURLBase64
    • CompressGzip() → AttestationCOSEGzip
  2. AttestationCOSEBase64 - Standard base64-encoded COSE bytes

    • Decode() → AttestationCOSE
    • CompressGzip() → AttestationCOSEGzip
    • String() for JSON marshaling
  3. AttestationCOSEURLBase64 - URL-safe base64 (no padding)

    • Decode() with automatic padding restoration
    • String() for JSON marshaling
  4. AttestationCOSEGzip - GZIP-compressed + base64url-encoded (no padding)

    • Decompress() → AttestationCOSE
    • String() for JSON marshaling

API Changes

Struct Fields:

  • EnclaveAuctionResponse.AttestationCOSEBase64: string → AttestationCOSEBase64
  • KeyResponse.AttestationCOSEBase64: string → AttestationCOSEBase64

Function Signatures:

  • GenerateTEEProofs(): Returns AttestationCOSE instead of []byte
  • GenerateAttestation(): Returns AttestationCOSE instead of []byte
  • GenerateKeyAttestation(): Returns AttestationCOSE instead of []byte
  • ValidateKeyAttestation(): Accepts AttestationCOSEBase64 parameter instead of string
  • VerifyCOSESignature(): Accepts AttestationCOSEBase64 parameter instead of string

Implementation Updates

Enclave (enclave/):

  • Use .Encode() method instead of manual base64 encoding
  • Updated variable names for clarity (coseAttestation instead of attestationCBOR)
  • Removed unnecessary encoding/base64 imports

Validation (validation/):

  • Use .Decode() method instead of manual base64 decoding
  • Type-safe function signatures throughout
  • Key validator CLI updated to use .String() for empty checks

Benefits

  1. Type Safety: Cannot accidentally mix up different encoding formats (base64 vs base64url vs gzipped)
  2. Self-Documenting: Types make encoding format explicit without verbose names
  3. Third-Party Ready: Complete reference implementation for handling COSE attestations
  4. Convenience: Methods like .EncodeBase64(), .Decode(), .CompressGzip() make conversions explicit and readable
  5. Backward Compatible: JSON marshaling/unmarshaling works transparently since types wrap primitives
  6. Testable: Compression/decompression logic can be tested directly on types

Test Plan

All existing tests pass. Adds test coverage for the new functions.

Breaking Changes

None. While internal signatures changed, JSON format remains identical and the types automatically marshal/unmarshal as their underlying primitives.

@kestutisg kestutisg left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

LGTM

Comment thread enclaveapi/types.go
data, err := base64.URLEncoding.DecodeString(str)
if err != nil {
return nil, fmt.Errorf("decode COSE URL base64: %w", err)
}

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

nit: padding and decoding is the same as in func Decompress only error message is different, I wonder if it makes sense to create small function for that and avoid repeated code. We can leave TODO and make decision on this later.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

Great suggestion. Added helper functions for both adding and removing padding: 8e1398c

@peterldowns peterldowns left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Per IRL discussion — OK with me to leave the names as-is, also OK to update as you see fit. If you do simplify the names, make sure the docstring comments on the type definitions include clear descriptions of the underlying data (which they already basically do!)

Also, fantastic use of Safety Through Incompatibility and a great idea overall (cc @lukasschwab).

Comment thread enclaveapi/types.go

// CompressGzip compresses COSE bytes with GZIP and encodes as base64url (no padding)
// Used for URL-safe transmission in win/loss notifications and bid responses
func (a AttestationCOSE) CompressGzip() (AttestationCOSEGzip, error) {

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

For things that can fail, best to return (*Type, error) instead of (Type, error)

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

The five functions that return errors in enclaveapi/types.go all return AttestationCOSE which is a reference type (to []byte) so there shouldn't be a need for *.

@nickpell
nickpell merged commit 5912f78 into main Dec 11, 2025
@nickpell
nickpell deleted the nick/types branch December 11, 2025 21:30
nickpell added a commit that referenced this pull request Oct 2, 2026
…ary ignores (#85)

## Summary

- `key-validator` and `auction-validator` each have their own
`showUsage()` text, but neither sets `flag.Usage`. `-h` and an unknown
flag therefore print Go's default `Usage of <path>:` flag list instead
of the tool's usage text. Both tools now set `flag.Usage = showUsage`
before `flag.Parse()`, so `-h`, `-help`, `--help` and flag errors all
print the tool's own usage. The exit codes stay the `flag.ExitOnError`
ones: 0 for `-h`, 2 for a flag error. The tools' own exit-code table
already defines 2 as invalid input.
- In `.gitignore`, the unanchored `key-validator` pattern also matched
the source directory `validation/cmd/key-validator/`, so `git add`
refused new files there without `-f`. `go build` writes the binary to
the directory it runs from. The pattern now names only the binary in the
two usual build directories: the repo root (`go build
./validation/cmd/key-validator`) and the package directory (`go build`
run inside it). `auction-validator` gets the same anchored pair, because
before this change its built binary was not ignored at all.

## Notes for reviewers

- The original `key-validator` ignore line came from #13, under the `#
compiled commands` comment. It was meant for the compiled binary, and
the anchored patterns keep that intent.
- Open #44 edits the body of `auction-validator`'s `showUsage()`. This
PR adds one line next to `flag.Parse()` and does not touch
`showUsage()`, so no textual overlap is expected.
- On a flag error, the flag package writes the error to stderr and the
usage text goes to stdout, because `showUsage()` prints to stdout. The
existing missing-input path has the same split: usage on stdout, error
on stderr.

## Pre-merge checklist

- [x] Build passes (`go build ./...` and `go vet ./...`)
- [x] Lint passes (`mise run //:lint`: 0 issues; `mise run //:tidy`
leaves no changes)
- [x] Tests pass (`go test ./...`)
- [x] For both tools, `-h`, `-help` and `--help` print the tool's usage
text and exit 0. `-bogus` prints `flag provided but not defined: -bogus`
on stderr, then the usage text, and exits 2. Before this change, `-h`
and `-bogus` printed Go's default flag list.
- [x] `git check-ignore -v` matches `/key-validator`,
`/validation/cmd/key-validator/key-validator`, `/auction-validator` and
`/validation/cmd/auction-validator/auction-validator`. It reports no
match for `validation/cmd/key-validator/`,
`validation/cmd/auction-validator/`, or a new file in either directory.
After building both tools from the repo root and from each package
directory, `git status --porcelain --ignored` lists the four binaries as
ignored and the new files as untracked.
- [x] Enclave binary unchanged: `go list -deps ./enclave/...` is
identical before and after
- [x] Diff contains no unintended changes: `.gitignore` and the two
`main.go` files only

## Post-deploy/apply verification

- [ ] The Go, Docker Build and EIF build runs on `main` for the merge
commit are green, including `update-pcrs` (the enclave binary does not
depend on these commands)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants