KMSAgent.h revision 4f14b0f29aa144cc03efdde5508ae126ae197acf
/*
* 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
* 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
*/
/*
*/
/** @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
#else
#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:
* <ul>
* <li>Agent is not enabled on the KMS
* <li>Invalid DataUnitID or DataUnit does not exist
* <li>Invalid ExternalUniqueID or DataUnit does not exist with specified ID
* <li>Invalid ExternalTag
* <li>Invalid KeyID
* <li>Invalid KeyGroup or KeyGroup does not exist
* <li>The Agent ID is not recognized as an agent by the KMS, i.e. the agent may not exist or the
* ID represents another kind of entity.
* <li>No KeyGroup specified and the Agent is not configured to have a default KeyGroup
* <li>Agent does not have access to the specified KeyGroup
* </ul>
* to prevent leakage of information the specific details for access being denied are not
* disclosed. Audit log entries at the KMS can be used to determine specific reasons for
* access being denied.
*/
#define KMS_AGENT_STATUS_ACCESS_DENIED 200
/**
* This error status is only returned when received from the KMS and the transaction
* timeout has been exceeded.
*/
#define KMS_AGENT_STATUS_SERVER_BUSY 201
/**
* a data unit already exists with the specified external unique identifier
*/
#define KMS_AGENT_STATUS_EXTERNAL_UNIQUE_ID_EXISTS 202
/**
* The external unique ID specified was found to exist but the corresponding
* DataUnitID did not exist.
*/
/**
* The specified key has been destroyed or is unknown to the KMS
*/
#define KMS_AGENT_STATUS_KEY_DOES_NOT_EXIST 204
/**
* The requested key has been destroyed.
*/
#define KMS_AGENT_STATUS_KEY_DESTROYED 205
/**
* The key received from a KMA encountered an error during AES Key Unwrapping
*/
#define KMS_AGENT_AES_KEY_UNWRAP_ERROR 206
/**
* An error occurred during establishment of an AES Key-Encryption Key
*/
#define KMS_AGENT_AES_KEY_WRAP_SETUP_ERROR 207
/*
* Failed to decrypt the client private key data file due to incorrect PIN
*/
#define KMS_AGENT_LOCAL_AUTH_FAILURE 208
/**
* supported key types
*/
enum KMS_KEY_TYPE
{
/**
* AES 256 key type
*/
};
/**
* This enumerator type defines the various Key States.
*/
enum KMS_AGENT_KEY_STATE
{
/**
* A key in this state can be used for both encryption and decryption.
* A key is placed into this state when it is assigned. The assignment is done when an encryption agent requests a new key be created.
*/
/**
* A key in this state can be used for decryption but not encryption. When an agent determines that none of the keys available to
* it (e.g., for a specific data unit that is being read or written) are in the protect-and-process state, it should create a new key.
* Keys transition from protect-and-process to process only when the encryption period for the key expires.
*/
/**
* The key has passed its cryptoperiod but may still be needed to process (decrypt) information. Auditable events are generated
* when keys in this state are provided to the agent.
*/
/**
* Keys are compromised when they are released to or discovered by an unauthorized entity.
* Compromised keys should not be used to protect information, but may be used to process information.
* Auditable events are generated
* when keys in this state are provided to the agent.
*/
};
/*---------------------------------------------------------------------------
* Data Unit State
*--------------------------------------------------------------------------*/
/**
* this enumeration defines the DataUnit states
*/
{
/**
* When a data unit has been created, but has not yet had any keys created it will be in "no key" state.
* This should be a short, transient condition that will be exited as soon as a key has been created.
*/
/**
* Normal is a substate of readable. In this state, a data unit has at least one protect-and-process state key that can be used to encrypt data.
* The data unit is therefore writable.
*/
/**
* Needs rekey is a substate of readable. In this state, the data unit has no protect-and-process keys.
* Data should not be encrypted and written to the data unit unless the data unit is rekeyed and a new, active key is assigned.
* Its the responsibility of the agent to avoid using a key that is not in protect-and-process state for encryption.
* The data unit may have keys that are in process only, deactivated, or compromised state. Any of these keys can be used for decryption.
*/
/**
* When all of the keys for a data unit are destroyed, the data unit is shredded. The data unit cannot be read or written.
* However, a new key can be created for the data unit. This will return the data unit to normal state, allowing it to be read and written.
*/
};
/**
* This enumeration type defines Audit Log Retention values
*/
{
/**
* specifies that an audit log entry should have long term retention
*/
/**
* specifies that an audit log entry should have medium term retention
*/
/**
* specifies that an audit log entry should have short term retention
*/
};
/**
* This enumeration type defines Audit Log Condition values
*/
{
/**
* specifies that an audit log entry should should indicate a success condition
*/
/**
* specifies that an audit log entry should should indicate an error condition
*/
/**
* specifies that an audit log entry should should indicate a warning condition
*/
};
/**
* supported security modes
*/
enum KMS_SECURITY_MODE
{
/**
* agent will work with any level of KMA
*/
DEFAULT_MODE = 0,
/**
* agent will only communicate with KMAs supporting FIPS 140-2 so that
* keys are encrypted at the KMA using AES Key Wrap.
*/
};
/*---------------------------------------------------------------------------
*--------------------------------------------------------------------------*/
/**
* typedef for descriptions used in various places within the API
*/
/**
* typedef for key group ID
*/
/**
* typedef for the Key Group struct
*/
typedef struct KMSAgent_KeyGroup KMSAgent_KeyGroup;
/** \struct KMSAgent_KeyGroup
* a Key Group with its ID and description
*/
struct KMSAgent_KeyGroup
{
/**
* the unique ID of the KeyGroup
*/
/**
* the description of the KeyGroup
*/
};
/**
* An array of Key Groups
*/
typedef struct KMSAgent_ArrayOfKeyGroups KMSAgent_ArrayOfKeyGroups;
/** \struct KMSAgent_ArrayOfKeyGroups
* An array of Key Groups
*/
struct KMSAgent_ArrayOfKeyGroups
{
/**
* pointer to an array of Key Groups
*/
/**
* the number of Key Groups in the array
*/
int m_iSize;
};
/**
* typedef for a Key struct
*/
typedef struct KMSAgent_Key KMSAgent_Key;
/** \struct KMSAgent_Key
* key and its associated properites: KeyID, state, type, lenth, KeyGroup and the Key value
*/
struct KMSAgent_Key
{
/**
* the unique ID of the key
*/
/**
* the state of the Key
*/
/**
* the type of the key, e.g. AES_256
*/
enum KMS_KEY_TYPE m_iKeyType;
/**
* the unique ID of the KeyGroup
*/
/**
* the key in plaintext.
*/
/**
* length of #m_acKey
*/
int m_iKeyLength;
};
/**
* typedef for the External Unique ID
*/
typedef unsigned char EXTERNAL_UNIQUE_ID [KMS_MAX_EXTERNAL_UNIQUE_ID_SIZE];
/**
* typedef for the Data Unit ID
*/
typedef unsigned char DATA_UNIT_ID [KMS_DATA_UNIT_ID_SIZE];
/**
* typedef for the External Tag
*/
/**
* typedef for aData Unit structure.
*/
typedef struct KMSAgent_DataUnit KMSAgent_DataUnit;
/** \struct KMSAgent_DataUnit
* struct for a DataUnit and its associated properties: DataUnitID, external unique ID,
* external tag, description and state. Data units are associated with zero or more keys.
*/
struct KMSAgent_DataUnit
{
/**
* the unique DataUnit ID provided by the KMS
*/
/**
* a unique external ID for the data unit that is provided by the agent, may be NULL if one is not provided.
* The KMS will enforce the uniqueness of this identifier and not allow multiple data units having the same
* #m_acExternalUniqueID value.
*/
/**
* the length in bytes of the #m_acExternalUniqueID field that represents the
* ID. The length
* must be less than or equal to #KMS_MAX_EXTERNAL_UNIQUE_ID_SIZE
*/
/**
* an external tag representing information pertinent to the data unit, for example a volume serial number
*/
/**
* a description of the data unit
*/
/**
* the state of the DataUnit
*/
};
/**
* typedef for a list of keys
*/
typedef struct KMSAgent_ArrayOfKeys KMSAgent_ArrayOfKeys;
/** \struct KMSAgent_ArrayOfKeys
* struct for an array of keys
*/
struct KMSAgent_ArrayOfKeys
{
/**
* keys are in chronological order based upon key creation date. However,
* when page offset argument to #KMSAgent_RetrieveDataUnitKeys
* is 0 the first key in the array will be the key in the
* #KMS_KEY_STATE_ACTIVE_PROTECT_AND_PROCESS.
*/
/**
* the number of keys in the list
*/
int m_iSize;
};
/**
* @return the version string for the KMS Agent Library
*/
const char * KMSAgent_GetVersion();
/**
*
* This function initializes the KMS Agent API library. It
* should be called before any other functions are invoked. Internally,
* sets up the SSL library and Logging module.
*
* @param i_pWorkingDirectory Working directory of the program which uses the
* library. Default is "." if NULL is passed.
* @param i_bUseFileLog: True(1) if errors should go to a log file in the working directory.
* If false(0) then errors will not be logged to a file.
*
* @return #KMS_AGENT_STATUS_OK
* @return #KMS_AGENT_STATUS_GENERIC_ERROR if library initialization fails
*/
const utf8cstr i_pWorkingDirectory,
int i_bUseFileLog );
/**
* This function exercises FIPS 140-2 Known Answer Tests for certified algorithms
* used in the agent toolkit. This function should only be called once and may
* be called prior to #KMSAgent_InitializeLibrary.
*
* @return #KMS_AGENT_STATUS_OK
* @return #KMS_AGENT_STATUS_FIPS_KAT_AES_KEYWRAP_ERROR
* @return #KMS_AGENT_STATUS_FIPS_KAT_AES_ECB_ERROR
* @return #KMS_AGENT_STATUS_FIPS_KAT_HMAC_SHA1_ERROR
*/
/**
* This function finalizes the KMS Agent API library. It should
* be called when the library is not needed by the program. Internally it
* cleans up the SSL library and Logging module.
*
* @return #KMS_AGENT_STATUS_OK
* @return #KMS_AGENT_STATUS_GENERIC_ERROR if library finalization fails
*
*/
/**
* This function can be used to get the last error message when
* an API function encounters an error. These error messages also
* are written to the log, if file logging was enabled during library
* initialization.
*
* @param i_pProfile an initialized #KMSClientProfile; the failed
* function must have used this profile.
* @return the pointer to the last error message or NULL
*
*/
/**
* Get the cluster information by calling the KMS_Discovery service using the KMA specified in the
* profile, no load balancing will occur. If discovery to this KMA fails then discovery will be
* attempted using previously retrieved cluster information.
*
* If #KMSAgent_LoadProfile was called with an IPv6 address for
* the <code>i_pInitialApplianceAddress</code> argument then the <code>o_pClusterEntryArray</code> 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 <code>i_iClusterEntryArraySize</code>
* then the KMA list is filtered to contain the
* first <code>i_iClusterEntryArraySize</code> 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
*/
KMSClientProfile * const i_pProfile,
int i_iEntitySiteIDSize,
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
*
*/
KMSClientProfile* const i_pProfile,
utf8cstr const i_pApplianceAddress );
/**
* Load profile handles both agent enrollment with the KMS and post enrollment setup.
* <p>
* <b>Enrollment Behavior</b>
* <br>
* 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 <code>i_pApplianceAddress</code>.
* <p>
* 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 <code>i_pApplianceAddress</code> 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.
* </p>
* Once enrolled successfully the KMS
* will then disable usage of the agent's passphrase for enrollment as a security precaution.
* Subsequent enrollment will require a new passphrase.
* <p>
* <b>Post Enrollment Behavior</b>
* <br>
* 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.
* <p>
* 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 <code>iClusterDiscoveryFrequency</code>. 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 <code>i_iFailOverLimit</code> * <code>i_iTransactionTimeout</code>.
*
* @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
*/
KMSClientProfile* const io_pProfile,
utf8cstr const i_pProfileName,
utf8cstr const i_pAgentID,
utf8cstr const i_pPassphrase,
int i_iFailOverLimit,
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
*
*/
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
*/
/**
* 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
*/
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
*
*/
/**
* 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
*/
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
* <code>i_pExternalUniqueID</code> 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
*/
KMSClientProfile* const i_pProfile,
const unsigned char * i_pExternalUniqueID,
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
*/
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
*/
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
* <code>i_pExternalUniqueID</code> 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
*/
KMSClientProfile* const i_pProfile,
const unsigned char * const i_pDataUnitID,
const unsigned char * const i_pExternalUniqueID,
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
*/
KMSClientProfile* const i_pProfile,
const unsigned char* const i_pExternalUniqueID,
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 <code>i_pKeyID</code> 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 <code>i_iPageSize</code>, <code>i_iPageOffset</code> and <code>o_piKeysRemaining</code> parameters may be used for retrieving
* subsets of the list. For the <code>i_pKeyID</code> 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 <code>i_pKeyID</code> 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
* <code>i_iPageSize</code> keys associated with the data unit having an activation date greater than the key
* corresponding to <code>i_pKeyID</code>. The first key in the list is not guaranteed
* to be in the #KMS_KEY_STATE_ACTIVE_PROTECT_AND_PROCESS state. If the specified <code>i_pKeyID</code>
* is not associated with the Data Unit then the behavior is like #KMSAgent_RetrieveKey and
* a single key is returned.
* When non-null the <code>i_iPageOffset</code>
* 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 <code>i_iPageSize</code>
* 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 <code>i_pKeyID</code> does not exist in the KMS.
* @return #KMS_AGENT_STATUS_KEY_DESTROYED if <code>i_pKeyID</code> 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
*/
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
*/
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(
/**
* 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
*/
int i_bIssueAlert,
#ifdef KMSUSERPKCS12
utf8cstr const i_pOldPassphrase,
utf8cstr const i_pNewPassphrase);
#define KMSAGENT_PROFILE_FLAGS uint32_t
char *i_pProfileName,
#define KMSAGENT_PROFILE_EXISTS_FLAG 0x01
#define KMSAGENT_CLIENTKEY_EXISTS_FLAG 0x02
#endif /* KMSUSERPKCS12 */
#ifdef __cplusplus
}
#endif
#endif