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