PureBasic

SSH HSM Public Key Authentication

Demonstrates SSH public-key authentication using a private key stored on an HSM — a USB token or smart card — accessed through PKCS#11. A session is opened with the vendor's driver, the key handles are located, and an SshKey object is bound to them with UsePkcs11.

Background: The point of an HSM is that the private key is generated on the device and cannot be exported: the signing operation happens on the hardware, so the key material never reaches your application's memory or disk. Even a fully compromised host cannot yield a copy of the key. PKCS#11 is the vendor-neutral interface to such devices, which is why the driver path and the object-finding template are the only vendor-specific parts of this example.

Chilkat PureBasic Downloads

Download Chilkat for PureBasic

PureBasic

IncludeFile "CkPkcs11.pb"
IncludeFile "CkJsonObject.pb"
IncludeFile "CkSsh.pb"
IncludeFile "CkSshKey.pb"

Procedure ChilkatExample()

    success.i = 0

    ;  This example requires the Chilkat API to have been previously unlocked.
    ;  See Global Unlock Sample for sample code.

    ;  Demonstrates SSH public-key authentication using a private key stored on an HSM (a USB token
    ;  or smart card) accessed through PKCS#11.
    ;  
    ;  Note: Chilkat's PKCS#11 implementation runs on Windows, Linux, macOS, and other supported
    ;  operating systems.

    pkcs11.i = CkPkcs11::ckCreate()
    If pkcs11.i = 0
        Debug "Failed to create object."
        ProcedureReturn
    EndIf

    ;  The PKCS#11 driver supplied by your HSM vendor: a .dll on Windows, a .so on Linux, or a
    ;  .dylib on macOS.
    CkPkcs11::setCkSharedLibPath(pkcs11, "C:/Program Files (x86)/Gemalto/IDGo 800 PKCS#11/IDPrimePKCS1164.dll")

    ;  The PIN should come from a secure source rather than being hard-coded.
    pin.s = "0000"

    ;  Normal user = 1
    userType.i = 1

    success = CkPkcs11::ckQuickSession(pkcs11,userType,pin)
    If success = 0
        Debug CkPkcs11::ckLastErrorText(pkcs11)
        CkPkcs11::ckDispose(pkcs11)
        ProcedureReturn
    EndIf

    ;  Describe the private key object to be located on the HSM.
    json.i = CkJsonObject::ckCreate()
    If json.i = 0
        Debug "Failed to create object."
        ProcedureReturn
    EndIf

    CkJsonObject::ckUpdateString(json,"class","private_key")
    CkJsonObject::ckUpdateString(json,"label","MySshKey")

    priv_handle.i = CkPkcs11::ckFindObject(pkcs11,json)
    If priv_handle = 0
        Debug CkPkcs11::ckLastErrorText(pkcs11)
        CkPkcs11::ckDispose(pkcs11)
        CkJsonObject::ckDispose(json)
        ProcedureReturn
    EndIf

    ;  Find the corresponding public key by changing the class in the same template.
    CkJsonObject::ckUpdateString(json,"class","public_key")

    pub_handle.i = CkPkcs11::ckFindObject(pkcs11,json)
    If pub_handle = 0
        Debug CkPkcs11::ckLastErrorText(pkcs11)
        CkPkcs11::ckDispose(pkcs11)
        CkJsonObject::ckDispose(json)
        ProcedureReturn
    EndIf

    ;  Create an SSH key object that uses the HSM handles.  The key type may be "rsa" or "ec".
    key.i = CkSshKey::ckCreate()
    If key.i = 0
        Debug "Failed to create object."
        ProcedureReturn
    EndIf

    keyType.s = "rsa"
    success = CkSshKey::ckUsePkcs11(key,pkcs11,priv_handle,pub_handle,keyType)
    If success = 0
        Debug CkSshKey::ckLastErrorText(key)
        CkPkcs11::ckDispose(pkcs11)
        CkJsonObject::ckDispose(json)
        CkSshKey::ckDispose(key)
        ProcedureReturn
    EndIf

    ssh.i = CkSsh::ckCreate()
    If ssh.i = 0
        Debug "Failed to create object."
        ProcedureReturn
    EndIf

    port.i = 22
    success = CkSsh::ckConnect(ssh,"ssh.example.com",port)
    If success = 0
        Debug CkSsh::ckLastErrorText(ssh)
        CkPkcs11::ckDispose(pkcs11)
        CkJsonObject::ckDispose(json)
        CkSshKey::ckDispose(key)
        CkSsh::ckDispose(ssh)
        ProcedureReturn
    EndIf

    ;  The corresponding public key must already be installed on the SSH server for the account.
    ;  The signing operation happens on the HSM -- the private key never leaves the device.
    success = CkSsh::ckAuthenticatePk(ssh,"mySshLogin",key)
    If success = 0
        Debug CkSsh::ckLastErrorText(ssh)
        CkPkcs11::ckDispose(pkcs11)
        CkJsonObject::ckDispose(json)
        CkSshKey::ckDispose(key)
        CkSsh::ckDispose(ssh)
        ProcedureReturn
    EndIf

    Debug "Public-key authentication successful."

    CkSsh::ckDisconnect(ssh)

    CkPkcs11::ckLogout(pkcs11)
    CkPkcs11::ckCloseSession(pkcs11)


    CkPkcs11::ckDispose(pkcs11)
    CkJsonObject::ckDispose(json)
    CkSshKey::ckDispose(key)
    CkSsh::ckDispose(ssh)


    ProcedureReturn
EndProcedure