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:
'length' is the current size of the buffer in bytes, 'max' is the amount of
memory allocated to the buffer. There are three functions which handle these
-and one "miscelanous" function.
+and one "miscellaneous" function.
BUF_MEM *BUF_MEM_new()
self signed root certificate.
The 'x509' utility also supports extensions when it signs a certificate.
-The -config option is used to set the configuration file containing the
+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 include then
+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
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:
nsComment="This is a Comment"
-Multi valued extensions have a short form and a long form. The short form
+Multi-valued extensions have a short form and a long form. The short form
is a list of names and values:
basicConstraints=critical,CA:true,pathlen:1
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:
+
+basicConstraints=critical,DER:00:01:02:03
-WARNING: raw extensions should be used with caution. It is possible to create
-totally invalid extensions unless care is taken.
+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:
Bit Strings.
-Bit string extensions just consist of a list of suppported bits, currently
+Bit string extensions just consist of a list of supported bits, currently
two extensions are in this category: PKIX keyUsage and the Netscape specific
nsCertType.
Basic Constraints.
-Basic constraints is a multi valued extension that supports a CA and an
+Basic constraints is a multi-valued extension that supports a CA and an
optional pathlen option. The CA option takes the values true and false and
pathlen takes an integer. Note if the CA option is false the pathlen option
should be omitted.
CRL distribution points.
-This is a multivalued extension that supports all the literal options of
+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.
Certificate Policies.
This is a RAW extension. It attempts to display the contents of this extension:
-unfortuntately this extension is often improperly encoded.
+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
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.
+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:
add all algorithms (you should at least add SHA1 though) then you can manually
initialise the PKCS#12 library with:
-PKSC12_PBE_add();
+PKCS12_PBE_add();
-The memory allocated by the PKCS#12 libray is freed up when EVP_cleanup() is
+The memory allocated by the PKCS#12 library is freed up when EVP_cleanup() is
called or it can be directly freed with:
EVP_PBE_cleanup();
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. cryptographically 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 / openssl.git / blobdiff