1/* 2 * CDDL HEADER START 3 * 4 * The contents of this file are subject to the terms of the 5 * Common Development and Distribution License (the "License"). 6 * You may not use this file except in compliance with the License. 7 * 8 * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 9 * or http://www.opensolaris.org/os/licensing. 10 * See the License for the specific language governing permissions 11 * and limitations under the License. 12 * 13 * When distributing Covered Code, include this CDDL HEADER in each 14 * file and include the License file at usr/src/OPENSOLARIS.LICENSE. 15 * If applicable, add the following below this CDDL HEADER, with the 16 * fields enclosed by brackets "[]" replaced with your own identifying 17 * information: Portions Copyright [yyyy] [name of copyright owner] 18 * 19 * CDDL HEADER END 20 */ 21 22/* 23 * Copyright (c) 2010, Oracle and/or its affiliates. All rights reserved. 24 */ 25 26/*-------------------------------------------------------------------------*/ 27/** 28 * \file KMSClientProfile.h 29 * 30 * The KMS Client profile management API, including profile setup, CA 31 * certificate download, and Certificate retrieval 32 * 33 */ 34/*-------------------------------------------------------------------------*/ 35 36#ifndef KMSCLIENT_PROFILE_H 37#define KMSCLIENT_PROFILE_H 38 39#ifdef __cplusplus 40extern "C" { 41#endif 42 43#ifndef KMS_LONG_LONG 44#define KMS_LONG_LONG 45 46#ifdef WIN32 47 typedef __int64 Long64; 48#else 49 typedef long long Long64; 50#endif 51 52 53#endif 54 55#ifdef KMSUSERPKCS12 56#define CLIENT_PK12_FILE "clientkey.p12" 57#endif 58 59/** 60 * \note UTF-8 encoding is used for the underlying SOAP RPC transactions by 61 * this API. In order to support environments lacking wchar.h 62 * traditional C strings are used instead. 63 */ 64typedef char * utf8cstr; 65 66/** 67 * @see commments for utf8cstr. 68 */ 69typedef char utf8char; 70 71/** 72 * KMS Agent Toolkit Version identifier 73 */ 74#define KMS_AGENT_VERSION 0x210 75 76/*--------------------------------------------------------------------------- 77 * Limits and sizes 78 *--------------------------------------------------------------------------*/ 79/** 80 * The maximum length of an agent name. 81 */ 82#define KMS_MAX_AGENT_NAME 64 83 84/** 85 * The size of a data unit ID in bytes. 86 */ 87#define KMS_DATA_UNIT_ID_SIZE 16 88 89/** 90 * The maximum lenght of a description for key group or data unit. 91 */ 92#define KMS_MAX_DESCRIPTION 64 93 94/** 95 * The maximum maximum length of an external unique id. 96 */ 97#define KMS_MAX_EXTERNAL_UNIQUE_ID_SIZE 32 98 99/** 100 * The maximum external tag length. 101 */ 102#define KMS_MAX_EXTERNAL_TAG 64 103 104/** 105 * The size of a key ID in bytes. 106 */ 107#define KMS_KEY_ID_SIZE 30 108 109/** 110 * The size of an AES Key Wrapping Key ID. 111 */ 112#define KMS_KWK_KEY_ID_SIZE 8 113 114/** 115 * The maximum size of a key in bytes. 116 */ 117#define KMS_MAX_KEY_SIZE 32 118 119/** 120 * The maximum size of an wrapped key(RFC3394 AES Key Wrap) in bytes. 121 */ 122#define KMS_MAX_WRAPPED_KEY_SIZE KMS_MAX_KEY_SIZE+8 123 124/** 125 * The maximum length of a key group ID. 126 */ 127#define KMS_MAX_KEY_GROUP_ID_SIZE 64 128 129/** 130 * The maximum size of a key group list to be returned. This should 131 * be sufficient for agents as this is an atypical call. 132 */ 133#define KMS_MAX_LIST_KEY_GROUPS 100 134 135/** 136 * The maximum number of keys returned in a key list. 137 */ 138#define KMS_MAX_PAGE_SIZE 32 139 140/** 141 * The maximum passphrase length. 142 */ 143#define KMS_MAX_PASSPHRASE 64 144 145/** 146 * The maximum length of agent's name, aka ID. 147 */ 148#define KMS_MAX_ENTITY_ID 64 149 150/** 151 * The maximum length of an agent's sited ID. 152 */ 153#define KMS_MAX_ENTITY_SITE_ID 64 154 155/** 156 * The maximum length of a URL. 157 */ 158#define KMS_MAX_URL 512 159 160/** 161 * The maximum length of a filter parameter field name. 162 */ 163#define KMS_MAX_FIELD_NAME 64 164 165/** 166 * The maximum length of a query parameter sort field value. 167 */ 168#define KMS_MAX_FIELD_VALUE 64 169 170/** 171 * The maximum ID length used in various types of IDs. 172 */ 173#define KMS_MAX_ID 64 174 175/** 176 * The maximum length of a KMA network address, either IPv4 or IPv6. 177 * Also maximum hostname length if/when hostnames are supported 178 */ 179#define KMS_MAX_NETWORK_ADDRESS 256 180 181/** 182 * The maximum length of a file name. 183 */ 184#define KMS_MAX_FILE_NAME 256 185 186/** 187 * The maximum length of error strings. 188 */ 189#define KMS_MAX_ERROR_STRING 1024 190 191/** 192 * the number of nodes in a KMS is variable. This constant 193 * dictates how many of the KMAs in a KMS will be saved to the 194 * profile, persisted to storage and used for load balancing and failover. See 195 * <code>KMSAgent_GetClusterInformation</code> 196 * Range: 1 .. max int, users should con 197 */ 198#ifndef KMS_MAX_CLUSTER_NUM 199#define KMS_MAX_CLUSTER_NUM 20 200#endif 201 202/** 203 * The maximum length for SHA1 hashes used in authentication. 204 */ 205#define KMS_MAX_HASH_SIZE 20 206 207/** 208 * The maximum length of a KMS verstion string. 209 */ 210#define KMS_MAX_VERSION_LENGTH 100 211 212/** 213 * The maximum length of working directory. 214 */ 215#define KMS_MAX_PATH_LENGTH 1024 216 217/** 218 * typedef for Key ID 219 */ 220typedef unsigned char KEY_ID [KMS_KEY_ID_SIZE]; 221 222/** 223 * typedef for an unwrapped Key 224 */ 225typedef unsigned char KEY [KMS_MAX_KEY_SIZE]; 226 227/** 228 * typedef for an AES wrapped key 229 */ 230typedef unsigned char WRAPPED_KEY [KMS_MAX_WRAPPED_KEY_SIZE]; 231 232/** 233 * typedef for KMSClusterEntry struct 234 */ 235typedef struct KMSClusterEntry KMSClusterEntry; 236 237/** \struct KMSClusterEntry 238 * A struct representing each Key Management Appliance discovered in the KMS cluster 239 */ 240struct KMSClusterEntry 241{ 242 /** 243 * The KMA's identifier. 244 */ 245 Long64 m_lApplianceID; 246 247 /** 248 * The KMA's name. 249 */ 250 utf8char m_wsApplianceAlias[KMS_MAX_ENTITY_ID + 1]; 251 252 /** 253 * The Sited ID for the KMA. 254 */ 255 utf8char m_wsApplianceSiteID[KMS_MAX_ENTITY_SITE_ID + 1]; 256 257 /** 258 * A network address for the KMA that corresponds to the agent's network. 259 * KMAs are multi-homed so only an address useful to the agent is provided. 260 */ 261 utf8char m_wsApplianceNetworkAddress[KMS_MAX_NETWORK_ADDRESS + 1]; 262 263 /** 264 * Enabled status for the KMA, 1 for enabled, 0 if disabled. 265 */ 266 int m_iEnabled; 267 268 /** 269 * Unused at present but may be used for reporting a KMAs load to be used 270 * as a load balancing heuristic. 271 */ 272 Long64 m_lLoad; 273 274 /** 275 * A boolean indicating the current response status of a KMA on the network. 276 * A non-responding KMA may be either down or unreachable due to the network. 277 */ 278 int m_iResponding; 279 280 /** 281 * The KMA's version level. 282 */ 283 utf8char m_sKMAVersion[KMS_MAX_VERSION_LENGTH+1]; 284 285 /** 286 * KMA lock status as provided by KMS Discover Cluster service. Defaults 287 * to false for KMAs earlier than KMS 2.3 where it was first introduced. 288 */ 289 int m_iKMALocked; 290}; 291 292 293/** 294 * the profile for an agent. The profile contains sections that are persisted 295 * and fields that are volatile. See KMSAgentStorage.h for interfaces to load/store 296 * the persistent sections. 297 * <p><b>Note</b> that members of this struct should 298 * not be accessed directly by users of this library. 299 */ 300 301/** \struct KMSClientProfile 302 * the properties comprising the profile, some of which must be persisted. 303 */ 304typedef struct KMSClientProfile_s 305{ 306 /** 307 * the version of the KMS Agent Library 308 */ 309 int m_iVersion; 310 311 /** 312 * Profile Name 313 */ 314 utf8char m_wsProfileName[KMS_MAX_ENTITY_ID + 1]; 315 316 /** 317 * Subject Name 318 */ 319 utf8char m_wsEntityID[KMS_MAX_ENTITY_ID + 1]; 320 321 /** 322 * Appliance Address used for enrollment and discovery 323 */ 324 utf8char m_wsApplianceAddress[KMS_MAX_NETWORK_ADDRESS + 1]; 325 326 /** 327 * KMS CA service port 328 */ 329 int m_iPortForCAService; 330 /** 331 * KMS Certificate service port 332 */ 333 int m_iPortForCertificateService; 334 335 /** 336 * KMS Agent service port 337 */ 338 int m_iPortForAgentService; 339 340 /** 341 * KMS Discovery service port 342 */ 343 int m_iPortForDiscoveryService; 344 345 /** 346 * timeout in seconds before failover to alternate KMS in cluster 347 */ 348 int m_iTransactionTimeout; 349 350 /** 351 * the number of times failover will be attempted 352 */ 353 int m_iFailoverLimit; 354 355 /** 356 * the number of times the current transaction has failed over 357 */ 358 int m_iFailoverAttempts; 359 360 /** 361 * TRUE when agent has enrolled and stored its certificates. 362 */ 363 int m_iEnrolled; 364 365 /** 366 * The agent's passphrase after "key stretching", i.e. hashing the number of 367 * times specified by the KMA during enrollment, and converted to hexadecimal. 368 */ 369 char m_sHexHashedPassphrase[2*KMS_MAX_HASH_SIZE+1]; 370 371 /** 372 * gSOAP runtime context. 373 */ 374 void *m_pvSoap; 375 376 /** 377 * gSOAP runtime context for discovery. 378 */ 379 void *m_pvDiscoverySoap; 380 381 /** 382 * A lock used internally by the agent library. 383 */ 384 void *m_pLock; 385 386 /** 387 * The minimum interval between automatic cluster discovery requests in seconds. 388 * A value of zero seconds disables load balancing and periodic cluster 389 * discovery calls. 390 */ 391 int m_iClusterDiscoveryFrequency; 392 393 /** 394 * The time in seconds when the cluster discovery service was last called for the 395 * current session. 396 */ 397 int m_iLastClusterDiscoveryTime; 398 399 /** 400 * The Site ID assigned to the agent by the KMS administrators. 401 */ 402 utf8char m_wsEntitySiteID[KMS_MAX_ENTITY_SITE_ID + 1]; 403 404 /** 405 * The total number of KMA in the KMS cluster as reported by the last 406 * cluster discovery. 407 */ 408 int m_iClusterNum; 409 410 /** 411 * An array of the KMAs withhin the cluster. 412 */ 413 KMSClusterEntry m_aCluster[KMS_MAX_CLUSTER_NUM]; 414 415 /** 416 * A boolean flag for the first cluster discovery call. 417 */ 418 int m_bIsClusterDiscoveryCalled; 419 420 /** 421 * A handle to the DataUnitCache used for selection of a KMA. 422 */ 423 void *m_pDataUnitCache; 424 425 /** 426 * A handle to the load balancer. 427 */ 428 void *m_pAgentLoadBalancer; 429 430 /** 431 * error string 432 */ 433 utf8char m_wsErrorString[KMS_MAX_ERROR_STRING + 1]; 434 435 /** 436 * URL to KMA service within cluster 437 */ 438 char m_sURL[KMS_MAX_URL + 1]; 439 440 /** 441 * The security mode specified to <code>KMSAgent_LoadProfile</code> 442 */ 443 int m_eKMSmode; 444 445#ifdef KMSUSERPKCS12 446 int m_iLastErrorCode; 447#endif 448} KMSClientProfile; 449 450#ifdef __cplusplus 451} 452#endif 453 454 455#endif 456 457