hawkes is a Go package providing a interface to establish shared secrets between two or more parties.
It includes implementations of this interface for OATH-TOTP as well as PIV, OpenPGP, PCS11 smart cards and TPM2 modules.
hawkes' main use case is the establishment of pre-shared keys for cunīcu, a WireGuard mesh-network, using hardware-secured or post-quantum resilient key establishment methods.
When build with CGO_ENABLED, hawkes requires the following external dependencies.
apt-get install \
libpcsclite-dev
Secret keys are stored in local file or memory.
⚠ Use only for testing.
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.
- Documentation: Protecting keys with the Secure Enclave
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.
- Specification: TPM 2.0 Library
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.
- Specification: Functional Specification of the OpenPGP application on ISO Smart Card Operating Systems
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.
- Specification: FIPS 201-3
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).
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.
- Specification: YKOATH Protocol Specification
hawkes uses supports two families of handshake protocols for establishing a shared secret between two parties:
- Keyed-hash message authentication code (HMAC)
- Noise protocol framework (ECDH)
The following table gives an overview of the supported protocols for each key provider
| Provider | Protocols | Curve | Hash | Enumerate | Create | Destroy |
|---|---|---|---|---|---|---|
| Memory | HMAC, ECDH | secp256r11 | SHA256 | ✅ | ✅ | ✅ |
| YKOATH | HMAC | SHA256 | ✅ | ✅ | ✅ | |
| AppleSE | ECDH | secp256r1 | ✅ | ✅ | ✅ | |
| TPM2 | HMAC, ECDH | secp256r1 | SHA256 | ❌ | ❌ | ❌ |
| OpenPGP | ECDH | secp256r1 | ✅ | ✅ | ✅ | |
| PIV | ECDH | secp256r1 | ✅ | ✅ | ✅ | |
| PKCS11 | ECDH | secp256r1 | ✅ | ✅ | ✅ |
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.
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.
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. TOTP is the cornerstone of Initiative for Open Authentication (OATH), and is used in a number of two-factor authentication (2FA) systems. 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.
hawkes uses protocol identifiers to describe the handshake protocol which should be used to for establishing a shared secret.
Noise_<Pattern>_<Cipher>_<Hash>for elliptic curve Diffie-Helman key exchange using the Noise protocol framework.WireGuardis an alias forNoise_IK_ChaChaPoly_BLAKE2s
OATH-TOTP_<Hash>for a HMAC key used to calculate an OATH-TOTP one-time password.Rosenpassfor the Rosenpass post-qunatum key exchange
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.
Please have a look at the contact page: cunicu.li/docs/contact.
hawkes is licensed under the Apache 2.0 license.