cryptlib  3.4.1
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Properties Macros
user.h
Go to the documentation of this file.
1 /****************************************************************************
2 * *
3 * User Routines Header File *
4 * Copyright Peter Gutmann 1999-2007 *
5 * *
6 ****************************************************************************/
7 
8 #ifndef _USER_DEFINED
9 
10 #define _USER_DEFINED
11 
12 /* Initialisation states for the user object */
13 
14 typedef enum {
15  USER_STATE_NONE, /* No initialisation state */
16  USER_STATE_SOINITED, /* SSO inited, not usable */
17  USER_STATE_USERINITED, /* User inited, usable */
18  USER_STATE_LOCKED, /* Disabled, not usable */
19  USER_STATE_LAST /* Last possible state */
20  } USER_STATE_TYPE;
21 
22 /* User information flags. These are:
23 
24  FLAG_ZEROISE: Zeroise in progress, further messages (except destroy) are
25  bounced, and all files are deleted on destroy */
26 
27 #define USER_FLAG_NONE 0x00 /* No flag */
28 #define USER_FLAG_ZEROISE 0x01 /* Zeroise in progress */
29 
30 /* Content disposition when writing configuration data */
31 
32 typedef enum {
33  CONFIG_DISPOSITION_NONE, /* No disposition type */
34  CONFIG_DISPOSITION_NO_CHANGE, /* No change in data and certificates */
35  CONFIG_DISPOSITION_EMPTY_CONFIG_FILE, /* No data/certs present, empty file */
36  CONFIG_DISPOSITION_TRUSTED_CERTS_ONLY, /* Only trusted certs present */
37  CONFIG_DISPOSITION_DATA_ONLY, /* Only configuratin data present */
38  CONFIG_DISPOSITION_BOTH, /* Both data and certificates present */
39  CONFIG_DISPOSITION_LAST /* Last possible disposition type */
40  } CONFIG_DISPOSITION_TYPE;
41 
42 /****************************************************************************
43 * *
44 * Data Structures *
45 * *
46 ****************************************************************************/
47 
48 /* User information as stored in the user info file */
49 
50 typedef struct {
51  CRYPT_USER_TYPE type; /* User type */
52  USER_STATE_TYPE state; /* User state */
53  BUFFER( CRYPT_MAX_TEXTSIZE, userNameLength ) \
54  BYTE userName[ CRYPT_MAX_TEXTSIZE + 8 ];
55  int userNameLength; /* User name */
56  BUFFER_FIXED( KEYID_SIZE ) \
57  BYTE userID[ KEYID_SIZE + 8 ];
58  BUFFER_FIXED( KEYID_SIZE ) \
59  BYTE creatorID[ KEYID_SIZE + 8 ];/* ID of user and creator of this user */
60  int fileRef; /* User info file reference */
61  } USER_FILE_INFO;
62 
63 /* The structure that stores the information on a user */
64 
65 typedef struct UI {
66  /* Control and status information */
67  int flags; /* User flags */
68  USER_FILE_INFO userFileInfo; /* General user info */
69 
70  /* User index information for the default user */
71  void *userIndexPtr;
72 
73  /* Configuration options for this user. These are managed through the
74  user config code, so they're just treated as a dynamically-allocated
75  blob within the user object */
76  void *configOptions;
77  int configOptionsCount;
78 
79  /* Certificate trust information for this user, and a flag indicating
80  whether the trust info has changed and potentially needs to be
81  committed to disk. This requires access to cert-internal details
82  so it's handled externally via the cert code, the user object just
83  sees the info as an opaque blob */
84  void *trustInfoPtr;
85  BOOLEAN trustInfoChanged;
86 
87  /* The user object contains an associated keyset which is used to store
88  user information to disk. In addition for SOs and CAs it also
89  contains an associated encryption context, either a private key (for
90  an SO) or a conventional key (for a CA) */
91  CRYPT_KEYSET iKeyset; /* Keyset */
92  CRYPT_CONTEXT iCryptContext; /* Private/secret key */
93 
94  /* Error information */
95  CRYPT_ATTRIBUTE_TYPE errorLocus;/* Error locus */
96  CRYPT_ERRTYPE_TYPE errorType; /* Error type */
97 
98  /* The object's handle, used when sending messages to the object when
99  only the xxx_INFO is available */
100  CRYPT_HANDLE objectHandle;
101  } USER_INFO;
102 
103 /****************************************************************************
104 * *
105 * Internal API Functions *
106 * *
107 ****************************************************************************/
108 
109 /* User attribute handling functions */
110 
111 CHECK_RETVAL STDC_NONNULL_ARG( ( 1, 2 ) ) \
112 int getUserAttribute( INOUT USER_INFO *userInfoPtr,
113  OUT_INT_Z int *valuePtr,
114  IN_ATTRIBUTE const CRYPT_ATTRIBUTE_TYPE attribute );
115 CHECK_RETVAL STDC_NONNULL_ARG( ( 1, 2 ) ) \
116 int getUserAttributeS( INOUT USER_INFO *userInfoPtr,
117  INOUT MESSAGE_DATA *msgData,
118  IN_ATTRIBUTE const CRYPT_ATTRIBUTE_TYPE attribute );
119 CHECK_RETVAL STDC_NONNULL_ARG( ( 1 ) ) \
120 int setUserAttribute( INOUT USER_INFO *userInfoPtr,
121  IN_INT_Z const int value,
122  IN_ATTRIBUTE const CRYPT_ATTRIBUTE_TYPE attribute );
123 CHECK_RETVAL STDC_NONNULL_ARG( ( 1, 2 ) ) \
124 int setUserAttributeS( INOUT USER_INFO *userInfoPtr,
125  IN_BUFFER( dataLength ) const void *data,
126  IN_LENGTH const int dataLength,
127  IN_ATTRIBUTE const CRYPT_ATTRIBUTE_TYPE attribute );
128 CHECK_RETVAL STDC_NONNULL_ARG( ( 1 ) ) \
129 int deleteUserAttribute( INOUT USER_INFO *userInfoPtr,
130  IN_ATTRIBUTE const CRYPT_ATTRIBUTE_TYPE attribute );
131 
132 /* Prototypes for functions in user.c */
133 
134 CHECK_RETVAL \
135 const USER_FILE_INFO *getPrimarySoUserInfo( void );
136 CHECK_RETVAL_BOOL STDC_NONNULL_ARG( ( 1 ) ) \
137 BOOLEAN isZeroisePassword( IN_BUFFER( passwordLen ) const char *password,
138  IN_LENGTH_SHORT const int passwordLen );
139 CHECK_RETVAL STDC_NONNULL_ARG( ( 1 ) ) \
140 int zeroiseUsers( INOUT USER_INFO *userInfoPtr );
141 CHECK_RETVAL STDC_NONNULL_ARG( ( 1, 2 ) ) \
142 int setUserPassword( INOUT USER_INFO *userInfoPtr,
143  IN_BUFFER( passwordLength ) const char *password,
144  IN_LENGTH_SHORT const int passwordLength );
145 CHECK_RETVAL STDC_NONNULL_ARG( ( 1 ) ) \
146 int initUserIndex( OUT_OPT_PTR void **userIndexPtrPtr );
147 STDC_NONNULL_ARG( ( 1 ) ) \
148 void endUserIndex( INOUT void *userIndexPtr );
149 
150 /* Prototypes for functions in user_cfg.c */
151 
152 CHECK_RETVAL STDC_NONNULL_ARG( ( 1, 2 ) ) \
153 int initOptions( OUT_OPT_PTR void **configOptionsPtr,
154  OUT_INT_SHORT_Z int *configOptionsCount );
155 STDC_NONNULL_ARG( ( 1 ) ) \
156 void endOptions( INOUT_ARRAY( configOptionsCount ) TYPECAST( OPTION_INFO * ) \
157  void *configOptions,
158  IN_INT_SHORT const int configOptionsCount );
159 CHECK_RETVAL STDC_NONNULL_ARG( ( 1 ) ) \
160 int setOption( INOUT_ARRAY( configOptionsCount ) TYPECAST( OPTION_INFO * ) \
161  void *configOptions,
162  IN_INT_SHORT const int configOptionsCount,
163  IN_ATTRIBUTE const CRYPT_ATTRIBUTE_TYPE option,
164  IN_INT const int value );
165 CHECK_RETVAL STDC_NONNULL_ARG( ( 1 ) ) \
166 int setOptionSpecial( INOUT_ARRAY( configOptionsCount ) TYPECAST( OPTION_INFO * ) \
167  void *configOptions,
168  IN_INT_SHORT const int configOptionsCount,
169  IN_RANGE_FIXED( CRYPT_OPTION_SELFTESTOK ) \
170  const CRYPT_ATTRIBUTE_TYPE option,
171  IN_INT const int value );
172 CHECK_RETVAL STDC_NONNULL_ARG( ( 1, 4 ) ) \
173 int setOptionString( INOUT_ARRAY( configOptionsCount ) TYPECAST( OPTION_INFO * ) \
174  void *configOptions,
175  IN_INT_SHORT const int configOptionsCount,
176  IN_ATTRIBUTE const CRYPT_ATTRIBUTE_TYPE option,
177  IN_BUFFER( valueLength ) const char *value,
178  IN_LENGTH_SHORT const int valueLength );
179 CHECK_RETVAL STDC_NONNULL_ARG( ( 1, 4 ) ) \
180 int getOption( IN_ARRAY( configOptionsCount ) TYPECAST( OPTION_INFO * ) \
181  const void *configOptions,
182  IN_INT_SHORT const int configOptionsCount,
183  IN_ATTRIBUTE const CRYPT_ATTRIBUTE_TYPE option,
184  OUT_INT_Z int *value );
185 CHECK_RETVAL STDC_NONNULL_ARG( ( 1, 4, 5 ) ) \
186 int getOptionString( IN_ARRAY( configOptionsCount ) TYPECAST( OPTION_INFO * ) \
187  const void *configOptions,
188  IN_INT_SHORT const int configOptionsCount,
189  IN_ATTRIBUTE const CRYPT_ATTRIBUTE_TYPE option,
190  OUT_OPT_PTR const void **strPtrPtr,
191  OUT_LENGTH_SHORT_Z int *strLen );
192 CHECK_RETVAL STDC_NONNULL_ARG( ( 1 ) ) \
193 int deleteOption( INOUT_ARRAY( configOptionsCount ) TYPECAST( OPTION_INFO * ) \
194  void *configOptions,
195  IN_INT_SHORT const int configOptionsCount,
196  IN_ATTRIBUTE const CRYPT_ATTRIBUTE_TYPE option );
197 
198 /* Prototypes for functions in user_rw.c */
199 
200 CHECK_RETVAL STDC_NONNULL_ARG( ( 2 ) ) \
201 int readConfig( IN_HANDLE const CRYPT_USER iCryptUser,
202  IN_STRING const char *fileName,
203  INOUT_OPT void *trustInfoPtr );
204 CHECK_RETVAL STDC_NONNULL_ARG( ( 1, 3, 4 ) ) \
205 int getConfigDisposition( INOUT_ARRAY( configOptionsCount ) TYPECAST( OPTION_INFO * ) \
206  void *configOptions,
207  IN_INT_SHORT const int configOptionsCount,
208  const void *trustInfoPtr,
209  OUT_ENUM( CONFIG_DISPOSITION ) \
210  CONFIG_DISPOSITION_TYPE *disposition );
211 CHECK_RETVAL STDC_NONNULL_ARG( ( 1, 3, 4 ) ) \
212 int prepareConfigData( INOUT_ARRAY( configOptionsCount ) TYPECAST( OPTION_INFO * ) \
213  void *configOptions,
214  IN_INT_SHORT const int configOptionsCount,
215  OUT_BUFFER_ALLOC_OPT( *dataLength ) void **dataPtrPtr,
216  OUT_LENGTH_Z int *dataLength );
217 CHECK_RETVAL STDC_NONNULL_ARG( ( 1 ) ) \
218 int commitConfigData( IN_STRING const char *fileName,
219  IN_BUFFER_OPT( dataLength ) const void *data,
220  IN_LENGTH_Z const int dataLength,
221  IN_HANDLE_OPT const CRYPT_USER iTrustedCertUserObject );
222 CHECK_RETVAL STDC_NONNULL_ARG( ( 1 ) ) \
223 int deleteConfig( IN_STRING const char *fileName );
224 
225 #endif /* _USER_DEFINED */
Generated on Thu Jan 10 2013 10:00:51 for cryptlib by   doxygen 1.8.2