mirror of
https://git.libssh.org/projects/libssh.git
synced 2026-01-06 14:21:55 +03:00
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 <praneethsarode@gmail.com> Reviewed-by: Jakub Jelen <jjelen@redhat.com> Reviewed-by: Eshan Kelkar <eshankelkar@galorithm.com>
This commit is contained in:
Praneeth Sarode
@@ -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}
|
||||
|
||||
283
include/libssh/sk_api.h
Normal file
283
include/libssh/sk_api.h
Normal file
@@ -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 <stddef.h>
|
||||
#include <stdint.h>
|
||||
|
||||
/* 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 */
|
||||
Reference in New Issue
Block a user