0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync/** @file
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync * Main - Secret key interface.
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync */
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync/*
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync * Copyright (C) 2015 Oracle Corporation
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync *
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync * This file is part of VirtualBox Open Source Edition (OSE), as
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync * available from http://www.virtualbox.org. This file is free software;
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync * you can redistribute it and/or modify it under the terms of the GNU
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync * General Public License (GPL) as published by the Free Software
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync * Foundation, in version 2 as it comes in the "COPYING" file of the
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync */
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync#ifndef ____H_SECRETKEYSTORE
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync#define ____H_SECRETKEYSTORE
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync#include "VirtualBoxBase.h"
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync#include "VBox/com/array.h"
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsyncclass SecretKey
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync{
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync public:
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync /**
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync * Constructor for a secret key.
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync *
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync * @param pbKey The key buffer.
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync * @param cbKey Size of the key.
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync * @param fKeyBufNonPageable Flag whether the key buffer should be non pageable.
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync */
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync SecretKey(const uint8_t *pbKey, size_t cbKey, bool fKeyBufNonPageable);
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync /**
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync * Secret key destructor.
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync */
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync ~SecretKey();
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync /**
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync * Increments the reference counter of the key.
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync *
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync * @returns The new reference count.
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync */
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync uint32_t retain();
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync /**
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync * Releases a reference of the key.
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync * If the reference counter reaches 0 the key buffer might be protected
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync * against further access or the data will become scrambled.
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync *
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync * @returns The new reference count.
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync */
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync uint32_t release();
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync /**
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync * Returns the reference count of the secret key.
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync */
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync uint32_t refCount();
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync /**
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync * Sets the possible number of users for this key.
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync *
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync * @returns VBox status code.
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync * @param cUsers The possible number of user for this key.
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync */
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync int setUsers(uint32_t cUsers);
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync /**
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync * Returns the possible amount of users.
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync *
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync * @returns Possible amount of users.
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync */
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync uint32_t getUsers();
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync /**
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync * Sets the remove on suspend flag.
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync *
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync * @returns VBox status code.
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync * @param fRemoveOnSuspend Flag whether to remove the key on host suspend.
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync */
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync int setRemoveOnSuspend(bool fRemoveOnSuspend);
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync /**
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync * Returns whether the key should be destroyed on suspend.
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync */
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync bool getRemoveOnSuspend();
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync /**
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync * Returns the buffer to the key.
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync */
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync const void *getKeyBuffer();
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync /**
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync * Returns the size of the key.
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync */
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync size_t getKeySize();
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync private:
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync /** Reference counter of the key. */
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync volatile uint32_t m_cRefs;
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync /** Key material. */
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync uint8_t *m_pbKey;
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync /** Size of the key in bytes. */
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync size_t m_cbKey;
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync /** Flag whether to remove the key on suspend. */
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync bool m_fRemoveOnSuspend;
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync /** Number of entities which will use this key. */
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync uint32_t m_cUsers;
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync};
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsyncclass SecretKeyStore
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync{
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync public:
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync /**
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync * Constructor for a secret key store.
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync *
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync * @param fKeyBufNonPageable Flag whether the key buffer is required to
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync * be non pageable.
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync */
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync SecretKeyStore(bool fKeyBufNonPageable);
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync /**
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync * Destructor of a secret key store. This will free all stored secret keys
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync * inluding the key buffers. Make sure there no one accesses one of the keys
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync * stored.
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync */
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync ~SecretKeyStore();
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync /**
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync * Add a secret key to the store.
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync *
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync * @returns VBox status code.
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync * @param strKeyId The key identifier.
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync * @param pbKey The key to store.
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync * @param cbKey Size of the key.
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync */
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync int addSecretKey(const com::Utf8Str &strKeyId, const uint8_t *pbKey, size_t cbKey);
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync /**
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync * Deletes a key from the key store associated with the given identifier.
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync *
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync * @returns VBox status code.
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync * @param strKeyId The key identifier.
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync */
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync int deleteSecretKey(const com::Utf8Str &strKeyId);
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync /**
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync * Returns the secret key object associated with the given identifier.
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync * This increments the reference counter of the secret key object.
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync *
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync * @returns VBox status code.
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync * @param strKeyId The key identifier.
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync * @param ppKey Where to store the secret key object on success.
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync */
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync int retainSecretKey(const com::Utf8Str &strKeyId, SecretKey **ppKey);
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync /**
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync * Releases a reference to the secret key object.
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync *
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync * @returns VBox status code.
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync * @param strKeyId The key identifier.
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync */
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync int releaseSecretKey(const com::Utf8Str &strKeyId);
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync /**
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync * Deletes all secret keys from the key store.
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync *
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync * @returns VBox status code.
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync * @param fSuspend Flag whether to delete only keys which are
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync * marked for deletion during a suspend.
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync * @param fForce Flag whether to force deletion if some keys
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync * are still in use. Otherwise an error is returned.
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync */
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync int deleteAllSecretKeys(bool fSuspend, bool fForce);
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync private:
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync typedef std::map<com::Utf8Str, SecretKey *> SecretKeyMap;
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync /** The map to map key identifers to secret keys. */
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync SecretKeyMap m_mapSecretKeys;
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync /** Flag whether key buffers should be non pagable. */
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync bool m_fKeyBufNonPageable;
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync};
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync
0df8f2889273aee65079da0f4b5727a4ac6d3e7bvboxsync#endif /* !____H_SECRETKEYSTORE */