From 302d868875c90247688dfb0ca909786c8bd15258 Mon Sep 17 00:00:00 2001 From: Praneeth Sarode Date: Tue, 27 May 2025 10:00:19 +0530 Subject: [PATCH] fido2: add sk_api.h The sk_api.h file added is a copy of the sk-api.h file in openSSH, including only the struct and constant definitions. This has been done to ensure compatibility with any security key middleware developed for openSSH. Signed-off-by: Praneeth Sarode Reviewed-by: Jakub Jelen Reviewed-by: Eshan Kelkar --- include/libssh/CMakeLists.txt | 7 + include/libssh/sk_api.h | 283 ++++++++++++++++++++++++++++++++++ 2 files changed, 290 insertions(+) create mode 100644 include/libssh/sk_api.h diff --git a/include/libssh/CMakeLists.txt b/include/libssh/CMakeLists.txt index 93445680..109e6837 100644 --- a/include/libssh/CMakeLists.txt +++ b/include/libssh/CMakeLists.txt @@ -29,6 +29,13 @@ if (WITH_SERVER) endif (WITH_SFTP) endif (WITH_SERVER) +if (WITH_FIDO2) + set(libssh_HDRS + ${libssh_HDRS} + sk_api.h + ) +endif (WITH_FIDO2) + install( FILES ${libssh_HDRS} diff --git a/include/libssh/sk_api.h b/include/libssh/sk_api.h new file mode 100644 index 00000000..f85f4b8b --- /dev/null +++ b/include/libssh/sk_api.h @@ -0,0 +1,283 @@ +/* + * Copyright (c) 2019 Google LLC + * + * Permission to use, copy, modify, and distribute this software for any + * purpose with or without fee is hereby granted, provided that the above + * copyright notice and this permission notice appear in all copies. + * + * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES + * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF + * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR + * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES + * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN + * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF + * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + */ + +/* + * This file is a copy of the OpenSSH project's sk-api.h file pulled from + * https://github.com/openssh/openssh-portable/commit/a9cbe10da2be5be76755af0cea029db0f9c1f263 + * with only the flags, algorithms, error codes, and struct definitions. The + * function declarations and other OpenSSH-specific code have been removed. + */ + +#ifndef SK_API_H +#define SK_API_H 1 + +#include +#include + +/* FIDO2/U2F Operation Flags */ + +/** Requires user presence confirmation (tap/touch) */ +#ifndef SSH_SK_USER_PRESENCE_REQD +#define SSH_SK_USER_PRESENCE_REQD 0x01 +#endif + +/** Requires user verification (PIN/biometric) - FIDO2 only */ +#ifndef SSH_SK_USER_VERIFICATION_REQD +#define SSH_SK_USER_VERIFICATION_REQD 0x04 +#endif + +/** Force resident key enrollment even if a resident key with given user ID + * already exists - FIDO2 only */ +#ifndef SSH_SK_FORCE_OPERATION +#define SSH_SK_FORCE_OPERATION 0x10 +#endif + +/** Create/use resident key stored on authenticator - FIDO2 only */ +#ifndef SSH_SK_RESIDENT_KEY +#define SSH_SK_RESIDENT_KEY 0x20 +#endif + +/* Algorithms */ + +/** ECDSA with P-256 curve */ +#define SSH_SK_ECDSA 0x00 + +/** Ed25519 - FIDO2 only */ +#define SSH_SK_ED25519 0x01 + +/* Error codes */ + +/** General unspecified failure */ +#define SSH_SK_ERR_GENERAL -1 + +/** Requested algorithm/feature/option not supported */ +#define SSH_SK_ERR_UNSUPPORTED -2 + +/** PIN (or other user verification) required but either missing or invalid */ +#define SSH_SK_ERR_PIN_REQUIRED -3 + +/** No suitable security key / authenticator device was found */ +#define SSH_SK_ERR_DEVICE_NOT_FOUND -4 + +/** Attempt to create a resident key that already exists (duplicate) */ +#define SSH_SK_ERR_CREDENTIAL_EXISTS -5 + +/** + * @brief Response structure for FIDO2/U2F key enrollment operations + * + * Contains all data returned by a FIDO2/U2F authenticator after successful + * enrollment of a new credential. + */ +struct sk_enroll_response { + /** @brief FIDO2/U2F authenticator flags from the enrollment operation + * + * Contains flags indicating authenticator capabilities and state during + * enrollment, such as user presence (UP), user verification + * (UV), and resident key. + */ + uint8_t flags; + + /** @brief Public key data in standard format + * + * For ECDSA (P-256): 65 bytes in SEC1 uncompressed point format + * (0x04 prefix + 32-byte X coordinate + 32-byte Y coordinate) + * For Ed25519: 32 bytes containing the raw public key (FIDO2 only) + */ + uint8_t *public_key; + + /** @brief Length of public_key buffer in bytes + * + * Expected values: 65 for ECDSA P-256, 32 for Ed25519 + */ + size_t public_key_len; + + /** @brief Opaque credential handle/ID used to identify this key + * + * Authenticator-generated binary data that uniquely identifies this + * credential. Used in subsequent sign operations to specify which + * key to use. Format and contents are authenticator-specific. + */ + uint8_t *key_handle; + + /** @brief Length of key_handle buffer in bytes + * + * Length varies by authenticator. + */ + size_t key_handle_len; + + /** @brief Enrollment signature over the enrollment data + * + * FIDO2/U2F authenticator signature proving the credential was created + * by this specific authenticator. Used for enrollment verification. + * Format depends on algorithm. + */ + uint8_t *signature; + + /** @brief Length of signature buffer in bytes + * + * Length varies by algorithm. + */ + size_t signature_len; + + /** @brief X.509 attestation certificate + * + * Certificate that attests to the authenticity of the authenticator + * and the enrollment operation. Used to verify the authenticator's + * identity and manufacturer. + */ + uint8_t *attestation_cert; + + /** @brief Length of attestation_cert buffer in bytes */ + size_t attestation_cert_len; + + /** @brief FIDO2/U2F authenticator data from enrollment + * + * CBOR-encoded authenticator data containing RP ID hash, flags, + * counter, and attested credential data. Used for attestation + * verification according to the FIDO2 specification. + */ + uint8_t *authdata; + + /** @brief Length of authdata buffer in bytes + * + * Length varies depending on credential data and extensions. + */ + size_t authdata_len; +}; + +/** + * @brief Response structure for FIDO2/U2F key signing operations + * + * Contains signature components and metadata returned by a FIDO2/U2F + * authenticator after a successful signing operation. + */ +struct sk_sign_response { + /** @brief FIDO2/U2F authenticator flags from the signing operation + * + * Contains flags indicating authenticator state during signing, + * including user presence (UP) and user verification (UV) flags. + * Used to verify that proper user interaction occurred while signing. + */ + uint8_t flags; + + /** @brief Authenticator signature counter value + * + * Monotonically increasing counter maintained by the authenticator. + * Incremented on each successful signing operation. Used to detect + * cloned or duplicated authenticators. + */ + uint32_t counter; + + /** @brief R component of ECDSA signature or Ed25519 signature */ + uint8_t *sig_r; + + /** @brief Length of sig_r buffer in bytes */ + size_t sig_r_len; + + /** @brief S component of ECDSA signature */ + uint8_t *sig_s; + + /** @brief Length of sig_s buffer in bytes */ + size_t sig_s_len; +}; + +/** + * @brief Structure representing a resident/discoverable credential + * + * Represents a FIDO2 resident key (discoverable credential) that is + * stored on the authenticator and can be discovered without providing + * a credential ID. + */ +struct sk_resident_key { + /** @brief Cryptographic algorithm identifier for this key + * + * SSH_SK_ECDSA (0x00): ECDSA with P-256 curve + * SSH_SK_ED25519 (0x01): Ed25519 signature algorithm + */ + uint32_t alg; + + /** @brief Slot/index number of this key on the authenticator + * + * Zero-based index indicating the position of this resident key + * in the authenticator's internal storage. Used for key management + * and identification when multiple resident keys exist. + */ + size_t slot; + + /** @brief Relying Party (application) identifier string + * + * The RP ID (typically a domain name) that this resident key + * is associated with. Determines which application/service + * this key can be used for. + */ + char *application; + + /** @brief Embedded enrollment response containing key material + * + * Contains the same data as returned during initial enrollment, + * including public key, key handle, and associated metadata. + */ + struct sk_enroll_response key; + + /** @brief Flags associated with this resident key + * + * SSH_SK_USER_PRESENCE_REQD: Requires user presence for operations + * SSH_SK_USER_VERIFICATION_REQD: Requires user verification + * (PIN/biometric) + */ + uint8_t flags; + + /** @brief User identifier associated with this resident key + * + * Binary user ID that was provided during key enrollment. + * Used to identify which user account this key belongs to. + */ + uint8_t *user_id; + + /** @brief Length of user_id buffer in bytes + * + * Length of the user identifier. + */ + size_t user_id_len; +}; + +/** + * @brief Configuration option structure for FIDO2/U2F operations + * + * Represents a single configuration parameter that can be passed + * to FIDO2/U2F middleware. + */ +struct sk_option { + /** @brief Option name/key identifier */ + char *name; + + /** @brief Option value as bytes */ + char *value; + + /** @brief Indicates if this option is required for the operation + * + * Non-zero if this option must be processed and cannot be ignored. + * Zero if this option is advisory and can be skipped if the + * middleware does not support it. + */ + uint8_t required; +}; + +/** Current SK API version */ +#define SSH_SK_VERSION_MAJOR 0x000a0000 +#define SSH_SK_VERSION_MAJOR_MASK 0xffff0000 + +#endif /* SK_API_H */