mirror of
https://git.libssh.org/projects/libssh.git
synced 2026-02-04 20:30:38 +09:00
302d868875
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>
284 lines
8.7 KiB
C
284 lines
8.7 KiB
C
/*
|
|
* 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 */
|