1: 
    2: This is some preliminary documentation for OpenSSL.
    3: 
    4: Contents:
    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: 
   15: OpenSSL X509V3 extension configuration: preliminary documentation.
   16: 
   17: INTRODUCTION.
   18: 
   19: For OpenSSL 0.9.2 the extension code has be considerably enhanced. It is now
   20: possible to add and print out common X509 V3 certificate and CRL extensions.
   21: 
   22: BEGINNERS NOTE
   23: 
   24: For most simple applications you don't need to know too much about extensions:
   25: the default openssl.cnf values will usually do sensible things.
   26: 
   27: If you want to know more you can initially quickly look through the sections
   28: describing how the standard OpenSSL utilities display and add extensions and
   29: then the list of supported extensions.
   30: 
   31: For more technical information about the meaning of extensions see:
   32: 
   33: http://www.imc.org/ietf-pkix/
   34: http://home.netscape.com/eng/security/certs.html
   35: 
   36: PRINTING EXTENSIONS.
   37: 
   38: Extension values are automatically printed out for supported extensions.
   39: 
   40: openssl x509 -in cert.pem -text
   41: openssl crl -in crl.pem -text
   42: 
   43: will 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: 
   57: CONFIGURATION FILES.
   58: 
   59: The OpenSSL utilities 'ca' and 'req' can now have extension sections listing
   60: which certificate extensions to include. In each case a line:
   61: 
   62: x509_extensions = extension_section
   63: 
   64: indicates which section contains the extensions. In the case of 'req' the
   65: extension section is used when the -x509 option is present to create a
   66: self signed root certificate.
   67: 
   68: The 'x509' utility also supports extensions when it signs a certificate.
   69: The -extfile option is used to set the configuration file containing the
   70: extensions. In this case a line with:
   71: 
   72: extensions = extension_section
   73: 
   74: in the nameless (default) section is used. If no such line is included then
   75: it uses the default section.
   76: 
   77: You can also add extensions to CRLs: a line
   78: 
   79: crl_extensions = crl_extension_section
   80: 
   81: will include extensions when the -gencrl option is used with the 'ca' utility.
   82: You can add any extension to a CRL but of the supported extensions only
   83: issuerAltName and authorityKeyIdentifier make any real sense. Note: these are
   84: CRL extensions NOT CRL *entry* extensions which cannot currently be generated.
   85: CRL entry extensions can be displayed.
   86: 
   87: NB. At this time Netscape Communicator rejects V2 CRLs: to get an old V1 CRL
   88: you should not include a crl_extensions line in the configuration file.
   89: 
   90: As with all configuration files you can use the inbuilt environment expansion
   91: to allow the values to be passed in the environment. Therefore if you have
   92: several extension sections used for different purposes you can have a line:
   93: 
   94: x509_extensions = $ENV::ENV_EXT
   95: 
   96: and set the ENV_EXT environment variable before calling the relevant utility.
   97: 
   98: EXTENSION SYNTAX.
   99: 
  100: Extensions have the basic form:
  101: 
  102: extension_name=[critical,] extension_options
  103: 
  104: the use of the critical option makes the extension critical. Extreme caution
  105: should be made when using the critical flag. If an extension is marked
  106: as critical then any client that does not understand the extension should
  107: reject it as invalid. Some broken software will reject certificates which
  108: have *any* critical extensions (these violates PKIX but we have to live
  109: with it).
  110: 
  111: There are three main types of extension: string extensions, multi-valued
  112: extensions, and raw extensions.
  113: 
  114: String extensions simply have a string which contains either the value itself
  115: or how it is obtained.
  116: 
  117: For example:
  118: 
  119: nsComment="This is a Comment"
  120: 
  121: Multi-valued extensions have a short form and a long form. The short form
  122: is a list of names and values:
  123: 
  124: basicConstraints=critical,CA:true,pathlen:1
  125: 
  126: The long form allows the values to be placed in a separate section:
  127: 
  128: basicConstraints=critical,@bs_section
  129: 
  130: [bs_section]
  131: 
  132: CA=true
  133: pathlen=1
  134: 
  135: Both forms are equivalent. However it should be noted that in some cases the
  136: same name can appear multiple times, for example,
  137: 
  138: subjectAltName=email:steve@here,email:steve@there
  139: 
  140: in this case an equivalent long form is:
  141: 
  142: subjectAltName=@alt_section
  143: 
  144: [alt_section]
  145: 
  146: email.1=steve@here
  147: email.2=steve@there
  148: 
  149: This is because the configuration file code cannot handle the same name
  150: occurring twice in the same section.
  151: 
  152: The syntax of raw extensions is governed by the extension code: it can
  153: for example contain data in multiple sections. The correct syntax to
  154: use is defined by the extension code itself: check out the certificate
  155: policies extension for an example.
  156: 
  157: There are two ways to encode arbitrary extensions.
  158: 
  159: The first way is to use the word ASN1 followed by the extension content
  160: using the same syntax as ASN1_generate_nconf(). For example:
  161: 
  162: 1.2.3.4=critical,ASN1:UTF8String:Some random data
  163: 
  164: 1.2.3.4=ASN1:SEQUENCE:seq_sect
  165: 
  166: [seq_sect]
  167: 
  168: field1 = UTF8:field1
  169: field2 = UTF8:field2
  170: 
  171: It is also possible to use the word DER to include arbitrary data in any
  172: extension.
  173: 
  174: 1.2.3.4=critical,DER:01:02:03:04
  175: 1.2.3.4=DER:01020304
  176: 
  177: The value following DER is a hex dump of the DER encoding of the extension
  178: Any extension can be placed in this form to override the default behaviour.
  179: For example:
  180: 
  181: basicConstraints=critical,DER:00:01:02:03
  182: 
  183: WARNING: DER should be used with caution. It is possible to create totally
  184: invalid extensions unless care is taken.
  185: 
  186: CURRENTLY SUPPORTED EXTENSIONS.
  187: 
  188: If you aren't sure about extensions then they can be largely ignored: its only
  189: when you want to do things like restrict certificate usage when you need to
  190: worry about them. 
  191: 
  192: The only extension that a beginner might want to look at is Basic Constraints.
  193: If in addition you want to try Netscape object signing the you should also
  194: look at Netscape Certificate Type.
  195: 
  196: Literal String extensions.
  197: 
  198: In each case the 'value' of the extension is placed directly in the
  199: extension. Currently supported extensions in this category are: nsBaseUrl,
  200: nsRevocationUrl, nsCaRevocationUrl, nsRenewalUrl, nsCaPolicyUrl,
  201: nsSslServerName and nsComment.
  202: 
  203: For example:
  204: 
  205: nsComment="This is a test comment"
  206: 
  207: Bit Strings.
  208: 
  209: Bit string extensions just consist of a list of supported bits, currently
  210: two extensions are in this category: PKIX keyUsage and the Netscape specific
  211: nsCertType.
  212: 
  213: nsCertType (netscape certificate type) takes the flags: client, server, email,
  214: objsign, reserved, sslCA, emailCA, objCA.
  215: 
  216: keyUsage (PKIX key usage) takes the flags: digitalSignature, nonRepudiation,
  217: keyEncipherment, dataEncipherment, keyAgreement, keyCertSign, cRLSign,
  218: encipherOnly, decipherOnly.
  219: 
  220: For example:
  221: 
  222: nsCertType=server
  223: 
  224: keyUsage=digitalSignature, nonRepudiation
  225: 
  226: Hints on Netscape Certificate Type.
  227: 
  228: Other than Basic Constraints this is the only extension a beginner might
  229: want to use, if you want to try Netscape object signing, otherwise it can
  230: be ignored.
  231: 
  232: If you want a certificate that can be used just for object signing then:
  233: 
  234: nsCertType=objsign
  235: 
  236: will do the job. If you want to use it as a normal end user and server
  237: certificate as well then
  238: 
  239: nsCertType=objsign,email,server
  240: 
  241: is more appropriate. You cannot use a self signed certificate for object
  242: signing (well Netscape signtool can but it cheats!) so you need to create
  243: a CA certificate and sign an end user certificate with it.
  244: 
  245: Side note: If you want to conform to the Netscape specifications then you
  246: should really also set:
  247: 
  248: nsCertType=objCA
  249: 
  250: in the *CA* certificate for just an object signing CA and
  251: 
  252: nsCertType=objCA,emailCA,sslCA
  253: 
  254: for everything. Current Netscape software doesn't enforce this so it can
  255: be omitted.
  256: 
  257: Basic Constraints.
  258: 
  259: This is generally the only extension you need to worry about for simple
  260: applications. If you want your certificate to be usable as a CA certificate
  261: (in addition to an end user certificate) then you set this to:
  262: 
  263: basicConstraints=CA:TRUE
  264: 
  265: if you want to be certain the certificate cannot be used as a CA then do:
  266: 
  267: basicConstraints=CA:FALSE
  268: 
  269: The rest of this section describes more advanced usage.
  270: 
  271: Basic constraints is a multi-valued extension that supports a CA and an
  272: optional pathlen option. The CA option takes the values true and false and
  273: pathlen takes an integer. Note if the CA option is false the pathlen option
  274: should be omitted. 
  275: 
  276: The pathlen parameter indicates the maximum number of CAs that can appear
  277: below this one in a chain. So if you have a CA with a pathlen of zero it can
  278: only be used to sign end user certificates and not further CAs. This all
  279: assumes that the software correctly interprets this extension of course.
  280: 
  281: Examples:
  282: 
  283: basicConstraints=CA:TRUE
  284: basicConstraints=critical,CA:TRUE, pathlen:0
  285: 
  286: NOTE: for a CA to be considered valid it must have the CA option set to
  287: TRUE. An end user certificate MUST NOT have the CA value set to true.
  288: According to PKIX recommendations it should exclude the extension entirely,
  289: however some software may require CA set to FALSE for end entity certificates.
  290: 
  291: Extended Key Usage.
  292: 
  293: This extensions consists of a list of usages.
  294: 
  295: These can either be object short names of the dotted numerical form of OIDs.
  296: While any OID can be used only certain values make sense. In particular the
  297: following PKIX, NS and MS values are meaningful:
  298: 
  299: Value                   Meaning
  300: -----                   -------
  301: serverAuth              SSL/TLS Web Server Authentication.
  302: clientAuth              SSL/TLS Web Client Authentication.
  303: codeSigning             Code signing.
  304: emailProtection         E-mail Protection (S/MIME).
  305: timeStamping            Trusted Timestamping
  306: msCodeInd               Microsoft Individual Code Signing (authenticode)
  307: msCodeCom               Microsoft Commercial Code Signing (authenticode)
  308: msCTLSign               Microsoft Trust List Signing
  309: msSGC                   Microsoft Server Gated Crypto
  310: msEFS                   Microsoft Encrypted File System
  311: nsSGC                   Netscape Server Gated Crypto
  312: 
  313: For example, under IE5 a CA can be used for any purpose: by including a list
  314: of the above usages the CA can be restricted to only authorised uses.
  315: 
  316: Note: software packages may place additional interpretations on certificate 
  317: use, in particular some usages may only work for selected CAs. Don't for example
  318: expect just including msSGC or nsSGC will automatically mean that a certificate
  319: can be used for SGC ("step up" encryption) otherwise anyone could use it.
  320: 
  321: Examples:
  322: 
  323: extendedKeyUsage=critical,codeSigning,1.2.3.4
  324: extendedKeyUsage=nsSGC,msSGC
  325: 
  326: Subject Key Identifier.
  327: 
  328: This is really a string extension and can take two possible values. Either
  329: a hex string giving details of the extension value to include or the word
  330: 'hash' which then automatically follow PKIX guidelines in selecting and
  331: appropriate key identifier. The use of the hex string is strongly discouraged.
  332: 
  333: Example: subjectKeyIdentifier=hash
  334: 
  335: Authority Key Identifier.
  336: 
  337: The authority key identifier extension permits two options. keyid and issuer:
  338: both can take the optional value "always".
  339: 
  340: If the keyid option is present an attempt is made to copy the subject key
  341: identifier from the parent certificate. If the value "always" is present
  342: then an error is returned if the option fails.
  343: 
  344: The issuer option copies the issuer and serial number from the issuer
  345: certificate. Normally this will only be done if the keyid option fails or
  346: is not included: the "always" flag will always include the value.
  347: 
  348: Subject Alternative Name.
  349: 
  350: The subject alternative name extension allows various literal values to be
  351: included in the configuration file. These include "email" (an email address)
  352: "URI" a uniform resource indicator, "DNS" (a DNS domain name), RID (a
  353: registered ID: OBJECT IDENTIFIER), IP (and IP address) and otherName.
  354: 
  355: Also the email option include a special 'copy' value. This will automatically
  356: include and email addresses contained in the certificate subject name in
  357: the extension.
  358: 
  359: otherName can include arbitrary data associated with an OID: the value
  360: should be the OID followed by a semicolon and the content in standard
  361: ASN1_generate_nconf() format.
  362: 
  363: Examples:
  364: 
  365: subjectAltName=email:copy,email:my@other.address,URI:http://my.url.here/
  366: subjectAltName=email:my@other.address,RID:1.2.3.4
  367: subjectAltName=otherName:1.2.3.4;UTF8:some other identifier
  368: 
  369: Issuer Alternative Name.
  370: 
  371: The issuer alternative name option supports all the literal options of
  372: subject alternative name. It does *not* support the email:copy option because
  373: that would not make sense. It does support an additional issuer:copy option
  374: that will copy all the subject alternative name values from the issuer 
  375: certificate (if possible).
  376: 
  377: Example:
  378: 
  379: issuserAltName = issuer:copy
  380: 
  381: Authority Info Access.
  382: 
  383: The authority information access extension gives details about how to access
  384: certain information relating to the CA. Its syntax is accessOID;location
  385: where 'location' has the same syntax as subject alternative name (except
  386: that email:copy is not supported). accessOID can be any valid OID but only
  387: certain values are meaningful for example OCSP and caIssuers. OCSP gives the
  388: location of an OCSP responder: this is used by Netscape PSM and other software.
  389: 
  390: Example:
  391: 
  392: authorityInfoAccess = OCSP;URI:http://ocsp.my.host/
  393: authorityInfoAccess = caIssuers;URI:http://my.ca/ca.html
  394: 
  395: CRL distribution points.
  396: 
  397: This is a multi-valued extension that supports all the literal options of
  398: subject alternative name. Of the few software packages that currently interpret
  399: this extension most only interpret the URI option.
  400: 
  401: Currently each option will set a new DistributionPoint with the fullName
  402: field set to the given value.
  403: 
  404: Other fields like cRLissuer and reasons cannot currently be set or displayed:
  405: at this time no examples were available that used these fields.
  406: 
  407: If you see this extension with <UNSUPPORTED> when you attempt to print it out
  408: or it doesn't appear to display correctly then let me know, including the
  409: certificate (mail me at steve@openssl.org) .
  410: 
  411: Examples:
  412: 
  413: crlDistributionPoints=URI:http://www.myhost.com/myca.crl
  414: crlDistributionPoints=URI:http://www.my.com/my.crl,URI:http://www.oth.com/my.crl
  415: 
  416: Certificate Policies.
  417: 
  418: This is a RAW extension. It attempts to display the contents of this extension:
  419: unfortunately this extension is often improperly encoded.
  420: 
  421: The certificate policies extension will rarely be used in practice: few
  422: software packages interpret it correctly or at all. IE5 does partially
  423: support this extension: but it needs the 'ia5org' option because it will
  424: only correctly support a broken encoding. Of the options below only the
  425: policy OID, explicitText and CPS options are displayed with IE5.
  426: 
  427: All the fields of this extension can be set by using the appropriate syntax.
  428: 
  429: If you follow the PKIX recommendations of not including any qualifiers and just
  430: using only one OID then you just include the value of that OID. Multiple OIDs
  431: can be set separated by commas, for example:
  432: 
  433: certificatePolicies= 1.2.4.5, 1.1.3.4
  434: 
  435: If you wish to include qualifiers then the policy OID and qualifiers need to
  436: be specified in a separate section: this is done by using the @section syntax
  437: instead of a literal OID value.
  438: 
  439: The section referred to must include the policy OID using the name
  440: policyIdentifier, cPSuri qualifiers can be included using the syntax:
  441: 
  442: CPS.nnn=value
  443: 
  444: userNotice qualifiers can be set using the syntax:
  445: 
  446: userNotice.nnn=@notice
  447: 
  448: The value of the userNotice qualifier is specified in the relevant section.
  449: This section can include explicitText, organization and noticeNumbers
  450: options. explicitText and organization are text strings, noticeNumbers is a
  451: comma separated list of numbers. The organization and noticeNumbers options
  452: (if included) must BOTH be present. If you use the userNotice option with IE5
  453: then you need the 'ia5org' option at the top level to modify the encoding:
  454: otherwise it will not be interpreted properly.
  455: 
  456: Example:
  457: 
  458: certificatePolicies=ia5org,1.2.3.4,1.5.6.7.8,@polsect
  459: 
  460: [polsect]
  461: 
  462: policyIdentifier = 1.3.5.8
  463: CPS.1="http://my.host.name/"
  464: CPS.2="http://my.your.name/"
  465: userNotice.1=@notice
  466: 
  467: [notice]
  468: 
  469: explicitText="Explicit Text Here"
  470: organization="Organisation Name"
  471: noticeNumbers=1,2,3,4
  472: 
  473: TECHNICAL NOTE: the ia5org option changes the type of the 'organization' field,
  474: according to PKIX it should be of type DisplayText but Verisign uses an 
  475: IA5STRING and IE5 needs this too.
  476: 
  477: Display only extensions.
  478: 
  479: Some extensions are only partially supported and currently are only displayed
  480: but cannot be set. These include private key usage period, CRL number, and
  481: CRL reason.
  482: 
  483: ==============================================================================
  484:                 X509V3 Extension code: programmers guide
  485: ==============================================================================
  486: 
  487: The purpose of the extension code is twofold. It allows an extension to be
  488: created from a string or structure describing its contents and it prints out an
  489: extension in a human or machine readable form.
  490: 
  491: 1. Initialisation and cleanup.
  492: 
  493: No special initialisation is needed before calling the extension functions.
  494: You used to have to call X509V3_add_standard_extensions(); but this is no longer
  495: required and this function no longer does anything.
  496: 
  497: void X509V3_EXT_cleanup(void);
  498: 
  499: This function should be called to cleanup the extension code if any custom
  500: extensions have been added. If no custom extensions have been added then this
  501: call does nothing. After this call all custom extension code is freed up but
  502: you can still use the standard extensions.
  503: 
  504: 2. Printing and parsing extensions.
  505: 
  506: The simplest way to print out extensions is via the standard X509 printing
  507: routines: if you use the standard X509_print() function, the supported
  508: extensions will be printed out automatically.
  509: 
  510: The following functions allow finer control over extension display:
  511: 
  512: int X509V3_EXT_print(BIO *out, X509_EXTENSION *ext, int flag, int indent);
  513: int X509V3_EXT_print_fp(FILE *out, X509_EXTENSION *ext, int flag, int indent);
  514: 
  515: These two functions print out an individual extension to a BIO or FILE pointer.
  516: Currently the flag argument is unused and should be set to 0. The 'indent'
  517: argument is the number of spaces to indent each line.
  518: 
  519: void *X509V3_EXT_d2i(X509_EXTENSION *ext);
  520: 
  521: This function parses an extension and returns its internal structure. The
  522: precise structure you get back depends on the extension being parsed. If the
  523: extension if basicConstraints you will get back a pointer to a
  524: BASIC_CONSTRAINTS structure. Check out the source in crypto/x509v3 for more
  525: details about the structures returned. The returned structure should be freed
  526: after use using the relevant free function, BASIC_CONSTRAINTS_free() for 
  527: example.
  528: 
  529: void    *  X509_get_ext_d2i(X509 *x, int nid, int *crit, int *idx);
  530: void    *  X509_CRL_get_ext_d2i(X509_CRL *x, int nid, int *crit, int *idx);
  531: void    *  X509_REVOKED_get_ext_d2i(X509_REVOKED *x, int nid, int *crit, int *idx);
  532: void    * X509V3_get_d2i(STACK_OF(X509_EXTENSION) *x, int nid, int *crit, int *idx);
  533: 
  534: These functions combine the operations of searching for extensions and
  535: parsing them. They search a certificate, a CRL a CRL entry or a stack
  536: of extensions respectively for extension whose NID is 'nid' and return
  537: the parsed result of NULL if an error occurred. For example:
  538: 
  539: BASIC_CONSTRAINTS *bs;
  540: bs = X509_get_ext_d2i(cert, NID_basic_constraints, NULL, NULL);
  541: 
  542: This will search for the basicConstraints extension and either return
  543: it value or NULL. NULL can mean either the extension was not found, it
  544: occurred more than once or it could not be parsed.
  545: 
  546: If 'idx' is NULL then an extension is only parsed if it occurs precisely
  547: once. This is standard behaviour because extensions normally cannot occur
  548: more than once. If however more than one extension of the same type can
  549: occur it can be used to parse successive extensions for example:
  550: 
  551: int i;
  552: void *ext;
  553: 
  554: i = -1;
  555: for(;;) {
  556:         ext = X509_get_ext_d2i(x, nid, crit, &idx);
  557:         if(ext == NULL) break;
  558:          /* Do something with ext */
  559: }
  560: 
  561: If 'crit' is not NULL and the extension was found then the int it points to
  562: is set to 1 for critical extensions and 0 for non critical. Therefore if the
  563: function returns NULL but 'crit' is set to 0 or 1 then the extension was
  564: found but it could not be parsed.
  565: 
  566: The int pointed to by crit will be set to -1 if the extension was not found
  567: and -2 if the extension occurred more than once (this will only happen if
  568: idx is NULL). In both cases the function will return NULL.
  569: 
  570: 3. Generating extensions.
  571: 
  572: An extension will typically be generated from a configuration file, or some
  573: other kind of configuration database.
  574: 
  575: int X509V3_EXT_add_conf(LHASH *conf, X509V3_CTX *ctx, char *section,
  576:                                                                  X509 *cert);
  577: int X509V3_EXT_CRL_add_conf(LHASH *conf, X509V3_CTX *ctx, char *section,
  578:                                                                  X509_CRL *crl);
  579: 
  580: These functions add all the extensions in the given section to the given
  581: certificate or CRL. They will normally be called just before the certificate
  582: or CRL is due to be signed. Both return 0 on error on non zero for success.
  583: 
  584: In each case 'conf' is the LHASH pointer of the configuration file to use
  585: and 'section' is the section containing the extension details.
  586: 
  587: See the 'context functions' section for a description of the ctx parameter.
  588: 
  589: 
  590: X509_EXTENSION *X509V3_EXT_conf(LHASH *conf, X509V3_CTX *ctx, char *name,
  591:                                                                  char *value);
  592: 
  593: This function returns an extension based on a name and value pair, if the
  594: pair will not need to access other sections in a config file (or there is no
  595: config file) then the 'conf' parameter can be set to NULL.
  596: 
  597: X509_EXTENSION *X509V3_EXT_conf_nid(char *conf, X509V3_CTX *ctx, int nid,
  598:                                                                  char *value);
  599: 
  600: This function creates an extension in the same way as X509V3_EXT_conf() but
  601: takes the NID of the extension rather than its name.
  602: 
  603: For example to produce basicConstraints with the CA flag and a path length of
  604: 10:
  605: 
  606: x = X509V3_EXT_conf_nid(NULL, NULL, NID_basic_constraints,"CA:TRUE,pathlen:10");
  607: 
  608: 
  609: X509_EXTENSION *X509V3_EXT_i2d(int ext_nid, int crit, void *ext_struc);
  610: 
  611: This function sets up an extension from its internal structure. The ext_nid
  612: parameter is the NID of the extension and 'crit' is the critical flag.
  613: 
  614: 4. Context functions.
  615: 
  616: The following functions set and manipulate an extension context structure.
  617: The purpose of the extension context is to allow the extension code to
  618: access various structures relating to the "environment" of the certificate:
  619: for example the issuers certificate or the certificate request.
  620: 
  621: void X509V3_set_ctx(X509V3_CTX *ctx, X509 *issuer, X509 *subject,
  622:                                  X509_REQ *req, X509_CRL *crl, int flags);
  623: 
  624: This function sets up an X509V3_CTX structure with details of the certificate
  625: environment: specifically the issuers certificate, the subject certificate,
  626: the certificate request and the CRL: if these are not relevant or not
  627: available then they can be set to NULL. The 'flags' parameter should be set
  628: to zero.
  629: 
  630: X509V3_set_ctx_test(ctx)
  631: 
  632: This macro is used to set the 'ctx' structure to a 'test' value: this is to
  633: allow the syntax of an extension (or configuration file) to be tested.
  634: 
  635: X509V3_set_ctx_nodb(ctx)
  636: 
  637: This macro is used when no configuration database is present.
  638: 
  639: void X509V3_set_conf_lhash(X509V3_CTX *ctx, LHASH *lhash);
  640: 
  641: This function is used to set the configuration database when it is an LHASH
  642: structure: typically a configuration file.
  643: 
  644: The following functions are used to access a configuration database: they
  645: should only be used in RAW extensions.
  646: 
  647: char * X509V3_get_string(X509V3_CTX *ctx, char *name, char *section);
  648: 
  649: This function returns the value of the parameter "name" in "section", or NULL
  650: if there has been an error.
  651: 
  652: void X509V3_string_free(X509V3_CTX *ctx, char *str);