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 40 extern "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 */ 64 typedef char * utf8cstr; 65 66 /** 67 * @see commments for utf8cstr. 68 */ 69 typedef 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 */ 220 typedef unsigned char KEY_ID [KMS_KEY_ID_SIZE]; 221 222 /** 223 * typedef for an unwrapped Key 224 */ 225 typedef unsigned char KEY [KMS_MAX_KEY_SIZE]; 226 227 /** 228 * typedef for an AES wrapped key 229 */ 230 typedef unsigned char WRAPPED_KEY [KMS_MAX_WRAPPED_KEY_SIZE]; 231 232 /** 233 * typedef for KMSClusterEntry struct 234 */ 235 typedef struct KMSClusterEntry KMSClusterEntry; 236 237 /** \struct KMSClusterEntry 238 * A struct representing each Key Management Appliance discovered in the KMS cluster 239 */ 240 struct 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 */ 304 typedef 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