openssl.txt revision 59191
1 2This is some preliminary documentation for OpenSSL. 3 4Contents: 5 6 OpenSSL X509V3 extension configuration 7 X509V3 Extension code: programmers guide 8 PKCS#12 Library 9 10 11============================================================================== 12 OpenSSL X509V3 extension configuration 13============================================================================== 14 15OpenSSL X509V3 extension configuration: preliminary documentation. 16 17INTRODUCTION. 18 19For OpenSSL 0.9.2 the extension code has be considerably enhanced. It is now 20possible to add and print out common X509 V3 certificate and CRL extensions. 21 22BEGINNERS NOTE 23 24For most simple applications you don't need to know too much about extensions: 25the default openssl.cnf values will usually do sensible things. 26 27If you want to know more you can initially quickly look through the sections 28describing how the standard OpenSSL utilities display and add extensions and 29then the list of supported extensions. 30 31For more technical information about the meaning of extensions see: 32 33http://www.imc.org/ietf-pkix/ 34http://home.netscape.com/eng/security/certs.html 35 36PRINTING EXTENSIONS. 37 38Extension values are automatically printed out for supported extensions. 39 40openssl x509 -in cert.pem -text 41openssl crl -in crl.pem -text 42 43will give information in the extension printout, for example: 44 45 X509v3 extensions: 46 X509v3 Basic Constraints: 47 CA:TRUE 48 X509v3 Subject Key Identifier: 49 73:FE:F7:59:A7:E1:26:84:44:D6:44:36:EE:79:1A:95:7C:B1:4B:15 50 X509v3 Authority Key Identifier: 51 keyid:73:FE:F7:59:A7:E1:26:84:44:D6:44:36:EE:79:1A:95:7C:B1:4B:15, DirName:/C=AU/ST=Some-State/O=Internet Widgits Pty Ltd/Email=email@1.address/Email=email@2.address, serial:00 52 X509v3 Key Usage: 53 Certificate Sign, CRL Sign 54 X509v3 Subject Alternative Name: 55 email:email@1.address, email:email@2.address 56 57CONFIGURATION FILES. 58 59The OpenSSL utilities 'ca' and 'req' can now have extension sections listing 60which certificate extensions to include. In each case a line: 61 62x509_extensions = extension_section 63 64indicates which section contains the extensions. In the case of 'req' the 65extension section is used when the -x509 option is present to create a 66self signed root certificate. 67 68The 'x509' utility also supports extensions when it signs a certificate. 69The -extfile option is used to set the configuration file containing the 70extensions. In this case a line with: 71 72extensions = extension_section 73 74in the nameless (default) section is used. If no such line is included then 75it uses the default section. 76 77You can also add extensions to CRLs: a line 78 79crl_extensions = crl_extension_section 80 81will include extensions when the -gencrl option is used with the 'ca' utility. 82You can add any extension to a CRL but of the supported extensions only 83issuerAltName and authorityKeyIdentifier make any real sense. Note: these are 84CRL extensions NOT CRL *entry* extensions which cannot currently be generated. 85CRL entry extensions can be displayed. 86 87NB. At this time Netscape Communicator rejects V2 CRLs: to get an old V1 CRL 88you should not include a crl_extensions line in the configuration file. 89 90As with all configuration files you can use the inbuilt environment expansion 91to allow the values to be passed in the environment. Therefore if you have 92several extension sections used for different purposes you can have a line: 93 94x509_extensions = $ENV::ENV_EXT 95 96and set the ENV_EXT environment variable before calling the relevant utility. 97 98EXTENSION SYNTAX. 99 100Extensions have the basic form: 101 102extension_name=[critical,] extension_options 103 104the use of the critical option makes the extension critical. Extreme caution 105should be made when using the critical flag. If an extension is marked 106as critical then any client that does not understand the extension should 107reject it as invalid. Some broken software will reject certificates which 108have *any* critical extensions (these violates PKIX but we have to live 109with it). 110 111There are three main types of extension: string extensions, multi-valued 112extensions, and raw extensions. 113 114String extensions simply have a string which contains either the value itself 115or how it is obtained. 116 117For example: 118 119nsComment="This is a Comment" 120 121Multi-valued extensions have a short form and a long form. The short form 122is a list of names and values: 123 124basicConstraints=critical,CA:true,pathlen:1 125 126The long form allows the values to be placed in a separate section: 127 128basicConstraints=critical,@bs_section 129 130[bs_section] 131 132CA=true 133pathlen=1 134 135Both forms are equivalent. However it should be noted that in some cases the 136same name can appear multiple times, for example, 137 138subjectAltName=email:steve@here,email:steve@there 139 140in this case an equivalent long form is: 141 142subjectAltName=@alt_section 143 144[alt_section] 145 146email.1=steve@here 147email.2=steve@there 148 149This is because the configuration file code cannot handle the same name 150occurring twice in the same section. 151 152The syntax of raw extensions is governed by the extension code: it can 153for example contain data in multiple sections. The correct syntax to 154use is defined by the extension code itself: check out the certificate 155policies extension for an example. 156 157In addition it is also possible to use the word DER to include arbitrary 158data in any extension. 159 1601.2.3.4=critical,DER:01:02:03:04 1611.2.3.4=DER:01020304 162 163The value following DER is a hex dump of the DER encoding of the extension 164Any extension can be placed in this form to override the default behaviour. 165For example: 166 167basicConstraints=critical,DER:00:01:02:03 168 169WARNING: DER should be used with caution. It is possible to create totally 170invalid extensions unless care is taken. 171 172CURRENTLY SUPPORTED EXTENSIONS. 173 174If you aren't sure about extensions then they can be largely ignored: its only 175when you want to do things like restrict certificate usage when you need to 176worry about them. 177 178The only extension that a beginner might want to look at is Basic Constraints. 179If in addition you want to try Netscape object signing the you should also 180look at Netscape Certificate Type. 181 182Literal String extensions. 183 184In each case the 'value' of the extension is placed directly in the 185extension. Currently supported extensions in this category are: nsBaseUrl, 186nsRevocationUrl, nsCaRevocationUrl, nsRenewalUrl, nsCaPolicyUrl, 187nsSslServerName and nsComment. 188 189For example: 190 191nsComment="This is a test comment" 192 193Bit Strings. 194 195Bit string extensions just consist of a list of supported bits, currently 196two extensions are in this category: PKIX keyUsage and the Netscape specific 197nsCertType. 198 199nsCertType (netscape certificate type) takes the flags: client, server, email, 200objsign, reserved, sslCA, emailCA, objCA. 201 202keyUsage (PKIX key usage) takes the flags: digitalSignature, nonRepudiation, 203keyEncipherment, dataEncipherment, keyAgreement, keyCertSign, cRLSign, 204encipherOnly, decipherOnly. 205 206For example: 207 208nsCertType=server 209 210keyUsage=digitalSignature, nonRepudiation 211 212Hints on Netscape Certificate Type. 213 214Other than Basic Constraints this is the only extension a beginner might 215want to use, if you want to try Netscape object signing, otherwise it can 216be ignored. 217 218If you want a certificate that can be used just for object signing then: 219 220nsCertType=objsign 221 222will do the job. If you want to use it as a normal end user and server 223certificate as well then 224 225nsCertType=objsign,email,server 226 227is more appropriate. You cannot use a self signed certificate for object 228signing (well Netscape signtool can but it cheats!) so you need to create 229a CA certificate and sign an end user certificate with it. 230 231Side note: If you want to conform to the Netscape specifications then you 232should really also set: 233 234nsCertType=objCA 235 236in the *CA* certificate for just an object signing CA and 237 238nsCertType=objCA,emailCA,sslCA 239 240for everything. Current Netscape software doesn't enforce this so it can 241be omitted. 242 243Basic Constraints. 244 245This is generally the only extension you need to worry about for simple 246applications. If you want your certificate to be usable as a CA certificate 247(in addition to an end user certificate) then you set this to: 248 249basicConstraints=CA:TRUE 250 251if you want to be certain the certificate cannot be used as a CA then do: 252 253basicConstraints=CA:FALSE 254 255The rest of this section describes more advanced usage. 256 257Basic constraints is a multi-valued extension that supports a CA and an 258optional pathlen option. The CA option takes the values true and false and 259pathlen takes an integer. Note if the CA option is false the pathlen option 260should be omitted. 261 262The pathlen parameter indicates the maximum number of CAs that can appear 263below this one in a chain. So if you have a CA with a pathlen of zero it can 264only be used to sign end user certificates and not further CAs. This all 265assumes that the software correctly interprets this extension of course. 266 267Examples: 268 269basicConstraints=CA:TRUE 270basicConstraints=critical,CA:TRUE, pathlen:0 271 272NOTE: for a CA to be considered valid it must have the CA option set to 273TRUE. An end user certificate MUST NOT have the CA value set to true. 274According to PKIX recommendations it should exclude the extension entirely, 275however some software may require CA set to FALSE for end entity certificates. 276 277Extended Key Usage. 278 279This extensions consists of a list of usages. 280 281These can either be object short names of the dotted numerical form of OIDs. 282While any OID can be used only certain values make sense. In particular the 283following PKIX, NS and MS values are meaningful: 284 285Value Meaning 286----- ------- 287serverAuth SSL/TLS Web Server Authentication. 288clientAuth SSL/TLS Web Client Authentication. 289codeSigning Code signing. 290emailProtection E-mail Protection (S/MIME). 291timeStamping Trusted Timestamping 292msCodeInd Microsoft Individual Code Signing (authenticode) 293msCodeCom Microsoft Commercial Code Signing (authenticode) 294msCTLSign Microsoft Trust List Signing 295msSGC Microsoft Server Gated Crypto 296msEFS Microsoft Encrypted File System 297nsSGC Netscape Server Gated Crypto 298 299For example, under IE5 a CA can be used for any purpose: by including a list 300of the above usages the CA can be restricted to only authorised uses. 301 302Note: software packages may place additional interpretations on certificate 303use, in particular some usages may only work for selected CAs. Don't for example 304expect just including msSGC or nsSGC will automatically mean that a certificate 305can be used for SGC ("step up" encryption) otherwise anyone could use it. 306 307Examples: 308 309extendedKeyUsage=critical,codeSigning,1.2.3.4 310extendedKeyUsage=nsSGC,msSGC 311 312Subject Key Identifier. 313 314This is really a string extension and can take two possible values. Either 315a hex string giving details of the extension value to include or the word 316'hash' which then automatically follow PKIX guidelines in selecting and 317appropriate key identifier. The use of the hex string is strongly discouraged. 318 319Example: subjectKeyIdentifier=hash 320 321Authority Key Identifier. 322 323The authority key identifier extension permits two options. keyid and issuer: 324both can take the optional value "always". 325 326If the keyid option is present an attempt is made to copy the subject key 327identifier from the parent certificate. If the value "always" is present 328then an error is returned if the option fails. 329 330The issuer option copies the issuer and serial number from the issuer 331certificate. Normally this will only be done if the keyid option fails or 332is not included: the "always" flag will always include the value. 333 334Subject Alternative Name. 335 336The subject alternative name extension allows various literal values to be 337included in the configuration file. These include "email" (an email address) 338"URI" a uniform resource indicator, "DNS" (a DNS domain name), RID (a 339registered ID: OBJECT IDENTIFIER) and IP (and IP address). 340 341Also the email option include a special 'copy' value. This will automatically 342include and email addresses contained in the certificate subject name in 343the extension. 344 345Examples: 346 347subjectAltName=email:copy,email:my@other.address,URL:http://my.url.here/ 348subjectAltName=email:my@other.address,RID:1.2.3.4 349 350Issuer Alternative Name. 351 352The issuer alternative name option supports all the literal options of 353subject alternative name. It does *not* support the email:copy option because 354that would not make sense. It does support an additional issuer:copy option 355that will copy all the subject alternative name values from the issuer 356certificate (if possible). 357 358CRL distribution points. 359 360This is a multi-valued extension that supports all the literal options of 361subject alternative name. Of the few software packages that currently interpret 362this extension most only interpret the URI option. 363 364Currently each option will set a new DistributionPoint with the fullName 365field set to the given value. 366 367Other fields like cRLissuer and reasons cannot currently be set or displayed: 368at this time no examples were available that used these fields. 369 370If you see this extension with <UNSUPPORTED> when you attempt to print it out 371or it doesn't appear to display correctly then let me know, including the 372certificate (mail me at steve@openssl.org) . 373 374Examples: 375 376crlDistributionPoints=URI:http://www.myhost.com/myca.crl 377crlDistributionPoints=URI:http://www.my.com/my.crl,URI:http://www.oth.com/my.crl 378 379Certificate Policies. 380 381This is a RAW extension. It attempts to display the contents of this extension: 382unfortunately this extension is often improperly encoded. 383 384The certificate policies extension will rarely be used in practice: few 385software packages interpret it correctly or at all. IE5 does partially 386support this extension: but it needs the 'ia5org' option because it will 387only correctly support a broken encoding. Of the options below only the 388policy OID, explicitText and CPS options are displayed with IE5. 389 390All the fields of this extension can be set by using the appropriate syntax. 391 392If you follow the PKIX recommendations of not including any qualifiers and just 393using only one OID then you just include the value of that OID. Multiple OIDs 394can be set separated by commas, for example: 395 396certificatePolicies= 1.2.4.5, 1.1.3.4 397 398If you wish to include qualifiers then the policy OID and qualifiers need to 399be specified in a separate section: this is done by using the @section syntax 400instead of a literal OID value. 401 402The section referred to must include the policy OID using the name 403policyIdentifier, cPSuri qualifiers can be included using the syntax: 404 405CPS.nnn=value 406 407userNotice qualifiers can be set using the syntax: 408 409userNotice.nnn=@notice 410 411The value of the userNotice qualifier is specified in the relevant section. 412This section can include explicitText, organization and noticeNumbers 413options. explicitText and organization are text strings, noticeNumbers is a 414comma separated list of numbers. The organization and noticeNumbers options 415(if included) must BOTH be present. If you use the userNotice option with IE5 416then you need the 'ia5org' option at the top level to modify the encoding: 417otherwise it will not be interpreted properly. 418 419Example: 420 421certificatePolicies=ia5org,1.2.3.4,1.5.6.7.8,@polsect 422 423[polsect] 424 425policyIdentifier = 1.3.5.8 426CPS.1="http://my.host.name/" 427CPS.2="http://my.your.name/" 428userNotice.1=@notice 429 430[notice] 431 432explicitText="Explicit Text Here" 433organization="Organisation Name" 434noticeNumbers=1,2,3,4 435 436TECHNICAL NOTE: the ia5org option changes the type of the 'organization' field, 437according to PKIX it should be of type DisplayText but Verisign uses an 438IA5STRING and IE5 needs this too. 439 440Display only extensions. 441 442Some extensions are only partially supported and currently are only displayed 443but cannot be set. These include private key usage period, CRL number, and 444CRL reason. 445 446============================================================================== 447 X509V3 Extension code: programmers guide 448============================================================================== 449 450The purpose of the extension code is twofold. It allows an extension to be 451created from a string or structure describing its contents and it prints out an 452extension in a human or machine readable form. 453 4541. Initialisation and cleanup. 455 456No special initialisation is needed before calling the extension functions. 457You used to have to call X509V3_add_standard_extensions(); but this is no longer 458required and this function no longer does anything. 459 460void X509V3_EXT_cleanup(void); 461 462This function should be called to cleanup the extension code if any custom 463extensions have been added. If no custom extensions have been added then this 464call does nothing. After this call all custom extension code is freed up but 465you can still use the standard extensions. 466 4672. Printing and parsing extensions. 468 469The simplest way to print out extensions is via the standard X509 printing 470routines: if you use the standard X509_print() function, the supported 471extensions will be printed out automatically. 472 473The following functions allow finer control over extension display: 474 475int X509V3_EXT_print(BIO *out, X509_EXTENSION *ext, int flag, int indent); 476int X509V3_EXT_print_fp(FILE *out, X509_EXTENSION *ext, int flag, int indent); 477 478These two functions print out an individual extension to a BIO or FILE pointer. 479Currently the flag argument is unused and should be set to 0. The 'indent' 480argument is the number of spaces to indent each line. 481 482void *X509V3_EXT_d2i(X509_EXTENSION *ext); 483 484This function parses an extension and returns its internal structure. The 485precise structure you get back depends on the extension being parsed. If the 486extension if basicConstraints you will get back a pointer to a 487BASIC_CONSTRAINTS structure. Check out the source in crypto/x509v3 for more 488details about the structures returned. The returned structure should be freed 489after use using the relevant free function, BASIC_CONSTRAINTS_free() for 490example. 491 4923. Generating extensions. 493 494An extension will typically be generated from a configuration file, or some 495other kind of configuration database. 496 497int X509V3_EXT_add_conf(LHASH *conf, X509V3_CTX *ctx, char *section, 498 X509 *cert); 499int X509V3_EXT_CRL_add_conf(LHASH *conf, X509V3_CTX *ctx, char *section, 500 X509_CRL *crl); 501 502These functions add all the extensions in the given section to the given 503certificate or CRL. They will normally be called just before the certificate 504or CRL is due to be signed. Both return 0 on error on non zero for success. 505 506In each case 'conf' is the LHASH pointer of the configuration file to use 507and 'section' is the section containing the extension details. 508 509See the 'context functions' section for a description of the ctx parameter. 510 511 512X509_EXTENSION *X509V3_EXT_conf(LHASH *conf, X509V3_CTX *ctx, char *name, 513 char *value); 514 515This function returns an extension based on a name and value pair, if the 516pair will not need to access other sections in a config file (or there is no 517config file) then the 'conf' parameter can be set to NULL. 518 519X509_EXTENSION *X509V3_EXT_conf_nid(char *conf, X509V3_CTX *ctx, int nid, 520 char *value); 521 522This function creates an extension in the same way as X509V3_EXT_conf() but 523takes the NID of the extension rather than its name. 524 525For example to produce basicConstraints with the CA flag and a path length of 52610: 527 528x = X509V3_EXT_conf_nid(NULL, NULL, NID_basic_constraints,"CA:TRUE,pathlen:10"); 529 530 531X509_EXTENSION *X509V3_EXT_i2d(int ext_nid, int crit, void *ext_struc); 532 533This function sets up an extension from its internal structure. The ext_nid 534parameter is the NID of the extension and 'crit' is the critical flag. 535 5364. Context functions. 537 538The following functions set and manipulate an extension context structure. 539The purpose of the extension context is to allow the extension code to 540access various structures relating to the "environment" of the certificate: 541for example the issuers certificate or the certificate request. 542 543void X509V3_set_ctx(X509V3_CTX *ctx, X509 *issuer, X509 *subject, 544 X509_REQ *req, X509_CRL *crl, int flags); 545 546This function sets up an X509V3_CTX structure with details of the certificate 547environment: specifically the issuers certificate, the subject certificate, 548the certificate request and the CRL: if these are not relevant or not 549available then they can be set to NULL. The 'flags' parameter should be set 550to zero. 551 552X509V3_set_ctx_test(ctx) 553 554This macro is used to set the 'ctx' structure to a 'test' value: this is to 555allow the syntax of an extension (or configuration file) to be tested. 556 557X509V3_set_ctx_nodb(ctx) 558 559This macro is used when no configuration database is present. 560 561void X509V3_set_conf_lhash(X509V3_CTX *ctx, LHASH *lhash); 562 563This function is used to set the configuration database when it is an LHASH 564structure: typically a configuration file. 565 566The following functions are used to access a configuration database: they 567should only be used in RAW extensions. 568 569char * X509V3_get_string(X509V3_CTX *ctx, char *name, char *section); 570 571This function returns the value of the parameter "name" in "section", or NULL 572if there has been an error. 573 574void X509V3_string_free(X509V3_CTX *ctx, char *str); 575 576This function frees up the string returned by the above function. 577 578STACK_OF(CONF_VALUE) * X509V3_get_section(X509V3_CTX *ctx, char *section); 579 580This function returns a whole section as a STACK_OF(CONF_VALUE) . 581 582void X509V3_section_free( X509V3_CTX *ctx, STACK_OF(CONF_VALUE) *section); 583 584This function frees up the STACK returned by the above function. 585 586Note: it is possible to use the extension code with a custom configuration 587database. To do this the "db_meth" element of the X509V3_CTX structure should 588be set to an X509V3_CTX_METHOD structure. This structure contains the following 589function pointers: 590 591char * (*get_string)(void *db, char *section, char *value); 592STACK_OF(CONF_VALUE) * (*get_section)(void *db, char *section); 593void (*free_string)(void *db, char * string); 594void (*free_section)(void *db, STACK_OF(CONF_VALUE) *section); 595 596these will be called and passed the 'db' element in the X509V3_CTX structure 597to access the database. If a given function is not implemented or not required 598it can be set to NULL. 599 6005. String helper functions. 601 602There are several "i2s" and "s2i" functions that convert structures to and 603from ASCII strings. In all the "i2s" cases the returned string should be 604freed using Free() after use. Since some of these are part of other extension 605code they may take a 'method' parameter. Unless otherwise stated it can be 606safely set to NULL. 607 608char *i2s_ASN1_OCTET_STRING(X509V3_EXT_METHOD *method, ASN1_OCTET_STRING *oct); 609 610This returns a hex string from an ASN1_OCTET_STRING. 611 612char * i2s_ASN1_INTEGER(X509V3_EXT_METHOD *meth, ASN1_INTEGER *aint); 613char * i2s_ASN1_ENUMERATED(X509V3_EXT_METHOD *meth, ASN1_ENUMERATED *aint); 614 615These return a string decimal representations of an ASN1_INTEGER and an 616ASN1_ENUMERATED type, respectively. 617 618ASN1_OCTET_STRING *s2i_ASN1_OCTET_STRING(X509V3_EXT_METHOD *method, 619 X509V3_CTX *ctx, char *str); 620 621This converts an ASCII hex string to an ASN1_OCTET_STRING. 622 623ASN1_INTEGER * s2i_ASN1_INTEGER(X509V3_EXT_METHOD *meth, char *value); 624 625This converts a decimal ASCII string into an ASN1_INTEGER. 626 6276. Multi valued extension helper functions. 628 629The following functions can be used to manipulate STACKs of CONF_VALUE 630structures, as used by multi valued extensions. 631 632int X509V3_get_value_bool(CONF_VALUE *value, int *asn1_bool); 633 634This function expects a boolean value in 'value' and sets 'asn1_bool' to 635it. That is it sets it to 0 for FALSE or 0xff for TRUE. The following 636strings are acceptable: "TRUE", "true", "Y", "y", "YES", "yes", "FALSE" 637"false", "N", "n", "NO" or "no". 638 639int X509V3_get_value_int(CONF_VALUE *value, ASN1_INTEGER **aint); 640 641This accepts a decimal integer of arbitrary length and sets an ASN1_INTEGER. 642 643int X509V3_add_value(const char *name, const char *value, 644 STACK_OF(CONF_VALUE) **extlist); 645 646This simply adds a string name and value pair. 647 648int X509V3_add_value_uchar(const char *name, const unsigned char *value, 649 STACK_OF(CONF_VALUE) **extlist); 650 651The same as above but for an unsigned character value. 652 653int X509V3_add_value_bool(const char *name, int asn1_bool, 654 STACK_OF(CONF_VALUE) **extlist); 655 656This adds either "TRUE" or "FALSE" depending on the value of 'asn1_bool' 657 658int X509V3_add_value_bool_nf(char *name, int asn1_bool, 659 STACK_OF(CONF_VALUE) **extlist); 660 661This is the same as above except it adds nothing if asn1_bool is FALSE. 662 663int X509V3_add_value_int(const char *name, ASN1_INTEGER *aint, 664 STACK_OF(CONF_VALUE) **extlist); 665 666This function adds the value of the ASN1_INTEGER in decimal form. 667 6687. Other helper functions. 669 670<to be added> 671 672ADDING CUSTOM EXTENSIONS. 673 674Currently there are three types of supported extensions. 675 676String extensions are simple strings where the value is placed directly in the 677extensions, and the string returned is printed out. 678 679Multi value extensions are passed a STACK_OF(CONF_VALUE) name and value pairs 680or return a STACK_OF(CONF_VALUE). 681 682Raw extensions are just passed a BIO or a value and it is the extensions 683responsibility to handle all the necessary printing. 684 685There are two ways to add an extension. One is simply as an alias to an already 686existing extension. An alias is an extension that is identical in ASN1 structure 687to an existing extension but has a different OBJECT IDENTIFIER. This can be 688done by calling: 689 690int X509V3_EXT_add_alias(int nid_to, int nid_from); 691 692'nid_to' is the new extension NID and 'nid_from' is the already existing 693extension NID. 694 695Alternatively an extension can be written from scratch. This involves writing 696the ASN1 code to encode and decode the extension and functions to print out and 697generate the extension from strings. The relevant functions are then placed in 698a X509V3_EXT_METHOD structure and int X509V3_EXT_add(X509V3_EXT_METHOD *ext); 699called. 700 701The X509V3_EXT_METHOD structure is described below. 702 703strut { 704int ext_nid; 705int ext_flags; 706X509V3_EXT_NEW ext_new; 707X509V3_EXT_FREE ext_free; 708X509V3_EXT_D2I d2i; 709X509V3_EXT_I2D i2d; 710X509V3_EXT_I2S i2s; 711X509V3_EXT_S2I s2i; 712X509V3_EXT_I2V i2v; 713X509V3_EXT_V2I v2i; 714X509V3_EXT_R2I r2i; 715X509V3_EXT_I2R i2r; 716 717void *usr_data; 718}; 719 720The elements have the following meanings. 721 722ext_nid is the NID of the object identifier of the extension. 723 724ext_flags is set of flags. Currently the only external flag is 725 X509V3_EXT_MULTILINE which means a multi valued extensions 726 should be printed on separate lines. 727 728usr_data is an extension specific pointer to any relevant data. This 729 allows extensions to share identical code but have different 730 uses. An example of this is the bit string extension which uses 731 usr_data to contain a list of the bit names. 732 733All the remaining elements are function pointers. 734 735ext_new is a pointer to a function that allocates memory for the 736 extension ASN1 structure: for example ASN1_OBJECT_new(). 737 738ext_free is a pointer to a function that free up memory of the extension 739 ASN1 structure: for example ASN1_OBJECT_free(). 740 741d2i is the standard ASN1 function that converts a DER buffer into 742 the internal ASN1 structure: for example d2i_ASN1_IA5STRING(). 743 744i2d is the standard ASN1 function that converts the internal 745 structure into the DER representation: for example 746 i2d_ASN1_IA5STRING(). 747 748The remaining functions are depend on the type of extension. One i2X and 749one X2i should be set and the rest set to NULL. The types set do not need 750to match up, for example the extension could be set using the multi valued 751v2i function and printed out using the raw i2r. 752 753All functions have the X509V3_EXT_METHOD passed to them in the 'method' 754parameter and an X509V3_CTX structure. Extension code can then access the 755parent structure via the 'method' parameter to for example make use of the value 756of usr_data. If the code needs to use detail relating to the request it can 757use the 'ctx' parameter. 758 759A note should be given here about the 'flags' member of the 'ctx' parameter. 760If it has the value CTX_TEST then the configuration syntax is being checked 761and no actual certificate or CRL exists. Therefore any attempt in the config 762file to access such information should silently succeed. If the syntax is OK 763then it should simply return a (possibly bogus) extension, otherwise it 764should return NULL. 765 766char *i2s(struct v3_ext_method *method, void *ext); 767 768This function takes the internal structure in the ext parameter and returns 769a Malloc'ed string representing its value. 770 771void * s2i(struct v3_ext_method *method, struct v3_ext_ctx *ctx, char *str); 772 773This function takes the string representation in the ext parameter and returns 774an allocated internal structure: ext_free() will be used on this internal 775structure after use. 776 777i2v and v2i handle a STACK_OF(CONF_VALUE): 778 779typedef struct 780{ 781 char *section; 782 char *name; 783 char *value; 784} CONF_VALUE; 785 786Only the name and value members are currently used. 787 788STACK_OF(CONF_VALUE) * i2v(struct v3_ext_method *method, void *ext); 789 790This function is passed the internal structure in the ext parameter and 791returns a STACK of CONF_VALUE structures. The values of name, value, 792section and the structure itself will be freed up with Free after use. 793Several helper functions are available to add values to this STACK. 794 795void * v2i(struct v3_ext_method *method, struct v3_ext_ctx *ctx, 796 STACK_OF(CONF_VALUE) *values); 797 798This function takes a STACK_OF(CONF_VALUE) structures and should set the 799values of the external structure. This typically uses the name element to 800determine which structure element to set and the value element to determine 801what to set it to. Several helper functions are available for this 802purpose (see above). 803 804int i2r(struct v3_ext_method *method, void *ext, BIO *out, int indent); 805 806This function is passed the internal extension structure in the ext parameter 807and sends out a human readable version of the extension to out. The 'indent' 808parameter should be noted to determine the necessary amount of indentation 809needed on the output. 810 811void * r2i(struct v3_ext_method *method, struct v3_ext_ctx *ctx, char *str); 812 813This is just passed the string representation of the extension. It is intended 814to be used for more elaborate extensions where the standard single and multi 815valued options are insufficient. They can use the 'ctx' parameter to parse the 816configuration database themselves. See the context functions section for details 817of how to do this. 818 819Note: although this type takes the same parameters as the "r2s" function there 820is a subtle difference. Whereas an "r2i" function can access a configuration 821database an "s2i" function MUST NOT. This is so the internal code can safely 822assume that an "s2i" function will work without a configuration database. 823 824============================================================================== 825 PKCS#12 Library 826============================================================================== 827 828This section describes the internal PKCS#12 support. There are very few 829differences between the old external library and the new internal code at 830present. This may well change because the external library will not be updated 831much in future. 832 833This version now includes a couple of high level PKCS#12 functions which 834generally "do the right thing" and should make it much easier to handle PKCS#12 835structures. 836 837HIGH LEVEL FUNCTIONS. 838 839For most applications you only need concern yourself with the high level 840functions. They can parse and generate simple PKCS#12 files as produced by 841Netscape and MSIE or indeed any compliant PKCS#12 file containing a single 842private key and certificate pair. 843 8441. Initialisation and cleanup. 845 846No special initialisation is needed for the internal PKCS#12 library: the 847standard SSLeay_add_all_algorithms() is sufficient. If you do not wish to 848add all algorithms (you should at least add SHA1 though) then you can manually 849initialise the PKCS#12 library with: 850 851PKCS12_PBE_add(); 852 853The memory allocated by the PKCS#12 library is freed up when EVP_cleanup() is 854called or it can be directly freed with: 855 856EVP_PBE_cleanup(); 857 858after this call (or EVP_cleanup() ) no more PKCS#12 library functions should 859be called. 860 8612. I/O functions. 862 863i2d_PKCS12_bio(bp, p12) 864 865This writes out a PKCS12 structure to a BIO. 866 867i2d_PKCS12_fp(fp, p12) 868 869This is the same but for a FILE pointer. 870 871d2i_PKCS12_bio(bp, p12) 872 873This reads in a PKCS12 structure from a BIO. 874 875d2i_PKCS12_fp(fp, p12) 876 877This is the same but for a FILE pointer. 878 8793. High level functions. 880 8813.1 Parsing with PKCS12_parse(). 882 883int PKCS12_parse(PKCS12 *p12, char *pass, EVP_PKEY **pkey, X509 **cert, 884 STACK **ca); 885 886This function takes a PKCS12 structure and a password (ASCII, null terminated) 887and returns the private key, the corresponding certificate and any CA 888certificates. If any of these is not required it can be passed as a NULL. 889The 'ca' parameter should be either NULL, a pointer to NULL or a valid STACK 890structure. Typically to read in a PKCS#12 file you might do: 891 892p12 = d2i_PKCS12_fp(fp, NULL); 893PKCS12_parse(p12, password, &pkey, &cert, NULL); /* CAs not wanted */ 894PKCS12_free(p12); 895 8963.2 PKCS#12 creation with PKCS12_create(). 897 898PKCS12 *PKCS12_create(char *pass, char *name, EVP_PKEY *pkey, X509 *cert, 899 STACK *ca, int nid_key, int nid_cert, int iter, 900 int mac_iter, int keytype); 901 902This function will create a PKCS12 structure from a given password, name, 903private key, certificate and optional STACK of CA certificates. The remaining 9045 parameters can be set to 0 and sensible defaults will be used. 905 906The parameters nid_key and nid_cert are the key and certificate encryption 907algorithms, iter is the encryption iteration count, mac_iter is the MAC 908iteration count and keytype is the type of private key. If you really want 909to know what these last 5 parameters do then read the low level section. 910 911Typically to create a PKCS#12 file the following could be used: 912 913p12 = PKCS12_create(pass, "My Certificate", pkey, cert, NULL, 0,0,0,0,0); 914i2d_PKCS12_fp(fp, p12); 915PKCS12_free(p12); 916 9173.3 Changing a PKCS#12 structure password. 918 919int PKCS12_newpass(PKCS12 *p12, char *oldpass, char *newpass); 920 921This changes the password of an already existing PKCS#12 structure. oldpass 922is the old password and newpass is the new one. An error occurs if the old 923password is incorrect. 924 925LOW LEVEL FUNCTIONS. 926 927In some cases the high level functions do not provide the necessary 928functionality. For example if you want to generate or parse more complex 929PKCS#12 files. The sample pkcs12 application uses the low level functions 930to display details about the internal structure of a PKCS#12 file. 931 932Introduction. 933 934This is a brief description of how a PKCS#12 file is represented internally: 935some knowledge of PKCS#12 is assumed. 936 937A PKCS#12 object contains several levels. 938 939At the lowest level is a PKCS12_SAFEBAG. This can contain a certificate, a 940CRL, a private key, encrypted or unencrypted, a set of safebags (so the 941structure can be nested) or other secrets (not documented at present). 942A safebag can optionally have attributes, currently these are: a unicode 943friendlyName (a Unicode string) or a localKeyID (a string of bytes). 944 945At the next level is an authSafe which is a set of safebags collected into 946a PKCS#7 ContentInfo. This can be just plain data, or encrypted itself. 947 948At the top level is the PKCS12 structure itself which contains a set of 949authSafes in an embedded PKCS#7 Contentinfo of type data. In addition it 950contains a MAC which is a kind of password protected digest to preserve 951integrity (so any unencrypted stuff below can't be tampered with). 952 953The reason for these levels is so various objects can be encrypted in various 954ways. For example you might want to encrypt a set of private keys with 955triple-DES and then include the related certificates either unencrypted or 956with lower encryption. Yes it's the dreaded crypto laws at work again which 957allow strong encryption on private keys and only weak encryption on other 958stuff. 959 960To build one of these things you turn all certificates and keys into safebags 961(with optional attributes). You collect the safebags into (one or more) STACKS 962and convert these into authsafes (encrypted or unencrypted). The authsafes 963are collected into a STACK and added to a PKCS12 structure. Finally a MAC 964inserted. 965 966Pulling one apart is basically the reverse process. The MAC is verified against 967the given password. The authsafes are extracted and each authsafe split into 968a set of safebags (possibly involving decryption). Finally the safebags are 969decomposed into the original keys and certificates and the attributes used to 970match up private key and certificate pairs. 971 972Anyway here are the functions that do the dirty work. 973 9741. Construction functions. 975 9761.1 Safebag functions. 977 978M_PKCS12_x5092certbag(x509) 979 980This macro takes an X509 structure and returns a certificate bag. The 981X509 structure can be freed up after calling this function. 982 983M_PKCS12_x509crl2certbag(crl) 984 985As above but for a CRL. 986 987PKCS8_PRIV_KEY_INFO *PKEY2PKCS8(EVP_PKEY *pkey) 988 989Take a private key and convert it into a PKCS#8 PrivateKeyInfo structure. 990Works for both RSA and DSA private keys. NB since the PKCS#8 PrivateKeyInfo 991structure contains a private key data in plain text form it should be free'd 992up as soon as it has been encrypted for security reasons (freeing up the 993structure zeros out the sensitive data). This can be done with 994PKCS8_PRIV_KEY_INFO_free(). 995 996PKCS8_add_keyusage(PKCS8_PRIV_KEY_INFO *p8, int usage) 997 998This sets the key type when a key is imported into MSIE or Outlook 98. Two 999values are currently supported: KEY_EX and KEY_SIG. KEY_EX is an exchange type 1000key that can also be used for signing but its size is limited in the export 1001versions of MS software to 512 bits, it is also the default. KEY_SIG is a 1002signing only key but the keysize is unlimited (well 16K is supposed to work). 1003If you are using the domestic version of MSIE then you can ignore this because 1004KEY_EX is not limited and can be used for both. 1005 1006PKCS12_SAFEBAG *PKCS12_MAKE_KEYBAG(PKCS8_PRIV_KEY_INFO *p8) 1007 1008Convert a PKCS8 private key structure into a keybag. This routine embeds the 1009p8 structure in the keybag so p8 should not be freed up or used after it is 1010called. The p8 structure will be freed up when the safebag is freed. 1011 1012PKCS12_SAFEBAG *PKCS12_MAKE_SHKEYBAG(int pbe_nid, unsigned char *pass, int passlen, unsigned char *salt, int saltlen, int iter, PKCS8_PRIV_KEY_INFO *p8) 1013 1014Convert a PKCS#8 structure into a shrouded key bag (encrypted). p8 is not 1015embedded and can be freed up after use. 1016 1017int PKCS12_add_localkeyid(PKCS12_SAFEBAG *bag, unsigned char *name, int namelen) 1018int PKCS12_add_friendlyname(PKCS12_SAFEBAG *bag, unsigned char *name, int namelen) 1019 1020Add a local key id or a friendlyname to a safebag. 1021 10221.2 Authsafe functions. 1023 1024PKCS7 *PKCS12_pack_p7data(STACK *sk) 1025Take a stack of safebags and convert them into an unencrypted authsafe. The 1026stack of safebags can be freed up after calling this function. 1027 1028PKCS7 *PKCS12_pack_p7encdata(int pbe_nid, unsigned char *pass, int passlen, unsigned char *salt, int saltlen, int iter, STACK *bags); 1029 1030As above but encrypted. 1031 10321.3 PKCS12 functions. 1033 1034PKCS12 *PKCS12_init(int mode) 1035 1036Initialise a PKCS12 structure (currently mode should be NID_pkcs7_data). 1037 1038M_PKCS12_pack_authsafes(p12, safes) 1039 1040This macro takes a STACK of authsafes and adds them to a PKCS#12 structure. 1041 1042int PKCS12_set_mac(PKCS12 *p12, unsigned char *pass, int passlen, unsigned char *salt, int saltlen, int iter, EVP_MD *md_type); 1043 1044Add a MAC to a PKCS12 structure. If EVP_MD is NULL use SHA-1, the spec suggests 1045that SHA-1 should be used. 1046 10472. Extraction Functions. 1048 10492.1 Safebags. 1050 1051M_PKCS12_bag_type(bag) 1052 1053Return the type of "bag". Returns one of the following 1054 1055NID_keyBag 1056NID_pkcs8ShroudedKeyBag 7 1057NID_certBag 8 1058NID_crlBag 9 1059NID_secretBag 10 1060NID_safeContentsBag 11 1061 1062M_PKCS12_cert_bag_type(bag) 1063 1064Returns type of certificate bag, following are understood. 1065 1066NID_x509Certificate 14 1067NID_sdsiCertificate 15 1068 1069M_PKCS12_crl_bag_type(bag) 1070 1071Returns crl bag type, currently only NID_crlBag is recognised. 1072 1073M_PKCS12_certbag2x509(bag) 1074 1075This macro extracts an X509 certificate from a certificate bag. 1076 1077M_PKCS12_certbag2x509crl(bag) 1078 1079As above but for a CRL. 1080 1081EVP_PKEY * PKCS82PKEY(PKCS8_PRIV_KEY_INFO *p8) 1082 1083Extract a private key from a PKCS8 private key info structure. 1084 1085M_PKCS12_decrypt_skey(bag, pass, passlen) 1086 1087Decrypt a shrouded key bag and return a PKCS8 private key info structure. 1088Works with both RSA and DSA keys 1089 1090char *PKCS12_get_friendlyname(bag) 1091 1092Returns the friendlyName of a bag if present or NULL if none. The returned 1093string is a null terminated ASCII string allocated with Malloc(). It should 1094thus be freed up with Free() after use. 1095 10962.2 AuthSafe functions. 1097 1098M_PKCS12_unpack_p7data(p7) 1099 1100Extract a STACK of safe bags from a PKCS#7 data ContentInfo. 1101 1102#define M_PKCS12_unpack_p7encdata(p7, pass, passlen) 1103 1104As above but for an encrypted content info. 1105 11062.3 PKCS12 functions. 1107 1108M_PKCS12_unpack_authsafes(p12) 1109 1110Extract a STACK of authsafes from a PKCS12 structure. 1111 1112M_PKCS12_mac_present(p12) 1113 1114Check to see if a MAC is present. 1115 1116int PKCS12_verify_mac(PKCS12 *p12, unsigned char *pass, int passlen) 1117 1118Verify a MAC on a PKCS12 structure. Returns an error if MAC not present. 1119 1120 1121Notes. 1122 11231. All the function return 0 or NULL on error. 11242. Encryption based functions take a common set of parameters. These are 1125described below. 1126 1127pass, passlen 1128ASCII password and length. The password on the MAC is called the "integrity 1129password" the encryption password is called the "privacy password" in the 1130PKCS#12 documentation. The passwords do not have to be the same. If -1 is 1131passed for the length it is worked out by the function itself (currently 1132this is sometimes done whatever is passed as the length but that may change). 1133 1134salt, saltlen 1135A 'salt' if salt is NULL a random salt is used. If saltlen is also zero a 1136default length is used. 1137 1138iter 1139Iteration count. This is a measure of how many times an internal function is 1140called to encrypt the data. The larger this value is the longer it takes, it 1141makes dictionary attacks on passwords harder. NOTE: Some implementations do 1142not support an iteration count on the MAC. If the password for the MAC and 1143encryption is the same then there is no point in having a high iteration 1144count for encryption if the MAC has no count. The MAC could be attacked 1145and the password used for the main decryption. 1146 1147pbe_nid 1148This is the NID of the password based encryption method used. The following are 1149supported. 1150NID_pbe_WithSHA1And128BitRC4 1151NID_pbe_WithSHA1And40BitRC4 1152NID_pbe_WithSHA1And3_Key_TripleDES_CBC 1153NID_pbe_WithSHA1And2_Key_TripleDES_CBC 1154NID_pbe_WithSHA1And128BitRC2_CBC 1155NID_pbe_WithSHA1And40BitRC2_CBC 1156 1157Which you use depends on the implementation you are exporting to. "Export 1158grade" (i.e. cryptographically challenged) products cannot support all 1159algorithms. Typically you may be able to use any encryption on shrouded key 1160bags but they must then be placed in an unencrypted authsafe. Other authsafes 1161may only support 40bit encryption. Of course if you are using SSLeay 1162throughout you can strongly encrypt everything and have high iteration counts 1163on everything. 1164 11653. For decryption routines only the password and length are needed. 1166 11674. Unlike the external version the nid's of objects are the values of the 1168constants: that is NID_certBag is the real nid, therefore there is no 1169PKCS12_obj_offset() function. Note the object constants are not the same as 1170those of the external version. If you use these constants then you will need 1171to recompile your code. 1172 11735. With the exception of PKCS12_MAKE_KEYBAG(), after calling any function or 1174macro of the form PKCS12_MAKE_SOMETHING(other) the "other" structure can be 1175reused or freed up safely. 1176 1177