BUFFER Library
==============================================================================
-The buffer library handles simple character arrays. Buffers are used for various
-purposes in the library, most notably memory BIOs.
+The buffer library handles simple character arrays. Buffers are used for
+various purposes in the library, most notably memory BIOs.
The library uses the BUF_MEM structure defined in buffer.h:
extension section is used when the -x509 option is present to create a
self signed root certificate.
+The 'x509' utility also supports extensions when it signs a certificate.
+The -extfile option is used to set the configuration file containing the
+extensions. In this case a line with:
+
+extensions = extension_section
+
+in the nameless (default) section is used. If no such line is included then
+it uses the default section.
+
You can also add extensions to CRLs: a line
crl_extensions = crl_extension_section
CRL extensions NOT CRL *entry* extensions which cannot currently be generated.
CRL entry extensions can be displayed.
+NB. At this time Netscape Communicator rejects V2 CRLs: to get an old V1 CRL
+you should comment out the crl_extensions line in the configuration file.
+
+As with all configuration files you can use the inbuilt environment expansion
+to allow the values to be passed in the environment. Therefore if you have
+several extension sections used for different purposes you can have a line:
+
+x509_extensions = $ENV::ENV_EXT
+
+and set the ENV_EXT environment variable before calling the relevant utility.
+
EXTENSION SYNTAX.
Extensions have the basic form:
have *any* critical extensions (these violates PKIX but we have to live
with it).
-There are three main types of extension, string extensions, multi valued
+There are three main types of extension: string extensions, multi valued
extensions, and raw extensions.
-String extensions simply have a string which defines the value of the or how
-it is obtained.
+String extensions simply have a string which contains either the value itself
+or how it is obtained.
For example:
This is because the configuration file code cannot handle the same name
occurring twice in the same extension.
-Raw extensions allow arbitrary data to be placed in an extension. For
-example
+The syntax of raw extensions is governed by the extension code: it can
+for example contain data in multiple sections. The correct syntax to
+use is defined by the extension code itself: check out the certificate
+policies extension for an example.
-1.2.3.4=critical,RAW:01:02:03:04
-1.2.3.4=RAW:01020304
+In addition it is also possible to use the word DER to include arbitrary
+data in any extension.
-The value following RAW is a hex dump of the extension contents. Any extension
-can be placed in this form to override the default behaviour. For example:
+1.2.3.4=critical,DER:01:02:03:04
+1.2.3.4=DER:01020304
-basicConstraints=critical,RAW:00:01:02:03
+The value following DER is a hex dump of the DER encoding of the extension
+Any extension can be placed in this form to override the default behaviour.
+For example:
-WARNING: raw extensions should be used with caution. It is possible to create
-totally invalid extensions unless care is taken.
+basicConstraints=critical,DER:00:01:02:03
+
+WARNING: DER should be used with caution. It is possible to create totally
+invalid extensions unless care is taken.
CURRENTLY SUPPORTED EXTENSIONS.
Literal String extensions.
-In each case the 'value' of the extension is placed directly in the extension.
-Currently supported extensions in this category are: nsBaseUrl, nsRevocationUrl
-nsCaRevocationUrl, nsRenewalUrl, nsCaPolicyUrl, nsSslServerName and nsComment.
+In each case the 'value' of the extension is placed directly in the
+extension. Currently supported extensions in this category are: nsBaseUrl,
+nsRevocationUrl, nsCaRevocationUrl, nsRenewalUrl, nsCaPolicyUrl,
+nsSslServerName and nsComment.
For example:
unfortuntately 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.
+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.
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.
+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=1.2.3.4,1.5.6.7.8,@polsect
+certificatePolicies=ia5org,1.2.3.4,1.5.6.7.8,@polsect
[polsect]
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
No special initialisation is needed for the internal PKCS#12 library: the
standard SSLeay_add_all_algorithms() is sufficient. If you do not wish to
-add all algorithms then you can manually initialise the PKCS#12 library with:
+add all algorithms (you should at least add SHA1 though) then you can manually
+initialise the PKCS#12 library with:
PKSC12_PBE_add();
LOW LEVEL FUNCTIONS.
In some cases the high level functions do not provide the necessary
-functionality. For example if you want to generate or parse more complex PKCS#12
-files. The sample pkcs12 application uses the low level functions to display
-details about the internal structure of a PKCS#12 file.
+functionality. For example if you want to generate or parse more complex
+PKCS#12 files. The sample pkcs12 application uses the low level functions
+to display details about the internal structure of a PKCS#12 file.
Introduction.
The reason for these levels is so various objects can be encrypted in various
ways. For example you might want to encrypt a set of private keys with
-triple-DES and then include the related certificates either unencrypted or with
-lower encryption. Yes it's the dreaded crypto laws at work again which
-allow strong encryption on private keys and only weak encryption on other stuff.
+triple-DES and then include the related certificates either unencrypted or
+with lower encryption. Yes it's the dreaded crypto laws at work again which
+allow strong encryption on private keys and only weak encryption on other
+stuff.
To build one of these things you turn all certificates and keys into safebags
(with optional attributes). You collect the safebags into (one or more) STACKS
-and convert these into authsafes (encrypted or unencrypted). The authsafes are
-collected into a STACK and added to a PKCS12 structure. Finally a MAC inserted.
+and convert these into authsafes (encrypted or unencrypted). The authsafes
+are collected into a STACK and added to a PKCS12 structure. Finally a MAC
+inserted.
Pulling one apart is basically the reverse process. The MAC is verified against
the given password. The authsafes are extracted and each authsafe split into
Take a private key and convert it into a PKCS#8 PrivateKeyInfo structure.
Works for both RSA and DSA private keys. NB since the PKCS#8 PrivateKeyInfo
-structure contains a private key data in plain text form it should be free'd up
-as soon as it has been encrypted for security reasons (freeing up the structure
-zeros out the sensitive data). This can be done with PKCS8_PRIV_KEY_INFO_free().
+structure contains a private key data in plain text form it should be free'd
+up as soon as it has been encrypted for security reasons (freeing up the
+structure zeros out the sensitive data). This can be done with
+PKCS8_PRIV_KEY_INFO_free().
PKCS8_add_keyusage(PKCS8_PRIV_KEY_INFO *p8, int usage)
PKCS12_SAFEBAG *PKCS12_MAKE_KEYBAG(PKCS8_PRIV_KEY_INFO *p8)
-Convert a PKCS8 private key structure into a keybag. This routine embeds the p8
-structure in the keybag so p8 should not be freed up or used after it is called.
-The p8 structure will be freed up when the safebag is freed.
+Convert a PKCS8 private key structure into a keybag. This routine embeds the
+p8 structure in the keybag so p8 should not be freed up or used after it is
+called. The p8 structure will be freed up when the safebag is freed.
PKCS12_SAFEBAG *PKCS12_MAKE_SHKEYBAG(int pbe_nid, unsigned char *pass, int passlen, unsigned char *salt, int saltlen, int iter, PKCS8_PRIV_KEY_INFO *p8)
NID_pbe_WithSHA1And128BitRC2_CBC
NID_pbe_WithSHA1And40BitRC2_CBC
-Which you use depends on the implementation you are exporting to. "Export grade"(i.e. cryptograhically challenged) products cannot support all algorithms.
-Typically you may be able to use any encryption on shrouded key bags but they
-must then be placed in an unencrypted authsafe. Other authsafes may only support
-40bit encryption. Of course if you are using SSLeay throughout you can strongly
-encrypt everything and have high iteration counts on everything.
+Which you use depends on the implementation you are exporting to. "Export
+grade" (i.e. cryptograhically challenged) products cannot support all
+algorithms. Typically you may be able to use any encryption on shrouded key
+bags but they must then be placed in an unencrypted authsafe. Other authsafes
+may only support 40bit encryption. Of course if you are using SSLeay
+throughout you can strongly encrypt everything and have high iteration counts
+on everything.
3. For decryption routines only the password and length are needed.
projects / oweals / openssl.git / blobdiff