Interface Management

interface Management {
    getShadow(pin: string, path?: 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(path?: string): Promise<ScInfo | ErrorResponseNH>;
    getScLabel(pin: string, path?: string): Promise<ErrorResponseNH | ScLabel>;
    setScLabel(
        pin: string,
        label: string,
        path?: string,
    ): Promise<ErrorResponseNH | SucessResponseNH>;
    changeScPin(
        oldPin: string,
        newPin: string,
        path?: string,
    ): Promise<ErrorResponseNH | SucessResponseNH>;
    writeScSVMK(
        pin: string,
        shadow: string,
        overwrite: boolean,
        path?: string,
    ): Promise<ErrorResponseNH | SucessResponseNH>;
    eraseSmartCard(
        pin: string,
        path?: string,
    ): Promise<ErrorResponseNH | SucessResponseNH>;
    listObjs(): Promise<string[] | null[]>;
    setTlsBundle(key?: string, cert?: string): Promise<SucessResponse>;
    setUserParam(user: string, der: Buffer): Promise<SucessResponse>;
    deleteAuthSA(user: string, tfaType: TFA_TYPE): Promise<SucessResponse>;
    getUserAcl(user: string): Promise<AclList>;
    setUserAcl(user: string, acl: ACL_MASK[]): Promise<SucessResponse>;
    listBlobs(): Promise<string[]>;
    getObjectInfo(objId: string): Promise<ObjectInfo>;
    getObjectInfoModprobe(objId: string): Promise<ObjectInfo>;
}

Methods

getShadow setNsAuthState generateSVMK recoverSVMK getScInfo getScLabel setScLabel changeScPin writeScSVMK eraseSmartCard listObjs setTlsBundle setUserParam deleteAuthSA getUserAcl setUserAcl listBlobs getObjectInfo getObjectInfoModprobe

Methods

getShadow

  • getShadow(pin: string, path?: string): 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.

    • Optionalpath: string

      Optional attribute with the path to the dinamonh.exe utility.

    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 a smartcard reader certified by Dinamo Networks.

    OBS:Although it is possible to indicate the path of the Dinamo Native Host manually via the path attribute, Dinamo Networks recommends using it only in cases of severe restriction to the Windows registry or changes to the client's default installation method. Dinamo

    See

    Example code: Recovering the shadow of a smartcard

setNsAuthState

generateSVMK

  • generateSVMK(
        m: number,
        n: number,
        secret: null | string,
        version?: SVMK_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 parts, so that at least m parts are needed to reconstruct the original secret. No combination of m-1 parts reveals 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 response.

    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: string[]): 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. It 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 method. The number of parts provided 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(path?: string): Promise<ScInfo | ErrorResponseNH>

    Obtains information about the smart card.

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

    Parameters

    • Optionalpath: string

      Optional attribute with the path to the dinamonh.exe utility.

    Returns Promise<ScInfo | ErrorResponseNH>

    A Promise that resolves with an ScInfo object containing the smart card information in case of success, or rejects with an ErrorResponseNH object in case of 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

    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 a smartcard reader certified by Dinamo Networks.

    OBS:Although it is possible to indicate the path of the Dinamo Native Host manually via the path attribute, Dinamo Networks recommends using it only in cases of severe restriction to the Windows registry or changes to the client's default installation method. Dinamo

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

    See

    Example code: Retrieving information from a smartcard

getScLabel

  • getScLabel(pin: string, path?: string): Promise<ErrorResponseNH | ScLabel>

    Get the smart card label.

    Parameters

    • pin: string

      The smart card PIN.

    • Optionalpath: string

      Optional attribute with the path to the dinamonh.exe utility.

    Returns Promise<ErrorResponseNH | ScLabel>

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

    Throws

    If an error occurs.

    Remarks

    The smart card label is returned in a ScLabel object. In the event of an error, an ErrorResponseNH object is returned, containing the status and error code.

    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 a smartcard reader certified by Dinamo Networks.

    OBS:Although it is possible to indicate the path of the Dinamo Native Host manually via the path attribute, Dinamo Networks recommends using it only in cases of severe restriction to the Windows registry or changes to the client's default installation method. Dinamo

    See

    Example code: Retrieving the label from a smartcard

setScLabel

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

    Define the smart card label.

    Parameters

    • pin: string

      The smart card PIN.

    • label: string

      The new label to be defined.

    • Optionalpath: string

      Optional attribute with the path to the dinamonh.exe utility.

    Returns Promise<ErrorResponseNH | SucessResponseNH>

    A Promise that resolves with a SuccessResponseNH object in the event of success, or rejects with an ErrorResponseNH object in the event of an error.

    Throws

    If an error occurs.

    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 a smartcard reader certified by Dinamo Networks.

    OBS:Although it is possible to indicate the path of the Dinamo Native Host manually via the path attribute, Dinamo Networks recommends using it only in cases of severe restriction to the Windows registry or changes to the client's default installation method. Dinamo

changeScPin

  • changeScPin(
        oldPin: string,
        newPin: string,
        path?: string,
    ): 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.

    • Optionalpath: string

      Optional attribute with the path to the dinamonh.exe utility.

    Returns Promise<ErrorResponseNH | SucessResponseNH>

    A Promise that resolves with a SuccessResponseNH object in the event of success, or rejects with an ErrorResponseNH object in the event of an error.

    Throws

    If an error occurs.

    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 a smartcard reader certified by Dinamo Networks.

    OBS:Although it is possible to indicate the path of the Dinamo Native Host manually via the path attribute, Dinamo Networks recommends using it only in cases of severe restriction to the Windows registry or changes to the client's default installation method. Dinamo

writeScSVMK

  • writeScSVMK(
        pin: string,
        shadow: string,
        overwrite: boolean,
        path?: string,
    ): 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.

    • Optionalpath: string

      Optional attribute with the path to the dinamonh.exe utility.

    Returns Promise<ErrorResponseNH | SucessResponseNH>

    A Promise that resolves with a SuccessResponseNH object in the event of success, or rejects with an ErrorResponseNH object 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 is false.

    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 a smartcard reader certified by Dinamo Networks.

    OBS:Although it is possible to indicate the path of the Dinamo Native Host manually via the path attribute, Dinamo Networks recommends using it only in cases of severe restriction to the Windows registry or changes to the client's default installation method. Dinamo

    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: string,
        path?: string,
    ): 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.

    • Optionalpath: string

      Optional attribute with the path to the dinamonh.exe utility.

    Returns Promise<ErrorResponseNH | SucessResponseNH>

    A Promise that resolves with a SuccessResponseNH object in the event of success, or rejects with an ErrorResponseNH object 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

    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 a smartcard reader certified by Dinamo Networks.

    OBS:Although it is possible to indicate the path of the Dinamo Native Host manually via the path attribute, Dinamo Networks recommends using it only in cases of severe restriction to the Windows registry or changes to the client's default installation method. Dinamo

    Warning: This operation is irreversible and will erase all the data on the smart card. Make sure you want to erase the smart card before using this method.

listObjs

  • listObjs(): Promise<string[] | null[]>

    Lists the objects stored in the HSM.

    Returns Promise<string[] | null[]>

    A Promise that resolves to an array of strings, containing list of objects contained in the HSM partition.

    Throws

    If an error occurs during communication with the HSM, such as connection problems or errors in the HSM's response.

    See

    Example code: Listing objects in an HSM partition

setTlsBundle

  • setTlsBundle(key?: string, cert?: string): Promise<SuccessResponse>

    Enable TLS Bundle in HSM

    Parameters

    • Optionalkey: string

      Id of the private key in string.

    • Optionalcert: string

      Certificate id in string.

    Returns Promise<SucessResponse>

    A promise that resolves with a SuccessResponse object in case of success, or rejects with an error in case of failure.

    Remarks

    If key and cert are omitted, the TLS Bundle will be reset to the default OEM state.

    Throws

    HsmError If an error occurs during communication with the HSM.

setUserParam

  • setUserParam(user: string, der: Buffer): Promise<SuccessResponse>

    Enable second factor authentication (TFA) for a user

    Parameters

    • user: string

      User identifier

    • der: Buffer

      Certificate used to enable x509.

    Returns Promise<SucessResponse>

    A promise that resolves with a SuccessResponse object in case of success, or rejects with an error in case of failure.

    Throws

    HsmError If an error occurs during communication with the HSM.

deleteAuthSA

  • deleteAuthSA(user: string, tfaType: TFA_TYPE): Promise<SuccessResponse>

    Removes Second Authentication Factor (TFA) assigned to a user

    Parameters

    • user: string

      User identifier

    • tfaType: TFA_TYPE

      TFA identifier to be removed.

    Returns Promise<SucessResponse>

    A promise that resolves with a SuccessResponse object in case of success, or rejects with an error in case of failure.

    Throws

    HsmError If an error occurs during communication with the HSM.

getUserAcl

  • getUserAcl(user: string): Promise<AclList>

    Retrieves a user's ACL.

    Parameters

    • user: string

      User identifier

    Returns Promise<AclList>

    A promise that resolves with an acls-listed object in case of success, or rejects with an error in case of failure.

    Throws

    HsmError If an error occurs during communication with the HSM.

    See

    Example Code: Retrieving a user's ACLs from an HSM partition

setUserAcl

listBlobs

  • listBlobs(): Promise<string[]>

    Lists blobs stored in the HSM partition.

    Returns Promise<string[]>

    • Promise solved with an array of strings containing a list of blobs stored in the HSM partition.

    Throws

    exceptions.HsmError - Returned if an error is encountered.

    See

    Example code: Listing blobs in an HSM partition

getObjectInfo

getObjectInfoModprobe

  • getObjectInfoModprobe(objId: string): Promise<ObjectInfo>

    Returns information about an object stored in the HSM, avoiding possible noise in the log when trying to query objects that do not exist in the partition.

    Parameters

    • objId: string

      The identifier of the object in the HSM partition.

    Returns Promise<ObjectInfo>

    • Promise resolved with an ObjectInfo object containing information about the object.

    Throws

    exceptions.HsmError - Returned if an error is encountered.

    See

    Example code: Retrieving information from an object stored in the HSM

Settings

On This Page

Methods
MMNEPVFCICPMFPCPTTAAATR