.. hsm2-errors.rst

.. _hsm2-concepts-errors-label:

===============================
YubiHSM Error and Status Codes
===============================

Error Codes 
------------

Below are error codes returned by a YubiHSM device.

.. table::

   +--------------------------+-------+-------------------------------------------+
   | Name                     | Value | Description                               |
   +==========================+=======+===========================================+
   | AUTHENTICATION FAILED    | 0x04  | Wrong Authentication Key                  |
   +--------------------------+-------+-------------------------------------------+
   | DEMO MODE                | 0x10  | Demo device must be power-cycled          |
   +--------------------------+-------+-------------------------------------------+
   | INSUFFICIENT PERMISSIONS | 0x09  | Insufficient permissions for the command  |
   +--------------------------+-------+-------------------------------------------+
   | INVALID COMMAND          | 0x01  | Unknown command                           |
   +--------------------------+-------+-------------------------------------------+
   | INVALID DATA             | 0x02  | Malformed data for the command            |
   +--------------------------+-------+-------------------------------------------+
   | INVALID ID               | 0x0c  | Invalid ID                                |
   +--------------------------+-------+-------------------------------------------+
   | INVALID OTP              | 0x0f  | OTP decryption failed                     |
   +--------------------------+-------+-------------------------------------------+
   | INVALID SESSION          | 0x03  | The session has expired or does not exist |
   +--------------------------+-------+-------------------------------------------+
   | LOG FULL                 | 0x0a  | The log is full and force audit is enabled|
   +--------------------------+-------+-------------------------------------------+
   | OBJECT EXISTS            | 0x11  | Unable to overwrite object                |
   +--------------------------+-------+-------------------------------------------+
   | OBJECT NOT FOUND         | 0x0b  | No object found matching given ID and Type|
   +--------------------------+-------+-------------------------------------------+
   | OK                       | 0x00  | Success                                   |
   +--------------------------+-------+-------------------------------------------+
   | SESSION FAILED           | 0x06  | Session setup failed                      |
   +--------------------------+-------+-------------------------------------------+
   | SESSIONS FULL            | 0x05  | No more available sessions                |
   +--------------------------+-------+-------------------------------------------+
   || SSH CA CONSTRAINT       | 0x0e  | Constraints in SSH Template not met       |
   || VIOLATION               |       |                                           |
   +--------------------------+-------+-------------------------------------------+
   | STORAGE FAILED           | 0x07  | Storage full                              |
   +--------------------------+-------+-------------------------------------------+
   | WRONG LENGTH             | 0x08  | Wrong data length for the command         |
   +--------------------------+-------+-------------------------------------------+
   


Status Codes Reference
-------------------------

The YubiHSM software components have a standard set of status codes to report the status of an HSM operation. To comply with the expectations of specific platforms, these status codes are converted to the appropriate API status code.

Currently, this translation is only performed for the Windows Key Storage Provider. The error codes, their meanings and translated values are as follows.

.. table::

   +---------------------------+----------------------+-------------------------+
   | Libyubihsm Error Code     | Description          | Windows CNG Translation |
   +===========================+======================+=========================+
   | YHR_BUFFER_TOO_SMALL      || Not enough space    | NTE_BUFFER_TOO_SMALL    |
   |                           || to store data       |                         |
   +---------------------------+----------------------+-------------------------+
   | YHR_CONNECTION_ERROR      || Transport Backend   | NTE_DEVICE_NOT_READY    |
   |                           || error               |                         |
   +---------------------------+----------------------+-------------------------+
   | YHR_CONNECTOR_ERROR       || Connector           | NTE_DEVICE_NOT_READY    |
   |                           || operation Failed    |                         |
   +---------------------------+----------------------+-------------------------+
   | YHR_CONNECTOR_NOT_FOUND   || Unable to find a    | NTE_DEVICE_NOT_READY    |
   |                           || suitable connector  |                         |
   +---------------------------+----------------------+-------------------------+
   | YHR_CRYPTOGRAM_MISMATCH   || Unable to verify    | NTE_BAD_SIGNATURE       |
   |                           || cryptogram          |                         |
   +---------------------------+----------------------+-------------------------+
   || YHR_DEVICE_AUTHENTICATION|| Message encryption /|| NTE_INCORRECT_PASSWORD |
   || _FAILED                  || verification failed ||                        |
   +---------------------------+----------------------+-------------------------+
   || YHR_DEVICE_COMMAND       || The HSM attempted to| NTE_SYS_ERR             |
   || _UNEXECUTED              || execute a command,  |                         |
   ||                          || but it did not      |                         |
   ||                          || complete in allotted|                         |
   ||                          || time. The command   |                         |
   ||                          || has not terminated, |                         |
   ||                          || and the current     |                         |
   ||                          || state of the session|                         |
   ||                          || is unavailable      |                         |
   +---------------------------+----------------------+-------------------------+
   || YHR_DEVICE_DEMO_MODE     || Demo mode, power    | NTE_DEVICE_NOT_READY    |
   ||                          || cycle device        |                         |
   +---------------------------+----------------------+-------------------------+
   || YHR_DEVICE_INSUFFICIENT  || Wrong permissions   | NTE_PERM                |
   || _PERMISSIONS             || for operation       |                         |
   +---------------------------+----------------------+-------------------------+
   || YHR_DEVICE_INVALID       | Invalid command      | NTE_NOT_SUPPORTED       |
   || _COMMAND                 |                      |                         |
   +---------------------------+----------------------+-------------------------+
   | YHR_DEVICE_INVALID_DATA   || Malformed command / | NTE_INVALID_PARAMETER   |
   |                           || invalid data        |                         |
   +---------------------------+----------------------+-------------------------+
   | YHR_DEVICE_INVALID_ID     || Illegal ID used     | NTE_INVALID_PARAMETER[] |
   +---------------------------+----------------------+-------------------------+
   | YHR_DEVICE_INVALID_OTP    || Invalid OTP         | NTE_INCORRECT_PASSWORD  |
   +---------------------------+----------------------+-------------------------+
   || YHR_DEVICE_INVALID       | Invalid session      | NTE_DEVICE_NOT_READY    |
   || _SESSION                 |                      |                         |
   +---------------------------+----------------------+-------------------------+
   || YHR_DEVICE_LOG_FULL      || Log buffer is full  | NTE_DEVICE_NOT_READY    |
   ||                          || and forced audit is |                         |
   ||                          || set                 |                         |
   +---------------------------+----------------------+-------------------------+
   | YHR_DEVICE_OBJECT_EXISTS  || An object with the  | NTE_EXISTS              |
   |                           || specified ID already|                         |
   |                           || exists              |                         |
   +---------------------------+----------------------+-------------------------+
   || YHR_DEVICE_OBJECT        | Object not found     | NTE_NOT_FOUND           |
   || _NOT_FOUND               |                      |                         |
   +---------------------------+----------------------+-------------------------+
   | YHR_DEVICE_OK             | No error             | NTE_OP_OK               |
   +---------------------------+----------------------+-------------------------+
   | YHR_DEVICE_SESSION_FAILED || Session creation    | NTE_DEVICE_NOT_READY    |
   |                           || failed              |                         |
   +---------------------------+----------------------+-------------------------+
   | YHR_DEVICE_SESSIONS_FULL  || All sessions are    | NTE_DEVICE_NOT_READY    |
   |                           || allocated           |                         |
   +---------------------------+----------------------+-------------------------+
   | YHR_DEVICE_STORAGE_FAILED | Storage failure      || NTE_TOKEN_KEYSET       |
   |                           |                      || _STORAGE_FULL          |
   +---------------------------+----------------------+-------------------------+
   | YHR_DEVICE_WRONG_LENGTH   | Wrong length         | NTE_BAD_LEN             |
   +---------------------------+----------------------+-------------------------+
   | YHR_GENERIC_ERROR         | Generic error        | NTE_FAIL                |
   +---------------------------+----------------------+-------------------------+
   | YHR_INIT_ERROR            || Unable to initialize| NTE_PROVIDER_DLL_FAIL   |
   |                           || libyubihsm          |                         |
   +---------------------------+----------------------+-------------------------+
   | YHR_INVALID_PARAMETERS    || Invalid argument to | NTE_INVALID_PARAMETER   |
   |                           || a function          |                         |
   +---------------------------+----------------------+-------------------------+
   || YHR_MAC_MISMATCH         || Unable to verify MAC|| NTE_BAD_SIGNATURE      |
   +---------------------------+----------------------+-------------------------+
   || YHR_MEMORY_ERROR         || The YubiHSM or      || NTE_NO_MEMORY          |
   |                           || software library was|                         |
   |                           || not able to allocate|                         |
   |                           || memory to perform   |                         |
   |                           || the requested       |                         |
   |                           || operation           |                         |
   +---------------------------+----------------------+-------------------------+
   || YHR_SESSION              || Unable to           | NTE_INCORRECT_PASSWORD  |
   || _AUTHENTICATION_FAILED   || authenticate session|                         |
   +---------------------------+----------------------+-------------------------+
   | YHR_SUCCESS               || The operation       | ERROR_SUCCESS           |
   |                           || completed           |                         |
   |                           || Successfully        |                         |
   +---------------------------+----------------------+-------------------------+
   | YHR_WRONG_LENGTH          || This error may occur| NTE_BAD_LEN             |
   |                           || if there is a       |                         |
   |                           || mismatch between the|                         |
   |                           || YubiHSM firmware    |                         |
   |                           || version and         |                         |
   |                           || libyubihsm library  |                         |
   |                           || version             |                         |
   +---------------------------+----------------------+-------------------------+