/* * 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: * * 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. */ #define KMS_AGENT_STATUS_DATA_UNIT_ID_NOT_FOUND_EXTERNAL_ID_EXISTS 203 /** * 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 */ KMS_KEY_TYPE_AES_256 }; /** * This enumerator type defines the various Key States. */ enum KMS_AGENT_KEY_STATE { KMS_KEY_STATE_GENERATED = 0, KMS_KEY_STATE_READY, /** * 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. */ KMS_KEY_STATE_ACTIVE_PROTECT_AND_PROCESS, /** * 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. */ KMS_KEY_STATE_ACTIVE_PROCESS_ONLY, /** * 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. */ KMS_KEY_STATE_DEACTIVATED, /** * 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. */ KMS_KEY_STATE_COMPROMISED, KMS_KEY_STATE_DESTROYED_INCOMPLETE, KMS_KEY_STATE_DESTROYED_COMPLETE, KMS_KEY_STATE_DESTROYED_COMPROMISED_INCOMPLETE, KMS_KEY_STATE_DESTROYED_COMPROMISED_COMPLETE }; /*--------------------------------------------------------------------------- * Data Unit State *--------------------------------------------------------------------------*/ /** * this enumeration defines the DataUnit states */ enum KMS_AGENT_DATA_UNIT_STATE { /** * 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. */ KMS_DATA_UNIT_STATE_NO_KEY = 0, /** * 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. */ KMS_DATA_UNIT_STATE_READABLE_NORMAL, /** * 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. */ KMS_DATA_UNIT_STATE_READABLE_NEEDS_REKEY, /** * 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. */ KMS_DATA_UNIT_STATE_SHREDDED }; /** * This enumeration type defines Audit Log Retention values */ enum KMS_AUDIT_LOG_RETENTION { /** * specifies that an audit log entry should have long term retention */ KMS_AUDIT_LOG_LONG_TERM_RETENTION = 0, /** * specifies that an audit log entry should have medium term retention */ KMS_AUDIT_LOG_MEDIUM_TERM_RETENTION, /** * specifies that an audit log entry should have short term retention */ KMS_AUDIT_LOG_SHORT_TERM_RETENTION }; /** * This enumeration type defines Audit Log Condition values */ enum KMS_AUDIT_LOG_CONDITION { /** * specifies that an audit log entry should should indicate a success condition */ KMS_AUDIT_LOG_SUCCESS_CONDITION = 0, /** * specifies that an audit log entry should should indicate an error condition */ KMS_AUDIT_LOG_ERROR_CONDITION, /** * specifies that an audit log entry should should indicate a warning condition */ KMS_AUDIT_LOG_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. */ FIPS_MODE }; /*--------------------------------------------------------------------------- * API Input/Output Data Structures *--------------------------------------------------------------------------*/ /** * typedef for descriptions used in various places within the API */ typedef utf8char DESCRIPTION [KMS_MAX_DESCRIPTION+1]; /** * typedef for key group ID */ typedef utf8char KEY_GROUP_ID[KMS_MAX_ID+1]; /** * 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 */ KEY_GROUP_ID m_acKeyGroupID; /** * the description of the KeyGroup */ DESCRIPTION m_acDescription; }; /** * 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 */ KMSAgent_KeyGroup* m_pKeyGroups; /** * 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 */ KEY_ID m_acKeyID; /** * the state of the Key */ enum KMS_AGENT_KEY_STATE m_iKeyState; /** * the type of the key, e.g. AES_256 */ enum KMS_KEY_TYPE m_iKeyType; /** * the unique ID of the KeyGroup */ KEY_GROUP_ID m_acKeyGroupID; /** * the key in plaintext. */ KEY m_acKey; /** * 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 utf8char EXTERNAL_TAG [KMS_MAX_EXTERNAL_TAG+1]; /** * 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 */ DATA_UNIT_ID m_acDataUnitID; /** * 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. */ EXTERNAL_UNIQUE_ID m_acExternalUniqueID; /** * 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 */ int m_iExternalUniqueIDLength; /** * an external tag representing information pertinent to the data unit, for example a volume serial number */ EXTERNAL_TAG m_acExternalTag; /** * a description of the data unit */ DESCRIPTION m_acDescription; /** * the state of the DataUnit */ enum KMS_AGENT_DATA_UNIT_STATE m_iDataUnitState; }; /** * 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. */ KMSAgent_Key* m_pKeys; /** * 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 */ KMS_AGENT_STATUS KMSAgent_InitializeLibrary( 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 */ KMS_AGENT_STATUS KMSAgent_KnownAnswerTests(); /** * 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 * */ KMS_AGENT_STATUS KMSAgent_FinalizeLibrary(); /** * 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 * */ utf8cstr KMSAgent_GetLastErrorMessage( KMSClientProfile* i_pProfile ); /** * 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 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. *

* 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. *

* 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 KMS_AGENT_STATUS KMSAgent_ChangeLocalPWD( KMSClientProfile* i_pProfile, utf8cstr const i_pOldPassphrase, utf8cstr const i_pNewPassphrase); #define KMSAGENT_PROFILE_FLAGS uint32_t KMS_AGENT_STATUS KMSAgent_GetProfileStatus( char *i_pProfileName, KMSAGENT_PROFILE_FLAGS *flags); #define KMSAGENT_PROFILE_EXISTS_FLAG 0x01 #define KMSAGENT_CLIENTKEY_EXISTS_FLAG 0x02 #endif /* KMSUSERPKCS12 */ #ifdef __cplusplus } #endif #endif