{"id":25161512,"url":"https://github.com/cunicu/hawkes","last_synced_at":"2025-04-03T13:42:41.352Z","repository":{"id":189230923,"uuid":"679103338","full_name":"cunicu/hawkes","owner":"cunicu","description":"A Go implementation of hardware-secured key establishment methods","archived":false,"fork":false,"pushed_at":"2024-04-08T05:02:58.000Z","size":220,"stargazers_count":2,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-04-09T05:36:52.561Z","etag":null,"topics":["enclave","go","golang","key-establishment","pqc","psk","rosenpass","token","tpm"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cunicu.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-08-16T05:26:30.000Z","updated_at":"2024-04-29T02:48:36.495Z","dependencies_parsed_at":"2024-04-29T02:58:39.301Z","dependency_job_id":null,"html_url":"https://github.com/cunicu/hawkes","commit_stats":null,"previous_names":["cunicu/poc-pske","cunicu/go-skes","cunicu/hawkes"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cunicu%2Fhawkes","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cunicu%2Fhawkes/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cunicu%2Fhawkes/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cunicu%2Fhawkes/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cunicu","download_url":"https://codeload.github.com/cunicu/hawkes/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247013787,"owners_count":20869358,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["enclave","go","golang","key-establishment","pqc","psk","rosenpass","token","tpm"],"created_at":"2025-02-09T02:35:24.334Z","updated_at":"2025-04-03T13:42:41.316Z","avatar_url":"https://github.com/cunicu.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!--\nSPDX-FileCopyrightText: 2023-2024 Steffen Vogel \u003cpost@steffenvogel.de\u003e\nSPDX-License-Identifier: Apache-2.0\n--\u003e\n\n\u003cdiv align=\"center\" \u003e\n    \u003cimg style=\"width: 40%;\" src=\"docs/hawkes_logo.svg\" alt=\"cunīcu logo\" /\u003e\n\n# Hardware-secured Key Establishment\n\n[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/cunicu/hawkes/test.yaml?style=flat-square)](https://github.com/cunicu/hawkes/actions)\n[![goreportcard](https://goreportcard.com/badge/github.com/cunicu/hawkes?style=flat-square)](https://goreportcard.com/report/github.com/cunicu/hawkes)\n[![Codecov branch](https://img.shields.io/codecov/c/github/cunicu/hawkes/main?style=flat-square\u0026token=6XoWouQg6K)](https://app.codecov.io/gh/cunicu/hawkes/tree/main)\n[![License](https://img.shields.io/badge/license-Apache%202.0-blue?style=flat-square)](https://github.com/cunicu/hawkes/blob/main/LICENSES/Apache-2.0.txt)\n![GitHub go.mod Go version](https://img.shields.io/github/go-mod/go-version/cunicu/hawkes?style=flat-square)\n[![Go Reference](https://pkg.go.dev/badge/github.com/cunicu/hawkes.svg)](https://pkg.go.dev/github.com/cunicu/hawkes)\n\u003c/div\u003e\n\n`hawkes` is a Go package providing a interface to establish shared secrets between two or more parties.\nIt includes implementations of this interface for OATH-TOTP as well as PIV, OpenPGP, PCS11 smart cards and TPM2 modules.\n\nhawkes' main use case is the establishment of pre-shared keys for [cunīcu](https://cunicu.li), a WireGuard mesh-network, using hardware-secured or post-quantum resilient key establishment methods.\n\n## Building\n\nWhen build with `CGO_ENABLED`, hawkes requires the following external dependencies.\n\n```bash\napt-get install \\\n    libpcsclite-dev\n```\n\n## Key Providers\n\n![Providers](docs/providers.svg)\n\n#### `File`: Secrets stored in files / memory\n\nSecret keys are stored in local file or memory.\n\n⚠ Use only for testing.\n\n#### `AppleSE`: Apple Secure Enclave\n\n\u003e The Secure Enclave is a hardware-based key manager that’s isolated from the main processor to provide an extra layer of security. When you protect a private key with the Secure Enclave, you never handle the plain-text key, making it difficult for the key to become compromised. Instead, you instruct the Secure Enclave to create and encode the key, and later to decode and perform operations with it. You receive only the output of these operations, such as encrypted data or a cryptographic signature verification outcome.\n\n- **Documentation:** [Protecting keys with the Secure Enclave](https://developer.apple.com/documentation/security/certificate_key_and_trust_services/keys/protecting_keys_with_the_secure_enclave?language=objc)\n\n#### `TPM2`: Trusted Platform Module v2 (TPM)\n\n\u003e Trusted Platform Module (TPM, also known as ISO/IEC 11889) is an international standard for a secure crypto processor, a dedicated micro controller designed to secure hardware through integrated cryptographic keys. The term can also refer to a chip conforming to the standard.\n\n- **Specification:** [TPM 2.0 Library](https://trustedcomputinggroup.org/resource/tpm-library-specification/)\n\n#### `OpenPGP`: OpenPGP Card\n\n\u003e The OpenPGP card is an ISO/IEC 7816-4, -8 compatible smart card that is integrated with many OpenPGP functions. Using this smart card, various cryptographic tasks (encryption, decryption, digital signing/verification, authentication etc.) can be performed. It allows secure storage of secret key material.\n\n- **Specification:** [Functional Specification of the OpenPGP application on ISO Smart Card Operating Systems](https://www.gnupg.org/ftp/specs/OpenPGP-smart-card-application-3.4.1.pdf)\n\n#### `PIV`: Personal Identity Verification (PIV) Card\n\n\u003e FIPS 201 (Federal Information Processing Standard Publication 201) is a United States federal government standard that specifies Personal Identity Verification (PIV) requirements for Federal employees and contractors. This Standard specifies the architecture and technical requirements for a common identification standard for Federal employees and contractors.[1] FIPS 201 specifies that an identity credential must be stored on a smart card.\n\n- **Specification:** [FIPS 201-3](https://csrc.nist.gov/pubs/fips/201-3/final)\n\n#### `PKCS11`: PKCS11 Token\n\n\u003e PKCS #11 is one of the Public-Key Cryptography Standards, and also refers to the programming interface to create and manipulate cryptographic tokens (a token where the secret is a cryptographic key).\n\n- **Specification:** [PKCS #11 Cryptographic Token Interface Base Specification Version 2.40](https://docs.oasis-open.org/pkcs11/pkcs11-base/v2.40/pkcs11-base-v2.40.html)\n\n#### `YKOATH`: Yubico's YKOATH Protocol\n\n\u003e The YKOATH protocol is used to manage and use OATH credentials with a YubiKey NEO, YubiKey 4, or YubiKey 5. It can be accessed over USB (when the CCID transport is enabled) or over NFC, using ISO 7816-4 commands as defined in this document.\n\n- **Specification:** [YKOATH Protocol Specification](https://developers.yubico.com/OATH/YKOATH_Protocol.html)\n\n## Handshake Protocols\n\n_hawkes_ uses supports two families of handshake protocols for establishing a shared secret between two parties:\n\n- Keyed-hash message authentication code (HMAC)\n- Noise protocol framework (ECDH)\n\nThe following table gives an overview of the supported protocols for each key provider\n\n| Provider  | Protocols  | Curve         | Hash   | Enumerate | Create | Destroy |\n|:--        |:--         |:--            |:--     |:--        |:--     |:--      |\n| Memory    | HMAC, ECDH | secp256r1[^1] | SHA256 | ✅ | ✅ | ✅ |\n| YKOATH    | HMAC       |               | SHA256 | ✅ | ✅ | ✅ |\n| AppleSE   | ECDH       | secp256r1     |        | ✅ | ✅ | ✅ |\n| TPM2      | HMAC, ECDH | secp256r1     | SHA256 | ❌ | ❌ | ❌ |\n| OpenPGP   | ECDH       | secp256r1     |        | ✅ | ✅ | ✅ |\n| PIV       | ECDH       | secp256r1     |        | ✅ | ✅ | ✅ |\n| PKCS11    | ECDH       | secp256r1     |        | ✅ | ✅ | ✅ |\n\n### Noise Protocol Framework using Elliptic-curve Diffie-Hellman (ECDH)\n\n\u003e Noise is a framework for crypto protocols based on Diffie-Hellman key agreement. Noise can describe protocols that consist of a single message as well as interactive protocols.\n\n\u003e Elliptic-curve Diffie–Hellman (ECDH) is a key agreement protocol that allows two parties, each having an elliptic-curve public–private key pair, to establish a shared secret over an insecure channel. This shared secret may be directly used as a key, or to derive another key. The key, or the derived key, can then be used to encrypt subsequent communications using a symmetric-key cipher. It is a variant of the Diffie–Hellman protocol using elliptic-curve cryptography.\n\n- **Specifications:** \n  - [Noise Protocol Framework](http://www.noiseprotocol.org/noise.html)\n  - [SEC 2: Recommended Elliptic Curve Domain Parameters](https://www.secg.org/sec2-v2.pdf)\n\n### OATH-TOTP using HMAC (HMAC)\n\n\u003e Time-based one-time password (TOTP) is a computer algorithm that generates a one-time password (OTP) that uses the current time as a source of uniqueness. As an extension of the HMAC-based one-time password algorithm (HOTP), it has been adopted as Internet Engineering Task Force (IETF) standard RFC 6238.\n\u003e TOTP is the cornerstone of Initiative for Open Authentication (OATH), and is used in a number of two-factor authentication (2FA) systems.\n\u003e HMACs can provide authentication using a shared secret instead of using digital signatures with asymmetric cryptography. It trades off the need for a complex public key infrastructure by delegating the key exchange to the communicating parties, who are responsible for establishing and using a trusted channel to agree on the key prior to communication.\n\n- **Specification:** [RFC 6238](https://datatracker.ietf.org/doc/html/rfc6238) \u0026 [RFC 4226](https://datatracker.ietf.org/doc/html/rfc4226)\n\n### Protocol Identifiers\n\n_hawkes_ uses protocol identifiers to describe the handshake protocol which should be used to for establishing a shared secret.\n\n- `Noise_\u003cPattern\u003e_\u003cCipher\u003e_\u003cHash\u003e` for elliptic curve Diffie-Helman key exchange using the [Noise protocol framework](http://www.noiseprotocol.org/).\n  - `WireGuard` is an alias for `Noise_IK_ChaChaPoly_BLAKE2s`\n- `OATH-TOTP_\u003cHash\u003e` for a HMAC key used to calculate an OATH-TOTP one-time password.\n- `Rosenpass` for the Rosenpass post-qunatum key exchange\n\n**Note:** Deviating from the Noise protocol framework, _hawkes_ is mainly using NIST elliptic curves for the `Noise` protocol due to increased compatibility with hardware tokens and smart cards.\n\n## Usage\n\n### Types\n\n![Types](docs/types.svg)\n\n## Contact\n\nPlease have a look at the contact page: [cunicu.li/docs/contact](https://cunicu.li/docs/contact).\n\n## License\n\nhawkes is licensed under the [Apache 2.0](./LICENSE) license.\n\n[^1]: [secp256r1 curve in the standard curve database](https://neuromancer.sk/std/secg/secp256r1)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcunicu%2Fhawkes","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcunicu%2Fhawkes","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcunicu%2Fhawkes/lists"}