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

   1 .TH "hx509 CA functions" 3 "11 Jan 2012" "Version 1.5.2" "Heimdalx509library" \" -*- nroff -*-
   2 .ad l
   3 .nh
   4 .SH NAME
   5 hx509 CA functions \-
   6 .SS "Functions"
   7
   8 .in +1c
   9 .ti -1c
  10 .RI "int \fBhx509_ca_tbs_init\fP (hx509_context context, hx509_ca_tbs *tbs)"
  11 .br
  12 .ti -1c
  13 .RI "void \fBhx509_ca_tbs_free\fP (hx509_ca_tbs *tbs)"
  14 .br
  15 .ti -1c
  16 .RI "int \fBhx509_ca_tbs_set_notBefore\fP (hx509_context context, hx509_ca_tbs tbs, time_t t)"
  17 .br
  18 .ti -1c
  19 .RI "int \fBhx509_ca_tbs_set_notAfter\fP (hx509_context context, hx509_ca_tbs tbs, time_t t)"
  20 .br
  21 .ti -1c
  22 .RI "int \fBhx509_ca_tbs_set_notAfter_lifetime\fP (hx509_context context, hx509_ca_tbs tbs, time_t delta)"
  23 .br
  24 .ti -1c
  25 .RI "struct units * \fBhx509_ca_tbs_template_units\fP (void)"
  26 .br
  27 .ti -1c
  28 .RI "int \fBhx509_ca_tbs_set_template\fP (hx509_context context, hx509_ca_tbs tbs, int flags, hx509_cert cert)"
  29 .br
  30 .ti -1c
  31 .RI "int \fBhx509_ca_tbs_set_ca\fP (hx509_context context, hx509_ca_tbs tbs, int pathLenConstraint)"
  32 .br
  33 .ti -1c
  34 .RI "int \fBhx509_ca_tbs_set_proxy\fP (hx509_context context, hx509_ca_tbs tbs, int pathLenConstraint)"
  35 .br
  36 .ti -1c
  37 .RI "int \fBhx509_ca_tbs_set_domaincontroller\fP (hx509_context context, hx509_ca_tbs tbs)"
  38 .br
  39 .ti -1c
  40 .RI "int \fBhx509_ca_tbs_set_spki\fP (hx509_context context, hx509_ca_tbs tbs, const SubjectPublicKeyInfo *spki)"
  41 .br
  42 .ti -1c
  43 .RI "int \fBhx509_ca_tbs_set_serialnumber\fP (hx509_context context, hx509_ca_tbs tbs, const heim_integer *serialNumber)"
  44 .br
  45 .ti -1c
  46 .RI "int \fBhx509_ca_tbs_add_eku\fP (hx509_context context, hx509_ca_tbs tbs, const heim_oid *oid)"
  47 .br
  48 .ti -1c
  49 .RI "int \fBhx509_ca_tbs_add_crl_dp_uri\fP (hx509_context context, hx509_ca_tbs tbs, const char *uri, hx509_name issuername)"
  50 .br
  51 .ti -1c
  52 .RI "int \fBhx509_ca_tbs_add_san_otherName\fP (hx509_context context, hx509_ca_tbs tbs, const heim_oid *oid, const heim_octet_string *os)"
  53 .br
  54 .ti -1c
  55 .RI "int \fBhx509_ca_tbs_add_san_pkinit\fP (hx509_context context, hx509_ca_tbs tbs, const char *principal)"
  56 .br
  57 .ti -1c
  58 .RI "int \fBhx509_ca_tbs_add_san_ms_upn\fP (hx509_context context, hx509_ca_tbs tbs, const char *principal)"
  59 .br
  60 .ti -1c
  61 .RI "int \fBhx509_ca_tbs_add_san_jid\fP (hx509_context context, hx509_ca_tbs tbs, const char *jid)"
  62 .br
  63 .ti -1c
  64 .RI "int \fBhx509_ca_tbs_add_san_hostname\fP (hx509_context context, hx509_ca_tbs tbs, const char *dnsname)"
  65 .br
  66 .ti -1c
  67 .RI "int \fBhx509_ca_tbs_add_san_rfc822name\fP (hx509_context context, hx509_ca_tbs tbs, const char *rfc822Name)"
  68 .br
  69 .ti -1c
  70 .RI "int \fBhx509_ca_tbs_set_subject\fP (hx509_context context, hx509_ca_tbs tbs, hx509_name subject)"
  71 .br
  72 .ti -1c
  73 .RI "int \fBhx509_ca_tbs_set_unique\fP (hx509_context context, hx509_ca_tbs tbs, const heim_bit_string *subjectUniqueID, const heim_bit_string *issuerUniqueID)"
  74 .br
  75 .ti -1c
  76 .RI "int \fBhx509_ca_tbs_subject_expand\fP (hx509_context context, hx509_ca_tbs tbs, hx509_env env)"
  77 .br
  78 .ti -1c
  79 .RI "int \fBhx509_ca_sign\fP (hx509_context context, hx509_ca_tbs tbs, hx509_cert signer, hx509_cert *certificate)"
  80 .br
  81 .ti -1c
  82 .RI "int \fBhx509_ca_sign_self\fP (hx509_context context, hx509_ca_tbs tbs, hx509_private_key signer, hx509_cert *certificate)"
  83 .br
  84 .in -1c
  85 .SH "Detailed Description"
  86 .PP
  87 See the \fBHx509 CA functions\fP for description and examples.
  88 .SH "Function Documentation"
  89 .PP
  90 .SS "int hx509_ca_sign (hx509_context context, hx509_ca_tbs tbs, hx509_cert signer, hx509_cert * certificate)"
  91 .PP
  92 Sign a to-be-signed certificate object with a issuer certificate.
  93 .PP
  94 The caller needs to at least have called the following functions on the to-be-signed certificate object:
  95 .IP "\(bu" 2
  96 \fBhx509_ca_tbs_init()\fP
  97 .IP "\(bu" 2
  98 \fBhx509_ca_tbs_set_subject()\fP
  99 .IP "\(bu" 2
 100 \fBhx509_ca_tbs_set_spki()\fP
 101 .PP
 102 .PP
 103 When done the to-be-signed certificate object should be freed with \fBhx509_ca_tbs_free()\fP.
 104 .PP
 105 When creating self-signed certificate use \fBhx509_ca_sign_self()\fP instead.
 106 .PP
 107 \fBParameters:\fP
 108 .RS 4
 109 \fIcontext\fP A hx509 context.
 110 .br
 111 \fItbs\fP object to be signed.
 112 .br
 113 \fIsigner\fP the CA certificate object to sign with (need private key).
 114 .br
 115 \fIcertificate\fP return cerificate, free with \fBhx509_cert_free()\fP.
 116 .RE
 117 .PP
 118 \fBReturns:\fP
 119 .RS 4
 120 An hx509 error code, see \fBhx509_get_error_string()\fP.
 121 .RE
 122 .PP
 123
 124 .SS "int hx509_ca_sign_self (hx509_context context, hx509_ca_tbs tbs, hx509_private_key signer, hx509_cert * certificate)"
 125 .PP
 126 Work just like \fBhx509_ca_sign()\fP but signs it-self.
 127 .PP
 128 \fBParameters:\fP
 129 .RS 4
 130 \fIcontext\fP A hx509 context.
 131 .br
 132 \fItbs\fP object to be signed.
 133 .br
 134 \fIsigner\fP private key to sign with.
 135 .br
 136 \fIcertificate\fP return cerificate, free with \fBhx509_cert_free()\fP.
 137 .RE
 138 .PP
 139 \fBReturns:\fP
 140 .RS 4
 141 An hx509 error code, see \fBhx509_get_error_string()\fP.
 142 .RE
 143 .PP
 144
 145 .SS "int hx509_ca_tbs_add_crl_dp_uri (hx509_context context, hx509_ca_tbs tbs, const char * uri, hx509_name issuername)"
 146 .PP
 147 Add CRL distribution point URI to the to-be-signed certificate object.
 148 .PP
 149 \fBParameters:\fP
 150 .RS 4
 151 \fIcontext\fP A hx509 context.
 152 .br
 153 \fItbs\fP object to be signed.
 154 .br
 155 \fIuri\fP uri to the CRL.
 156 .br
 157 \fIissuername\fP name of the issuer.
 158 .RE
 159 .PP
 160 \fBReturns:\fP
 161 .RS 4
 162 An hx509 error code, see \fBhx509_get_error_string()\fP.
 163 .RE
 164 .PP
 165
 166 .PP
 167 issuername not supported
 168 .SS "int hx509_ca_tbs_add_eku (hx509_context context, hx509_ca_tbs tbs, const heim_oid * oid)"
 169 .PP
 170 An an extended key usage to the to-be-signed certificate object. Duplicates will detected and not added.
 171 .PP
 172 \fBParameters:\fP
 173 .RS 4
 174 \fIcontext\fP A hx509 context.
 175 .br
 176 \fItbs\fP object to be signed.
 177 .br
 178 \fIoid\fP extended key usage to add.
 179 .RE
 180 .PP
 181 \fBReturns:\fP
 182 .RS 4
 183 An hx509 error code, see \fBhx509_get_error_string()\fP.
 184 .RE
 185 .PP
 186
 187 .SS "int hx509_ca_tbs_add_san_hostname (hx509_context context, hx509_ca_tbs tbs, const char * dnsname)"
 188 .PP
 189 Add a Subject Alternative Name hostname to to-be-signed certificate object. A domain match starts with ., an exact match does not.
 190 .PP
 191 Example of a an domain match: .domain.se matches the hostname host.domain.se.
 192 .PP
 193 \fBParameters:\fP
 194 .RS 4
 195 \fIcontext\fP A hx509 context.
 196 .br
 197 \fItbs\fP object to be signed.
 198 .br
 199 \fIdnsname\fP a hostame.
 200 .RE
 201 .PP
 202 \fBReturns:\fP
 203 .RS 4
 204 An hx509 error code, see \fBhx509_get_error_string()\fP.
 205 .RE
 206 .PP
 207
 208 .SS "int hx509_ca_tbs_add_san_jid (hx509_context context, hx509_ca_tbs tbs, const char * jid)"
 209 .PP
 210 Add a Jabber/XMPP jid Subject Alternative Name to the to-be-signed certificate object. The jid is an UTF8 string.
 211 .PP
 212 \fBParameters:\fP
 213 .RS 4
 214 \fIcontext\fP A hx509 context.
 215 .br
 216 \fItbs\fP object to be signed.
 217 .br
 218 \fIjid\fP string of an a jabber id in UTF8.
 219 .RE
 220 .PP
 221 \fBReturns:\fP
 222 .RS 4
 223 An hx509 error code, see \fBhx509_get_error_string()\fP.
 224 .RE
 225 .PP
 226
 227 .SS "int hx509_ca_tbs_add_san_ms_upn (hx509_context context, hx509_ca_tbs tbs, const char * principal)"
 228 .PP
 229 Add Microsoft UPN Subject Alternative Name to the to-be-signed certificate object. The principal string is a UTF8 string.
 230 .PP
 231 \fBParameters:\fP
 232 .RS 4
 233 \fIcontext\fP A hx509 context.
 234 .br
 235 \fItbs\fP object to be signed.
 236 .br
 237 \fIprincipal\fP Microsoft UPN string.
 238 .RE
 239 .PP
 240 \fBReturns:\fP
 241 .RS 4
 242 An hx509 error code, see \fBhx509_get_error_string()\fP.
 243 .RE
 244 .PP
 245
 246 .SS "int hx509_ca_tbs_add_san_otherName (hx509_context context, hx509_ca_tbs tbs, const heim_oid * oid, const heim_octet_string * os)"
 247 .PP
 248 Add Subject Alternative Name otherName to the to-be-signed certificate object.
 249 .PP
 250 \fBParameters:\fP
 251 .RS 4
 252 \fIcontext\fP A hx509 context.
 253 .br
 254 \fItbs\fP object to be signed.
 255 .br
 256 \fIoid\fP the oid of the OtherName.
 257 .br
 258 \fIos\fP data in the other name.
 259 .RE
 260 .PP
 261 \fBReturns:\fP
 262 .RS 4
 263 An hx509 error code, see \fBhx509_get_error_string()\fP.
 264 .RE
 265 .PP
 266
 267 .SS "int hx509_ca_tbs_add_san_pkinit (hx509_context context, hx509_ca_tbs tbs, const char * principal)"
 268 .PP
 269 Add Kerberos Subject Alternative Name to the to-be-signed certificate object. The principal string is a UTF8 string.
 270 .PP
 271 \fBParameters:\fP
 272 .RS 4
 273 \fIcontext\fP A hx509 context.
 274 .br
 275 \fItbs\fP object to be signed.
 276 .br
 277 \fIprincipal\fP Kerberos principal to add to the certificate.
 278 .RE
 279 .PP
 280 \fBReturns:\fP
 281 .RS 4
 282 An hx509 error code, see \fBhx509_get_error_string()\fP.
 283 .RE
 284 .PP
 285
 286 .SS "int hx509_ca_tbs_add_san_rfc822name (hx509_context context, hx509_ca_tbs tbs, const char * rfc822Name)"
 287 .PP
 288 Add a Subject Alternative Name rfc822 (email address) to to-be-signed certificate object.
 289 .PP
 290 \fBParameters:\fP
 291 .RS 4
 292 \fIcontext\fP A hx509 context.
 293 .br
 294 \fItbs\fP object to be signed.
 295 .br
 296 \fIrfc822Name\fP a string to a email address.
 297 .RE
 298 .PP
 299 \fBReturns:\fP
 300 .RS 4
 301 An hx509 error code, see \fBhx509_get_error_string()\fP.
 302 .RE
 303 .PP
 304
 305 .SS "void hx509_ca_tbs_free (hx509_ca_tbs * tbs)"
 306 .PP
 307 Free an To Be Signed object.
 308 .PP
 309 \fBParameters:\fP
 310 .RS 4
 311 \fItbs\fP object to free.
 312 .RE
 313 .PP
 314
 315 .SS "int hx509_ca_tbs_init (hx509_context context, hx509_ca_tbs * tbs)"
 316 .PP
 317 Allocate an to-be-signed certificate object that will be converted into an certificate.
 318 .PP
 319 \fBParameters:\fP
 320 .RS 4
 321 \fIcontext\fP A hx509 context.
 322 .br
 323 \fItbs\fP returned to-be-signed certicate object, free with \fBhx509_ca_tbs_free()\fP.
 324 .RE
 325 .PP
 326 \fBReturns:\fP
 327 .RS 4
 328 An hx509 error code, see \fBhx509_get_error_string()\fP.
 329 .RE
 330 .PP
 331
 332 .SS "int hx509_ca_tbs_set_ca (hx509_context context, hx509_ca_tbs tbs, int pathLenConstraint)"
 333 .PP
 334 Make the to-be-signed certificate object a CA certificate. If the pathLenConstraint is negative path length constraint is used.
 335 .PP
 336 \fBParameters:\fP
 337 .RS 4
 338 \fIcontext\fP A hx509 context.
 339 .br
 340 \fItbs\fP object to be signed.
 341 .br
 342 \fIpathLenConstraint\fP path length constraint, negative, no constraint.
 343 .RE
 344 .PP
 345 \fBReturns:\fP
 346 .RS 4
 347 An hx509 error code, see \fBhx509_get_error_string()\fP.
 348 .RE
 349 .PP
 350
 351 .SS "int hx509_ca_tbs_set_domaincontroller (hx509_context context, hx509_ca_tbs tbs)"
 352 .PP
 353 Make the to-be-signed certificate object a windows domain controller certificate.
 354 .PP
 355 \fBParameters:\fP
 356 .RS 4
 357 \fIcontext\fP A hx509 context.
 358 .br
 359 \fItbs\fP object to be signed.
 360 .RE
 361 .PP
 362 \fBReturns:\fP
 363 .RS 4
 364 An hx509 error code, see \fBhx509_get_error_string()\fP.
 365 .RE
 366 .PP
 367
 368 .SS "int hx509_ca_tbs_set_notAfter (hx509_context context, hx509_ca_tbs tbs, time_t t)"
 369 .PP
 370 Set the absolute time when the certificate is valid to.
 371 .PP
 372 \fBParameters:\fP
 373 .RS 4
 374 \fIcontext\fP A hx509 context.
 375 .br
 376 \fItbs\fP object to be signed.
 377 .br
 378 \fIt\fP time when the certificate will expire
 379 .RE
 380 .PP
 381 \fBReturns:\fP
 382 .RS 4
 383 An hx509 error code, see \fBhx509_get_error_string()\fP.
 384 .RE
 385 .PP
 386
 387 .SS "int hx509_ca_tbs_set_notAfter_lifetime (hx509_context context, hx509_ca_tbs tbs, time_t delta)"
 388 .PP
 389 Set the relative time when the certificiate is going to expire.
 390 .PP
 391 \fBParameters:\fP
 392 .RS 4
 393 \fIcontext\fP A hx509 context.
 394 .br
 395 \fItbs\fP object to be signed.
 396 .br
 397 \fIdelta\fP seconds to the certificate is going to expire.
 398 .RE
 399 .PP
 400 \fBReturns:\fP
 401 .RS 4
 402 An hx509 error code, see \fBhx509_get_error_string()\fP.
 403 .RE
 404 .PP
 405
 406 .SS "int hx509_ca_tbs_set_notBefore (hx509_context context, hx509_ca_tbs tbs, time_t t)"
 407 .PP
 408 Set the absolute time when the certificate is valid from. If not set the current time will be used.
 409 .PP
 410 \fBParameters:\fP
 411 .RS 4
 412 \fIcontext\fP A hx509 context.
 413 .br
 414 \fItbs\fP object to be signed.
 415 .br
 416 \fIt\fP time the certificated will start to be valid
 417 .RE
 418 .PP
 419 \fBReturns:\fP
 420 .RS 4
 421 An hx509 error code, see \fBhx509_get_error_string()\fP.
 422 .RE
 423 .PP
 424
 425 .SS "int hx509_ca_tbs_set_proxy (hx509_context context, hx509_ca_tbs tbs, int pathLenConstraint)"
 426 .PP
 427 Make the to-be-signed certificate object a proxy certificate. If the pathLenConstraint is negative path length constraint is used.
 428 .PP
 429 \fBParameters:\fP
 430 .RS 4
 431 \fIcontext\fP A hx509 context.
 432 .br
 433 \fItbs\fP object to be signed.
 434 .br
 435 \fIpathLenConstraint\fP path length constraint, negative, no constraint.
 436 .RE
 437 .PP
 438 \fBReturns:\fP
 439 .RS 4
 440 An hx509 error code, see \fBhx509_get_error_string()\fP.
 441 .RE
 442 .PP
 443
 444 .SS "int hx509_ca_tbs_set_serialnumber (hx509_context context, hx509_ca_tbs tbs, const heim_integer * serialNumber)"
 445 .PP
 446 Set the serial number to use for to-be-signed certificate object.
 447 .PP
 448 \fBParameters:\fP
 449 .RS 4
 450 \fIcontext\fP A hx509 context.
 451 .br
 452 \fItbs\fP object to be signed.
 453 .br
 454 \fIserialNumber\fP serial number to use for the to-be-signed certificate object.
 455 .RE
 456 .PP
 457 \fBReturns:\fP
 458 .RS 4
 459 An hx509 error code, see \fBhx509_get_error_string()\fP.
 460 .RE
 461 .PP
 462
 463 .SS "int hx509_ca_tbs_set_spki (hx509_context context, hx509_ca_tbs tbs, const SubjectPublicKeyInfo * spki)"
 464 .PP
 465 Set the subject public key info (SPKI) in the to-be-signed certificate object. SPKI is the public key and key related parameters in the certificate.
 466 .PP
 467 \fBParameters:\fP
 468 .RS 4
 469 \fIcontext\fP A hx509 context.
 470 .br
 471 \fItbs\fP object to be signed.
 472 .br
 473 \fIspki\fP subject public key info to use for the to-be-signed certificate object.
 474 .RE
 475 .PP
 476 \fBReturns:\fP
 477 .RS 4
 478 An hx509 error code, see \fBhx509_get_error_string()\fP.
 479 .RE
 480 .PP
 481
 482 .SS "int hx509_ca_tbs_set_subject (hx509_context context, hx509_ca_tbs tbs, hx509_name subject)"
 483 .PP
 484 Set the subject name of a to-be-signed certificate object.
 485 .PP
 486 \fBParameters:\fP
 487 .RS 4
 488 \fIcontext\fP A hx509 context.
 489 .br
 490 \fItbs\fP object to be signed.
 491 .br
 492 \fIsubject\fP the name to set a subject.
 493 .RE
 494 .PP
 495 \fBReturns:\fP
 496 .RS 4
 497 An hx509 error code, see \fBhx509_get_error_string()\fP.
 498 .RE
 499 .PP
 500
 501 .SS "int hx509_ca_tbs_set_template (hx509_context context, hx509_ca_tbs tbs, int flags, hx509_cert cert)"
 502 .PP
 503 Initialize the to-be-signed certificate object from a template certifiate.
 504 .PP
 505 \fBParameters:\fP
 506 .RS 4
 507 \fIcontext\fP A hx509 context.
 508 .br
 509 \fItbs\fP object to be signed.
 510 .br
 511 \fIflags\fP bit field selecting what to copy from the template certifiate.
 512 .br
 513 \fIcert\fP template certificate.
 514 .RE
 515 .PP
 516 \fBReturns:\fP
 517 .RS 4
 518 An hx509 error code, see \fBhx509_get_error_string()\fP.
 519 .RE
 520 .PP
 521
 522 .SS "int hx509_ca_tbs_set_unique (hx509_context context, hx509_ca_tbs tbs, const heim_bit_string * subjectUniqueID, const heim_bit_string * issuerUniqueID)"
 523 .PP
 524 Set the issuerUniqueID and subjectUniqueID
 525 .PP
 526 These are only supposed to be used considered with version 2 certificates, replaced by the two extensions SubjectKeyIdentifier and IssuerKeyIdentifier. This function is to allow application using legacy protocol to issue them.
 527 .PP
 528 \fBParameters:\fP
 529 .RS 4
 530 \fIcontext\fP A hx509 context.
 531 .br
 532 \fItbs\fP object to be signed.
 533 .br
 534 \fIissuerUniqueID\fP to be set
 535 .br
 536 \fIsubjectUniqueID\fP to be set
 537 .RE
 538 .PP
 539 \fBReturns:\fP
 540 .RS 4
 541 An hx509 error code, see \fBhx509_get_error_string()\fP.
 542 .RE
 543 .PP
 544
 545 .SS "int hx509_ca_tbs_subject_expand (hx509_context context, hx509_ca_tbs tbs, hx509_env env)"
 546 .PP
 547 Expand the the subject name in the to-be-signed certificate object using \fBhx509_name_expand()\fP.
 548 .PP
 549 \fBParameters:\fP
 550 .RS 4
 551 \fIcontext\fP A hx509 context.
 552 .br
 553 \fItbs\fP object to be signed.
 554 .br
 555 \fIenv\fP enviroment variable to expand variables in the subject name, see hx509_env_init().
 556 .RE
 557 .PP
 558 \fBReturns:\fP
 559 .RS 4
 560 An hx509 error code, see \fBhx509_get_error_string()\fP.
 561 .RE
 562 .PP
 563
 564 .SS "struct units* hx509_ca_tbs_template_units (void)\fC [read]\fP"
 565 .PP
 566 Make of template units, use to build flags argument to \fBhx509_ca_tbs_set_template()\fP with parse_units().
 567 .PP
 568 \fBReturns:\fP
 569 .RS 4
 570 an units structure.
 571 .RE
 572 .PP
 573