/*
* 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__