diff options
Diffstat (limited to 'src/lib/libssl/doc/openssl.txt')
-rw-r--r-- | src/lib/libssl/doc/openssl.txt | 120 |
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 | ||
2 | This is some preliminary documentation for OpenSSL. | 2 | This is some preliminary documentation for OpenSSL. |
3 | 3 | ||
4 | ============================================================================== | 4 | Contents: |
5 | BUFFER Library | ||
6 | ============================================================================== | ||
7 | |||
8 | The buffer library handles simple character arrays. Buffers are used for | ||
9 | various purposes in the library, most notably memory BIOs. | ||
10 | |||
11 | The library uses the BUF_MEM structure defined in buffer.h: | ||
12 | |||
13 | typedef 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 | ||
21 | memory allocated to the buffer. There are three functions which handle these | ||
22 | and one "miscellaneous" function. | ||
23 | |||
24 | BUF_MEM *BUF_MEM_new() | ||
25 | |||
26 | This allocates a new buffer of zero size. Returns the buffer or NULL on error. | ||
27 | |||
28 | void BUF_MEM_free(BUF_MEM *a) | ||
29 | |||
30 | This frees up an already existing buffer. The data is zeroed before freeing | ||
31 | up in case the buffer contains sensitive data. | ||
32 | |||
33 | int BUF_MEM_grow(BUF_MEM *str, int len) | ||
34 | |||
35 | This changes the size of an already existing buffer. It returns zero on error | ||
36 | or the new size (i.e. 'len'). Any data already in the buffer is preserved if | ||
37 | it increases in size. | ||
38 | |||
39 | char * BUF_strdup(char *str) | ||
40 | 5 | ||
41 | This is the previously mentioned strdup function: like the standard library | 6 | OpenSSL X509V3 extension configuration |
42 | strdup() it copies a null terminated string into a block of allocated memory | 7 | X509V3 Extension code: programmers guide |
43 | and returns a pointer to the allocated block. | 8 | PKCS#12 Library |
44 | 9 | ||
45 | Unlike the standard C library strdup() this function uses Malloc() and so | ||
46 | should be used in preference to the standard library strdup() because it can | ||
47 | be used for memory leak checking or replacing the malloc() function. | ||
48 | |||
49 | The memory allocated from BUF_strdup() should be freed up using the Free() | ||
50 | function. | ||
51 | 10 | ||
52 | ============================================================================== | 11 | ============================================================================== |
53 | OpenSSL X509V3 extension configuration | 12 | OpenSSL X509V3 extension configuration |
@@ -188,7 +147,7 @@ email.1=steve@here | |||
188 | email.2=steve@there | 147 | email.2=steve@there |
189 | 148 | ||
190 | This is because the configuration file code cannot handle the same name | 149 | This is because the configuration file code cannot handle the same name |
191 | occurring twice in the same extension. | 150 | occurring twice in the same section. |
192 | 151 | ||
193 | The syntax of raw extensions is governed by the extension code: it can | 152 | The syntax of raw extensions is governed by the extension code: it can |
194 | for example contain data in multiple sections. The correct syntax to | 153 | for 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. | |||
315 | According to PKIX recommendations it should exclude the extension entirely, | 274 | According to PKIX recommendations it should exclude the extension entirely, |
316 | however some software may require CA set to FALSE for end entity certificates. | 275 | however some software may require CA set to FALSE for end entity certificates. |
317 | 276 | ||
277 | Extended Key Usage. | ||
278 | |||
279 | This extensions consists of a list of usages. | ||
280 | |||
281 | These can either be object short names of the dotted numerical form of OIDs. | ||
282 | While any OID can be used only certain values make sense. In particular the | ||
283 | following PKIX, NS and MS values are meaningful: | ||
284 | |||
285 | Value Meaning | ||
286 | ----- ------- | ||
287 | serverAuth SSL/TLS Web Server Authentication. | ||
288 | clientAuth SSL/TLS Web Client Authentication. | ||
289 | codeSigning Code signing. | ||
290 | emailProtection E-mail Protection (S/MIME). | ||
291 | timeStamping Trusted Timestamping | ||
292 | msCodeInd Microsoft Individual Code Signing (authenticode) | ||
293 | msCodeCom Microsoft Commercial Code Signing (authenticode) | ||
294 | msCTLSign Microsoft Trust List Signing | ||
295 | msSGC Microsoft Server Gated Crypto | ||
296 | msEFS Microsoft Encrypted File System | ||
297 | nsSGC Netscape Server Gated Crypto | ||
298 | |||
299 | For example, under IE5 a CA can be used for any purpose: by including a list | ||
300 | of the above usages the CA can be restricted to only authorised uses. | ||
301 | |||
302 | Note: software packages may place additional interpretations on certificate | ||
303 | use, in particular some usages may only work for selected CAs. Don't for example | ||
304 | expect just including msSGC or nsSGC will automatically mean that a certificate | ||
305 | can be used for SGC ("step up" encryption) otherwise anyone could use it. | ||
306 | |||
307 | Examples: | ||
308 | |||
309 | extendedKeyUsage=critical,codeSigning,1.2.3.4 | ||
310 | extendedKeyUsage=nsSGC,msSGC | ||
311 | |||
318 | Subject Key Identifier. | 312 | Subject Key Identifier. |
319 | 313 | ||
320 | This is really a string extension and can take two possible values. Either | 314 | This 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 | ||
460 | 1. Initialisation and cleanup. | 454 | 1. Initialisation and cleanup. |
461 | 455 | ||
462 | X509V3_add_standard_extensions(); | 456 | No special initialisation is needed before calling the extension functions. |
463 | 457 | You used to have to call X509V3_add_standard_extensions(); but this is no longer | |
464 | This function should be called before any other extension code. It adds support | 458 | required and this function no longer does anything. |
465 | for some common PKIX and Netscape extensions. Additional custom extensions can | ||
466 | be added as well (see later). | ||
467 | 459 | ||
468 | void X509V3_EXT_cleanup(void); | 460 | void X509V3_EXT_cleanup(void); |
469 | 461 | ||
470 | This function should be called last to cleanup the extension code. After this | 462 | This function should be called to cleanup the extension code if any custom |
471 | call no other extension calls should be made. | 463 | extensions have been added. If no custom extensions have been added then this |
464 | call does nothing. After this call all custom extension code is freed up but | ||
465 | you can still use the standard extensions. | ||
472 | 466 | ||
473 | 2. Printing and parsing extensions. | 467 | 2. 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. | |||
512 | In each case 'conf' is the LHASH pointer of the configuration file to use | 506 | In each case 'conf' is the LHASH pointer of the configuration file to use |
513 | and 'section' is the section containing the extension details. | 507 | and 'section' is the section containing the extension details. |
514 | 508 | ||
515 | See the 'context functions' section for a description of the ctx paramater. | 509 | See the 'context functions' section for a description of the ctx parameter. |
516 | 510 | ||
517 | 511 | ||
518 | X509_EXTENSION *X509V3_EXT_conf(LHASH *conf, X509V3_CTX *ctx, char *name, | 512 | X509_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. | |||
531 | For example to produce basicConstraints with the CA flag and a path length of | 525 | For example to produce basicConstraints with the CA flag and a path length of |
532 | 10: | 526 | 10: |
533 | 527 | ||
534 | x = X509V3_EXT_conf_nid(NULL, NULL, NID_basicConstraints, "CA:TRUE,pathlen:10"); | 528 | x = X509V3_EXT_conf_nid(NULL, NULL, NID_basic_constraints,"CA:TRUE,pathlen:10"); |
535 | 529 | ||
536 | 530 | ||
537 | X509_EXTENSION *X509V3_EXT_i2d(int ext_nid, int crit, void *ext_struc); | 531 | X509_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. | |||
659 | int X509V3_add_value_bool(const char *name, int asn1_bool, | 653 | int X509V3_add_value_bool(const char *name, int asn1_bool, |
660 | STACK_OF(CONF_VALUE) **extlist); | 654 | STACK_OF(CONF_VALUE) **extlist); |
661 | 655 | ||
662 | This adds either "TRUE" or "FALSE" depending on the value of 'ans1_bool' | 656 | This adds either "TRUE" or "FALSE" depending on the value of 'asn1_bool' |
663 | 657 | ||
664 | int X509V3_add_value_bool_nf(char *name, int asn1_bool, | 658 | int 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 | |||
686 | or return a STACK_OF(CONF_VALUE). | 680 | or return a STACK_OF(CONF_VALUE). |
687 | 681 | ||
688 | Raw extensions are just passed a BIO or a value and it is the extensions | 682 | Raw extensions are just passed a BIO or a value and it is the extensions |
689 | responsiblity to handle all the necessary printing. | 683 | responsibility to handle all the necessary printing. |
690 | 684 | ||
691 | There are two ways to add an extension. One is simply as an alias to an already | 685 | There are two ways to add an extension. One is simply as an alias to an already |
692 | existing extension. An alias is an extension that is identical in ASN1 structure | 686 | existing 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 | ||
812 | This function is passed the internal extension structure in the ext parameter | 806 | This function is passed the internal extension structure in the ext parameter |
813 | and sends out a human readable version of the extension to out. The 'indent' | 807 | and sends out a human readable version of the extension to out. The 'indent' |
814 | paremeter should be noted to determine the necessary amount of indentation | 808 | parameter should be noted to determine the necessary amount of indentation |
815 | needed on the output. | 809 | needed on the output. |
816 | 810 | ||
817 | void * r2i(struct v3_ext_method *method, struct v3_ext_ctx *ctx, char *str); | 811 | void * r2i(struct v3_ext_method *method, struct v3_ext_ctx *ctx, char *str); |
@@ -882,7 +876,7 @@ d2i_PKCS12_fp(fp, p12) | |||
882 | 876 | ||
883 | This is the same but for a FILE pointer. | 877 | This is the same but for a FILE pointer. |
884 | 878 | ||
885 | 3. Parsing and creation functions. | 879 | 3. High level functions. |
886 | 880 | ||
887 | 3.1 Parsing with PKCS12_parse(). | 881 | 3.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); | |||
920 | i2d_PKCS12_fp(fp, p12); | 914 | i2d_PKCS12_fp(fp, p12); |
921 | PKCS12_free(p12); | 915 | PKCS12_free(p12); |
922 | 916 | ||
917 | 3.3 Changing a PKCS#12 structure password. | ||
918 | |||
919 | int PKCS12_newpass(PKCS12 *p12, char *oldpass, char *newpass); | ||
920 | |||
921 | This changes the password of an already existing PKCS#12 structure. oldpass | ||
922 | is the old password and newpass is the new one. An error occurs if the old | ||
923 | password is incorrect. | ||
924 | |||
923 | LOW LEVEL FUNCTIONS. | 925 | LOW LEVEL FUNCTIONS. |
924 | 926 | ||
925 | In some cases the high level functions do not provide the necessary | 927 | In some cases the high level functions do not provide the necessary |