Security/Tizen 5.X Key Manager backends
Key manager is able to use different backends for cryptographic operations and storage operations. To identify an item like key or certifcate it uses aliases. Key manager keeps a mapping between an item alias and item metadata in its internal database. This metadata is called a token. A token contains an information about the type of the item, the backend associated with this item and a backend specific data that is used to retrieve the actual item. Every item can be associated with only one backend. That backend is responsible for storing the item and performing cryptographic operations using the item.
- REE - Rich Execution Environment
- TEE - Trusted Execution Environment
By default, key-manager uses a software backend (SW backend) which utilizes openssl to perform cryptographic operations and stores the item (keys, certficates, etc) directly in the token (in backend specific data).
The TZ backend stores the item in Trusted Execution Environment (TEE) storage and it puts an internal identifier of that item into the token.
Even though the software backend is used by default, the TZ backend is strongly recommended because it is more secure than the software backend. When the software backend have to be used unavoidably(for example, on devices without TrustZone), the decryption key for the encrypted token DB must be additionally protected with a product specific way.
Item data stored in key-manager's token database. It contains:
- Backend identifier.
- Data type.
- Backend specific item data.
Class responsible for deciding which backend to use for given operation. For example, if given backend supports only RSA keys it should be used only for operations related to RSA keys:
- Returns a GStore implementation (backend) with which the given token is associated.
GStore &getStore(const Token &token) const;
- Returns a GStore implementation dedicated for given data type, item storage policy and encrypted item import capability.
GStore &getStore(DataType data, const Policy &policy, bool encrypted = false) const;
Base class for item storage. It can be treated as a backend representation. Every backend must provide a specialization of this class. It is responsible for key generation, retrieving the items from the storage using tokens and importing the items into the storage. It defines the following functions to be implemented by individual backends:
- Returns GObj representation of an item using given Token and optionally a password (if the item is encrypted)
GObjUPtr getObject(const Token &, const Password &);
- Generates a pair of asymmetric keys using given parameters and optionally a password if any of the key should be encrypted. Returns a pair of tokens to be stored in key-manager's token database.
TokenPair generateAKey(const CryptoAlgorithm &, const Password &, const Password &);
- As above but for symmetric key. Returns only one token.
Token generateSKey(const CryptoAlgorithm &, const Password &);
- Imports given data of given type, optionally encrypts it (if password is not empty) and returns a token.
Token import(const Data &, const Password &);
- Imports given data of given type encrypted with device key using encryption specified in DataEncryption argument and returns a token. May also encrypt the data if password is not empty. This functionality is used for initial values loaded by key-manager during booting.
Token importEncrypted(const Data &, const Password &, const DataEncryption &);
- Removes all the data associated to given token.
void destroy(const Token &);
Base class for cryptographic object like key or certificate. Every backend must provide a specialization of this class. It can be used to perform cryptographic operations like encryption/decryption, signing/verification. The store returns objects of this class when asked to retrieve an item. The following functions should be implemented by individual backends:
- Returns the item in form of a binary buffer.
RawBuffer getBinary() const;
- Encrypts given data using given algorithm. Returns encrypted data.
RawBuffer encrypt(const CryptoAlgorithm &, const RawBuffer &);
- Decrypts given data using given algorithm. Returns decrypted data.
RawBuffer decrypt(const CryptoAlgorithm &, const RawBuffer &);
- Signs given data using given algorithm. Returns signature in form of a binary buffer.
RawBuffer sign(const CryptoAlgorithm &, const RawBuffer &);
- Verifies the signature of given data using given algorithm. Returns the result of the verification in form of a numeric code.
int verify(const CryptoAlgorithm &, const RawBuffer &, const RawBuffer &);
It is possible to store an encrypted item in backend storage. GStore methods use the password argument for that purpose. When item is stored and password is not empty the backend derives a key from it, encrypts the data with the key and stores the encrypted data with all metadata necessary to decrypt it later using the password. When item is retrieved the given password is again used to derive the key and decrypt the encrypted data. If it fails an exception is thrown.
Key-manager's tz-backend is actually a Client Application (CA) communicating with key-manager Trusted Application (TA) which runs in TEE.
To communicate with the Key-manager TA the tz-backend uses a wrapper library over TEE client API (Global Platform Client API) called libteec.
Key-manager TA utilizes Global Platform Internal API 1.0. It is assumed that such API is provided by target TEE implementation. GP API makes the key-manager TA portable between different TEE's. However, the building process may differ. A trusted application development package (unified-ta-devkit) is an abstraction layer that hides the target specific details from TA. Thanks to the devkit the TA can be used without modifications with any TEE implementation supporting GP API 1.0. To port key-manager TA to a specific target it may be necessary to adjust the unified devkit.
- Libteec: https://review.tizen.org/gerrit/#/admin/projects/platform/core/api/libteec.
- Key-manager TA: https://review.tizen.org/gerrit/#/admin/projects/platform/core/security/trusted/key-manager-ta.
- Unified TA development package: https://review.tizen.org/gerrit/#/admin/projects/platform/core/security/trusted/unified-ta-devkit.