/*
* 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;
#ifdef SYMBIAN_AUTH_SERVER
/**
* Generate a new key pair and store it in keystore. The key should be stored against an
* already authenticated user. If there is no user currently authenticated then authentication
* should be performed before creation of the key.
*
* @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 aAuthenticationString The expression through which a user can be authenticated.
* Currently this should correspond to one of the alias values
* set by the licensee for authentication server configuration.
* This should be stored against the created key.
* @param aFreshness The validity to be considered for an already authenticated
* identity. This should be stored against the created key.
* Specification is in seconds.
*
* @param aStatus This will be completed with the final status code. Some specific
* codes are as follows.
* KErrPermissionDenied If the caller does not have WriteUserData
* capability.
* KErrAlreadyExists If a key with the specified label already
* exists in the keystore for the specific
* user.
* KErrKeySize If the requested key size is not supported.
* KErrKeyAccess If an invalid combination of key access
* flags were specified.
* KErrKeyValidity If a validity period was specified, but the
* end date was in the past.
* KErrAuthenticationFailure If the user authentication fails.
*
* @see AuthServer::CAuthExpression
*
* @capability WriteUserData Should require the caller to have WriteUserData capability.
*/
virtual void CreateKey( const TDesC& /*aAuthenticationString*/,
TInt /*aFreshness*/,
CCTKeyInfo*& /*aReturnedKey*/,
TRequestStatus& aStatus )
{
TRequestStatus* status = &aStatus;
User::RequestComplete(status,KErrNotSupported);
}
/**
* Imports a der-encoded PKCS#8 format key pair into the keystore. The key should be stored against an
* already authenticated user. If there is no user currently authenticated then authentication
* should be performed before creation of the key.
*
*
* @param aKey This is a descriptor representation of the PKCS#8 key data.
* @param aAuthenticationString The expression through which a user can be authenticated.
* Currently this should correspond to one of the alias values
* set by the licensee for authentication server configuration.
* This should be stored against the created key.
* @param aFreshness The validity to be considered for an already authenticated
* identity. This should be stored against the created key.
* Specification is in seconds.
* @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. Some specific
* codes are as follows.
* KErrPermissionDenied If the caller does not have WriteUserData
* capability.
* KErrAlreadyExists If a key with the specified label already
* exists in the keystore for the specific
* user.
* KErrKeySize If the requested key size is not supported.
* KErrKeyAccess If an invalid combination of key access flags
* were specified.
* KErrKeyValidity If a validity period was specified, but the end
* date was in the past.
* KErrArgument If there is an error parsing the key data.
* KErrAuthenticationFailure If the user authentication fails.
*
* @see AuthServer::CAuthExpression
*
* @capability WriteUserData Should require the caller to have WriteUserData capability
*/
virtual void ImportKey( const TDesC8& /*aKey*/,
const TDesC& /*aAuthenticationString*/,
TInt /*aFreshness*/,
CCTKeyInfo*& /*aReturnedKey*/,
TRequestStatus& aStatus )
{
TRequestStatus* status = &aStatus;
User::RequestComplete(status,KErrNotSupported);
}
/**
* Imports an encrypted key pair into the keystore. The key should be stored against an
* already authenticated user. If there is no user currently authenticated then authentication
* should be performed before creation of the key.
*
* The import data should be der-encoded PKCS#8 format encrypted in accordance to PKCS#5
* specification.
*
* @param aKey This is a descriptor representation of the PKCS#8 key data.
* Encrypted in accordance to PKCS#5 specification.
* @param aAuthenticationString The expression through which a user can be authenticated.
* Currently this should correspond to one of the alias values
* set by the licensee for authentication server configuration.
* This should be stored against the created key.
* @param aFreshness The validity to be considered for an already authenticated
* identity. This should be stored against the created key.
* Specification is in seconds.
* @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. Some specific
* codes are as follows.
* KErrPermissionDenied If the caller does not have WriteUserData
* capability.
* KErrAlreadyExists If a key with the specified label already
* exists in the keystore for the specific
* user.
* KErrKeySize If the requested key size is not supported.
* KErrKeyAccess If an invalid combination of key access flags
* were specified.
* KErrKeyValidity If a validity period was specified, but the end
* date was in the past.
* KErrArgument If there is an error parsing the key data.
* KErrAuthenticationFailure If the user authentication fails.
*
* @see AuthServer::CAuthExpression
*
* @capability WriteUserData Should require the caller to have WriteUserData capability
*/
virtual void ImportEncryptedKey( const TDesC8& /*aKey*/,
const TDesC& /*aAuthenticationString*/,
TInt /*aFreshness*/,
CCTKeyInfo*& /*aReturnedKey*/,
TRequestStatus& aStatus )
{
TRequestStatus* status = &aStatus;
User::RequestComplete(status, KErrNotSupported);
}
/**
* Set the authentication policy for an already existing key in the store.
*
* @param aHandle The handle of the key whose policy is to be changed.
* @param aAuthenticationString The expression associated to this key.
* @param aFreshness The validity associated to this key.
* Specification is in seconds.
* @param aStatus Final status of the operation.
* KErrAuthenticationFailure If the user authentication fails.
*
* @see AuthServer::CAuthExpression
*
*/
virtual void SetAuthenticationPolicy( const TCTTokenObjectHandle /*aHandle*/,
const TDesC& /*aAuthenticationString*/,
TInt /*aFreshness*/,
TRequestStatus& aStatus)
{
TRequestStatus* status = &aStatus;
User::RequestComplete(status, KErrNotSupported);
}
/**
* Retrieve authentication policy for an already existing key in the store.
*
* @param aHandle The handle of the key whose policy is to be retrieved.
* @param aAuthenticationString The expression associated to this key. The memory would
* be allocated at the server side.
* @param aFreshness The validity associated to this key.
* Specification is in seconds.
* @param aStatus Final status of the operation.
* KErrAuthenticationFailure If the user authentication fails.
*
* @see AuthServer::CAuthExpression
*
*/
virtual void GetAuthenticationPolicy( const TCTTokenObjectHandle /*aHandle*/,
HBufC*& /*aAuthenticationString*/,
TInt& /*aFreshness*/,
TRequestStatus& aStatus)
{
TRequestStatus* status = &aStatus;
User::RequestComplete(status, KErrNotSupported);
}
#endif // SYMBIAN_AUTH_SERVER
};
#endif // __MCTKEYSTOREMANAGER_H__