PureBasic

SSH Authenticate using a Smart Card Private Key

Demonstrates using a private key stored on an HSM (smart card or token) for SSH public-key authentication. A JSON template locates the private and public key objects by class, key type, and label, and the returned handles are bound to an SshKey object.

Background: PKCS#11 objects are found by attribute rather than by name alone, which is why a template describing the class, key type, and label is used. An important practical detail is that the returned handles are valid only for the lifetime of the PKCS#11 session — they cannot be cached and reused later, so a subsequent session must locate the objects again. Logging out and closing the session when finished releases the device for other applications.

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 using a private key stored on an HSM (smart card or token) for SSH public-key
    ;  authentication.  Public-key authentication means the client uses the private key, while the
    ;  corresponding public key is installed on the server under the SSH account.
    ;  
    ;  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

    ;  Use the PKCS#11 driver (.dll, .so, or .dylib) for your particular HSM.
    CkPkcs11::setCkSharedLibPath(pkcs11, "C:/Program Files (x86)/Gemalto/IDGo 800 PKCS#11/IDPrimePKCS11.dll")

    ;  The HSM 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

    ;  Provide a template describing the PKCS#11 object to find: an RSA private key labeled
    ;  "MySshKey".  For how such a key is originally imported, see
    ;  PKCS11 Import SSH Key
    jsonTemplate.i = CkJsonObject::ckCreate()
    If jsonTemplate.i = 0
        Debug "Failed to create object."
        ProcedureReturn
    EndIf

    CkJsonObject::ckUpdateString(jsonTemplate,"class","private_key")
    CkJsonObject::ckUpdateString(jsonTemplate,"key_type","rsa")
    CkJsonObject::ckUpdateString(jsonTemplate,"label","MySshKey")

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

    ;  The handle is only valid for the duration of this PKCS#11 session.  To use the key in a
    ;  later session, find it again.
    Debug "private key handle: " + Str(privKeyHandle)

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

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

    Debug "public key handle: " + Str(pubKeyHandle)

    ;  Create an empty SSH key object and tell it to use the PKCS#11 handles, indicating the key type.
    sshKey.i = CkSshKey::ckCreate()
    If sshKey.i = 0
        Debug "Failed to create object."
        ProcedureReturn
    EndIf

    success = CkSshKey::ckUsePkcs11(sshKey,pkcs11,privKeyHandle,pubKeyHandle,"rsa")
    If success = 0
        Debug CkSshKey::ckLastErrorText(sshKey)
        CkPkcs11::ckDispose(pkcs11)
        CkJsonObject::ckDispose(jsonTemplate)
        CkSshKey::ckDispose(sshKey)
        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(jsonTemplate)
        CkSshKey::ckDispose(sshKey)
        CkSsh::ckDispose(ssh)
        ProcedureReturn
    EndIf

    ;  Authentication uses the existing PKCS#11 session.  The signing happens on the smart card --
    ;  the private key never leaves the device.
    success = CkSsh::ckAuthenticatePk(ssh,"mySshLogin",sshKey)
    If success = 0
        Debug CkSsh::ckLastErrorText(ssh)
        CkPkcs11::ckDispose(pkcs11)
        CkJsonObject::ckDispose(jsonTemplate)
        CkSshKey::ckDispose(sshKey)
        CkSsh::ckDispose(ssh)
        ProcedureReturn
    EndIf

    Debug "Public-key authentication successful."

    ;  ... use the authenticated SSH session ...

    CkSsh::ckDisconnect(ssh)

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


    CkPkcs11::ckDispose(pkcs11)
    CkJsonObject::ckDispose(jsonTemplate)
    CkSshKey::ckDispose(sshKey)
    CkSsh::ckDispose(ssh)


    ProcedureReturn
EndProcedure