openssl.txt

mediastreamer2是开源的网络传输媒体流的库

Note: software packages may place additional interpretations on certificate 
use, in particular some usages may only work for selected CAs. Don't for example
expect just including msSGC or nsSGC will automatically mean that a certificate
can be used for SGC ("step up" encryption) otherwise anyone could use it.

Examples:

extendedKeyUsage=critical,codeSigning,1.2.3.4
extendedKeyUsage=nsSGC,msSGC

Subject Key Identifier.

This is really a string extension and can take two possible values. Either
a hex string giving details of the extension value to include or the word
'hash' which then automatically follow PKIX guidelines in selecting and
appropriate key identifier. The use of the hex string is strongly discouraged.

Example: subjectKeyIdentifier=hash

Authority Key Identifier.

The authority key identifier extension permits two options. keyid and issuer:
both can take the optional value "always".

If the keyid option is present an attempt is made to copy the subject key
identifier from the parent certificate. If the value "always" is present
then an error is returned if the option fails.

The issuer option copies the issuer and serial number from the issuer
certificate. Normally this will only be done if the keyid option fails or
is not included: the "always" flag will always include the value.

Subject Alternative Name.

The subject alternative name extension allows various literal values to be
included in the configuration file. These include "email" (an email address)
"URI" a uniform resource indicator, "DNS" (a DNS domain name), RID (a
registered ID: OBJECT IDENTIFIER), IP (and IP address) and otherName.

Also the email option include a special 'copy' value. This will automatically
include and email addresses contained in the certificate subject name in
the extension.

otherName can include arbitrary data associated with an OID: the value
should be the OID followed by a semicolon and the content in standard
ASN1_generate_nconf() format.

Examples:

subjectAltName=email:copy,email:[e-mail],URI:http://my.url.here/
subjectAltName=email:[e-mail],RID:1.2.3.4
subjectAltName=otherName:1.2.3.4;UTF8:some other identifier

Issuer Alternative Name.

The issuer alternative name option supports all the literal options of
subject alternative name. It does *not* support the email:copy option because
that would not make sense. It does support an additional issuer:copy option
that will copy all the subject alternative name values from the issuer 
certificate (if possible).

Example:

issuserAltName = issuer:copy

Authority Info Access.

The authority information access extension gives details about how to access
certain information relating to the CA. Its syntax is accessOID;location
where 'location' has the same syntax as subject alternative name (except
that email:copy is not supported). accessOID can be any valid OID but only
certain values are meaningful for example OCSP and caIssuers. OCSP gives the
location of an OCSP responder: this is used by Netscape PSM and other software.

Example:

authorityInfoAccess = OCSP;URI:http://ocsp.my.host/
authorityInfoAccess = caIssuers;URI:http://my.ca/ca.html

CRL distribution points.

This is a multi-valued extension that supports all the literal options of
subject alternative name. Of the few software packages that currently interpret
this extension most only interpret the URI option.

Currently each option will set a new DistributionPoint with the fullName
field set to the given value.

Other fields like cRLissuer and reasons cannot currently be set or displayed:
at this time no examples were available that used these fields.

If you see this extension with <UNSUPPORTED> when you attempt to print it out
or it doesn't appear to display correctly then let me know, including the
certificate (mail me at [e-mail]) .

Examples:

crlDistributionPoints=URI:http://www.myhost.com/myca.crl
crlDistributionPoints=URI:http://www.my.com/my.crl,URI:http://www.oth.com/my.crl

Certificate Policies.

This is a RAW extension. It attempts to display the contents of this extension:
unfortunately this extension is often improperly encoded.

The certificate policies extension will rarely be used in practice: few
software packages interpret it correctly or at all. IE5 does partially
support this extension: but it needs the 'ia5org' option because it will
only correctly support a broken encoding. Of the options below only the
policy OID, explicitText and CPS options are displayed with IE5.

All the fields of this extension can be set by using the appropriate syntax.

If you follow the PKIX recommendations of not including any qualifiers and just
using only one OID then you just include the value of that OID. Multiple OIDs
can be set separated by commas, for example:

certificatePolicies= 1.2.4.5, 1.1.3.4

If you wish to include qualifiers then the policy OID and qualifiers need to
be specified in a separate section: this is done by using the @section syntax
instead of a literal OID value.

The section referred to must include the policy OID using the name
policyIdentifier, cPSuri qualifiers can be included using the syntax:

CPS.nnn=value

userNotice qualifiers can be set using the syntax:

userNotice.nnn=@notice

The value of the userNotice qualifier is specified in the relevant section.
This section can include explicitText, organization and noticeNumbers
options. explicitText and organization are text strings, noticeNumbers is a
comma separated list of numbers. The organization and noticeNumbers options
(if included) must BOTH be present. If you use the userNotice option with IE5
then you need the 'ia5org' option at the top level to modify the encoding:
otherwise it will not be interpreted properly.

Example:

certificatePolicies=ia5org,1.2.3.4,1.5.6.7.8,@polsect

[polsect]

policyIdentifier = 1.3.5.8
CPS.1="http://my.host.name/"
CPS.2="http://my.your.name/"
userNotice.1=@notice

[notice]

explicitText="Explicit Text Here"
organization="Organisation Name"
noticeNumbers=1,2,3,4

TECHNICAL NOTE: the ia5org option changes the type of the 'organization' field,
according to PKIX it should be of type DisplayText but Verisign uses an 
IA5STRING and IE5 needs this too.

Display only extensions.

Some extensions are only partially supported and currently are only displayed
but cannot be set. These include private key usage period, CRL number, and
CRL reason.

==============================================================================
		X509V3 Extension code: programmers guide
==============================================================================

The purpose of the extension code is twofold. It allows an extension to be
created from a string or structure describing its contents and it prints out an
extension in a human or machine readable form.

1. Initialisation and cleanup.

No special initialisation is needed before calling the extension functions.
You used to have to call X509V3_add_standard_extensions(); but this is no longer
required and this function no longer does anything.

void X509V3_EXT_cleanup(void);

This function should be called to cleanup the extension code if any custom
extensions have been added. If no custom extensions have been added then this
call does nothing. After this call all custom extension code is freed up but
you can still use the standard extensions.

2. Printing and parsing extensions.

The simplest way to print out extensions is via the standard X509 printing
routines: if you use the standard X509_print() function, the supported
extensions will be printed out automatically.

The following functions allow finer control over extension display:

int X509V3_EXT_print(BIO *out, X509_EXTENSION *ext, int flag, int indent);
int X509V3_EXT_print_fp(FILE *out, X509_EXTENSION *ext, int flag, int indent);

These two functions print out an individual extension to a BIO or FILE pointer.
Currently the flag argument is unused and should be set to 0. The 'indent'
argument is the number of spaces to indent each line.

void *X509V3_EXT_d2i(X509_EXTENSION *ext);

This function parses an extension and returns its internal structure. The
precise structure you get back depends on the extension being parsed. If the
extension if basicConstraints you will get back a pointer to a
BASIC_CONSTRAINTS structure. Check out the source in crypto/x509v3 for more
details about the structures returned. The returned structure should be freed
after use using the relevant free function, BASIC_CONSTRAINTS_free() for 
example.

void	*	X509_get_ext_d2i(X509 *x, int nid, int *crit, int *idx);
void	*	X509_CRL_get_ext_d2i(X509_CRL *x, int nid, int *crit, int *idx);
void	*	X509_REVOKED_get_ext_d2i(X509_REVOKED *x, int nid, int *crit, int *idx);
void 	*	X509V3_get_d2i(STACK_OF(X509_EXTENSION) *x, int nid, int *crit, int *idx);

These functions combine the operations of searching for extensions and
parsing them. They search a certificate, a CRL a CRL entry or a stack
of extensions respectively for extension whose NID is 'nid' and return
the parsed result of NULL if an error occurred. For example:

BASIC_CONSTRAINTS *bs;
bs = X509_get_ext_d2i(cert, NID_basic_constraints, NULL, NULL);

This will search for the basicConstraints extension and either return
it value or NULL. NULL can mean either the extension was not found, it
occurred more than once or it could not be parsed.

If 'idx' is NULL then an extension is only parsed if it occurs precisely
once. This is standard behaviour because extensions normally cannot occur
more than once. If however more than one extension of the same type can
occur it can be used to parse successive extensions for example:

int i;
void *ext;

i = -1;
for(;;) {
	ext = X509_get_ext_d2i(x, nid, crit, &idx);
	if(ext == NULL) break;
	 /* Do something with ext */
}

If 'crit' is not NULL and the extension was found then the int it points to
is set to 1 for critical extensions and 0 for non critical. Therefore if the
function returns NULL but 'crit' is set to 0 or 1 then the extension was
found but it could not be parsed.

The int pointed to by crit will be set to -1 if the extension was not found
and -2 if the extension occurred more than once (this will only happen if
idx is NULL). In both cases the function will return NULL.

3. Generating extensions.

An extension will typically be generated from a configuration file, or some
other kind of configuration database.

int X509V3_EXT_add_conf(LHASH *conf, X509V3_CTX *ctx, char *section,
								 X509 *cert);
int X509V3_EXT_CRL_add_conf(LHASH *conf, X509V3_CTX *ctx, char *section,
								 X509_CRL *crl);

These functions add all the extensions in the given section to the given
certificate or CRL. They will normally be called just before the certificate
or CRL is due to be signed. Both return 0 on error on non zero for success.

In each case 'conf' is the LHASH pointer of the configuration file to use
and 'section' is the section containing the extension details.

See the 'context functions' section for a description of the ctx parameter.


X509_EXTENSION *X509V3_EXT_conf(LHASH *conf, X509V3_CTX *ctx, char *name,
								 char *value);

This function returns an extension based on a name and value pair, if the
pair will not need to access other sections in a config file (or there is no
config file) then the 'conf' parameter can be set to NULL.

X509_EXTENSION *X509V3_EXT_conf_nid(char *conf, X509V3_CTX *ctx, int nid,
								 char *value);

This function creates an extension in the same way as X509V3_EXT_conf() but
takes the NID of the extension rather than its name.

For example to produce basicConstraints with the CA flag and a path length of
10:

x = X509V3_EXT_conf_nid(NULL, NULL, NID_basic_constraints,"CA:TRUE,pathlen:10");


X509_EXTENSION *X509V3_EXT_i2d(int ext_nid, int crit, void *ext_struc);

This function sets up an extension from its internal structure. The ext_nid
parameter is the NID of the extension and 'crit' is the critical flag.

4. Context functions.

The following functions set and manipulate an extension context structure.
The purpose of the extension context is to allow the extension code to
access various structures relating to the "environment" of the certificate:
for example the issuers certificate or the certificate request.

void X509V3_set_ctx(X509V3_CTX *ctx, X509 *issuer, X509 *subject,
                                 X509_REQ *req, X509_CRL *crl, int flags);

This function sets up an X509V3_CTX structure with details of the certificate
environment: specifically the issuers certificate, the subject certificate,
the certificate request and the CRL: if these are not relevant or not
available then they can be set to NULL. The 'flags' parameter should be set
to zero.