crypto/heimdal/doc/doxyout/hx509/man/man3/hx509_keyset.3

   1 .TH "hx509 certificate store functions" 3 "11 Jan 2012" "Version 1.5.2" "Heimdalx509library" \" -*- nroff -*-
   2 .ad l
   3 .nh
   4 .SH NAME
   5 hx509 certificate store functions \-
   6 .SS "Functions"
   7
   8 .in +1c
   9 .ti -1c
  10 .RI "int \fBhx509_certs_init\fP (hx509_context context, const char *name, int flags, hx509_lock lock, hx509_certs *certs)"
  11 .br
  12 .ti -1c
  13 .RI "int \fBhx509_certs_store\fP (hx509_context context, hx509_certs certs, int flags, hx509_lock lock)"
  14 .br
  15 .ti -1c
  16 .RI "void \fBhx509_certs_free\fP (hx509_certs *certs)"
  17 .br
  18 .ti -1c
  19 .RI "int \fBhx509_certs_start_seq\fP (hx509_context context, hx509_certs certs, hx509_cursor *cursor)"
  20 .br
  21 .ti -1c
  22 .RI "int \fBhx509_certs_next_cert\fP (hx509_context context, hx509_certs certs, hx509_cursor cursor, hx509_cert *cert)"
  23 .br
  24 .ti -1c
  25 .RI "int \fBhx509_certs_end_seq\fP (hx509_context context, hx509_certs certs, hx509_cursor cursor)"
  26 .br
  27 .ti -1c
  28 .RI "int \fBhx509_certs_iter_f\fP (hx509_context context, hx509_certs certs, int(*func)(hx509_context, void *, hx509_cert), void *ctx)"
  29 .br
  30 .ti -1c
  31 .RI "int \fBhx509_ci_print_names\fP (hx509_context context, void *ctx, hx509_cert c)"
  32 .br
  33 .ti -1c
  34 .RI "int \fBhx509_certs_add\fP (hx509_context context, hx509_certs certs, hx509_cert cert)"
  35 .br
  36 .ti -1c
  37 .RI "int \fBhx509_certs_find\fP (hx509_context context, hx509_certs certs, const hx509_query *q, hx509_cert *r)"
  38 .br
  39 .ti -1c
  40 .RI "int \fBhx509_certs_filter\fP (hx509_context context, hx509_certs certs, const hx509_query *q, hx509_certs *result)"
  41 .br
  42 .ti -1c
  43 .RI "int \fBhx509_certs_merge\fP (hx509_context context, hx509_certs to, hx509_certs from)"
  44 .br
  45 .ti -1c
  46 .RI "int \fBhx509_certs_append\fP (hx509_context context, hx509_certs to, hx509_lock lock, const char *name)"
  47 .br
  48 .ti -1c
  49 .RI "int \fBhx509_get_one_cert\fP (hx509_context context, hx509_certs certs, hx509_cert *c)"
  50 .br
  51 .ti -1c
  52 .RI "int \fBhx509_certs_info\fP (hx509_context context, hx509_certs certs, int(*func)(void *, const char *), void *ctx)"
  53 .br
  54 .in -1c
  55 .SH "Detailed Description"
  56 .PP
  57 See the \fBCertificate store operations\fP for description and examples.
  58 .SH "Function Documentation"
  59 .PP
  60 .SS "int hx509_certs_add (hx509_context context, hx509_certs certs, hx509_cert cert)"
  61 .PP
  62 Add a certificate to the certificiate store.
  63 .PP
  64 The receiving keyset certs will either increase reference counter of the cert or make a deep copy, either way, the caller needs to free the cert itself.
  65 .PP
  66 \fBParameters:\fP
  67 .RS 4
  68 \fIcontext\fP a hx509 context.
  69 .br
  70 \fIcerts\fP certificate store to add the certificate to.
  71 .br
  72 \fIcert\fP certificate to add.
  73 .RE
  74 .PP
  75 \fBReturns:\fP
  76 .RS 4
  77 Returns an hx509 error code.
  78 .RE
  79 .PP
  80
  81 .SS "int hx509_certs_append (hx509_context context, hx509_certs to, hx509_lock lock, const char * name)"
  82 .PP
  83 Same a \fBhx509_certs_merge()\fP but use a lock and name to describe the from source.
  84 .PP
  85 \fBParameters:\fP
  86 .RS 4
  87 \fIcontext\fP a hx509 context.
  88 .br
  89 \fIto\fP the store to merge into.
  90 .br
  91 \fIlock\fP a lock that unlocks the certificates store, use NULL to select no password/certifictes/prompt lock (see \fBLocking and unlocking certificates and encrypted data.\fP).
  92 .br
  93 \fIname\fP name of the source store
  94 .RE
  95 .PP
  96 \fBReturns:\fP
  97 .RS 4
  98 Returns an hx509 error code.
  99 .RE
 100 .PP
 101
 102 .SS "int hx509_certs_end_seq (hx509_context context, hx509_certs certs, hx509_cursor cursor)"
 103 .PP
 104 End the iteration over certificates.
 105 .PP
 106 \fBParameters:\fP
 107 .RS 4
 108 \fIcontext\fP a hx509 context.
 109 .br
 110 \fIcerts\fP certificate store to iterate over.
 111 .br
 112 \fIcursor\fP cursor that will keep track of progress, freed.
 113 .RE
 114 .PP
 115 \fBReturns:\fP
 116 .RS 4
 117 Returns an hx509 error code.
 118 .RE
 119 .PP
 120
 121 .SS "int hx509_certs_filter (hx509_context context, hx509_certs certs, const hx509_query * q, hx509_certs * result)"
 122 .PP
 123 Filter certificate matching the query.
 124 .PP
 125 \fBParameters:\fP
 126 .RS 4
 127 \fIcontext\fP a hx509 context.
 128 .br
 129 \fIcerts\fP certificate store to search.
 130 .br
 131 \fIq\fP query allocated with \fBhx509 query functions\fP functions.
 132 .br
 133 \fIresult\fP the filtered certificate store, caller must free with \fBhx509_certs_free()\fP.
 134 .RE
 135 .PP
 136 \fBReturns:\fP
 137 .RS 4
 138 Returns an hx509 error code.
 139 .RE
 140 .PP
 141
 142 .PP
 143 Return HX509_CERT_NOT_FOUND if no certificate in certs matched the query.
 144 .SS "int hx509_certs_find (hx509_context context, hx509_certs certs, const hx509_query * q, hx509_cert * r)"
 145 .PP
 146 Find a certificate matching the query.
 147 .PP
 148 \fBParameters:\fP
 149 .RS 4
 150 \fIcontext\fP a hx509 context.
 151 .br
 152 \fIcerts\fP certificate store to search.
 153 .br
 154 \fIq\fP query allocated with \fBhx509 query functions\fP functions.
 155 .br
 156 \fIr\fP return certificate (or NULL on error), should be freed with \fBhx509_cert_free()\fP.
 157 .RE
 158 .PP
 159 \fBReturns:\fP
 160 .RS 4
 161 Returns an hx509 error code.
 162 .RE
 163 .PP
 164
 165 .PP
 166 Return HX509_CERT_NOT_FOUND if no certificate in certs matched the query.
 167 .SS "void hx509_certs_free (hx509_certs * certs)"
 168 .PP
 169 Free a certificate store.
 170 .PP
 171 \fBParameters:\fP
 172 .RS 4
 173 \fIcerts\fP certificate store to free.
 174 .RE
 175 .PP
 176
 177 .SS "int hx509_certs_info (hx509_context context, hx509_certs certs, int(*)(void *, const char *) func, void * ctx)"
 178 .PP
 179 Print some info about the certificate store.
 180 .PP
 181 \fBParameters:\fP
 182 .RS 4
 183 \fIcontext\fP a hx509 context.
 184 .br
 185 \fIcerts\fP certificate store to print information about.
 186 .br
 187 \fIfunc\fP function that will get each line of the information, if NULL is used the data is printed on a FILE descriptor that should be passed in ctx, if ctx also is NULL, stdout is used.
 188 .br
 189 \fIctx\fP parameter to func.
 190 .RE
 191 .PP
 192 \fBReturns:\fP
 193 .RS 4
 194 Returns an hx509 error code.
 195 .RE
 196 .PP
 197
 198 .SS "int hx509_certs_init (hx509_context context, const char * name, int flags, hx509_lock lock, hx509_certs * certs)"
 199 .PP
 200 Open or creates a new hx509 certificate store.
 201 .PP
 202 \fBParameters:\fP
 203 .RS 4
 204 \fIcontext\fP A hx509 context
 205 .br
 206 \fIname\fP name of the store, format is TYPE:type-specific-string, if NULL is used the MEMORY store is used.
 207 .br
 208 \fIflags\fP list of flags:
 209 .IP "\(bu" 2
 210 HX509_CERTS_CREATE create a new keystore of the specific TYPE.
 211 .IP "\(bu" 2
 212 HX509_CERTS_UNPROTECT_ALL fails if any private key failed to be extracted.
 213 .PP
 214 .br
 215 \fIlock\fP a lock that unlocks the certificates store, use NULL to select no password/certifictes/prompt lock (see \fBLocking and unlocking certificates and encrypted data.\fP).
 216 .br
 217 \fIcerts\fP return pointer, free with \fBhx509_certs_free()\fP.
 218 .RE
 219 .PP
 220
 221 .SS "int hx509_certs_iter_f (hx509_context context, hx509_certs certs, int(*)(hx509_context, void *, hx509_cert) func, void * ctx)"
 222 .PP
 223 Iterate over all certificates in a keystore and call an function for each fo them.
 224 .PP
 225 \fBParameters:\fP
 226 .RS 4
 227 \fIcontext\fP a hx509 context.
 228 .br
 229 \fIcerts\fP certificate store to iterate over.
 230 .br
 231 \fIfunc\fP function to call for each certificate. The function should return non-zero to abort the iteration, that value is passed back to the caller of \fBhx509_certs_iter_f()\fP.
 232 .br
 233 \fIctx\fP context variable that will passed to the function.
 234 .RE
 235 .PP
 236 \fBReturns:\fP
 237 .RS 4
 238 Returns an hx509 error code.
 239 .RE
 240 .PP
 241
 242 .SS "int hx509_certs_merge (hx509_context context, hx509_certs to, hx509_certs from)"
 243 .PP
 244 Merge a certificate store into another. The from store is keep intact.
 245 .PP
 246 \fBParameters:\fP
 247 .RS 4
 248 \fIcontext\fP a hx509 context.
 249 .br
 250 \fIto\fP the store to merge into.
 251 .br
 252 \fIfrom\fP the store to copy the object from.
 253 .RE
 254 .PP
 255 \fBReturns:\fP
 256 .RS 4
 257 Returns an hx509 error code.
 258 .RE
 259 .PP
 260
 261 .SS "int hx509_certs_next_cert (hx509_context context, hx509_certs certs, hx509_cursor cursor, hx509_cert * cert)"
 262 .PP
 263 Get next ceritificate from the certificate keystore pointed out by cursor.
 264 .PP
 265 \fBParameters:\fP
 266 .RS 4
 267 \fIcontext\fP a hx509 context.
 268 .br
 269 \fIcerts\fP certificate store to iterate over.
 270 .br
 271 \fIcursor\fP cursor that keeps track of progress.
 272 .br
 273 \fIcert\fP return certificate next in store, NULL if the store contains no more certificates. Free with \fBhx509_cert_free()\fP.
 274 .RE
 275 .PP
 276 \fBReturns:\fP
 277 .RS 4
 278 Returns an hx509 error code.
 279 .RE
 280 .PP
 281
 282 .SS "int hx509_certs_start_seq (hx509_context context, hx509_certs certs, hx509_cursor * cursor)"
 283 .PP
 284 Start the integration
 285 .PP
 286 \fBParameters:\fP
 287 .RS 4
 288 \fIcontext\fP a hx509 context.
 289 .br
 290 \fIcerts\fP certificate store to iterate over
 291 .br
 292 \fIcursor\fP cursor that will keep track of progress, free with \fBhx509_certs_end_seq()\fP.
 293 .RE
 294 .PP
 295 \fBReturns:\fP
 296 .RS 4
 297 Returns an hx509 error code. HX509_UNSUPPORTED_OPERATION is returned if the certificate store doesn't support the iteration operation.
 298 .RE
 299 .PP
 300
 301 .SS "int hx509_certs_store (hx509_context context, hx509_certs certs, int flags, hx509_lock lock)"
 302 .PP
 303 Write the certificate store to stable storage.
 304 .PP
 305 \fBParameters:\fP
 306 .RS 4
 307 \fIcontext\fP A hx509 context.
 308 .br
 309 \fIcerts\fP a certificate store to store.
 310 .br
 311 \fIflags\fP currently unused, use 0.
 312 .br
 313 \fIlock\fP a lock that unlocks the certificates store, use NULL to select no password/certifictes/prompt lock (see \fBLocking and unlocking certificates and encrypted data.\fP).
 314 .RE
 315 .PP
 316 \fBReturns:\fP
 317 .RS 4
 318 Returns an hx509 error code. HX509_UNSUPPORTED_OPERATION if the certificate store doesn't support the store operation.
 319 .RE
 320 .PP
 321
 322 .SS "int hx509_ci_print_names (hx509_context context, void * ctx, hx509_cert c)"
 323 .PP
 324 Iterate over all certificates in a keystore and call an function for each fo them.
 325 .PP
 326 \fBParameters:\fP
 327 .RS 4
 328 \fIcontext\fP a hx509 context.
 329 .br
 330 \fIcerts\fP certificate store to iterate over.
 331 .br
 332 \fIfunc\fP function to call for each certificate. The function should return non-zero to abort the iteration, that value is passed back to the caller of hx509_certs_iter().
 333 .RE
 334 .PP
 335 \fBReturns:\fP
 336 .RS 4
 337 Returns an hx509 error code. Function to use to \fBhx509_certs_iter_f()\fP as a function argument, the ctx variable to \fBhx509_certs_iter_f()\fP should be a FILE file descriptor.
 338 .RE
 339 .PP
 340 \fBParameters:\fP
 341 .RS 4
 342 \fIcontext\fP a hx509 context.
 343 .br
 344 \fIctx\fP used by \fBhx509_certs_iter_f()\fP.
 345 .br
 346 \fIc\fP a certificate
 347 .RE
 348 .PP
 349 \fBReturns:\fP
 350 .RS 4
 351 Returns an hx509 error code.
 352 .RE
 353 .PP
 354
 355 .SS "int hx509_get_one_cert (hx509_context context, hx509_certs certs, hx509_cert * c)"
 356 .PP
 357 Get one random certificate from the certificate store.
 358 .PP
 359 \fBParameters:\fP
 360 .RS 4
 361 \fIcontext\fP a hx509 context.
 362 .br
 363 \fIcerts\fP a certificate store to get the certificate from.
 364 .br
 365 \fIc\fP return certificate, should be freed with \fBhx509_cert_free()\fP.
 366 .RE
 367 .PP
 368 \fBReturns:\fP
 369 .RS 4
 370 Returns an hx509 error code.
 371 .RE
 372 .PP
 373