Telematics SDK - API Reference
v1.63.4
|
Typedefs | |
using | telux::sec::CryptoOperationTypes = int32_t |
using | telux::sec::BlockModeTypes = int32_t |
using | telux::sec::PaddingTypes = int32_t |
using | telux::sec::DigestTypes = int32_t |
using | telux::sec::AlgorithmTypes = int32_t |
using | telux::sec::CurveTypes = int32_t |
Variables | |
static const uint32_t | telux::sec::CA_RESULT_DATA_LENGTH = 96 |
This section contains APIs related to security management.
struct telux::sec::LoadConfig |
struct telux::sec::CACapacity |
Represents curve-wise absolute capacity. This value represents capacity as if only that type of curve is used in all crypto operations. For example, a capacity of 3000 for sm2 means, 3000 signature verifications of type sm2 can be done under current operating conditions, when no other type of verifications are performed.
Data Fields | ||
---|---|---|
uint32_t | sm2 | |
uint32_t | nist256 | |
uint32_t | nist384 | |
uint32_t | bp256 | |
uint32_t | bp384 |
struct telux::sec::CALoad |
Represents curve-wise absolute load as calculated in the time window defined by LoadConfig::calculationInterval. For example, a value of 1000 for sm2 means, in that time window, 1000 sm2 type verification were completed. This verification includes both passed and failed signature.
Data Fields | ||
---|---|---|
uint32_t | sm2 | |
uint32_t | nist256 | |
uint32_t | nist384 | |
uint32_t | bp256 | |
uint32_t | bp384 |
class telux::sec::ICAControlManagerListener |
Receives load and capacity updates.
Public Member Functions | |
virtual void | onCapacityUpdate (struct CACapacity newCapacity) |
virtual void | onLoadUpdate (struct CALoad currentLoad) |
virtual | ~ICAControlManagerListener () |
|
virtual |
Destructor for ICAControlManagerListener.
|
virtual |
Invoked to provide an updated capacity.
[in] | newCapacity | New capacity as per current allowed conditions. |
|
virtual |
Invoked to provide load on crypto accelerator, as observed during time window defined by LoadConfig::calculationInterval.
[in] | currentLoad | Load as observed in the set time window. |
class telux::sec::ICAControlManager |
Public Member Functions | |
virtual telux::common::ErrorCode | registerListener (std::weak_ptr< ICAControlManagerListener > listener)=0 |
virtual telux::common::ErrorCode | deRegisterListener (std::weak_ptr< ICAControlManagerListener > listener)=0 |
virtual telux::common::ErrorCode | startMonitoring (LoadConfig loadConfig)=0 |
virtual telux::common::ErrorCode | stopMonitoring ()=0 |
virtual telux::common::ErrorCode | getCapacity (CACapacity &capacity)=0 |
virtual | ~ICAControlManager () |
|
virtual |
Destructor of ICAControlManager. Cleans up as applicable.
|
pure virtual |
Registers the given listener to get load and capacity updates in ICAControlManagerListener::onLoadUpdate() and ICAControlManagerListener::onCapacityUpdate() methods.
Capacity updates are received whenever capacity changes. Load updates are received as per parameters specified with startMonitoring().
[in] | listener | Receives load and capacity updates |
|
pure virtual |
Unregisters the given listener registered previously with registerListener().
[in] | listener | Listener to deregister |
|
pure virtual |
Starts monitoring and reporting load calculated based on the parameters specified. Calculated load is received by ICAControlManagerListener::onLoadUpdate() periodically as per time interval specified.
On platforms with access control enabled, caller needs to have TELUX_SEC_CA_CTRL_LOAD_OPS permission to invoke this API successfully.
[in] | loadConfig | Defines load calculation parameters |
|
pure virtual |
Stops monitoring the load calculation previosuly started by startMonitoring().
On platforms with access control enabled, caller needs to have TELUX_SEC_CA_CTRL_LOAD_OPS permission to invoke this API successfully.
|
pure virtual |
Provides current verification capacity of the crypto accelerator.
[out] | capacity | current capacity of the crypto accelerator |
struct telux::sec::EnvironmentInfo |
Describes an overall cellular environment's information.
Data Fields | ||
---|---|---|
EnvironmentState | environmentState |
Please refer EnvironmentState for details. |
struct telux::sec::CellularSecurityReport |
Represents security scan report for a cellular connection per base station.
Data Fields | ||
---|---|---|
uint32_t | threatScore |
The higher the score higher the possibility of a compromised/malicious base station. The range of valid values for the score is configurable in the platform. The default range is 0 to 500. |
uint32_t | cellId |
Unique identifier of a cell operated by a mobile network operator. |
uint32_t | pid |
Physical cell id; identifier of a cell in the physical layer of the cellular technology. |
string | mcc |
Mobile country code to uniquely identify a mobile network operator (carrier). |
string | mnc |
Mobile network code to uniquely identify a mobile network operator (carrier). |
vector< CellularThreatType > | threats |
Types of the threat identified. Please refer CellularThreatType for more details. |
ActionType | actionType |
Action taken based on the policy configured and threat score. |
RATType | rat |
Radio access technology being used for communication between the device and the base station (2G/GERAN, 3G/WCDMA, 4G/LTE and 5G/NR). |
struct telux::sec::SessionStats |
For the current session, it represents a high-level summary of the security stats gathered till now. This gives an overall idea about the operational cellular environment.
This can be useful in cases for example, to decide whether a security sensitive operation should be deferred to a later time or place with less hostile environment or extra preventive measures should be activated.
Data Fields | ||
---|---|---|
uint32_t | reportsCount |
Number of the reports received. |
uint32_t | thresholdCrossedCount |
Number of times hostile score threshold was crossed. This count depends on the value of the threshold configured in the platform. This count increments each time the threat score increases beyond this threshold. |
vector< CellularThreatType > | threats |
Different types of threats detected. |
uint32_t | averageThreatScore |
An average score (average of CellularSecurityReport::threatScore). |
ActionType | lastAction |
Last action that was taken based on the policy configured, when a malicious activity was detected. |
bool | anyActionTaken |
Set to true, if an action was taken, when the score crossed hostile threshold. |
class telux::sec::ICellularScanReportListener |
Receives security scan reports when a change in cellular environment is detected. For example;
Public Member Functions | |
virtual void | onScanReportAvailable (CellularSecurityReport report, EnvironmentInfo environmentInfo) |
virtual | ~ICellularScanReportListener () |
Public Member Functions inherited from telux::common::IServiceStatusListener | |
virtual void | onServiceStatusChange (ServiceStatus status) |
virtual | ~IServiceStatusListener () |
|
virtual |
Destructor for ICellularScanReportListener.
|
virtual |
Invoked to provide a security scan report for cellular connection environment.
[in] | report | CellularSecurityReport result of the cellular security scanning |
[in] | environmentInfo | EnvironmentInfo overall environment information |
class telux::sec::ICellularSecurityManager |
Provides support for detecting, monitoring and generating security threat scan report for cellular connections.
When a change in the cellular operating environment is detected, information about the environment is gathered and analyzed for targeted, general purpose attacks and anomalies. This information is then provided as a security scan report.
The report includes information such as, IMSI leak, tracking location of the device, denial of service, man-in-the-middle attack, spam or phishing SMS, fake emergency messages and rogue base stations.
Public Member Functions | |
virtual telux::common::ErrorCode | registerListener (std::weak_ptr< ICellularScanReportListener > reportListener)=0 |
virtual telux::common::ErrorCode | deRegisterListener (std::weak_ptr< ICellularScanReportListener > reportListener)=0 |
virtual telux::common::ErrorCode | getCurrentSessionStats (SessionStats &sessionStats)=0 |
virtual | ~ICellularSecurityManager () |
|
virtual |
Destructor of ICellularSecurityManager. Cleans up as applicable.
|
pure virtual |
Registers given listener to receive cellular security scan report.
On platforms with access control enabled, caller needs to have TELUX_SEC_CCS_REPORT permission to invoke this API successfully.
[in] | reportListener | Receives security scan reports via ICellularScanReportListener::onScanReportAvailable() |
|
pure virtual |
Unregisters the given listener registered previously with registerListener().
On platforms with access control enabled, caller needs to have TELUX_SEC_CCS_REPORT permission to invoke this API successfully.
[in] | reportListener | Listener to unregister |
|
pure virtual |
Gets current session statistics such as average score, number of reports generated, and threat types detected etc.
A session starts when a listener is registered using ICellularSecurityManager::registerListener and ends when it is deregistered using ICellularSecurityManager::deRegisterListener.
On platforms with access control enabled, caller needs to have TELUX_SEC_CCS_REPORT permission to invoke this API successfully.
[out] | sessionStats | SessionStats will contain current session's stats upon method return |
class telux::sec::ConnectionSecurityFactory |
ConnectionConnectionSecurityFactory allows creation of CellularSecurityManager and WiFiSecurityManager.
Public Member Functions | |
virtual std::shared_ptr< ICellularSecurityManager > | getCellularSecurityManager (telux::common::ErrorCode &ec)=0 |
virtual std::shared_ptr< IWiFiSecurityManager > | getWiFiSecurityManager (telux::common::ErrorCode &ec)=0 |
Static Public Member Functions | |
static ConnectionSecurityFactory & | getInstance () |
|
static |
Gets the ConnectionSecurityFactory instance.
|
pure virtual |
Provides an ICellularSecurityManager instance that detects and monitors security threats and generates security scan reports for cellular connections.
[out] | ec | telux::common::ErrorCode::SUCCESS if ICellularSecurityManager is created successfully, otherwise, an appropriate error code |
|
pure virtual |
Provides an IWiFiSecurityManager instance that detects and monitors security threats and generates security analysis reports for WiFi connections.
[out] | ec | telux::common::ErrorCode::SUCCESS if IWiFiSecurityManager is created successfully, otherwise, an appropriate error code |
struct telux::sec::ECCPoint |
struct telux::sec::DataDigest |
struct telux::sec::Signature |
struct telux::sec::Scalar |
struct telux::sec::OperationResult |
Represents a result obtained from the crypto accelerator. The value of an individual field must only be interpreted through helper methods in ResultParser.
Data Fields | ||
---|---|---|
uint32_t | reserved:4 | |
uint32_t | id:12 | |
uint32_t | operationType:3 | |
uint32_t | result:4 | |
uint32_t | errCode:9 | |
uint8_t | data[CA_RESULT_DATA_LENGTH] |
class telux::sec::ICryptoAcceleratorListener |
Receives ECC signature verification and ECQV calculation result.
Public Member Functions | |
virtual void | onVerificationResult (uint32_t uniqueId, telux::common::ErrorCode errorCode, std::vector< uint8_t > resultData) |
virtual void | onCalculationResult (uint32_t uniqueId, telux::common::ErrorCode errorCode, std::vector< uint8_t > resultData) |
virtual | ~ICryptoAcceleratorListener () |
Public Member Functions inherited from telux::common::IServiceStatusListener | |
virtual void | onServiceStatusChange (ServiceStatus status) |
virtual | ~IServiceStatusListener () |
|
virtual |
Destructor for ICryptoAcceleratorListener.
|
virtual |
Invoked to provide an ECC signature verification result.
[in] | uniqueId | Unique request identifier. This is the same as what was passed to ICryptoAcceleratorManager::eccPostDigestForVerification() |
[in] | errorCode | telux::common::ErrorCode::SUCCESS, if signature passed validation, telux::common::ErrorCode::VERIFICATION_FAILED if all inputs were correct, verification completed and signature was invalid, an appropriate error code in all other cases |
[in] | resultData | Contains the r' (computed r-component of the signature) |
|
virtual |
Invoked to provide an ECQV calculation result.
[in] | uniqueId | Unique request identifier. This is the same as what was passed to ICryptoAcceleratorManager::ecqvPostDataForMultiplyAndAdd() |
[in] | errorCode | telux::common::ErrorCode::SUCCESS, if calculation succeeded, otherwise, an appropriate error code |
[in] | resultData | Output point Q (Q=kP+A). For CURVE_SM2, CURVE_NISTP256 and CURVE_BRAINPOOLP256R1, byte from 0 to 31 contains x-coordinate, and byte from 32 to 63 contains y-coordinate. For CURVE_NISTP384 and CURVE_BRAINPOOLP384R1, byte from 0 to 47 contains x-coordinate, and byte from 48 to 95 contains y-coordinate. |
class telux::sec::ICryptoAcceleratorManager |
Provides support for ECC based signature verification and calculation related crypto operations.
APIs with asynchronous and synchronous semantics are provided for the same operation, providing flexibility to optimally support multiple client solutions.
Clients that prefer to invoke verifications from a thread and consume the results on a different thread should use the asynchronous APIs. Clients that prefer to invoke verification APIs and block until the result is ready, should use the synchronous APIs.
Public Member Functions | |
virtual telux::common::ErrorCode | eccPostDigestForVerification (const DataDigest &digest, const ECCPoint &publicKey, const Signature &signature, telux::sec::ECCCurve curve, uint32_t uniqueId, telux::sec::RequestPriority priority)=0 |
virtual telux::common::ErrorCode | ecqvPostDataForMultiplyAndAdd (const ECCPoint &multiplicandPoint, const ECCPoint &addendPoint, const Scalar &scalar, telux::sec::ECCCurve curve, uint32_t uniqueId, telux::sec::RequestPriority priority)=0 |
virtual telux::common::ErrorCode | getAsyncResults (std::vector< OperationResult > &results, uint32_t numResultsToRead, int32_t timeout, uint32_t &numResultsRead)=0 |
virtual telux::common::ErrorCode | eccVerifyDigest (const DataDigest &digest, const ECCPoint &publicKey, const Signature &signature, telux::sec::ECCCurve curve, uint32_t uniqueId, telux::sec::RequestPriority priority, std::vector< uint8_t > &resultData)=0 |
virtual telux::common::ErrorCode | ecqvPointMultiplyAndAdd (const ECCPoint &multiplicandPoint, const ECCPoint &addendPoint, const Scalar &scalar, telux::sec::ECCCurve curve, uint32_t uniqueId, telux::sec::RequestPriority priority, std::vector< uint8_t > &resultData)=0 |
virtual | ~ICryptoAcceleratorManager () |
|
virtual |
Destructor of ICryptoAcceleratorManager. Cleans up as applicable.
|
pure virtual |
Sends hashed ECC data to the crypto accelerator for integrity verification using the given public key and signature.
Verification result is received by the ICryptoAcceleratorListener::onVerificationResult() method for MODE_ASYNC_LISTENER. For MODE_ASYNC_POLL, getAsyncResults() is used to obtain the results.
[in] | digest | Digest of data |
[in] | publicKey | Uncompressed public key used to verify the signature |
[in] | signature | Signature of the digest |
[in] | curve | ECC curve on which given public key lies |
[in] | uniqueId | Unique identifier for each request. This number must be unique across all requests for which results are pending. Once the result for a request is received, the same number can be reused. Valid value range is 0 <= uniqueId <= 4095. |
[in] | priority | Relative priority indicating this digest should be verified before any other low priority digest |
|
pure virtual |
Sends data to the crypto accelerator to perform a point multiplication and addition for 'Short Weierstrass' curves; Q=kP+A.
Calculation result is received by the ICryptoAcceleratorListener::onCalculationResult() method for MODE_ASYNC_LISTENER. For MODE_ASYNC_POLL, getAsyncResults() is used to obtain the results.
[in] | multiplicandPoint | Point to multiply (P). In context of public key reconstruction, it represents the reconstruction value |
[in] | addendPoint | Point to add (A). In context of public key reconstruction, it represents the CA public key |
[in] | scalar | Scalar for the scalar multiplication (k). In context of public key reconstruction, it represents the hash construct |
[in] | curve | ECC curve associated with point P and A |
[in] | uniqueId | Unique identifier for each request. This number must be unique across all requests for which results are pending. Once the result for a request is received, the the same number can be reused. Valid value range is 0 <= uniqueId <= 4095. |
[in] | priority | Relative priority indicating this calculation should be performed before any other low priority operation |
|
pure virtual |
When using Mode::MODE_ASYNC_POLL, ICryptoAcceleratorManager::eccPostDigestForVerification() and ICryptoAcceleratorManager::ecqvPostDataForMultiplyAndAdd() APIs are used to send request.
The result of these request is obtained asynchronously using this method. It blocks until result(s) is available or timeout occurs.
Caller should allocate sufficient memory pointed by 'results'.
[out] | results | Buffer that will contain the results |
[in] | numResultsToRead | Number of the results to read |
[in] | timeout | Time to wait (in milliseconds) for the result(s). Specifying a negative value means an infinite timeout. Zero value means return immediately (there may or may not be any results read). |
[out] | numResultsRead | Number of results actually read |
|
pure virtual |
Verifies the signature of the digest using given public key.
[in] | digest | Digest of data |
[in] | publicKey | Uncompressed public key used to verify the signature |
[in] | signature | Signature of the digest |
[in] | curve | ECC curve on which given public key lies |
[in] | uniqueId | Unique identifier for each request. This number must be unique across all requests for which results are pending. Once the result for a request is received, the same number can be reused. Valid value range is 0 <= uniqueId <= 4095. |
[in] | priority | Relative priority indicating this digest should be verified before any other low priority digest |
[out] | resultData | Contains the r' prime (computed r-component of the signature) |
|
pure virtual |
Performs a point multiplication and addition for 'Short Weierstrass' curves; Q=kP+A with the help of accelerator. This can be used, for example; to reconstruct a public key, using 'Elliptic Curve Qu-Vanstone (ECQV)' implicit certificate scheme.
[in] | multiplicandPoint | Point to multiply (P). In context of public key reconstruction, it represents the reconstruction value |
[in] | addendPoint | Point to add (A). In context of public key reconstruction, it represents the CA public key |
[in] | scalar | Scalar for the scalar multiplication (k). In context of public key reconstruction, it represents the hash construct |
[in] | curve | ECC curve associated with point P and A |
[in] | uniqueId | Unique identifier for each request. This number must be unique across all requests for which results are pending. Once the result for a request is received, the the same number can be reused. Valid value range is 0 <= uniqueId <= 4095. |
[in] | priority | Relative priority indicating this calculation should be performed before any other low priority operation |
[out] | resultData | Output point Q (Q=kP+A). For CURVE_SM2, CURVE_NISTP256 and CURVE_BRAINPOOLP256R1, byte from 0 to 31 contains x-coordinate, and byte from 32 to 63 contains y-coordinate. For CURVE_NISTP384 and CURVE_BRAINPOOLP384R1, byte from 0 to 47 contains x-coordinate, and byte from 48 to 95 contains y-coordinate. |
class telux::sec::ResultParser |
Provides helpers to parse fields in the OperationResult.
Static Public Member Functions | |
static uint32_t | getId (const OperationResult &result) |
static OperationType | getOperationType (const OperationResult &result) |
static telux::common::ErrorCode | getErrorCode (const OperationResult &result) |
static telux::common::ErrorCode | getCAErrorCode (const OperationResult &result) |
static uint8_t * | getData (OperationResult &result) |
|
static |
Gets the unique identifier associated with the result.
[in] | result | Result obtained from ICryptoAcceleratorManager::getAsyncResults() |
|
static |
Gets the type of operation corresponding to this result; values are and OperationType::OP_TYPE_VERIFY and OperationType::OP_TYPE_CALCULATE.
[in] | result | Result obtained from ICryptoAcceleratorManager::getAsyncResults() |
|
static |
Indicates if the operation passed.
[in] | result | Result obtained from ICryptoAcceleratorManager::getAsyncResults() |
|
static |
Provides a crypto accelerator hardware specific error code to further identify the actual error. Should be used only if getErrorCode() indicates an error occurred.
[in] | result | Result obtained from ICryptoAcceleratorManager::getAsyncResults() |
|
static |
Gets the actual result data. For ECC verification, it contains r-prime and for ECQV it contains coordinates.
[in] | result | Result obtained from ICryptoAcceleratorManager::getAsyncResults() |
class telux::sec::ICryptoParam |
Specifies how a crypto operation should be performed. An instance of this must be created only thorough CryptoParamBuilder.
Public Member Functions | |
virtual | ~ICryptoParam () |
|
virtual |
struct telux::sec::EncryptedData |
class telux::sec::ICryptoManager |
ICryptoManager provides key management and crypto operation support. It uses trusted hardware bound cryptography. All keys generated are bound to the device cryptographically.
Public Member Functions | |
virtual telux::common::ErrorCode | generateKey (std::shared_ptr< ICryptoParam > cryptoParam, std::vector< uint8_t > &keyBlob)=0 |
virtual telux::common::ErrorCode | importKey (std::shared_ptr< ICryptoParam > cryptoParam, telux::sec::KeyFormat keyFmt, std::vector< uint8_t > const &keyData, std::vector< uint8_t > &keyBlob)=0 |
virtual telux::common::ErrorCode | exportKey (telux::sec::KeyFormat keyFmt, std::vector< uint8_t > const &keyBlob, std::vector< uint8_t > &keyData)=0 |
virtual telux::common::ErrorCode | upgradeKey (std::shared_ptr< ICryptoParam > cryptoParam, std::vector< uint8_t > const &oldKeyBlob, std::vector< uint8_t > &newKeyBlob)=0 |
virtual telux::common::ErrorCode | signData (std::shared_ptr< ICryptoParam > cryptoParam, std::vector< uint8_t > const &keyBlob, std::vector< uint8_t > const &plainText, std::vector< uint8_t > &signature)=0 |
virtual telux::common::ErrorCode | verifyData (std::shared_ptr< ICryptoParam > cryptoParam, std::vector< uint8_t > const &keyBlob, std::vector< uint8_t > const &plainText, std::vector< uint8_t > const &signature)=0 |
virtual telux::common::ErrorCode | encryptData (std::shared_ptr< ICryptoParam > cryptoParam, std::vector< uint8_t > const &keyBlob, std::vector< uint8_t > const &plainText, std::shared_ptr< EncryptedData > &encryptedData)=0 |
virtual telux::common::ErrorCode | decryptData (std::shared_ptr< ICryptoParam > cryptoParam, std::vector< uint8_t > const &keyBlob, std::vector< uint8_t > const &encryptedText, std::vector< uint8_t > &decryptedText)=0 |
virtual | ~ICryptoManager () |
|
virtual |
Destroys the ICryptoManager instance. Performs cleanup as applicable.
|
pure virtual |
Generates key and provides it in the form of a corresponding key blob. The key's secret is encrypted in this key blob.
On platforms with access control enabled, the caller needs to have TELUX_SEC_KEY_OPS permission to successfully invoke this API.
[in] | cryptoParam | Specifications of the key. |
[out] | keyBlob | Key blob representing the key. |
|
pure virtual |
Creates a key blob from the given key data.
On platforms with access control enabled, the caller needs to have TELUX_SEC_KEY_OPS permission to successfully invoke this API.
[in] | cryptoParam | Specifications of the key |
[in] | keyFmt | Format in which the key should be imported (KeyFormat) |
[in] | keyData | Key's data, in the specified format, to be imported. |
[out] | keyBlob | Key blob created from the given key data. |
|
pure virtual |
Generates equivalent key data from the given key blob.
On platforms with access control enabled, the caller needs to have TELUX_SEC_KEY_OPS permission to successfully invoke this API.
[in] | keyFmt | KeyFormat Format in which key should be exported. |
[in] | keyBlob | Key blob representing the key to be exported. |
[out] | keyData | Key's data generated from the given key blob. |
|
pure virtual |
Upgrades the given key if it has expired. For example, This API can be used when a key has expired due to a system software upgrade.
On platforms with access control enabled, the caller needs to have TELUX_SEC_KEY_OPS permission to successfully invoke this API.
[in] | cryptoParam | Input parameters passed to the upgrade algorithm. Specifically, unique data should be set if it was used when the key was originally created. |
[in] | oldKeyBlob | Key blob representing the key to be upgraded. |
[out] | newKeyBlob | Key blob representing the upgraded key. |
|
pure virtual |
Generates a signature to verify the integrity of the given data.
On platforms with access control enabled, the caller needs to have TELUX_SEC_SIGN_OPS permission to successfully invoke this API.
[in] | cryptoParam | Input parameters passed to the signature generation algorithm. |
[in] | keyBlob | Key blob to sign given data. |
[in] | plainText | Data to be signed. |
[out] | signature | Signature generated for the given data. |
|
pure virtual |
Verifies integrity of the given data through its signature.
On platforms with access control enabled, the caller needs to have TELUX_SEC_SIGN_OPS permission to successfully invoke this API.
[in] | cryptoParam | Input parameters passed to the signature validation algorithm. |
[in] | keyBlob | Key blob to verify the given data. |
[in] | plainText | Data to be verified. |
[in] | signature | Signature of the data. |
|
pure virtual |
Encrypts data per the given inputs to the encryption algorithm.
On platforms with access control enabled, the caller needs to have TELUX_SEC_ENCRYPTION_OPS permission to successfully invoke this API.
[in] | cryptoParam | Input parameters passed to the encryption algorithm. |
[in] | keyBlob | Key blob to be used for encryption. |
[in] | plainText | Data to be encrypted. |
[out] | encryptedData | Encrypted data and nonce, if CryptoParamBuilder::setCallerNonce() was not set when creating keys for encryption/decryption). |
|
pure virtual |
Decrypts data per the given inputs to the decryption algorithm.
On platforms with access control enabled, the caller needs to have TELUX_SEC_ENCRYPTION_OPS permission to successfully invoke this API.
[in] | cryptoParam | Input parameters passed to the decryption algorithm. |
[in] | keyBlob | Key blob to be used for decryption. |
[in] | encryptedText | Encrypted data to be decrypted. |
[out] | decryptedText | Decrypted data. |
class telux::sec::CryptoParamBuilder |
CryptoParamBuilder helps setup input parameters for a given crypto operation.
Public Member Functions | |
CryptoParamBuilder () | |
CryptoParamBuilder | setAlgorithm (AlgorithmTypes algorithm) |
CryptoParamBuilder | setCryptoOperation (CryptoOperationTypes operation) |
CryptoParamBuilder | setDigest (DigestTypes digest) |
CryptoParamBuilder | setPadding (PaddingTypes padding) |
CryptoParamBuilder | setKeySize (int32_t keySize) |
CryptoParamBuilder | setMinimumMacLength (int32_t minMacLength) |
CryptoParamBuilder | setMacLength (int32_t macLength) |
CryptoParamBuilder | setBlockMode (BlockModeTypes blockMode) |
CryptoParamBuilder | setCurve (int32_t curve) |
CryptoParamBuilder | setCallerNonce (bool callerNonce) |
CryptoParamBuilder | setPublicExponent (uint64_t publicExponent) |
CryptoParamBuilder | setInitVector (std::vector< uint8_t > initVector) |
CryptoParamBuilder | setUniqueData (std::vector< uint8_t > uniqueData) |
CryptoParamBuilder | setAssociatedData (std::vector< uint8_t > associatedData) |
std::shared_ptr< ICryptoParam > | build (void) |
telux::sec::CryptoParamBuilder::CryptoParamBuilder | ( | ) |
Allocates an instance of CryptoParamBuilder.
CryptoParamBuilder telux::sec::CryptoParamBuilder::setAlgorithm | ( | AlgorithmTypes | algorithm | ) |
When generating keys, specifies with which algorithm the keys will be used. For crypto operations, specifies the algorithm to use. Use telux::sec::Algorithm enumeration to define this.
CryptoParamBuilder telux::sec::CryptoParamBuilder::setCryptoOperation | ( | CryptoOperationTypes | operation | ) |
When generating keys, specifies the crypto operation(s) for which the key will be used. For crypto operations, specifies the operation itself (encrypting/decrypting/ signing/verifying). Use telux::sec::CryptoOperation enumeration to define this. Multiple operation values can be OR'ed (|).
CryptoParamBuilder telux::sec::CryptoParamBuilder::setDigest | ( | DigestTypes | digest | ) |
When generating keys, specifies the digest algorithm(s) that may be used with the key to perform signing and verifying operations using RSA, ECDSA, and HMAC keys. For crypto operations, specifies exact digest algorithm to be used. Use telux::sec::Digest enumeration to define this. Multiple values can be OR'ed (|).
CryptoParamBuilder telux::sec::CryptoParamBuilder::setPadding | ( | PaddingTypes | padding | ) |
When generating keys, specifies the padding modes that may be used with the RSA and AES key. For crypto operations, specifies the exact padding to be used. Use telux::sec::Padding enumeration to define this. Multiple padding values can be OR'ed (|).
CryptoParamBuilder telux::sec::CryptoParamBuilder::setKeySize | ( | int32_t | keySize | ) |
When generating keys, specifies the size in bits, of the key, measured in the regular way for the key's algorithm.
CryptoParamBuilder telux::sec::CryptoParamBuilder::setMinimumMacLength | ( | int32_t | minMacLength | ) |
When generating keys, specifies minimum length of the MAC in bits that can be requested or verified with this key for HMAC keys and AES keys that support GCM mode.
CryptoParamBuilder telux::sec::CryptoParamBuilder::setMacLength | ( | int32_t | macLength | ) |
For crypto operations, specifies requested length of a MAC or GCM (which is guaranteed to be no less then minimum length of the MAC/GCM used when generating the key).
CryptoParamBuilder telux::sec::CryptoParamBuilder::setBlockMode | ( | BlockModeTypes | blockMode | ) |
When generating keys, specifies the block cipher mode(s) with which this key can be used. For crypto operations, specifies the exact block mode to be used. Use telux::sec::BlockMode enumeration to define this. Multiple block mode values can be OR'ed (|).
CryptoParamBuilder telux::sec::CryptoParamBuilder::setCurve | ( | int32_t | curve | ) |
When generating the keys using an EC algorithm, only key size, only curve, or both key size and curve can be specified. If only key size is specified, the appropriate NIST curve is selected automatically. If only curve is specified, the given curve is used. If both are specified, the given curve is used and key size is validated.
CryptoParamBuilder telux::sec::CryptoParamBuilder::setCallerNonce | ( | bool | callerNonce | ) |
When generating AES key, if callerNonce is set to true, it specifies that an explicit nonce will be supplied by the caller during encryption and decryption using setInitVector(). If the callerNonce is set to false (or not set), platform will generate the nonce during encryption. This nonce should be passed during decryption.
CryptoParamBuilder telux::sec::CryptoParamBuilder::setPublicExponent | ( | uint64_t | publicExponent | ) |
When generating an RSA key, specifies the value of the public exponent for an RSA key pair (necessary for all RSA keys).
CryptoParamBuilder telux::sec::CryptoParamBuilder::setInitVector | ( | std::vector< uint8_t > | initVector | ) |
When performing AES crypto operations, specifies the initialization vector to be used.
CryptoParamBuilder telux::sec::CryptoParamBuilder::setUniqueData | ( | std::vector< uint8_t > | uniqueData | ) |
When generating or importing a key, an optional arbitrary value can be supplied through this method. In all subsequent use of the key, this value must be supplied again. The data given is bound to the key cryptographically. This data ties the key to the caller.
CryptoParamBuilder telux::sec::CryptoParamBuilder::setAssociatedData | ( | std::vector< uint8_t > | associatedData | ) |
When encrypting/decrypting data, this specifies optional associated data to be used. This is applicable only for AES-GCM algorithm.
std::shared_ptr<ICryptoParam> telux::sec::CryptoParamBuilder::build | ( | void | ) |
Creates an instance of ICryptoParam based on the setter methods invoked on the builder. After building the builder's state is reset.
class telux::sec::SecurityFactory |
SecurityFactory allows creation of ICryptoManager and ICryptoAcceleratorManager.
Public Member Functions | |
virtual std::shared_ptr< ICryptoManager > | getCryptoManager (telux::common::ErrorCode &ec)=0 |
virtual std::shared_ptr< ICryptoAcceleratorManager > | getCryptoAcceleratorManager (telux::common::ErrorCode &ec, Mode mode, std::weak_ptr< ICryptoAcceleratorListener > cryptoAccelListener=std::weak_ptr< ICryptoAcceleratorListener >())=0 |
virtual std::shared_ptr< ICAControlManager > | getCAControlManager (telux::common::ErrorCode &ec)=0 |
Static Public Member Functions | |
static SecurityFactory & | getInstance () |
|
static |
Gets the SecurityFactory instance.
|
pure virtual |
Instantiates a CryptoManager instance that can be used to perform key management and cryptographic operations.
[out] | ec | telux::common::ErrorCode::SUCCESS if ICryptoManager is created successfully, otherwise, an appropriate error code |
|
pure virtual |
Provides a CryptoAcceleratorManager instance that can be used to perform cryptographic operations requiring elliptic-curve cryptography (ECC) verifications and calculations.
Providing ICryptoAcceleratorListener instance is mandatory when using Mode::MODE_ASYNC_LISTENER. It is not required with modes, Mode::MODE_SYNC and Mode::MODE_ASYNC_POLL for cryptographic operations.
To receive subsystem-restart (SSR) updates, application must provide ICryptoAcceleratorListener instance (irrespective of Mode::*) and implement method telux::common::IServiceStatusListener::onServiceStatusChange().
Specifying mode (Mode::*) defines how an application will send request and receive cryptographic results.
Passing listener determines whether an application is also interested in SSR updates in addition to cryptographic results or not.
On platforms with access control enabled, caller needs to have TELUX_SEC_ACCELERATOR_MGR permission to invoke this API successfully.
[out] | ec | telux::common::ErrorCode::SUCCESS if ICryptoAcceleratorManager is created successfully, otherwise, an appropriate error code |
[in] | mode | Defines how users obtain verification and calculation results |
[in] | cryptoAccelListener | Optional, listener for ECC signature verification and ECQV calculation results |
|
pure virtual |
Provides an ICAControlManager instance that can be used to collect statistical information about usage of the crypto accelerator.
On platforms with access control enabled, caller needs to have TELUX_SEC_CA_CONTROL_MGR permission to invoke this API successfully.
[out] | ec | telux::common::ErrorCode::SUCCESS if the ICAControlManager is created successfully, otherwise, an appropriate error code |
struct telux::sec::MLAlgorithmAnalysis |
Machine learning algorithm threat analysis result per AP.
Data Fields | ||
---|---|---|
uint32_t | threatScore |
Higher threat scores indicate a higher possibility that the AP is malicious; range is 0 to 100. |
AnalysisResult | result |
Result of the security analysis for a given AP. |
struct telux::sec::SummoningAnalysis |
Summoning attack threat analysis result.
Data Fields | ||
---|---|---|
AnalysisResult | result |
Result of the security analysis for a given AP. |
struct telux::sec::WiFiSecurityReport |
Represents the security report for a Wi-Fi AP.
Data Fields | ||
---|---|---|
string | ssid |
Network interface name of the AP. |
string | bssid |
MAC address of the AP. |
bool | isConnectedToAP |
True if the device is connected to this AP. |
bool | isOpenAP |
True if devices can connect to this AP without authentication. |
MLAlgorithmAnalysis | mlAlgorithmAnalysis |
Machine learning algorithm threat analysis result. |
SummoningAnalysis | summoningAnalysis |
Summoning attack threat analysis result. |
struct telux::sec::DeauthenticationInfo |
Represents information about a deauthentication attack.
struct telux::sec::ApInfo |
class telux::sec::IWiFiReportListener |
Receives security analysis reports for the Wi-Fi APs detected while scanning for APs in the vicinity and provides a listener for deauthentication attacks.
Public Member Functions | |
virtual void | onReportAvailable (WiFiSecurityReport report) |
virtual void | onDeauthenticationAttack (DeauthenticationInfo deauthenticationInfo) |
virtual void | isTrustedAP (ApInfo accessPoint, bool &isTrusted) |
virtual | ~IWiFiReportListener () |
|
virtual |
IWiFiReportListener destructor.
|
virtual |
Notifies that the implementation completed a threat analysis and that the report is available This analysis is performed at various triggers, for example, when a scan for APs is triggered the implementation will perform an analysis and provide a report for every AP it sees in the vicinity.
[in] | report | WiFiSecurityReport result of the Wi-Fi security analysis. |
|
virtual |
Notifies that a deauthentication attack is identified.
[in] | deauthenticationInfo | DeauthenticationInfo security analysis information. |
|
virtual |
Gets user confirmation that the given AP is trusted. This is called only once when the device connects to this AP for the very first time. If the application trusts the given AP, it should set 'isTrusted' to True. Otherwise it should be set to false.
Once the users confirms that an AP is trusted, this information is saved internally and used later to detect threats like evil twin attacks.
On platforms with access control enabled, the caller needs to have the TELUX_SEC_WCS_CONFIG permission to successfully invoke this API.
[in] | accessPoint | ApInfo provides information about an AP. |
[out] | isTrusted | True if trusted; false otherwise. |
class telux::sec::IWiFiSecurityManager |
Provides support for detecting, monitoring, and generating security reports for Wi-Fi APs.
Public Member Functions | |
virtual telux::common::ErrorCode | registerListener (std::weak_ptr< IWiFiReportListener > reportListener)=0 |
virtual telux::common::ErrorCode | deregisterListener (std::weak_ptr< IWiFiReportListener > reportListener)=0 |
virtual telux::common::ErrorCode | getTrustedApList (std::vector< ApInfo > &trustedAPList)=0 |
virtual telux::common::ErrorCode | removeApFromTrustedList (ApInfo apInfo)=0 |
virtual | ~IWiFiSecurityManager () |
|
virtual |
IWiFiSecurityManager destructor; cleans up as applicable.
|
pure virtual |
Registers the given listener to receive Wi-Fi connection security reports. These reports will be received by IWiFiReportListener::onReportAvailable().
On platforms with access control enabled, the caller needs to have the TELUX_SEC_WCS_REPORT permission to successfully invoke this API.
[in] | reportListener | Receives security reports. |
|
pure virtual |
Unregisters the given listener registered previously with registerListener().
On platforms with access control enabled, the caller needs to have the TELUX_SEC_WCS_REPORT permission to successfully invoke this API.
[in] | reportListener | Listener to unregister. |
|
pure virtual |
Lists all the trusted APs.
On platforms with access control enabled, the caller needs to have the TELUX_SEC_WCS_INFO permission to successfully invoke this API.
[out] | trustedAPList | List of trusted APs ( ApInfo ). |
|
pure virtual |
Removes the given AP from the saved list of trusted APs. If the device connects to the same AP again, IWiFiReportListener::isTrustedAP() will be invoked again.
On platforms with access control enabled, the caller needs to have the TELUX_SEC_WCS_CONFIG permission to successfully invoke this API.
[in] | apInfo | AP to distrust ( ApInfo ). |
using telux::sec::CryptoOperationTypes = typedef int32_t |
List of operation types consisting of entries from CryptoOperation. Multiple values can be OR'ed together, for example, (CRYPTO_OP_ENCRYPT | CRYPTO_OP_DECRYPT).
using telux::sec::BlockModeTypes = typedef int32_t |
List of block mode types consisting of entries from BlockMode. Multiple values can be OR'ed together, for example, (BLOCK_MODE_ECB | BLOCK_MODE_CBC).
using telux::sec::PaddingTypes = typedef int32_t |
List of padding types to use consisting of entries from Padding. Multiple values can be OR'ed together, for example, (PADDING_PKCS7 | PADDING_RSA_PSS).
using telux::sec::DigestTypes = typedef int32_t |
List of digest types to use consisting of entries from Digest. Multiple values can be OR'ed together, for example, (DIGEST_SHA_2_256 | DIGEST_SHA_2_512).
using telux::sec::AlgorithmTypes = typedef int32_t |
Specifies the algorithm to use; valid values are listed in Algorithm.
using telux::sec::CurveTypes = typedef int32_t |
Specifies the curve to use; valid values are listed in Curve.
|
strong |
Describes the cellular threats detected.
|
strong |
Describes the state of the cellular environment observed by the device.
|
strong |
Based on the policy configured on the device, certain actions are taken automatically. For example; when a compromised/malicious BS is detected, it is blacklisted (cell barring) for a certain period of time (hence device will not be able to connect to it).
When configured action has been taken, a security report is generated. In that report, ActionType represents exact action taken.
|
strong |
|
strong |
Defines how the user gets verification and calculation results.
Enumerator | |
---|---|
MODE_SYNC |
ICryptoAcceleratorManager::eccVerifyDigest() and ICryptoAcceleratorManager::ecqvPointMultiplyAndAdd() APIs are used to send verification and calculation data and obtain results synchronously. |
MODE_ASYNC_POLL |
ICryptoAcceleratorManager::eccPostDigestForVerification() and ICryptoAcceleratorManager::ecqvPostDataForMultiplyAndAdd() APIs are used to send verification and calculation data. Results are obtained via ICryptoAcceleratorManager::getAsyncResults() API. |
MODE_ASYNC_LISTENER |
ICryptoAcceleratorManager::eccPostDigestForVerification() and ICryptoAcceleratorManager::ecqvPostDataForMultiplyAndAdd() APIs are used to send verification and calculation data. Results are obtained asynchronously in ICryptoAcceleratorListener::onVerificationResult() and ICryptoAcceleratorListener::onCalculationResult() callbacks. |
|
strong |
|
strong |
|
strong |
Specifies the operation for which the key can be used. A key can be used for multiple operation types.
enum telux::sec::Padding |
Padding modes that may be applied to plain text for encryption operations. Only cryptographically-appropriate pairs are specified here.
enum telux::sec::Digest |
Specifies the digest algorithms that may be used with the key to perform signing and verification operations using RSA, ECDSA, and HMAC keys. The digest used during signing or verification must match the digest associated with the key when the key was generated.
Algorithm for signing, verification, encryption, and decryption operations.
enum telux::sec::Curve |
|
strong |
Security analysis result for a given access point (AP).
|
static |
Length of the unparsed raw result from the crypto accelerator.