diff -r 000000000000 -r 2c201484c85f cryptomgmtlibs/cryptotokenfw/inc_interfaces/MCTKeyStoreManager_v2.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/cryptomgmtlibs/cryptotokenfw/inc_interfaces/MCTKeyStoreManager_v2.h Wed Jul 08 11:25:26 2009 +0100 @@ -0,0 +1,285 @@ +/* +* Copyright (c) 2003-2009 Nokia Corporation and/or its subsidiary(-ies). +* All rights reserved. +* This component and the accompanying materials are made available +* under the terms of the License "Eclipse Public License v1.0" +* which accompanies this distribution, and is available +* at the URL "http://www.eclipse.org/legal/epl-v10.html". +* +* Initial Contributors: +* Nokia Corporation - initial contribution. +* +* Contributors: +* +* Description: +* MKeystoreManager.h +* +*/ + + + + +/** + @file + @publishedPartner + @released +*/ + +#ifndef __MCTKEYSTOREMANAGER_H__ +#define __MCTKEYSTOREMANAGER_H__ + +#include "mctkeystore.h" + +/** */ +const TInt KInterfaceKeyStoreManager = 0x101F7335; + +class CPBEncryptParms; + +/** + * Defines the interface for a key store manager token. + * + * This documentation describes the security policy that must be enforced by + * implementations of the interface. + * + * @publishedPartner + * @released + */ +class MCTKeyStoreManager : public MCTKeyStore + { +public: + /** + * Key creation + */ + + /** + * Generates a new key pair and store it in the keystore. + * + * @param aReturnedKey This is filled by the caller with required + * attributes, leaving the TKeyIdentifier iID and object handle iHandle + * uninitialised - these values are set if the key is created successfully + * @param aStatus This will be completed with the final status code + * + * @capability WriteUserData Requires the caller to have WriteUserData capability + * @leave KErrPermissionDenied If the caller does not have WriteUserData capability + * @leave KErrAlreadyExists If a key with the specified label already + * exists in the keystore. + * @leave KErrKeySize If the requested key size is not supported. + * @leave KErrKeyAccess If an invalid combination of key access flags were specified. + * @leave KErrKeyValidity If a validity period was specified, but the end + * date was in the past. + */ + virtual void CreateKey(CCTKeyInfo*& aReturnedKey, + TRequestStatus& aStatus) = 0; + + /** Cancels an ongoing CreateKey() operation. */ + virtual void CancelCreateKey() = 0; + + /** + * Import keys + */ + + /** + * Imports a cleartext key pair into the keystore. + * + * The import data is DER-encoded PKCS#8 format. + * + * @param aKey This is a descriptor representation of the PKCS#8 key data. + * @param aReturnedKey This is filled by the caller with required + * attributes, leaving the TKeyIdentifier iID and object handle iHandle + * uninitialised - these values are set if the key is created successfully. + * + * @capability WriteUserData Requires the caller to have WriteUserData capability + * @leave KErrPermissionDenied If the caller does not have WriteUserData capability + * @leave KErrAlreadyExists If a key with the specified label already exists + * in the keystore. + * @leave KErrKeySize If the requested key size is not supported. + * @leave KErrKeyAccess If an invalid combination of key access flags were specified. + * @leave KErrKeyValidity If a validity period was specified, but the end + * date was in the past. + * @leave KErrArgument If there is an error parsing the key data. + */ + virtual void ImportKey(const TDesC8& aKey, + CCTKeyInfo*& aReturnedKey, + TRequestStatus& aStatus) = 0; + + /** Cancels an ongoing ImportKey() operation. */ + virtual void CancelImportKey() = 0; + + /** + * Imports an encrypted key pair into the keystore. + * + * The import data is DER-encoded PKCS#5/PKCS#8 format. + * + * @param aKey This is a descriptor representation of the PKCS#8 key data + * @param aReturnedKey This is filled by the caller with required + * attributes, leaving the TKeyIdentifier iID and object handle iHandle + * uninitialised - these values are set if the key is created successfully + * + * @capability WriteUserData Requires the caller to have WriteUserData capability + * @leave KErrPermissionDenied If the caller does not have WriteUserData capability + * @leave KErrAlreadyExists If a key with the specified label already exists + * in the keystore. + * @leave KErrKeySize If the requested key size is not supported. + * @leave KErrKeyAccess If an invalid combination of key access flags were specified. + * @leave KErrKeyValidity If a validity period was specified, but the end + * date was in the past. + * @leave KErrArgument If there is an error parsing the key data. + */ + virtual void ImportEncryptedKey(const TDesC8& aKey, + CCTKeyInfo*& aReturnedKey, + TRequestStatus& aStatus) = 0; + + /** Cancels an ongoing ImportEncryptedKey() operation. */ + virtual void CancelImportEncryptedKey() = 0; + + /** + * Export keys + */ + + /** + * Exports a key pair in the clear. + * + * The key is exported as DER-encoded PKCS#8 data. + * + * @param aHandle The handle of the key to export + * @param aKey A reference to a HBufC8 pointer. The pointer will be set to + * a newly allocated buffer containing the key data. It is the caller's + * responsibility to delete this buffer. + * + * @capability Dependent Requires the caller to have any capabilities specified in the + * key management security policy. + * @leave KErrPermissionDenied If the caller does not conform to the key + * management security policy. + * @leave KErrNotFound If the key the handle referes to does not exist. + * @leave KErrKeyAccess If the sensitive flag is set for the key, or the + * exportable flag is not set. + * @leave KErrKeyAlgorithm If this type of key cannot be exported. + */ + virtual void ExportKey(TCTTokenObjectHandle aHandle, + HBufC8*& aKey, + TRequestStatus& aStatus) = 0; + + /** Cancels an ongoing ExportKey() operation. */ + virtual void CancelExportKey() = 0; + + /** + * Exports an encrypted key pair. + * + * The key is exported as DER-encoded PKCS#5/PKCS#8 data. + * + * @param aHandle The handle of the key to export + * @param aKey A reference to a HBufC8 pointer. The pointer will be set to + * a newly allocated buffer containing the key data. + * @param aParams The PBE encryption parameters to use when encrypting the key. + * + * @capability Dependent Requires the caller to have any capabilities specified in the + * key management security policy. + * @leave KErrPermissionDenied If the caller does not conform to the key + * management security policy. + * @leave KErrNotFound If the key the handle referes to does not exist. + * @leave KErrKeyAccess If the exportable flag is not set for the key. + * @leave KErrKeyAlgorithm If this type of key cannot be exported. + */ + virtual void ExportEncryptedKey(TCTTokenObjectHandle aHandle, + const CPBEncryptParms& aEncryptParams, + HBufC8*& aKey, + TRequestStatus& aStatus) = 0; + + /** Cancels an ongoing ExportEncryptedKey() operation. */ + virtual void CancelExportEncryptedKey() = 0; + + /** + * Deletes a key. + * + * @param aHandle The handle of the key to delete + * + * @capability Dependent Requires the caller to have any capabilities specified in the + * key management security policy. + * @leave KErrPermissionDenied If the caller does not conform to the key + * management security policy. + * @leave KErrNotFound If the key the handle referes to does not exist. + * @leave KErrAccessDenied If the calling process is not allowed to delete the key. + * @leave KErrInUse If another client is currently using the key. + */ + virtual void DeleteKey(TCTTokenObjectHandle aHandle, + TRequestStatus& aStatus) = 0; + + /** Cancels an ongoing DeleteKey() operation. */ + virtual void CancelDeleteKey() = 0; + + /** + * Sets the security policy for key use. + * + * Specifies which processes are allowed to use the key for cryptographic + * operations. + * + * @param aHandle The handle of the key + * @param aPolicy The new security policy. + * + * @capability Dependent Requires the caller to have any capabilities specified in the + * key management security policy. + * @leave KErrPermissionDenied If the caller does not conform to the key + * management security policy. + * @leave KErrNotFound If the key the handle referes to does not exist. + */ + virtual void SetUsePolicy(TCTTokenObjectHandle aHandle, + const TSecurityPolicy& aPolicy, + TRequestStatus& aStatus) = 0; + + /** Cancels an ongoing SetUsePolicy() operation. */ + virtual void CancelSetUsePolicy() = 0; + + /** + * Sets the security policy for key management. + * + * Specifies which processes are allowed to perform management operations on + * the key. + * + * @param aHandle The handle of the key + * @param aPolicy The new security policy. + * + * @capability Dependent Requires the caller to have any capabilities specified in the + * current and new key management security policies. + * @leave KErrPermissionDenied If the caller does not conform to the current + * and new key management security policies. + * @leave KErrNotFound If the key the handle referes to does not exist. + */ + virtual void SetManagementPolicy(TCTTokenObjectHandle aHandle, + const TSecurityPolicy& aPolicy, + TRequestStatus& aStatus) = 0; + + /** Cancels an ongoing SetManagementPolicy() operation. */ + virtual void CancelSetManagementPolicy() = 0; + + /** + * Sets the passphrase timeout for all keys owned by this process. + * + * @param aTimeout The timeout in seconds. 0 means that the passphrase is + * always asked for, and -1 means that it is never expired + * @param aStatus This will be completed with the final status code + * + * @capability Dependent Requires the caller to have any capabilities specified in the + * key management security policy. + * @leave KErrPermissionDenied If the caller does not conform to the key + * management security policy. + * @leave KErrArgument If the timeout specified is invalid. + */ + virtual void SetPassphraseTimeout(TInt aTimeout, + TRequestStatus& aStatus) = 0; + + /** Cancels an ongoing SetPassphraseTimeout() operation. */ + virtual void CancelSetPassphraseTimeout() = 0; + + /** + * Re-locks the entire store (i.e., forget the pasphrase) + * + * @param aStatus This will be completed with the final status code + */ + virtual void Relock(TRequestStatus& aStatus) = 0; + + /** Cancels an ongoing Relock() operation. */ + virtual void CancelRelock() = 0; +}; + + +#endif // __MCTKEYSTOREMANAGER_H__