/* * CDDL HEADER START * * The contents of this file are subject to the terms of the * Common Development and Distribution License (the "License"). * You may not use this file except in compliance with the License. * * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE * or http://www.opensolaris.org/os/licensing. * See the License for the specific language governing permissions * and limitations under the License. * * When distributing Covered Code, include this CDDL HEADER in each * file and include the License file at usr/src/OPENSOLARIS.LICENSE. * If applicable, add the following below this CDDL HEADER, with the * fields enclosed by brackets "[]" replaced with your own identifying * information: Portions Copyright [yyyy] [name of copyright owner] * * CDDL HEADER END */ /* * Copyright (c) 2008, 2010, Oracle and/or its affiliates. All rights reserved. */ /** @file KMSAgent.h * @defgroup EncryptionAgent Encryption Agent API * * The Agent API is used to communicate with the KMS Appliance for the * purpose of registering storage devices, obtaining device keys, and * receiving notifications of storage device events such as destruction. * */ #ifndef KMS_AGENT_H #define KMS_AGENT_H #include "KMSClientProfile.h" /*--------------------------------------------------------------------------- * The following ifdef block is the standard way of creating macros which * make exporting from a DLL simpler. All files within this DLL are compiled * with the KMS_AGENT_EXPORT symbol defined on the command line. this symbol * should not be defined on any project that uses this DLL. This way any * other project whose source files include this file see KMS Agent API functions * as being imported from a DLL, wheras this DLL sees symbols defined with * this macro as being exported. *--------------------------------------------------------------------------*/ #ifdef KMS_AGENT_EXPORT #define KMS_AGENT_API __declspec(dllexport) #else #define KMS_AGENT_API __declspec(dllimport) #endif #ifdef __cplusplus extern "C" { #endif /*--------------------------------------------------------------------------- * Return Codes *--------------------------------------------------------------------------*/ /** * The status type returned on API calls */ typedef int KMS_AGENT_STATUS; /** * successful status */ #define KMS_AGENT_STATUS_OK 0 /* error status values */ /** * generic error is a catch all for a wide variety of errors, see the specific * entry in the audit log for the details. In general, the client API will return * one of the specific status codes. */ #define KMS_AGENT_STATUS_GENERIC_ERROR 100 /** * insufficient memory for the agent library to complete the request */ #define KMS_AGENT_STATUS_NO_MEMORY 102 /** * parameter error, invalid input */ #define KMS_AGENT_STATUS_INVALID_PARAMETER 103 /** * an API call was made before the profile was loaded */ #define KMS_AGENT_STATUS_PROFILE_NOT_LOADED 104 /** * upon receipt of a key the callout function returned an error */ #define KMS_AGENT_STATUS_KEY_CALLOUT_FAILURE 105 /** * the specified profile failover attempts have been exceeded or no KMAs are available within the cluster */ #define KMS_AGENT_STATUS_KMS_UNAVAILABLE 106 /** * the KMS does not have any keys in the READY state, this is a KMS issue that requires attention * from a KMS administrator. */ #define KMS_AGENT_STATUS_KMS_NO_READY_KEYS 107 /** * the FIPS 140-2 known answer test (KAK) failed for AES Key wrap. */ #define KMS_AGENT_STATUS_FIPS_KAT_AES_KEYWRAP_ERROR 108 /** * #FIPS_MODE was specified on #KMSAgent_LoadProfile * but no FIPS compatible KMAs are currently * available. Also, it may be that no FIPS compatible KMAs have been * configured within the KMS. */ #define KMS_AGENT_STATUS_NO_FIPS_KMAS_AVAILABLE 109 /** * the profile was already successfully loaded and should be unloaded * before attempting to load it again */ #define KMS_AGENT_STATUS_PROFILE_ALREADY_LOADED 110 /** * the FIPS 140-2 known answer test (KAK) failed for AES ECB. */ #define KMS_AGENT_STATUS_FIPS_KAT_AES_ECB_ERROR 111 /** * the FIPS 140-2 known answer test (KAK) failed for HMAC-SHA1. */ #define KMS_AGENT_STATUS_FIPS_KAT_HMAC_SHA1_ERROR 112 /* * SOAP Sender Errors - client errors associated with a KMS SOAP service */ /** * the following conditions can result in access denied being returned by the KMSAgent Soap service: *
i_pInitialApplianceAddress
argument then the o_pClusterEntryArray
will contain
* IPv6 addresses instead of IPv4 addresses for each KMA that has an IPv6 address.
* @see #KMSAgent_LoadProfile and #KMSAgent_SelectAppliance.
*
* If the size of the cluster returned by the KMS_Discovery servic exceeds i_iClusterEntryArraySize
* then the KMA list is filtered to contain the
* first i_iClusterEntryArraySize
KMAs that meet the profile's FIPS setting, agent site and are reported as responding by the
* KMS discover cluster response.
*
* @param i_pProfile a pointer to an initialized #KMSClientProfile structure
* @param i_iEntitySiteIDSize the buffer size of the entity site ID including null terminator
* (should be greater than #KMS_MAX_ENTITY_SITE_ID )
* @param i_iClusterEntryArraySize the array size for cluster entries (must be less than or equal to #KMS_MAX_CLUSTER_NUM )
* @param o_pEntitySiteID a buffer allocated by the caller to store the agent's (aka entity) Site ID
* @param o_pApplianceNum the returned number of appliances in the cluster
* @param o_pClusterEntryArray a buffer allocated by the caller to store the array of cluster entries
*
* @return #KMS_AGENT_STATUS_OK
* @return #KMS_AGENT_STATUS_INVALID_PARAMETER
* @return #KMS_AGENT_STATUS_GENERIC_ERROR
* @return #KMS_AGENT_STATUS_ACCESS_DENIED
* @return #KMS_AGENT_STATUS_PROFILE_NOT_LOADED
* @return #KMS_AGENT_STATUS_SERVER_BUSY
* @return #KMS_AGENT_STATUS_KMS_UNAVAILABLE
* @return #KMS_AGENT_STATUS_NO_FIPS_KMAS_AVAILABLE
*/
KMS_AGENT_STATUS KMSAgent_GetClusterInformation(
KMSClientProfile * const i_pProfile,
int i_iEntitySiteIDSize,
int i_iClusterEntryArraySize,
utf8cstr const o_pEntitySiteID,
int * const o_pApplianceNum,
KMSClusterEntry * const o_pClusterEntryArray);
/**
* Specifies the Key Management Appliance to be used
* for retrieving cluster information.
*
* @param i_pProfile a pointer to an initialized #KMSClientProfile
* structure
* @param i_pApplianceAddress the IP address of the appliance. IPv6 addresses
* must be enclosed in brackets, [], see #KMSAgent_LoadProfile.
*
* @return #KMS_AGENT_STATUS_OK
* @return #KMS_AGENT_STATUS_INVALID_PARAMETER
* @return #KMS_AGENT_STATUS_GENERIC_ERROR
* @return #KMS_AGENT_STATUS_PROFILE_NOT_LOADED
*
*/
KMS_AGENT_STATUS KMSAgent_SelectAppliance(
KMSClientProfile* const i_pProfile,
utf8cstr const i_pApplianceAddress );
/**
* Load profile handles both agent enrollment with the KMS and post enrollment setup.
*
* Enrollment Behavior
*
* When a passphrase is supplied enrollment, or reenrollment, with a KMS cluster is attempted in order
* to establish a mutual trust relationship. Enrollment occurs with the KMA in the cluster specified
* by i_pApplianceAddress
.
*
* The KMS CA web service is used for CA certificate retrieval prior to
* invoking the KMS Certificate web service. Certficate retrieval via these services
* uses the i_pApplianceAddress
for enrollment. Cluster discovery is then performed to
* identify the set of KMAs within the cluster.
* Successful enrollment results in
* persistent storage of the CA X.509 certificate, agent X.509 certificate and private key.
*
* Post Enrollment Behavior
*
* When a passphrase is not provided a profile is assumed to exist and the library profile structure
* is initialized from persistent storage with the configuration settings(agent ID,
* KMA service port numbers, KMA Address, transaction timeout, discovery frequency, transaction timeout
* and failover limit), cluster information(agent's site ID and KMA cluster information and KMA status) and
* enrollment items: the CA certificate, Agent Certificate and agent private key.
*
* Finally, cluster discovery is performed(unless disabled), and a load balancer is initialized
* for balancing transactions across KMAs within the
* cluster and for handling transaction failover scenarios.
* Subsequent API calls using the profile will invoke cluster discovery at the frequency specified
* by iClusterDiscoveryFrequency
. Updated discovery information is persisted with the
* profile. The load balancer maintains affinity to KMAs within the same site as the agent for
* agent transactions unless an error requires failover
* to another KMA in the cluster. An agent's site ID may also be updated by a discovery
* operation.
*
* @param io_pProfile a pointer to a #KMSClientProfile buffer allocated by the caller
* @param i_pProfileName the profile name
* @param i_pAgentID Optional. For a new profile the encryption agent's ID is required.
* @param i_pPassphrase Optional. For a new profile the encryption agent's passphrase is required. This passphrase
* may only be used once for a successful retrieval of the Certificate and agent private key.
* @param i_pInitialApplianceAddress the initial IP Address of an Appliance in the KMS Cluster that is reachable by this agent. If
* enrollment has previously occurred specification of an initial IP address that is not
* a member of the profile's cluster information will force the cluster information
* to be deleted and discovery to be performed with the new IP address.
* An IPv6 address may be supplied but must be enclosed with brackets, [], in accordance
* with RFC 2396, "Format for Literal IPv6 Addresses in URL's". Supplying an IPv6 address will cause
* the agent library to utilize KMA IPv6 addresses over IPv4 addresses when they are available,
* otherwise IPv4 KMA addresses will be used.
* @param i_iTransactionTimeout the timeout setting for a transaction in seconds, must be a positive value.
* @param i_iFailOverLimit Failed KMA transactions will be retried up to this limit. Once this limit
* has been reached API calls will return #KMS_AGENT_STATUS_KMS_UNAVAILABLE.
* Specify -1 for unlimited failover attempts, 0 for no failover. The worst case completion time for
* an API call is approximately equal to i_iFailOverLimit
* i_iTransactionTimeout
.
*
* @param i_iClusterDiscoveryFrequency
* frequency of calling cluster discovery service
* in seconds (use 0 to disable load balancing and periodic cluster discovery)
* @param i_eKMSmode specifies the KMS operational mode that the
* agent should enforce. Setting this to #FIPS_MODE
* causes the agent to only communicate with KMAs in the
* cluster that support AES key wrapping for key requests.
* This is not a persisted setting and is only applicable
* to the current session.
*
* @return #KMS_AGENT_STATUS_OK
* @return #KMS_AGENT_STATUS_INVALID_PARAMETER
* @return #KMS_AGENT_STATUS_GENERIC_ERROR
* @return #KMS_AGENT_STATUS_PROFILE_NOT_LOADED
* @return #KMS_AGENT_STATUS_PROFILE_ALREADY_LOADED
* @return #KMS_AGENT_STATUS_ACCESS_DENIED
* @return #KMS_AGENT_STATUS_SERVER_BUSY
* @return #KMS_AGENT_STATUS_KMS_UNAVAILABLE
* @return #KMS_AGENT_STATUS_NO_FIPS_KMAS_AVAILABLE
*/
KMS_AGENT_STATUS KMSAgent_LoadProfile(
KMSClientProfile* const io_pProfile,
utf8cstr const i_pProfileName,
utf8cstr const i_pAgentID,
utf8cstr const i_pPassphrase,
utf8cstr const i_pInitialApplianceAddress,
int i_iTransactionTimeout,
int i_iFailOverLimit,
int i_iClusterDiscoveryFrequency,
int i_eKMSmode );
/**
* Destroy the profile information in memory, the agent's profile configuration,
* cluster information, certificate and
* private key are retained in persistant storage.
*
* @param i_pProfile a pointer to an initialized KMSClientProfile
* structure.
*
* @return #KMS_AGENT_STATUS_OK
* @return #KMS_AGENT_STATUS_INVALID_PARAMETER
*
*/
KMS_AGENT_STATUS KMSAgent_UnloadProfile(
KMSClientProfile* const i_pProfile );
/**
* Delete the profile information from persistent storage. The agent's profile configuration,
* cluster information, certificate and
* private key are discared, see #KMSAgent_LoadProfile for how to initialize
* the profile again. The profile should be unloaded prior to making this call.
*
* @param i_pProfileName the profile name
*
* @return #KMS_AGENT_STATUS_OK
* @return #KMS_AGENT_STATUS_INVALID_PARAMETER
* @return #KMS_AGENT_STATUS_GENERIC_ERROR
*/
KMS_AGENT_STATUS KMSAgent_DeleteProfile(
utf8cstr i_pProfileName );
/**
* Fetch the key groups this agent is allowed to access. The caller should invoke #KMSAgent_FreeArrayOfKeyGroups
* to release the allocated memory resources for the array. Up to #KMS_MAX_LIST_KEY_GROUPS key groups will be
* returned.
*
* @param i_pProfile an initialized #KMSClientProfile
* @param o_ppKeyGroups a buffer allocated by this routine for the array of Key Groups and individual key groups
* that this agent is allowed to access
*
* @return #KMS_AGENT_STATUS_OK
* @return #KMS_AGENT_STATUS_INVALID_PARAMETER
* @return #KMS_AGENT_STATUS_PROFILE_NOT_LOADED
* @return #KMS_AGENT_STATUS_NO_MEMORY
* @return #KMS_AGENT_STATUS_GENERIC_ERROR
* @return #KMS_AGENT_STATUS_ACCESS_DENIED
* @return #KMS_AGENT_STATUS_INVALID_PARAMETER
* @return #KMS_AGENT_STATUS_SERVER_BUSY
* @return #KMS_AGENT_STATUS_KMS_UNAVAILABLE
* @return #KMS_AGENT_STATUS_NO_FIPS_KMAS_AVAILABLE
*/
KMS_AGENT_STATUS KMSAgent_ListKeyGroups(
KMSClientProfile* const i_pProfile,
KMSAgent_ArrayOfKeyGroups** const o_ppKeyGroups );
/**
* Helper function which frees memory allocated for the output
* to #KMSAgent_ListKeyGroups.
*
* @param i_pArrayOfKeyGroups a pointer to #KMSAgent_ArrayOfKeyGroups
*
* @return void
*
*/
void KMSAgent_FreeArrayOfKeyGroups(
KMSAgent_ArrayOfKeyGroups* i_pArrayOfKeyGroups );
/**
* Creates a Key for the specified data unit. If a data unit is provided then the key will be associated with
* the data unit. The type of key created is dictated by the KMS key policy for the key group. This policy is set up by KMS
* administrators to be compatible with agents associated with the key group.
* If KeyGroup is provided then the new key is associated with the specified KeyGroup, otherwise the agent's
* default KeyGroup is associated with the key.
* @param i_pProfile an initialized #KMSClientProfile
* @param i_pDataUnit Optional. a pointer to a data unit to be associated with the key, if known.
* @param i_pKeyGroupID Optional, the KeyGroup ID to be assigned to the new Key, if known. Pass NULL
* if unknown and the new key will be associated with the agent's default key group
* @param o_pKey A pointer to a buffer for returning the new key and key associated data.
*
* @return #KMS_AGENT_STATUS_OK
* @return #KMS_AGENT_STATUS_INVALID_PARAMETER
* @return #KMS_AGENT_STATUS_PROFILE_NOT_LOADED
* @return #KMS_AGENT_STATUS_NO_MEMORY
* @return #KMS_AGENT_STATUS_KEY_CALLOUT_FAILURE
* @return #KMS_AGENT_STATUS_GENERIC_ERROR
* @return #KMS_AGENT_STATUS_ACCESS_DENIED
* @return #KMS_AGENT_STATUS_SERVER_BUSY
* @return #KMS_AGENT_STATUS_EXTERNAL_UNIQUE_ID_EXISTS
* @return #KMS_AGENT_STATUS_KMS_UNAVAILABLE
* @return #KMS_AGENT_STATUS_KMS_NO_READY_KEYS
* @return #KMS_AGENT_STATUS_NO_FIPS_KMAS_AVAILABLE
* @return #KMS_AGENT_AES_KEY_UNWRAP_ERROR
* @return #KMS_AGENT_AES_KEY_WRAP_SETUP_ERROR
*/
KMS_AGENT_STATUS KMSAgent_CreateKey(
KMSClientProfile* const i_pProfile,
const KMSAgent_DataUnit* const i_pDataUnit,
KEY_GROUP_ID const i_pKeyGroupID,
KMSAgent_Key* const o_pKey);
/**
* Creates a DataUnit with the specified external unique id and external tag.
*
* @param i_pProfile an initialized #KMSClientProfile
* @param i_pExternalUniqueID Optional. A unique data unit identifier to be associated with
* the data unit. Uniqueness is enforced by the KMS. See also #KMSAgent_RetrieveDataUnit.
* @param i_iExternalUniqueIDIDLen Length in bytes of the external unique identifier. If
* i_pExternalUniqueID
is NULL then this field is ignored, otherwise a positive length must be provided.
* @param i_pExternalTag Optional, but recommended. Pointer to an External Tag for the data unit, e.g. a volume serial number.
* @param i_pDescription Optional, a textual description of the data unit.
* @param o_pDataUnit a pointer to a DataUnit buffer where
* data unit information is returned
*
* @return #KMS_AGENT_STATUS_OK
* @return #KMS_AGENT_STATUS_INVALID_PARAMETER
* @return #KMS_AGENT_STATUS_PROFILE_NOT_LOADED
* @return #KMS_AGENT_STATUS_NO_MEMORY
* @return #KMS_AGENT_STATUS_GENERIC_ERROR
* @return #KMS_AGENT_STATUS_ACCESS_DENIED
* @return #KMS_AGENT_STATUS_SERVER_BUSY
* @return #KMS_AGENT_STATUS_EXTERNAL_UNIQUE_ID_EXISTS
* @return #KMS_AGENT_STATUS_KMS_UNAVAILABLE
* @return #KMS_AGENT_STATUS_NO_FIPS_KMAS_AVAILABLE
*/
KMS_AGENT_STATUS KMSAgent_CreateDataUnit(
KMSClientProfile* const i_pProfile,
const unsigned char * i_pExternalUniqueID,
int i_iExternalUniqueIDIDLen,
utf8cstr const i_pExternalTag,
utf8cstr const i_pDescription,
KMSAgent_DataUnit* const o_pDataUnit);
/**
* The agent may use this function to inform the KMS that the DataUnit has, or will be, overwritten.
* The KMS will remove the association from the specified DataUnit to all its keys, excluding its key
* in the #KMS_KEY_STATE_ACTIVE_PROTECT_AND_PROCESS state. By utilizing this API, agent's can help keep the
* number of keys returned by #KMSAgent_RetrieveDataUnitKeys to just the keys being used on the Data Unit.
*
* @param i_pProfile an initialized #KMSClientProfile
* @param i_pDataUnit A pointer to the data unit
*
* @return #KMS_AGENT_STATUS_OK
* @return #KMS_AGENT_STATUS_INVALID_PARAMETER
* @return #KMS_AGENT_STATUS_PROFILE_NOT_LOADED
* @return #KMS_AGENT_STATUS_NO_MEMORY
* @return #KMS_AGENT_STATUS_GENERIC_ERROR
* @return #KMS_AGENT_STATUS_ACCESS_DENIED
* @return #KMS_AGENT_STATUS_SERVER_BUSY
* @return #KMS_AGENT_STATUS_EXTERNAL_UNIQUE_ID_EXISTS
* @return #KMS_AGENT_STATUS_KMS_UNAVAILABLE
* @return #KMS_AGENT_STATUS_NO_FIPS_KMAS_AVAILABLE
*/
KMS_AGENT_STATUS KMSAgent_DisassociateDataUnitKeys(
KMSClientProfile* const i_pProfile,
const KMSAgent_DataUnit* const i_pDataUnit);
/**
* retrieve a key by the Key's ID, optionally specifying the Data Unit and KeyGroup to be
* associated with the key. Supplying the Data Unit information allows the KMS to add an
* association between the Key and the Data Unit. The assumption being made is that the key being
* retrieved has been used on the specified Data Unit and needs to be associated with it. This
* side affect allows the KMS to build up its knowledge of key usage as it relies upon agents
* for discovering and reporting how keys are being used on Data Units. For example, when keys
* are imported into a KMS the information associating keys with DataUnits may not be provided,
* consequently the KMS is unaware of what DataUnits were encrypted with a particular key.
*
* @param i_pProfile an initialized KMSClientProfile
* @param i_pKeyID The ID of the Key being requested
* @param i_pDataUnit Optional. If non-NULL, the KMS will verify that an association exists between the key and the Data Unit and create
* the association if it is missing.
* @param i_pKeyGroupID Optional. If non-NULL, and the key is not already associated with a KeyGroup, then the KMS will associate the key with the specified KeyGroup.
* @param o_pKey A pointer to a buffer allcoated by the caller for returning the new key and key associated data.
*
* @return #KMS_AGENT_STATUS_OK
* @return #KMS_AGENT_STATUS_INVALID_PARAMETER
* @return #KMS_AGENT_STATUS_PROFILE_NOT_LOADED
* @return #KMS_AGENT_STATUS_NO_MEMORY
* @return #KMS_AGENT_STATUS_KEY_CALLOUT_FAILURE
* @return #KMS_AGENT_STATUS_GENERIC_ERROR
* @return #KMS_AGENT_STATUS_ACCESS_DENIED
* @return #KMS_AGENT_STATUS_SERVER_BUSY
* @return #KMS_AGENT_STATUS_EXTERNAL_UNIQUE_ID_EXISTS
* @return #KMS_AGENT_STATUS_KEY_DOES_NOT_EXIST
* @return #KMS_AGENT_STATUS_KEY_DESTROYED
* @return #KMS_AGENT_STATUS_KMS_UNAVAILABLE
* @return #KMS_AGENT_STATUS_NO_FIPS_KMAS_AVAILABLE
* @return #KMS_AGENT_AES_KEY_UNWRAP_ERROR
* @return #KMS_AGENT_AES_KEY_WRAP_SETUP_ERROR
*/
KMS_AGENT_STATUS KMSAgent_RetrieveKey(
KMSClientProfile* const i_pProfile,
const unsigned char * const i_pKeyID,
const KMSAgent_DataUnit* const i_pDataUnit,
utf8cstr const i_pKeyGroupID,
KMSAgent_Key* const o_pKey);
/**
* Retrieve a Data Unit by its data unit identifier.
*
* @param i_pProfile an initialized #KMSClientProfile
* @param i_pDataUnitID the data unit ID by which retrieval will be performed
* @param i_pExternalUniqueID Optional, a unique data unit identifier to be associated with
* the data unit. Uniqueness is enforced by the KMS.
* @param i_iExternalUniqueIDLen Length in bytes of the external unique identifier, must be positive. If
* i_pExternalUniqueID
is NULL then this field is ignored.
* @param i_pExternalTag Optional, but recommended. Pointer to a data unit external tag, e.g. volser
* @param i_pDescription Optional, a textual description of the data unit.
* @param o_pDataUnit a pointer to a DataUnit buffer allocated by the caller where
* data unit information is returned
*
* @return #KMS_AGENT_STATUS_OK
* @return #KMS_AGENT_STATUS_INVALID_PARAMETER
* @return #KMS_AGENT_STATUS_PROFILE_NOT_LOADED
* @return #KMS_AGENT_STATUS_NO_MEMORY
* @return #KMS_AGENT_STATUS_GENERIC_ERROR
* @return #KMS_AGENT_STATUS_ACCESS_DENIED
* @return #KMS_AGENT_STATUS_SERVER_BUSY
* @return #KMS_AGENT_STATUS_EXTERNAL_UNIQUE_ID_EXISTS
* @return #KMS_AGENT_STATUS_KMS_UNAVAILABLE
* @return #KMS_AGENT_STATUS_NO_FIPS_KMAS_AVAILABLE
*/
KMS_AGENT_STATUS KMSAgent_RetrieveDataUnit(
KMSClientProfile* const i_pProfile,
const unsigned char * const i_pDataUnitID,
const unsigned char * const i_pExternalUniqueID,
int i_iExternalUniqueIDLen,
utf8cstr const i_pExternalTag,
utf8cstr const i_pDescription,
KMSAgent_DataUnit* const o_pDataUnit);
/**
* Retrieve a Data Unit by its external unique identifier.
* If the KMS does not contain a data unit with the specified unique identifier then a data unit will
* be created. The new data unit will contain the external unique identifier and the external tag, if
* provided.
*
* @param i_pProfile an initialized #KMSClientProfile
* @param i_pExternalUniqueID A unique data unit identifier to be associated with
* the data unit. Uniqueness is enforced by the KMS.
* @param i_iExternalUniqueIDLen Length in bytes of the external unique identifier, must be positive.
* @param i_pExternalTag Optional, but recommended. Pointer to a data unit external tag, e.g. volser
* @param i_pDescription Optional, a textual description of the data unit.
* @param o_pDataUnit a pointer to a DataUnit buffer allocated by the caller where
* data unit information is returned
*
* @return #KMS_AGENT_STATUS_OK
* @return #KMS_AGENT_STATUS_INVALID_PARAMETER
* @return #KMS_AGENT_STATUS_PROFILE_NOT_LOADED
* @return #KMS_AGENT_STATUS_NO_MEMORY
* @return #KMS_AGENT_STATUS_GENERIC_ERROR
* @return #KMS_AGENT_STATUS_ACCESS_DENIED
* @return #KMS_AGENT_STATUS_SERVER_BUSY
* @return #KMS_AGENT_STATUS_EXTERNAL_UNIQUE_ID_EXISTS
* @return #KMS_AGENT_STATUS_KMS_UNAVAILABLE
* @return #KMS_AGENT_STATUS_NO_FIPS_KMAS_AVAILABLE
*/
KMS_AGENT_STATUS KMSAgent_RetrieveDataUnitByExternalUniqueID(
KMSClientProfile* const i_pProfile,
const unsigned char* const i_pExternalUniqueID,
int i_iExternalUniqueIDLen,
utf8cstr const i_pExternalTag,
utf8cstr const i_pDescription,
KMSAgent_DataUnit* const o_pDataUnit);
/**
* retrieve keys assigned to a Data Unit.
* Agents should consult the state of each key that is returned and only
* use the key in the #KMS_KEY_STATE_ACTIVE_PROTECT_AND_PROCESS state for encryption. The agent service
* attempts to return the most recently created key in the #KMS_KEY_STATE_ACTIVE_PROTECT_AND_PROCESS state
* as the first key in the list when a i_pKeyID
is not specified. This cannot be guaranteed as
* there may not be a key in the #KMS_KEY_STATE_ACTIVE_PROTECT_AND_PROCESS state for the specified
* data unit. The rest of the keys returned are sorted in ascending order by the time in which
* they were created on the server.
* #KMSAgent_DisassociateDataUnitKeys may be used to manage the
* size of the key list associated with a data unit.
* The i_iPageSize
, i_iPageOffset
and o_piKeysRemaining
parameters may be used for retrieving
* subsets of the list. For the i_pKeyID
argument see the parameter's description.
* Callers should invoke#KMSAgent_FreeArrayOfKeys when finished with the buffer of keys.
*
* @param i_pProfile an initialized #KMSClientProfile
* @param i_pDataUnit The Data Unit for which all keys will be retrieved.
* @param i_iPageSize the number of keys to be retrieved, up to #KMS_MAX_PAGE_SIZE.
* @param i_iPageOffset the offset from the start of the data unit's key list. Set this to zero for
* retrieval from the start of the list or if i_pKeyID
is non-null.
* When set to zero the first key returned in the list
* will be the most recently created key in the #KMS_KEY_STATE_ACTIVE_PROTECT_AND_PROCESS state.
* @param o_piKeysRemaining a pointer to an integer where the number of keys remaining in the list will be returned
* @param i_pKeyID Optional. If non-null, the caller provides a pointer to a KeyID that is used for
* the retrieval and the list returned begins with the specified data unit's KeyID and up to
* i_iPageSize
keys associated with the data unit having an activation date greater than the key
* corresponding to i_pKeyID
. The first key in the list is not guaranteed
* to be in the #KMS_KEY_STATE_ACTIVE_PROTECT_AND_PROCESS state. If the specified i_pKeyID
* is not associated with the Data Unit then the behavior is like #KMSAgent_RetrieveKey and
* a single key is returned.
* When non-null the i_iPageOffset
* argument must be 0, these arguments are mutually exclusive.
* @param o_ppKeys a pointer to pointer to a #KMSAgent_ArrayOfKeys struct allocated by this routine for returning the specified number of
* Data Unit's keys and key associated data. Up to i_iPageSize
* keys will be returned. Callers should invoke #KMSAgent_FreeArrayOfKeys
* when finished with the buffer of keys.
* @return #KMS_AGENT_STATUS_OK
* @return #KMS_AGENT_STATUS_INVALID_PARAMETER
* @return #KMS_AGENT_STATUS_PROFILE_NOT_LOADED
* @return #KMS_AGENT_STATUS_NO_MEMORY
* @return #KMS_AGENT_STATUS_GENERIC_ERROR
* @return #KMS_AGENT_STATUS_ACCESS_DENIED
* @return #KMS_AGENT_STATUS_KEY_CALLOUT_FAILURE
* @return #KMS_AGENT_STATUS_SERVER_BUSY
* @return #KMS_AGENT_STATUS_EXTERNAL_UNIQUE_ID_EXISTS
* @return #KMS_AGENT_STATUS_KMS_UNAVAILABLE
* @return #KMS_AGENT_STATUS_KEY_DOES_NOT_EXIST if i_pKeyID
does not exist in the KMS.
* @return #KMS_AGENT_STATUS_KEY_DESTROYED if i_pKeyID
has been destroyed.
* @return #KMS_AGENT_STATUS_NO_FIPS_KMAS_AVAILABLE
* @return #KMS_AGENT_AES_KEY_UNWRAP_ERROR
* @return #KMS_AGENT_AES_KEY_WRAP_SETUP_ERROR
*/
KMS_AGENT_STATUS KMSAgent_RetrieveDataUnitKeys(
KMSClientProfile* const i_pProfile,
const KMSAgent_DataUnit* const i_pDataUnit,
int i_iPageSize,
int i_iPageOffset,
int* const o_piKeysRemaining,
const unsigned char * const i_pKeyID,
KMSAgent_ArrayOfKeys** const o_ppKeys);
/**
* returns a key in the #KMS_KEY_STATE_ACTIVE_PROTECT_AND_PROCESS for the specified data unit. A new
* key will be created if the data unit does not have a key in the protect and process state or if the
* agent is not authorized to access the key in the protect and process state.
* @param i_pProfile an initialized #KMSClientProfile
* @param i_pDataUnit The Data Unit for which a key in the protect and process state will be returned.
* @param i_pKeyGroupID Optional. If non-NULL and a new key is to be created, the KMS will associate the key with the specified KeyGroup
* @param o_pKey A pointer to a buffer for returning the protect and process key. If the data unit
* is associated with multiple keys in the protect and process state then the
* most recently created protect and process key is returned.
*
* @return #KMS_AGENT_STATUS_OK
* @return #KMS_AGENT_STATUS_INVALID_PARAMETER
* @return #KMS_AGENT_STATUS_PROFILE_NOT_LOADED
* @return #KMS_AGENT_STATUS_NO_MEMORY
* @return #KMS_AGENT_STATUS_GENERIC_ERROR
* @return #KMS_AGENT_STATUS_ACCESS_DENIED
* @return #KMS_AGENT_STATUS_KEY_CALLOUT_FAILURE
* @return #KMS_AGENT_STATUS_SERVER_BUSY
* @return #KMS_AGENT_STATUS_EXTERNAL_UNIQUE_ID_EXISTS
* @return #KMS_AGENT_STATUS_KMS_UNAVAILABLE
* @return #KMS_AGENT_STATUS_KMS_NO_READY_KEYS
* @return #KMS_AGENT_STATUS_NO_FIPS_KMAS_AVAILABLE
* @return #KMS_AGENT_AES_KEY_UNWRAP_ERROR
* @return #KMS_AGENT_AES_KEY_WRAP_SETUP_ERROR
*/
KMS_AGENT_STATUS KMSAgent_RetrieveProtectAndProcessKey(
KMSClientProfile* const i_pProfile,
const KMSAgent_DataUnit* const i_pDataUnit,
utf8cstr const i_pKeyGroupID,
KMSAgent_Key* const o_pKey);
/**
* Helper function which frees memory allocated for the output to #KMSAgent_RetrieveDataUnitKeys.
* @param i_pArrayOfKeys The array of keys to be freed
*/
void KMSAgent_FreeArrayOfKeys(
KMSAgent_ArrayOfKeys* i_pArrayOfKeys);
/**
* create an entry in the KMS audit log
*
* @param i_pProfile an initialized #KMSClientProfile
* @param i_iRetention the retention of audit log, can be one of:
* #KMS_AUDIT_LOG_LONG_TERM_RETENTION
* #KMS_AUDIT_LOG_MEDIUM_TERM_RETENTION
* #KMS_AUDIT_LOG_SHORT_TERM_RETENTION
* @param i_iCondition the condition of audit log, can be one of:
* #KMS_AUDIT_LOG_SUCCESS_CONDITION
* #KMS_AUDIT_LOG_ERROR_CONDITION
* #KMS_AUDIT_LOG_WARNING_CONDITION
* @param i_bIssueAlert issue alert (SNMP INFORM) for this audit
* @param i_pMessage the message text to be logged
*
* @return #KMS_AGENT_STATUS_OK
* @return #KMS_AGENT_STATUS_INVALID_PARAMETER
* @return #KMS_AGENT_STATUS_PROFILE_NOT_LOADED
* @return #KMS_AGENT_STATUS_GENERIC_ERROR
* @return #KMS_AGENT_STATUS_ACCESS_DENIED
* @return #KMS_AGENT_STATUS_SERVER_BUSY
* @return #KMS_AGENT_STATUS_KMS_UNAVAILABLE
* @return #KMS_AGENT_STATUS_NO_FIPS_KMAS_AVAILABLE
*/
KMS_AGENT_STATUS KMSAgent_CreateAuditLog(
KMSClientProfile* i_pProfile,
enum KMS_AUDIT_LOG_RETENTION i_iRetention,
enum KMS_AUDIT_LOG_CONDITION i_iCondition,
int i_bIssueAlert,
utf8cstr i_pMessage );
#ifdef KMSUSERPKCS12
#include