Class SmartCardHSM
Class implementing support for SmartCard-HSM access
Defined in: SmartCardHSM.js.
| Constructor Attributes | Constructor Name and Description |
|---|---|
|
SmartCardHSM(card)
Create a SmartCard-HSM access object
|
| Method Attributes | Method Name and Description |
|---|---|
|
addCACertificateToMap(cert, id, label)
Add a new CA certificate to the map
|
|
|
addKeyToMap(key)
Add a new key to the map of keys
|
|
|
associateXKEKKeyDomain(keyDomain, keyDomainUID, keyDomainAssociation, keyDomainAssociation)
Associate XKEK Key Domain
|
|
| <static> |
SmartCardHSM.buildCertDescription(commonObjectFlags, label, pubKey, certFID)
Create a PKCS#15 certificate description
|
| <static> |
SmartCardHSM.buildGAKPwithECC(innerCAR, algo, chr, dp, outerCAR, privateKey)
Build input for Generate Asymmetric Key Pair command for generating an ECC key pair
|
| <static> |
SmartCardHSM.buildGAKPwithRSA(innerCAR, algo, chr, keysize, outerCAR)
Build input for Generate Asymmetric Key Pair command for generating a RSA key pair
|
| <static> |
SmartCardHSM.buildPrkDforECC(keyid, label, keysize)
Create a PKCS#15 PrivateECCKey description
|
| <static> |
SmartCardHSM.buildPrkDforRSA(keyid, label, modulussize)
Create a PKCS#15 PrivateRSAKey description
|
| <static> |
SmartCardHSM.buildSKDforAES(keyid, label, keysize)
Create a PKCS#15 SecretKey description
|
|
changeInitializationCode(initializationCode, newInitializationCode)
Change InitializationCode
|
|
|
changeUserPIN(currentPIN, newPIN)
Change User PIN
|
|
|
createXKEKKeyDomain(keyDomain, keyDomainMembership, keyDomainMembership)
Create XKEK Key Domain
|
|
|
decipher(keyid, algo, data)
Decipher cryptogram or agree shared secret using Diffie-Hellman
|
|
| <static> |
SmartCardHSM.decodeAlgorithmList(list)
Decode algorithm list and return string array with names
|
|
deleteFile(fid)
Delete file system object (EF or key)
|
|
|
deleteKEK(keyDomain)
Delete the key encryption key in a key domain
|
|
|
deleteKeyDomain(keyDomain)
Delete the empty key domain
|
|
|
deriveSymmetricKey(id, algo, derivationParam)
Derive Symmetric Key
|
|
|
deriveXKEK(keyDomain, derivationParam, derivationParam)
Derive XKEK
|
|
|
Determine an unused CA certificate identifier
|
|
|
Determine an unused key identifier
|
|
| <static> |
SmartCardHSM.disableUTSRCA()
Remove Root Certificate of Development SRCA
Always call this on a productive system
|
| <static> |
SmartCardHSM.dumpKeyData(keydata)
Dump C-Data of Generate Asymmetric Key Pair command
|
| <static> |
SmartCardHSM.encodeAlgorithmList(list)
Parse and encode the algorithm list containing either algorithm ids or names
|
|
Enumerate CA certificates
|
|
|
Enumerate key objects in the SmartCard-HSM and build the map of keys
|
|
|
Enumerate Objects
|
|
|
generateAsymmetricKeyPair(newkid, signkid, keydata)
Generate an asymmetric key pair
|
|
|
generateRandom(length)
Generate random data
|
|
|
generateSymmetricKey(newkid, algo, keydata)
Generate a symmetric key
|
|
|
getCACertificate(label)
Return CA certificate with label
|
|
|
Get crypto object
|
|
|
Determine free memory
|
|
|
getKey(labelOrId)
Get a key reference object
|
|
|
Get key ids
|
|
|
getKeys()
Return a list of key objects
|
|
|
getLabel()
Get Token Label
|
|
|
Return the native OCF SmartCardHSMCardService
|
|
|
Get ProvisioningURL
|
|
|
Get Key Check Value of Token Management Key
|
|
|
Get salt for SO-PIN derivation using the Token Management Key
|
|
|
Return a string describing the SmartCard-HSM Version
|
|
|
hasFile(fid)
Try selecting the file to see if is present
|
|
|
importEncryptedKeyShare(keyshare, password, keyDomain)
Decrypt and import a DKEK share
|
|
|
importKeyShare(keyDomain, keyshare)
Import DKEK share or query status
|
|
|
initDevice(options, initialPIN, initializationCode, retryCounterInitial, keyshares)
Initialize device and clear all keys and files
|
|
|
Return true is SmartCard-HSM is initialized
|
|
|
Check if the RESET RETRY COUNTER command can reset the PIN
|
|
|
Check if the RESET RETRY COUNTER command is enabled
|
|
|
logout()
Logout
|
|
|
openSecureChannel(crypto, devAuthPK)
Open a secure channel using device authentication
|
|
| <static> |
SmartCardHSM.parseCertificateList(a)
Parse list of CVC in a binary blob
|
|
parseKeyDomainStatus(status)
Parse the key domain status returned from the device
|
|
|
Request Initialization Code Status
|
|
|
queryKeyDomainStatus(keyDomain)
Query the status of the key domain
|
|
|
queryPINStatus(p2)
Request PIN Status Information
|
|
|
Request PIN Status Information
|
|
|
readBinary(fid, offset, length)
Read transparent EF referenced by file identifier
|
|
|
selectFile(fid)
Select the file or key an return the FCP
|
|
|
sign(keyid, algo, data)
Sign data using referenced key
|
|
| <static> |
SmartCardHSM.stripLeadingZeros(value)
Strips leading zeros of a ByteString
|
|
unblockUserPIN(initializationCode, newPIN)
Unblock and set User PIN
|
|
|
unwrapAndReplaceKey(id, keyblob)
Replace symmetric key value encrypted under current key
|
|
|
unwrapKey(id, keyblob)
Unwrap key with DKEK
|
|
|
updateBinary(fid, offset, data)
Update transparent EF referenced by file identifier
|
|
|
updateKey(key)
Update key attributes, in particular the use counter
|
|
|
validateCertificateChain(crypto)
Validate device certificate chain
|
|
| <static> |
SmartCardHSM.validateCertificateChain(crypto, devAutCert)
Validate device certificate chain
|
|
verifyCertificate(cvc)
Verify card verifiable certificate
|
|
|
verifyUserPIN(userPIN)
Verify User PIN
|
|
|
wrapKey(id)
Wrap key under DKEK
|
Class Detail
SmartCardHSM(card)
Create a SmartCard-HSM access object
- Parameters:
- {Card} card
- the card object
Method Detail
addCACertificateToMap(cert, id, label)
Add a new CA certificate to the map
- Parameters:
- {X509} cert
- the CA certificate
- {Number} id
- the corresponding id
- {String} label
- the corresponding label
addKeyToMap(key)
Add a new key to the map of keys
- Parameters:
- {HSMKey} key
- the HSM key
{Object}
associateXKEKKeyDomain(keyDomain, keyDomainUID, keyDomainAssociation, keyDomainAssociation)
Associate XKEK Key Domain
- Parameters:
- {Number} keyDomain
- number of key domain in the range 0 to the maximum defined in the INITIALIZE DEVICE command
- {ByteString} keyDomainUID
- a encoded TLV object with tag 51 containing the key domain uid of the associated domain
- {ByteString} keyDomainAssociation
- a encoded TLV object with tag 56 or 57
- keyDomainAssociation
- Returns:
- object with properties sw{Number}, shares{Number}, outstanding{Number}, kcv{ByteString} and the key domain UID{ByteString}
<static>
{ASN1}
SmartCardHSM.buildCertDescription(commonObjectFlags, label, pubKey, certFID)
Create a PKCS#15 certificate description
- Parameters:
- {ByteString} commonObjectFlags
- default value is '0640'
- {String} label
- the key label
- {Key} pubKey
- the public key
- {ByteString} certFID
- the file identifier of the certificate
- Returns:
- the PrivateECCKey description
<static>
{ByteString}
SmartCardHSM.buildGAKPwithECC(innerCAR, algo, chr, dp, outerCAR, privateKey)
Build input for Generate Asymmetric Key Pair command for generating an ECC key pair
- Parameters:
- {PublicKeyReference} innerCAR
- the CA the request shall be directed to
- {ByteString} algo
- the public key algorithm
- {PublicKeyReference} chr
- the certificate holder reference associated with this key
- {Key} dp
- the domain parameter for the key
- {PublicKeyReference} outerCAR
- the certificate holder reference of the public key for verifying the outer signature
- {Key} privateKey
- optional parameter to supply a private key value for import. This only works with the development version of the SmartCard-HSM.
- Returns:
- the encoded C-Data for GENERATE ASYMMETRIC KEY PAIR
<static>
{ByteString}
SmartCardHSM.buildGAKPwithRSA(innerCAR, algo, chr, keysize, outerCAR)
Build input for Generate Asymmetric Key Pair command for generating a RSA key pair
- Parameters:
- {PublicKeyReference} innerCAR
- the CA the request shall be directed to
- {ByteString} algo
- the public key algorithm
- {PublicKeyReference} chr
- the certificate holder reference associated with this key
- {Number} keysize
- the module size in bits (1024, 1536 or 2048)
- {PublicKeyReference} outerCAR
- the certificate holder reference of the public key for verifying the outer signature
- Returns:
- the encoded C-Data for GENERATE ASYMMETRIC KEY PAIR
<static>
{ASN1}
SmartCardHSM.buildPrkDforECC(keyid, label, keysize)
Create a PKCS#15 PrivateECCKey description
- Parameters:
- {Number/ByteString} keyid
- the key identifier
- {String} label
- the key label
- keysize
- Returns:
- the PrivateECCKey description
<static>
{ASN1}
SmartCardHSM.buildPrkDforRSA(keyid, label, modulussize)
Create a PKCS#15 PrivateRSAKey description
- Parameters:
- {Number/ByteString} keyid
- the key identifier
- {String} label
- the key label
- {Number} modulussize
- Returns:
- the PrivateECCKey description
<static>
{ASN1}
SmartCardHSM.buildSKDforAES(keyid, label, keysize)
Create a PKCS#15 SecretKey description
- Parameters:
- {Number/ByteString} keyid
- the key identifier
- {String} label
- the key label
- {Number} keysize
- Returns:
- the secret key description
changeInitializationCode(initializationCode, newInitializationCode)
Change InitializationCode
- Parameters:
- {ByteString} initializationCode
- current initialization code
- {ByteString} newInitializationCode
- new initialization code
changeUserPIN(currentPIN, newPIN)
Change User PIN
- Parameters:
- {ByteString} currentPIN
- current user PIN value
- {ByteString} newPIN
- new user PIN value
{Object}
createXKEKKeyDomain(keyDomain, keyDomainMembership, keyDomainMembership)
Create XKEK Key Domain
- Parameters:
- {Number} keyDomain
- number of key domain in the range 0 to the maximum defined in the INITIALIZE DEVICE command
- {ByteString} keyDomainMembership
- either a 64 byte signature (old format) or a encoded TLV object with tag 54 or 55
- keyDomainMembership
- Returns:
- object with properties sw{Number}, shares{Number}, outstanding{Number}, kcv{ByteString} and the key domain UID{ByteString}
decipher(keyid, algo, data)
Decipher cryptogram or agree shared secret using Diffie-Hellman
- Parameters:
- {Number} keyid
- the key identifier
- {Number} algo
- the algorithm identifier
- {ByteString} data
- the the cryptogram or concatenation of x || y of ECC public key
- Returns:
- the plain output
<static>
{String[]}
SmartCardHSM.decodeAlgorithmList(list)
Decode algorithm list and return string array with names
- Parameters:
- {ByteString} list
- the algorithm list, e.g. as returned in the key meta data
- Returns:
- the list of algorithm names
deleteFile(fid)
Delete file system object (EF or key)
- Parameters:
- {ByteString} fid
- the two byte file object identifier
deleteKEK(keyDomain)
Delete the key encryption key in a key domain
- Parameters:
- {Number} keyDomain
- the number of the key domain
deleteKeyDomain(keyDomain)
Delete the empty key domain
- Parameters:
- {Number} keyDomain
- the number of the key domain
{ByteString}
deriveSymmetricKey(id, algo, derivationParam)
Derive Symmetric Key
- Parameters:
- {Number} id
- key id
- {Number} algo
- algorithm id (one of ALG_CBC_ENC, ALG_CBC_DEC, ALG_CMAC or ALG_DERIVE_SP800_56C)
- {ByteString} derivationParam
- the derivation parameter
- Returns:
- derived key value
{Object}
deriveXKEK(keyDomain, derivationParam, derivationParam)
Derive XKEK
- Parameters:
- {Number} keyDomain
- number of key domain in the range 0 to the maximum defined in the INITIALIZE DEVICE command
- {ByteString} derivationParam
- derivationParam
- Returns:
- object with properties sw{Number}, shares{Number}, outstanding{Number}, kcv{ByteString} and the key domain UID{ByteString}
{Number}
determineFreeCAId()
Determine an unused CA certificate identifier
- Returns:
- a free CA certificate identifier or -1 if all identifier in use
{Number}
determineFreeKeyId()
Determine an unused key identifier
- Returns:
- a free key identifier or -1 if all key identifier in use
<static>
SmartCardHSM.disableUTSRCA()
Remove Root Certificate of Development SRCA
Always call this on a productive system
<static>
SmartCardHSM.dumpKeyData(keydata)
Dump C-Data of Generate Asymmetric Key Pair command
- Parameters:
- {ByteString} keydata
- the content of C-Data
<static>
{ByteString}
SmartCardHSM.encodeAlgorithmList(list)
Parse and encode the algorithm list containing either algorithm ids or names
- Parameters:
- {String | String[]} list
- the list of algorithms
- Returns:
- the algorithm list
{String[]}
enumerateCACertificates()
Enumerate CA certificates
- Returns:
- the list of certificate labels
{String[]}
enumerateKeys()
Enumerate key objects in the SmartCard-HSM and build the map of keys
- Returns:
- the list of key labels
enumerateObjects()
Enumerate Objects
- Returns:
- the enumeration
{ByteString}
generateAsymmetricKeyPair(newkid, signkid, keydata)
Generate an asymmetric key pair
- Parameters:
- {Number} newkid
- key identifier for new key
- {Number} signkid
- key identifier for signing the new public key
- {ByteString} keydata
- the key data template
- Returns:
- the certificate signing request containing the new public key
generateRandom(length)
Generate random data
- Parameters:
- {Number} length
- number of bytes
- Returns:
- the random bytes
{ByteString}
generateSymmetricKey(newkid, algo, keydata)
Generate a symmetric key
- Parameters:
- {Number} newkid
- key identifier for new key
- {Number} algo
- key generation algorithm
- {ByteString} keydata
- the key data template
- Returns:
{ByteString}
getCACertificate(label)
Return CA certificate with label
- Parameters:
- {String} label
- the certificate label
- Returns:
- the encoded certificate
{HSMCrypto}
getCrypto()
Get crypto object
- Returns:
- the HSMCrypto object
{Number}
getFreeMemory()
Determine free memory
- Returns:
- the number of available bytes (this values is capped to 32767 on JCOP 2.4.1)
{Key}
getKey(labelOrId)
Get a key reference object
- Parameters:
- {String/Number/ByteString} labelOrId
- label or id of key
- Returns:
- the key or null if not found
{Number[]}
getKeyIds()
Get key ids
- Returns:
- a list of key identifier
{SmartCardHSMKey[]}
getKeys()
Return a list of key objects
- Returns:
- the list of keys
{String}
getLabel()
Get Token Label
- Returns:
- the token label from CIAInfo
{de.cardcontact.opencard.service.smartcardhsm.SmartCardHSMCardService}
getNativeCardService()
Return the native OCF SmartCardHSMCardService
- Returns:
- the OCF SmartCardHSMCardService
{String}
getProvisioningURL()
Get ProvisioningURL
- Returns:
- the configured ProvisioningURL or undefined
{ByteString}
getTokenManagementKeyKCV()
Get Key Check Value of Token Management Key
- Returns:
- the configured KCV of the Token Management Key or undefined
{ByteString}
getTokenManagementKeySalt()
Get salt for SO-PIN derivation using the Token Management Key
- Returns:
- the configured salt
{String}
getVersionInfo()
Return a string describing the SmartCard-HSM Version
- Returns:
- the version string
hasFile(fid)
Try selecting the file to see if is present
- Parameters:
- {ByteString} fid
- the two byte file object identifier
importEncryptedKeyShare(keyshare, password, keyDomain)
Decrypt and import a DKEK share
- Parameters:
- {ByteString} keyshare
- the encrypted key share as read from the .pbe file
- {ByteString} password
- the password
- {Number} keyDomain
- the number of the key domain
- Returns:
- object with properties sw{Number}, shares{Number}, outstanding{Number} and kcv{ByteString}
{Object}
importKeyShare(keyDomain, keyshare)
Import DKEK share or query status
- Parameters:
- {Number} keyDomain
- the number of the key domain
- {ByteString} keyshare
- 32 byte key share
- Returns:
- object with properties sw{Number}, shares{Number}, outstanding{Number} and kcv{ByteString}
initDevice(options, initialPIN, initializationCode, retryCounterInitial, keyshares)
Initialize device and clear all keys and files
- Parameters:
- {ByteString} options
- two byte option mask
- {ByteString} initialPIN
- initial user PIN value
- {ByteString} initializationCode
- secret code for device initialization (set during first use)
- {Number} retryCounterInitial
- retry counter for user PIN
- {Number} keyshares
- number of device key encryption key shares (optional)
{Boolean}
isInitialized()
Return true is SmartCard-HSM is initialized
- Returns:
- true if initialized
{Boolean}
isPINResetEnabled()
Check if the RESET RETRY COUNTER command can reset the PIN
- Returns:
- true if enable during initialization
{Boolean}
isResetRetryCounterEnabled()
Check if the RESET RETRY COUNTER command is enabled
- Returns:
- true if enable during initialization
logout()
Logout
{ISOSecureChannel}
openSecureChannel(crypto, devAuthPK)
Open a secure channel using device authentication
- Parameters:
- {Crypto} crypto
- the crypto provider to use
- {Key} devAuthPK
- the device authentication public key
- {Number} Key.AES
- or Key.DES to request AES or DES secure messaging (Default probe)
- Returns:
- the initialized secure channel
<static>
{CVC[]}
SmartCardHSM.parseCertificateList(a)
Parse list of CVC in a binary blob
- Parameters:
- {ByteString} a
- binary blob (e.g an EF) containing concatenated CVCs
- Returns:
- the list of CVCs
{object}
parseKeyDomainStatus(status)
Parse the key domain status returned from the device
- Parameters:
- {ByteString} status
- the R-DATA from the MANAGE KEY DOMAIN command
- Returns:
- the decoded status Info
{Number}
queryInitializationCodeStatus()
Request Initialization Code Status
- Returns:
- the status word SW1/SW2 returned by the device
{Object}
queryKeyDomainStatus(keyDomain)
Query the status of the key domain
- Parameters:
- {Number} keyDomain
- the number of the key domain which will be queried, default is 0
- Returns:
- object with properties sw{Number}, shares{Number}, outstanding{Number}, kcv{ByteString} and for a XKEK key domain the key domain UID{ByteString}
{Number}
queryPINStatus(p2)
Request PIN Status Information
- Parameters:
- {Number} p2
- the PIN object id
- Returns:
- the status word SW1/SW2 returned by the device
{Number}
queryUserPINStatus()
Request PIN Status Information
- Returns:
- the status word SW1/SW2 returned by the device
{ByteString}
readBinary(fid, offset, length)
Read transparent EF referenced by file identifier
- Parameters:
- {ByteString} fid
- the two byte file identifier (optional - use currently selected EF if absent)
- {Number} offset
- the offset into the EF (optional)
- {Number} length
- the number of byte to read (optional)
- Returns:
- the data read from the EF
selectFile(fid)
Select the file or key an return the FCP
- Parameters:
- {ByteString} fid
- the two byte file object identifier
sign(keyid, algo, data)
Sign data using referenced key
- Parameters:
- {Number} keyid
- the key identifier for signing
- {algo} algo
- the algorithm identifier
- {ByteString} data
- the data to be signed
- Returns:
- the signature value
<static>
{ByteString}
SmartCardHSM.stripLeadingZeros(value)
Strips leading zeros of a ByteString
- Parameters:
- {ByteString} value
- the ByteString value
- Returns:
- the stripped ByteString object, may be an empty ByteString
unblockUserPIN(initializationCode, newPIN)
Unblock and set User PIN
- Parameters:
- {ByteString} initializationCode
- the initialization code
- {ByteString} newPIN
- new user PIN value (optional)
unwrapAndReplaceKey(id, keyblob)
Replace symmetric key value encrypted under current key
- Parameters:
- {Number} id
- key id
- {ByteString} keyblob
- the wrapped key
unwrapKey(id, keyblob)
Unwrap key with DKEK
- Parameters:
- {Number} id
- key id
- {ByteString} keyblob
- the wrapped key
updateBinary(fid, offset, data)
Update transparent EF referenced by file identifier
- Parameters:
- {ByteString} fid
- the two byte file identifier
- {Number} offset
- the offset into the EF
- {ByteString} data
- the data to write
updateKey(key)
Update key attributes, in particular the use counter
- Parameters:
- {HSMKey} key
- the HSM key
{Key}
validateCertificateChain(crypto)
Validate device certificate chain
- Parameters:
- {Crypto} crypto
- the crypto provider to use
- Returns:
- the device authentication public key
<static>
{Key}
SmartCardHSM.validateCertificateChain(crypto, devAutCert)
Validate device certificate chain
- Parameters:
- {Crypto} crypto
- the crypto provider to use
- {ByteString} devAutCert
- the device certificate chain read from EF.C_DevAut
- Returns:
- the device authentication public key
verifyCertificate(cvc)
Verify card verifiable certificate
- Parameters:
- {CVC} cvc
- the card verifiable certificate
verifyUserPIN(userPIN)
Verify User PIN
- Parameters:
- {ByteString} userPIN
- user PIN value
- Returns:
- the status word SW1/SW2 returned by the device
{ByteString}
wrapKey(id)
Wrap key under DKEK
- Parameters:
- {Number} id
- key id
- Returns:
- key blob with encrypted key value