CC_UserCredential.h

Go to the documentation of this file.

/*
 * SPDX-FileCopyrightText: 2023 Silicon Laboratories Inc. <https://www.silabs.com/>
 *
 * SPDX-License-Identifier: BSD-3-Clause
 *
 */

 
#ifndef _COMMANDCLASSUSERCREDENTIAL_H_
#define _COMMANDCLASSUSERCREDENTIAL_H_
 
/****************************************************************************/
/*                              INCLUDE FILES                               */
/****************************************************************************/
 
#include <stdbool.h>
#include "CC_Common.h"
#include "ZW_classcmd.h"
#include "cc_user_credential_config.h"

 
/****************************************************************************/
/*                      EXPORTED TYPES and DEFINITIONS                      */
/****************************************************************************/
 
#define U3C_CREDENTIAL_TYPE_PIN_CODE_MIN_LENGTH_REQUIREMENT 4
#define U3C_CREDENTIAL_TYPE_PIN_CODE_MAX_LENGTH_REQUIREMENT 10
#define ASCII_AC_MAX 0x7F //< Maximum Admin PIN code character (highest ASCII code)
#define AC_MIN_LENGTH 4   //< Minimum Admin PIN code length
#define AC_MAX_LENGTH 10  //< Maximum Admin PIN code length
#define U3C_BUFFER_SIZE_USER_NAME CC_USER_CREDENTIAL_MAX_LENGTH_USER_NAME

#define DEFAULT_NAME_MAX_SIZE (sizeof("User-65535") - 1) * 2
 
// Number of bytes of a credential set frame if credential length and credential data fields are empty.
#define CREDENTIAL_SET_FRAME_LENGTH_WITHOUT_CREDENTIAL_LENGTH (offsetof(ZW_CREDENTIAL_SET_1BYTE_FRAME, credentialLength))
// Number of bytes of a credential set frame if credential data field is empty.
#define CREDENTIAL_SET_FRAME_LENGTH_WITHOUT_CREDENTIAL_DATA (offsetof(ZW_CREDENTIAL_SET_1BYTE_FRAME, credentialData1))
 
typedef enum u3c_modifier_type_ {
  MODIFIER_TYPE_DNE = CREDENTIAL_REPORT_DNE,
  MODIFIER_TYPE_UNKNOWN,
  MODIFIER_TYPE_Z_WAVE,
  MODIFIER_TYPE_LOCALLY,
  MODIFIER_TYPE_MOBILE_APP_OR_OTHER_IOT_TECHNOLOGY
} u3c_modifier_type;
 
typedef enum u3c_credential_type_ {
  CREDENTIAL_TYPE_NONE,
  CREDENTIAL_TYPE_PIN_CODE = CREDENTIAL_REPORT_PIN_CODE,
  CREDENTIAL_TYPE_PASSWORD,
  CREDENTIAL_TYPE_RFID_CODE,
  CREDENTIAL_TYPE_BLE,
  CREDENTIAL_TYPE_NFC,
  CREDENTIAL_TYPE_UWB,
  CREDENTIAL_TYPE_EYE_BIOMETRIC,
  CREDENTIAL_TYPE_FACE_BIOMETRIC,
  CREDENTIAL_TYPE_FINGER_BIOMETRIC,
  CREDENTIAL_TYPE_HAND_BIOMETRIC,
  CREDENTIAL_TYPE_UNSPECIFIED_BIOMETRIC,
  CREDENTIAL_TYPE_NUMBER_OF_TYPES
} u3c_credential_type;
 
typedef enum _u3c_credential_report_type_t_ {
  CREDENTIAL_REP_TYPE_ADDED =                       CREDENTIAL_REPORT_ADDED,
  CREDENTIAL_REP_TYPE_MODIFIED =                    CREDENTIAL_REPORT_MODIFIED,
  CREDENTIAL_REP_TYPE_DELETED =                     CREDENTIAL_REPORT_DELETED,
  CREDENTIAL_REP_TYPE_UNCHANGED =                   CREDENTIAL_REPORT_UNCHANGED,
  CREDENTIAL_REP_TYPE_RESPONSE_TO_GET =             CREDENTIAL_REPORT_RESPONSE_TO_GET,
  CREDENTIAL_REP_TYPE_ADD_AGAINST_OCCUPIED =        CREDENTIAL_REPORT_ADD_AGAINST_OCCUPIED,
  CREDENTIAL_REP_TYPE_MODIF_AGAINST_EMPTY =         CREDENTIAL_REPORT_MODIFY_AGAINST_EMPTY,
  CREDENTIAL_REP_TYPE_DUPLICATE =                   CREDENTIAL_REPORT_DUPLICATE,
  CREDENTIAL_REP_TYPE_MANUFACTURER_SECURITY_RULES = CREDENTIAL_REPORT_MANUFACTURER_SECURITY_RULES,
  CREDENTIAL_REP_TYPE_WRONG_UUID =                  CREDENTIAL_REPORT_WRONG_USER_UNIQUE_IDENTIFIER,
  CREDENTIAL_REP_TYPE_DUPLICATE_ADMIN_PIN_CODE =    CREDENTIAL_REPORT_DUPLICATE_ADMIN_PIN_CODE
} u3c_credential_report_type_t;
 
typedef enum u3c_credential_learn_status_t_ {
  CL_STATUS_STARTED =                       CREDENTIAL_LEARN_REPORT_STARTED,
  CL_STATUS_SUCCESS =                       CREDENTIAL_LEARN_REPORT_SUCCESS,
  CL_STATUS_ALREADY_IN_PROGRESS =           CREDENTIAL_LEARN_REPORT_ALREADY_IN_PROGRESS,
  CL_STATUS_ENDED_NOT_DUE_TO_TIMEOUT =      CREDENTIAL_LEARN_REPORT_ENDED_NOT_DUE_TO_TIMEOUT,
  CL_STATUS_TIMEOUT =                       CREDENTIAL_LEARN_REPORT_TIMEOUT,
  CL_STATUS_STEP_RETRY =                    CREDENTIAL_LEARN_REPORT_CREDENTIAL_LEARN_STEP_RETRY,
  CL_STATUS_INVALID_ADD_OPERATION_TYPE =    CREDENTIAL_LEARN_REPORT_INVALID_CREDENTIAL_LEARN_ADD_OPERATION_TYPE,
  CL_STATUS_INVALID_MODIFY_OPERATION_TYPE = CREDENTIAL_LEARN_REPORT_INVALID_CREDENTIAL_LEARN_MODIFY_OPERATION_TYPE
} u3c_credential_learn_status_t;
 
typedef enum {
  U3C_UCAR_STATUS_SUCCESS                                        = USER_CREDENTIAL_ASSOCIATION_REPORT_SUCCESS,
  U3C_UCAR_STATUS_CREDENTIAL_TYPE_INVALID                        = USER_CREDENTIAL_ASSOCIATION_REPORT_CREDENTIAL_TYPE_INVALID,
  U3C_UCAR_STATUS_CREDENTIAL_SLOT_INVALID                        = USER_CREDENTIAL_ASSOCIATION_REPORT_CREDENTIAL_SLOT_INVALID,
  U3C_UCAR_STATUS_CREDENTIAL_SLOT_EMPTY                          = USER_CREDENTIAL_ASSOCIATION_REPORT_CREDENTIAL_SLOT_EMPTY,
  U3C_UCAR_STATUS_DESTINATION_USER_UNIQUE_IDENTIFIER_INVALID     = USER_CREDENTIAL_ASSOCIATION_REPORT_DESTINATION_USER_UNIQUE_IDENTIFIER_INVALID,
  U3C_UCAR_STATUS_DESTINATION_USER_UNIQUE_IDENTIFIER_NONEXISTENT = USER_CREDENTIAL_ASSOCIATION_REPORT_DESTINATION_USER_UNIQUE_IDENTIFIER_NONEXISTENT,
} u3c_user_credential_association_report_status_t;
 
typedef enum u3c_user_report_type_t_ {
  USER_REP_TYPE_ADDED                = USER_REPORT_ADDED,
  USER_REP_TYPE_MODIFIED             = USER_REPORT_MODIFIED,
  USER_REP_TYPE_DELETED              = USER_REPORT_DELETED,
  USER_REP_TYPE_UNCHANGED            = USER_REPORT_UNCHANGED,
  USER_REP_TYPE_RESPONSE_TO_GET      = USER_REPORT_RESPONSE_TO_GET,
  USER_REP_TYPE_ADD_AGAINST_OCCUPIED = USER_REPORT_ADD_AGAINST_OCCUPIED,
  USER_REP_TYPE_MODIF_AGAINST_EMPTY  = USER_REPORT_MODIFY_AGAINST_EMPTY,
  USER_REP_TYPE_Z_EXP_MIN_INVALID    = USER_REPORT_ZERO_EXPIRING_MINUTES_INVALID
} u3c_user_report_type_t;
 
typedef enum u3c_user_type_ {
  USER_TYPE_GENERAL = 0x00,
  USER_TYPE_PROGRAMMING = 0x03,
  USER_TYPE_NON_ACCESS = 0x04,
  USER_TYPE_DURESS = 0x05,
  USER_TYPE_DISPOSABLE = 0x06,
  USER_TYPE_EXPIRING = 0x07,
  USER_TYPE_REMOTE_ONLY = 0x09,
  USER_TYPE_END
} u3c_user_type;
 
typedef enum u3c_credential_rule_ {
  CREDENTIAL_RULE_SINGLE = 0x01,
  CREDENTIAL_RULE_DUAL,
  CREDENTIAL_RULE_TRIPLE
} u3c_credential_rule;
 
typedef enum u3c_user_name_encoding_ {
  USER_NAME_ENCODING_STANDARD_ASCII,
  USER_NAME_ENCODING_STANDARD_AND_OEM_EXTENDED_ASCII,
  USER_NAME_ENCODING_UNICODE_UTF_16
} u3c_user_name_encoding;

typedef enum _u3c_admin_code_operation_result_ {
  ADMIN_CODE_OPERATION_RESULT_MODIFIED = 0x01,                
  ADMIN_CODE_OPERATION_RESULT_UNMODIFIED = 0x03,              
  ADMIN_CODE_OPERATION_RESULT_GET_RESP = 0x04,                
  ADMIN_CODE_OPERATION_RESULT_FAIL_DUPLICATE_CRED = 0x07,     
  ADMIN_CODE_OPERATION_RESULT_FAIL_MANUF_RULE = 0x08,         
  ADMIN_CODE_OPERATION_RESULT_ERROR_AC_NOT_SUPPORTED = 0x0D,  
  ADMIN_CODE_OPERATION_RESULT_ERROR_ACD_NOT_SUPPORTED = 0x0E, 
  ADMIN_CODE_OPERATION_RESULT_ERROR_NODE = 0x0F,              
  // Internal result values selected to mask to appropriate result codes in the report
  ADMIN_CODE_OPERATION_RESULT_INTERNAL_DUPLICATE_AC = 0x13,   
  ADMIN_CODE_OPERATION_RESULT_INTERNAL_NONE = 0x14,           
  ADMIN_CODE_OPERATION_RESULT_INTERNAL_INVALID_LENGTH = 0x1F, 
  ADMIN_CODE_OPERATION_RESULT_INTERNAL_INVALID_CHAR = 0x2F,   
} u3c_admin_code_operation_result;
 
typedef struct u3c_user_t_ {
  uint16_t unique_identifier;
  uint16_t modifier_node_id;
  uint16_t expiring_timeout_minutes;
  uint8_t name_length;
  u3c_user_type type;
  u3c_modifier_type modifier_type;
  u3c_credential_rule credential_rule;
  u3c_user_name_encoding name_encoding;
  bool active;
} u3c_user_t;
 
typedef struct u3c_credential_metadata_t_ {
  uint16_t uuid;
  uint16_t slot;
  uint16_t modifier_node_id;
  uint8_t length;
  u3c_modifier_type modifier_type;
  u3c_credential_type type;
} u3c_credential_metadata_t;
 
typedef struct u3c_credential_t_ {
  u3c_credential_metadata_t metadata;
  uint8_t * data;
} u3c_credential_t;
 
typedef enum {
  U3C_OPERATION_TYPE_ADD    = 0,
  U3C_OPERATION_TYPE_MODIFY = 1,
  U3C_OPERATION_TYPE_DELETE = 2
} u3c_operation_type_t;
 
typedef struct u3c_credential_identifier_t_ {
  uint16_t uuid;
  u3c_credential_type type;
  uint16_t slot;
} u3c_credential_identifier_t;

typedef struct u3c_event_data_validate_t_ {
  u3c_credential_t * credential;
  bool is_unlocked;
} u3c_event_data_validate_t;

typedef struct u3c_event_data_learn_read_done_t_ {
  uint8_t * data;
  uint8_t data_length;
} u3c_event_data_learn_read_done_t;

typedef struct u3c_event_data_learn_start_t_ {
  u3c_credential_identifier_t target;
  u3c_operation_type_t operation_type;
  uint16_t source_id;
  uint8_t timeout_seconds;
} u3c_event_data_learn_start_t;
 
typedef struct u3c_admin_code_metadata_t_ {
  u3c_admin_code_operation_result result;
  uint8_t code_length;
  // Admin code can't be any longer than the max length pin code
  uint8_t code_data[U3C_CREDENTIAL_TYPE_PIN_CODE_MAX_LENGTH_REQUIREMENT];
} u3c_admin_code_metadata_t;
 
typedef enum u3c_event_ {
  CC_USER_CREDENTIAL_EVENT_VALIDATE            = 1,  
  CC_USER_CREDENTIAL_EVENT_VALIDATE_VALID      = 2,  
  CC_USER_CREDENTIAL_EVENT_VALIDATE_INVALID    = 3,  
  CC_USER_CREDENTIAL_EVENT_LEARN_START_REQUEST = 4,  
  CC_USER_CREDENTIAL_EVENT_LEARN_START         = 5,  
  CC_USER_CREDENTIAL_EVENT_LEARN_STEP_START    = 6,  
  CC_USER_CREDENTIAL_EVENT_LEARN_READ_DONE     = 7,  
  CC_USER_CREDENTIAL_EVENT_LEARN_SUCCESS       = 8,  
  CC_USER_CREDENTIAL_EVENT_LEARN_FAILED        = 9,
  CC_USER_CREDENTIAL_EVENT_LEARN_STEP_RETRY    = 10, 
  CC_USER_CREDENTIAL_EVENT_LEARN_TIMEOUT       = 11, 
  CC_USER_CREDENTIAL_EVENT_LEARN_CANCEL_REMOTE = 12, 
  CC_USER_CREDENTIAL_EVENT_LEARN_CANCEL_LOCAL  = 13  
} u3c_event_type;
 
/****************************************************************************/
/*                              API FUNCTIONS                               */
/****************************************************************************/

bool CC_UserCredential_manufacturer_validate_credential(
  const u3c_credential_t * const credential
  );

bool CC_UserCredential_manufacturer_validate_admin_pin_code(
  u3c_admin_code_metadata_t * const code
  );

void CC_UserCredential_set_default_name(
  uint8_t * pName,
  u3c_user_t * pUser
  );

 
#endif /* _COMMANDCLASSUSERCREDENTIAL_H_ */