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