Interface Management

interface Management {
    getShadow(pin: string): Promise<GetShadowResponse>;
    setNsAuthState(aclMask: ACL_MASK, state: NSAUTH_STATE, share: string[]): Promise<boolean>;
    generateSVMK(m: number, n: number, secret: null | string, version?: SVMK_VERSION): Promise<genSVMKResponse>;
    recoverSVMK(parts: string[]): Promise<string>;
    getScInfo(): Promise<ScInfo | ErrorResponseNH>;
    getScLabel(pin: string): Promise<ErrorResponseNH | ScLabel>;
    setScLabel(pin: string, label: string): Promise<ErrorResponseNH | SucessResponseNH>;
    changeScPin(oldPin: string, newPin: string): Promise<ErrorResponseNH | SucessResponseNH>;
    writeScSVMK(pin: string, shadow: string, overwrite: boolean): Promise<ErrorResponseNH | SucessResponseNH>;
    eraseSmartCard(pin: string): Promise<ErrorResponseNH | SucessResponseNH>;
}

Methods

getShadow setNsAuthState generateSVMK recoverSVMK getScInfo getScLabel setScLabel changeScPin writeScSVMK eraseSmartCard

Methods

getShadow

  • getShadow(pin): Promise<GetShadowResponse>

  • Reads the shadow of a smart card M from N Dinamo.

    Parameters

    • pin: string

      Card PIN. It must be an ASCII numeric string with a maximum length of 8.

    Returns Promise<GetShadowResponse>

    • Shadow read data.

    Throws

    exceptions.HsmError If an error occurs in the operation.

    Remarks

    NOTE: To carry out this operation, you need to install the HSM Client in the Full option on the device. You can download the HSM Client via this link. You must also use an approved smartcard reader to read the cards.

    See

    Example code: Recovering the shadow of a smartcard

setNsAuthState

generateSVMK

  • generateSVMK(m, n, secret, version?): Promise<genSVMKResponse>

  • Generate a Secret and divide it into parts using Shamir's secret sharing scheme.

    Parameters

    • m: number

      Minimum number of parts needed to reconstruct the secret. It must be greater than or equal to 2 and less than or equal to n.

    • n: number

      Total number of parts generated. Must be greater than or equal to m and less than or equal to 255.

    • secret: null | string

      Secret to be divided. If null or not supplied, a random secret will be generated. If supplied, it must be an ASCII string with a fixed length depending on the SVMK version.

    • Optionalversion: SVMK_VERSION

      Version of SVMK that determines the size of the secret. (Optional. Default value is 2)

    Returns Promise<genSVMKResponse>

    • An object containing the original secret (if supplied or generated), the entropy used (if the secret was generated), the parameters m and n, and the parts generated by the Shamir scheme.

    Throws

    exceptions.HsmError If an error occurs during operation, such as invalid parameters or a communication error with the HSM.

    Remarks

    Shamir's scheme allows you to divide a secret into n parties, so that at least m parts are needed to reconstruct the original secret. No combination of m-1 parties reveal any information about the secret.

    The SVMK version defines the size of the secret and the format of the parts. Version 2 introduces security improvements over version 1.

    If secret is null, a new random secret with the appropriate size (determined by the version) will be generated. The entropy used to generate the secret will be included in the answer.

    If secret is provided, it will be used as the secret to be split. Make sure that the secret is the correct size for the specified version.

    See

    Example code: Generating a Server Master Key and Splitting it into parts with Shamir

recoverSVMK

  • recoverSVMK(parts): Promise<string>

  • Recovers the SVMK (Server Master Key) from a set of parts generated by Shamir's secret sharing scheme.

    Parameters

    • parts: string[]

      Array of hexadecimal strings representing the parts of the SVMK. Must contain at least m valid parts, where m is the minimum number of parts defined during SVMK generation.

    Returns Promise<string>

    • The original secret reconstructed as a hexadecimal string.

    Throws

    exceptions.HsmError If an error occurs during operation, such as invalid parts, insufficient number of parts or communication error with the HSM.

    Remarks

    This method recovers the original SVMK from the parts provided. The parts must have been previously generated by the generateSVMK. The number of parts supplied must be equal to or greater than the value of m defined in the generation. The order of the parts does not matter.

    If the parts supplied are invalid (incorrect format, different sizes, etc.) or if the number of parts is insufficient, an error will be thrown.

    See

    Example code: Recovering a split Server Master Key with Shamir

getScInfo

  • getScInfo(): Promise<ScInfo | ErrorResponseNH>

  • Obtains information about the smart card.

    This method obtains detailed information about the smart card inserted in the reader.

    Returns Promise<ScInfo | ErrorResponseNH>

    A Promise that resolves with an object ScInfo containing the smart card information in case of success, or rejects with an object ErrorResponseNH in the event of an error.

    Throws

    If an error occurs during communication with the Native Host, such as:

    • Native Host executable not found.
    • Error starting the Native Host process.
    • Error parsing the JSON response from Native Host.
    • Timeout in operation.
    • Native Host terminated with error code.

    Remarks

    This method requires the HSM client to be installed and configured correctly.

    The smart card information is returned in an object ScInfowhich contains details such as ATR, CSN, chip version, etc. In the event of an error, an ErrorResponseNH is returned, containing the status and error code.

    See

    Example code: Retrieving information from a smartcard

getScLabel

  • getScLabel(pin): Promise<ErrorResponseNH | ScLabel>

  • Get the smart card label.

    Parameters

    • pin: string

      The smart card PIN.

    Returns Promise<ErrorResponseNH | ScLabel>

    A Promise that resolves with an object ScLabel containing the smart card label in case of success, or reject with a ErrorResponseNH in the event of an error.

    Throws

    If an error occurs.

    Remarks

    This method requires the HSM client to be installed and configured correctly. The smart card label is returned in a ScLabel. In the event of an error, an object ErrorResponseNH is returned, containing the status and error code.

    See

    Example code: Retrieving the label from a smartcard

setScLabel

  • setScLabel(pin, label): Promise<ErrorResponseNH | SuccessResponseNH>

  • Define the smart card label.

    Parameters

    • pin: string

      The smart card PIN.

    • label: string

      The new label to be defined.

    Returns Promise<ErrorResponseNH | SucessResponseNH>

    A Promise that resolves with an object SuccessResponseNH if successful, or reject with an object ErrorResponseNH in the event of an error.

    Throws

    If an error occurs.

    Remarks

    This method requires the HSM client to be installed and configured correctly. The smart card label will be updated with the value provided. In the event of an error, a ErrorResponseNH is returned, containing the status and error code.

changeScPin

  • changeScPin(oldPin, newPin): Promise<ErrorResponseNH | SuccessResponseNH>

  • Change the smart card PIN.

    Parameters

    • oldPin: string

      The current PIN of the smart card.

    • newPin: string

      New PIN to be defined.

    Returns Promise<ErrorResponseNH | SucessResponseNH>

    A Promise that resolves with an object SuccessResponseNH if successful, or reject with an object ErrorResponseNH in the event of an error.

    Throws

    If an error occurs.

    Remarks

    This method requires the HSM client to be installed and configured correctly. The smart card PIN will be updated with the new value provided. In the event of an error, a ErrorResponseNH is returned, containing the status and error code.

writeScSVMK

  • writeScSVMK(pin, shadow, overwrite): Promise<ErrorResponseNH | SuccessResponseNH>

  • Saves the SVMK (Server Master Key) on the smart card.

    Parameters

    • pin: string

      The smart card PIN. This must be a numeric string with exactly 8 digits.

    • shadow: string

      The shadow to be recorded, in hexadecimal format. It must be the correct size according to the SVMK version.

    • overwrite: boolean

      Indicates whether to overwrite an existing shadow. If false and a shadow already exists, the operation will fail.

    Returns Promise<ErrorResponseNH | SucessResponseNH>

    A Promise that resolves with an object SuccessResponseNH if successful, or reject with an object ErrorResponseNH in the event of an error.

    Throws

    If an error occurs, such as:

    • Invalid PIN.
    • Invalid shadow (incorrect format, incorrect size).
    • Attempt to overwrite an existing shadow when overwrite é false.

    Remarks

    This method requires the HSM client to be installed and configured correctly. The shadow provided will be stored on the smart card, allowing it to be used for authentication and other operations. Make sure that the shadow is valid and of the correct size according to the SVMK version.

eraseSmartCard

  • eraseSmartCard(pin): Promise<ErrorResponseNH | SuccessResponseNH>

  • Erases the contents of a smart card.

    Parameters

    • pin: string

      The smart card PIN. This must be a numeric string with exactly 8 digits.

    Returns Promise<ErrorResponseNH | SucessResponseNH>

    A Promise that resolves with an object SuccessResponseNH if successful, or reject with an object ErrorResponseNH in the event of an error.

    Throws

    If an error occurs, such as:

    • Invalid PIN.
    • Communication error with the HSM.
    • Smart card not found or not accessible.

    Remarks

    This method requires the HSM client to be installed and configured correctly. Warning: This operation is irreversible and will erase all the data on the smart card. Make sure you want to delete the smart card before calling up this method.

Settings

On This Page

Methods