usr/src/lib/libkmsagent/common/KMSClientProfile.h

   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