summaryrefslogtreecommitdiff
path: root/src/lib/libssl/doc/openssl.txt
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/libssl/doc/openssl.txt')
-rw-r--r--src/lib/libssl/doc/openssl.txt120
1 files changed, 61 insertions, 59 deletions
diff --git a/src/lib/libssl/doc/openssl.txt b/src/lib/libssl/doc/openssl.txt
index 91b85e5f14..880eace4da 100644
--- a/src/lib/libssl/doc/openssl.txt
+++ b/src/lib/libssl/doc/openssl.txt
@@ -1,53 +1,12 @@
1 1
2This is some preliminary documentation for OpenSSL. 2This is some preliminary documentation for OpenSSL.
3 3
4============================================================================== 4Contents:
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 5
41This is the previously mentioned strdup function: like the standard library 6 OpenSSL X509V3 extension configuration
42strdup() it copies a null terminated string into a block of allocated memory 7 X509V3 Extension code: programmers guide
43and returns a pointer to the allocated block. 8 PKCS#12 Library
44 9
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 10
52============================================================================== 11==============================================================================
53 OpenSSL X509V3 extension configuration 12 OpenSSL X509V3 extension configuration
@@ -188,7 +147,7 @@ email.1=steve@here
188email.2=steve@there 147email.2=steve@there
189 148
190This is because the configuration file code cannot handle the same name 149This is because the configuration file code cannot handle the same name
191occurring twice in the same extension. 150occurring twice in the same section.
192 151
193The syntax of raw extensions is governed by the extension code: it can 152The syntax of raw extensions is governed by the extension code: it can
194for example contain data in multiple sections. The correct syntax to 153for example contain data in multiple sections. The correct syntax to
@@ -315,6 +274,41 @@ TRUE. An end user certificate MUST NOT have the CA value set to true.
315According to PKIX recommendations it should exclude the extension entirely, 274According to PKIX recommendations it should exclude the extension entirely,
316however some software may require CA set to FALSE for end entity certificates. 275however some software may require CA set to FALSE for end entity certificates.
317 276
277Extended Key Usage.
278
279This extensions consists of a list of usages.
280
281These can either be object short names of the dotted numerical form of OIDs.
282While any OID can be used only certain values make sense. In particular the
283following PKIX, NS and MS values are meaningful:
284
285Value Meaning
286----- -------
287serverAuth SSL/TLS Web Server Authentication.
288clientAuth SSL/TLS Web Client Authentication.
289codeSigning Code signing.
290emailProtection E-mail Protection (S/MIME).
291timeStamping Trusted Timestamping
292msCodeInd Microsoft Individual Code Signing (authenticode)
293msCodeCom Microsoft Commercial Code Signing (authenticode)
294msCTLSign Microsoft Trust List Signing
295msSGC Microsoft Server Gated Crypto
296msEFS Microsoft Encrypted File System
297nsSGC Netscape Server Gated Crypto
298
299For example, under IE5 a CA can be used for any purpose: by including a list
300of the above usages the CA can be restricted to only authorised uses.
301
302Note: software packages may place additional interpretations on certificate
303use, in particular some usages may only work for selected CAs. Don't for example
304expect just including msSGC or nsSGC will automatically mean that a certificate
305can be used for SGC ("step up" encryption) otherwise anyone could use it.
306
307Examples:
308
309extendedKeyUsage=critical,codeSigning,1.2.3.4
310extendedKeyUsage=nsSGC,msSGC
311
318Subject Key Identifier. 312Subject Key Identifier.
319 313
320This is really a string extension and can take two possible values. Either 314This is really a string extension and can take two possible values. Either
@@ -459,16 +453,16 @@ extension in a human or machine readable form.
459 453
4601. Initialisation and cleanup. 4541. Initialisation and cleanup.
461 455
462X509V3_add_standard_extensions(); 456No special initialisation is needed before calling the extension functions.
463 457You used to have to call X509V3_add_standard_extensions(); but this is no longer
464This function should be called before any other extension code. It adds support 458required and this function no longer does anything.
465for some common PKIX and Netscape extensions. Additional custom extensions can
466be added as well (see later).
467 459
468void X509V3_EXT_cleanup(void); 460void X509V3_EXT_cleanup(void);
469 461
470This function should be called last to cleanup the extension code. After this 462This function should be called to cleanup the extension code if any custom
471call no other extension calls should be made. 463extensions have been added. If no custom extensions have been added then this
464call does nothing. After this call all custom extension code is freed up but
465you can still use the standard extensions.
472 466
4732. Printing and parsing extensions. 4672. Printing and parsing extensions.
474 468
@@ -512,7 +506,7 @@ or CRL is due to be signed. Both return 0 on error on non zero for success.
512In each case 'conf' is the LHASH pointer of the configuration file to use 506In each case 'conf' is the LHASH pointer of the configuration file to use
513and 'section' is the section containing the extension details. 507and 'section' is the section containing the extension details.
514 508
515See the 'context functions' section for a description of the ctx paramater. 509See the 'context functions' section for a description of the ctx parameter.
516 510
517 511
518X509_EXTENSION *X509V3_EXT_conf(LHASH *conf, X509V3_CTX *ctx, char *name, 512X509_EXTENSION *X509V3_EXT_conf(LHASH *conf, X509V3_CTX *ctx, char *name,
@@ -531,7 +525,7 @@ takes the NID of the extension rather than its name.
531For example to produce basicConstraints with the CA flag and a path length of 525For example to produce basicConstraints with the CA flag and a path length of
53210: 52610:
533 527
534x = X509V3_EXT_conf_nid(NULL, NULL, NID_basicConstraints, "CA:TRUE,pathlen:10"); 528x = X509V3_EXT_conf_nid(NULL, NULL, NID_basic_constraints,"CA:TRUE,pathlen:10");
535 529
536 530
537X509_EXTENSION *X509V3_EXT_i2d(int ext_nid, int crit, void *ext_struc); 531X509_EXTENSION *X509V3_EXT_i2d(int ext_nid, int crit, void *ext_struc);
@@ -659,7 +653,7 @@ The same as above but for an unsigned character value.
659int X509V3_add_value_bool(const char *name, int asn1_bool, 653int X509V3_add_value_bool(const char *name, int asn1_bool,
660 STACK_OF(CONF_VALUE) **extlist); 654 STACK_OF(CONF_VALUE) **extlist);
661 655
662This adds either "TRUE" or "FALSE" depending on the value of 'ans1_bool' 656This adds either "TRUE" or "FALSE" depending on the value of 'asn1_bool'
663 657
664int X509V3_add_value_bool_nf(char *name, int asn1_bool, 658int X509V3_add_value_bool_nf(char *name, int asn1_bool,
665 STACK_OF(CONF_VALUE) **extlist); 659 STACK_OF(CONF_VALUE) **extlist);
@@ -686,7 +680,7 @@ Multi value extensions are passed a STACK_OF(CONF_VALUE) name and value pairs
686or return a STACK_OF(CONF_VALUE). 680or return a STACK_OF(CONF_VALUE).
687 681
688Raw extensions are just passed a BIO or a value and it is the extensions 682Raw extensions are just passed a BIO or a value and it is the extensions
689responsiblity to handle all the necessary printing. 683responsibility to handle all the necessary printing.
690 684
691There are two ways to add an extension. One is simply as an alias to an already 685There 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 686existing extension. An alias is an extension that is identical in ASN1 structure
@@ -811,7 +805,7 @@ int i2r(struct v3_ext_method *method, void *ext, BIO *out, int indent);
811 805
812This function is passed the internal extension structure in the ext parameter 806This 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' 807and sends out a human readable version of the extension to out. The 'indent'
814paremeter should be noted to determine the necessary amount of indentation 808parameter should be noted to determine the necessary amount of indentation
815needed on the output. 809needed on the output.
816 810
817void * r2i(struct v3_ext_method *method, struct v3_ext_ctx *ctx, char *str); 811void * r2i(struct v3_ext_method *method, struct v3_ext_ctx *ctx, char *str);
@@ -882,7 +876,7 @@ d2i_PKCS12_fp(fp, p12)
882 876
883This is the same but for a FILE pointer. 877This is the same but for a FILE pointer.
884 878
8853. Parsing and creation functions. 8793. High level functions.
886 880
8873.1 Parsing with PKCS12_parse(). 8813.1 Parsing with PKCS12_parse().
888 882
@@ -920,6 +914,14 @@ p12 = PKCS12_create(pass, "My Certificate", pkey, cert, NULL, 0,0,0,0,0);
920i2d_PKCS12_fp(fp, p12); 914i2d_PKCS12_fp(fp, p12);
921PKCS12_free(p12); 915PKCS12_free(p12);
922 916
9173.3 Changing a PKCS#12 structure password.
918
919int PKCS12_newpass(PKCS12 *p12, char *oldpass, char *newpass);
920
921This changes the password of an already existing PKCS#12 structure. oldpass
922is the old password and newpass is the new one. An error occurs if the old
923password is incorrect.
924
923LOW LEVEL FUNCTIONS. 925LOW LEVEL FUNCTIONS.
924 926
925In some cases the high level functions do not provide the necessary 927In some cases the high level functions do not provide the necessary