Skip to content

Latest commit

 

History

History
141 lines (86 loc) · 8.7 KB

README.md

File metadata and controls

141 lines (86 loc) · 8.7 KB
cunīcu logo

Hardware-secured Key Establishment

GitHub Workflow Status goreportcard Codecov branch License GitHub go.mod Go version Go Reference

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.

Building

When build with CGO_ENABLED, hawkes requires the following external dependencies.

apt-get install \
    libpcsclite-dev

Key Providers

Providers

File: Secrets stored in files / memory

Secret keys are stored in local file or memory.

⚠ Use only for testing.

AppleSE: Apple Secure Enclave

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.

TPM2: Trusted Platform Module v2 (TPM)

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.

OpenPGP: OpenPGP Card

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.

PIV: Personal Identity Verification (PIV) Card

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.

PKCS11: PKCS11 Token

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).

YKOATH: Yubico's YKOATH Protocol

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.

Handshake Protocols

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 Protocol Framework using Elliptic-curve Diffie-Hellman (ECDH)

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.

OATH-TOTP using HMAC (HMAC)

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.

Protocol Identifiers

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.
    • WireGuard is an alias for Noise_IK_ChaChaPoly_BLAKE2s
  • OATH-TOTP_<Hash> for a HMAC key used to calculate an OATH-TOTP one-time password.
  • Rosenpass for 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.

Usage

Types

Types

Contact

Please have a look at the contact page: cunicu.li/docs/contact.

License

hawkes is licensed under the Apache 2.0 license.

Footnotes

  1. secp256r1 curve in the standard curve database