granicus.if.org Git - esp-idf/blob - components/openssl/OpenSSL-APIs.rst

   1 OpenSSL-APIs
   2 ------------
   3
   4 This directory does not contain OpenSSL itself, but the code here can be used as a wrapper for applications using the OpenSSL API.
   5 It uses mbedTLS to do the actual work, so anyone compiling openssl code needs the mbedtls library and header file.
   6
   7 OpenSSL APIs not mentioned in this article are not open to public for the time,
   8 also do not have the corresponding function.
   9 If user calls it directly, it will always return an error or may show cannot link at compiling time.
  10
  11 Chapter Introduction
  12 ====================
  13
  14 - Chapter 1. SSL Context Method Create
  15 - Chapter 2. SSL Context Fucntion
  16 - Chapter 3. SSL Fucntion
  17 - Chapter 4. SSL X509 Certification and Private Key Function
  18
  19
  20 Chapter 1. SSL Context Method Create
  21 ====================================
  22
  23 1.1 const SSL_METHOD* ``SSLv3_client_method`` (void)
  24
  25     Arguments::
  26
  27         none
  28
  29     Return::
  30
  31         SSLV3.0 version SSL context client method point
  32
  33     Description::
  34
  35         create the target SSL context method
  36
  37     Example::
  38
  39         void example(void)
  40         {
  41             const SSL_METHOD *method = SSLv3_client_method();
  42
  43             ...
  44         }
  45
  46 1.2 const SSL_METHOD* ``TLSv1_client_method`` (void)
  47
  48     Arguments::
  49
  50         none
  51
  52     Return::
  53
  54         TLSV1.0 version SSL context client method point
  55
  56     Description::
  57
  58         create the target SSL context method
  59
  60     Example::
  61
  62         void example(void)
  63         {
  64             const SSL_METHOD *method = TLSv1_client_method();
  65
  66             ...
  67         }
  68
  69 1.3 const SSL_METHOD* ``TLSv1_1_client_method`` (void)
  70
  71     Arguments::
  72
  73         none
  74
  75     Return::
  76
  77         TLSV1.1 version SSL context client method point
  78
  79     Description::
  80
  81         create the target SSL context method
  82
  83     Example::
  84
  85         void example(void)
  86         {
  87             const SSL_METHOD *method = TLSv1_1_client_method();
  88
  89             ...
  90         }
  91
  92 1.4 const SSL_METHOD* ``TLSv1_2_client_method`` (void)
  93
  94     Arguments::
  95
  96        none
  97
  98     Return::
  99
 100        TLSV1.2 version SSL context client method point
 101
 102     Description::
 103
 104        create the target SSL context method
 105
 106     Example::
 107
 108         void example(void)
 109         {
 110             const SSL_METHOD *method = TLSv1_2_client_method();
 111
 112             ...
 113         }
 114
 115 1.5 const SSL_METHOD* ``TLS_client_method`` (void)
 116
 117     Arguments::
 118
 119        none
 120
 121     Return::
 122
 123        TLSV1.2 version SSL context client method point
 124
 125     Description::
 126
 127        create the default SSL context method, it's always to be TLSV1.2
 128
 129     Example::
 130
 131         void example(void)
 132         {
 133             const SSL_METHOD *method = TLSv1_2_client_method();
 134
 135             ...
 136         }
 137
 138 1.6 const SSL_METHOD* ``SSLv3_server_method`` (void)
 139
 140     Arguments::
 141
 142         none
 143
 144     Return::
 145
 146         SSLV3.0 version SSL context server method point
 147
 148     Description::
 149
 150         create the target SSL context method
 151
 152     Example::
 153
 154         void example(void)
 155         {
 156             const SSL_METHOD *method = SSLv3_server_method();
 157
 158             ...
 159         }
 160
 161 1.7 const SSL_METHOD* ``TLSv1_server_method`` (void)
 162
 163     Arguments::
 164
 165         none
 166
 167     Return::
 168
 169         TLSV1.0 version SSL context server method point
 170
 171     Description::
 172
 173         create the target SSL context method
 174
 175     Example::
 176
 177         void example(void)
 178         {
 179             const SSL_METHOD *method = TLSv1_server_method();
 180
 181             ...
 182         }
 183
 184 1.8 const SSL_METHOD* ``TLSv1_1_server_method`` (void)
 185
 186     Arguments::
 187
 188         none
 189
 190     Return::
 191
 192         TLSV1.1 version SSL context server method point
 193
 194     Description::
 195
 196         create the target SSL context method
 197
 198     Example :
 199
 200         void example(void)
 201         {
 202             const SSL_METHOD *method = TLSv1_1_server_method();
 203
 204             ...
 205         }
 206
 207
 208 1.9 const SSL_METHOD* ``TLSv1_2_server_method`` (void)
 209
 210     Arguments::
 211
 212         none
 213
 214     Return::
 215
 216         TLSV1.2 version SSL context server method point
 217
 218     Description::
 219
 220         create the target SSL context method
 221
 222     Example::
 223
 224         void example(void)
 225         {
 226             const SSL_METHOD *method = TLSv1_2_server_method();
 227
 228             ...
 229         }
 230
 231 1.10 const SSL_METHOD* ``TLS_server_method`` (void)
 232
 233     Arguments::
 234
 235         none
 236
 237     Return::
 238
 239         TLSV1.2 version SSL context server method point
 240
 241     Description::
 242
 243         create the default SSL context method, it's always to be TLSV1.2
 244
 245     Example::
 246
 247         void example(void)
 248         {
 249             const SSL_METHOD *method = TLSv1_2_server_method();
 250
 251             ...
 252         }
 253
 254
 255 Chapter 2. SSL Context Fucntion
 256 ===============================
 257
 258
 259 2.1 SSL_CTX* ``SSL_CTX_new`` (const SSL_METHOD *method)
 260
 261     Arguments::
 262
 263         method - the SSL context method point
 264
 265     Return::
 266
 267         context point
 268
 269     Description::
 270
 271         create a SSL context
 272
 273     Example::
 274
 275         void example(void)
 276         {
 277             SSL_CTX *ctx = SSL_CTX_new(SSLv3_server_method());
 278
 279             ...
 280         }
 281
 282
 283 2.2 ``void SSL_CTX_free`` (SSL_CTX *ctx)
 284
 285     Arguments::
 286
 287         ctx - the SSL context point
 288
 289     Return::
 290
 291         none
 292
 293     Description::
 294
 295         free a SSL context
 296
 297     Example::
 298
 299         void example(void)
 300         {
 301             SSL_CTX *ctx;
 302
 303             ... ...
 304
 305             SSL_CTX_free(ctx);
 306         }
 307
 308
 309 2.3 ``int SSL_CTX_set_ssl_version`` (SSL_CTX *ctx, const SSL_METHOD *meth)
 310
 311     Arguments::
 312
 313         ctx  - SSL context point
 314         meth - SSL method point
 315
 316     Return::
 317
 318         1 : OK
 319         0 : failed
 320
 321     Description::
 322
 323         set the SSL context version
 324
 325     Example::
 326
 327         void example(void)
 328         {
 329             SSL_CTX *ctx;
 330             const SSL_METHOD *meth;
 331
 332             ... ...
 333
 334             SSL_CTX_set_ssl_version(ctx, meth);
 335         }
 336
 337
 338 2.4 const SSL_METHOD* ``SSL_CTX_get_ssl_method`` (SSL_CTX *ctx)
 339
 340     Arguments::
 341
 342         ctx - SSL context point
 343
 344     Return::
 345
 346         SSL context method
 347
 348     Description::
 349
 350         get the SSL context method
 351
 352     Example::
 353
 354         void example(void)
 355         {
 356             const SSL_METHOD *method;
 357             SSL_CTX *ctx;
 358
 359             ... ...
 360
 361             method = SSL_CTX_get_ssl_method(ctx);
 362         }
 363
 364
 365
 366 Chapter 3. SSL Fucntion
 367 =======================
 368
 369
 370 3.1 SSL* ``SSL_new`` (SSL_CTX *ctx)
 371
 372     Arguments::
 373
 374         ctx - SSL context point
 375
 376     Return::
 377
 378         SSL method
 379
 380     Description::
 381
 382         create a SSL
 383
 384     Example::
 385
 386         void example(void)
 387         {
 388             SSL *ssl;
 389             SSL_CTX *ctx;
 390
 391             ... ...
 392
 393             ssl = SSL_new(ctx);
 394         }
 395
 396
 397 3.2 void ``SSL_free`` (SSL *ssl)
 398
 399     Arguments::
 400
 401         ssl - SSL point
 402
 403     Return::
 404
 405         none
 406
 407     Description::
 408
 409         free SSL
 410
 411     Example::
 412
 413         void example(void)
 414         {
 415             SSL *ssl;
 416
 417             ... ...
 418
 419             SSL_free(ssl);
 420         }
 421
 422
 423 3.3 int ``SSL_do_handshake`` (SSL *ssl)
 424
 425     Arguments::
 426
 427         ssl - SSL point
 428
 429     Return::
 430
 431         1 : OK
 432         0 : failed, connect is close by remote
 433        -1 : a error catch
 434
 435     Description::
 436
 437         perform the SSL handshake
 438
 439     Example::
 440
 441         void example(void)
 442         {
 443             SSL *ssl;
 444             int ret;
 445
 446             ... ...
 447
 448             ret = SSL_do_handshake(ssl);
 449         }
 450
 451
 452 3.4 int ``SSL_connect`` (SSL *ssl)
 453
 454     Arguments::
 455
 456         ssl - SSL point
 457
 458     Return::
 459
 460         1 : OK
 461         0 : failed, connect is close by remote
 462        -1 : a error catch
 463
 464     Description::
 465
 466         connect to the remote SSL server
 467
 468     Example::
 469
 470         void example(void)
 471         {
 472             SSL *ssl;
 473             int ret;
 474
 475             ... ...
 476
 477             ret = SSL_connect(ssl);
 478         }
 479
 480
 481 3.5 int ``SSL_accept`` (SSL *ssl)
 482
 483     Arguments::
 484
 485         ssl - SSL point
 486
 487     Return::
 488
 489         1 : OK
 490         0 : failed, connect is close by remote
 491        -1 : a error catch
 492
 493     Description::
 494
 495         accept the remote connection
 496
 497     Example::
 498
 499         void example(void)
 500         {
 501             SSL *ssl;
 502             int ret;
 503
 504             ... ...
 505
 506             ret = SSL_accept(ssl);
 507         }
 508
 509
 510 3.6 int ``SSL_shutdown`` (SSL *ssl)
 511
 512     Arguments::
 513
 514         ssl - SSL point
 515
 516     Return::
 517
 518         1 : OK
 519         0 : failed, connect is close by remote
 520        -1 : a error catch
 521
 522     Description::
 523
 524         shutdown the connection
 525
 526     Example::
 527
 528         void example(void)
 529         {
 530             SSL *ssl;
 531             int ret;
 532
 533             ... ...
 534
 535             ret = SSL_shutdown(ssl);
 536         }
 537
 538
 539 3.7 int ``SSL_clear`` (SSL *ssl)
 540
 541     Arguments::
 542
 543         ssl - SSL point
 544
 545     Return::
 546
 547         1 : OK
 548         0 : failed
 549
 550     Description::
 551
 552         shutdown the connection
 553
 554     Example::
 555
 556         void example(void)
 557         {
 558             SSL *ssl;
 559             int ret;
 560
 561             ... ...
 562
 563             ret = SSL_clear(ssl);
 564         }
 565
 566
 567 3.8 int ``SSL_read`` (SSL *ssl, void *buffer, int len)
 568
 569     Arguments::
 570
 571         ssl    - point
 572         buffer - data buffer point
 573         len    - data length
 574
 575     Return::
 576
 577         > 0 : OK, and return received data bytes
 578         = 0 : no data received or connection is closed
 579         < 0 : an error catch
 580
 581     Description::
 582
 583         read data from remote
 584
 585     Example::
 586
 587         void example(void)
 588         {
 589             SSL *ssl;
 590             char *buf;
 591             int len;
 592             int ret;
 593
 594             ... ...
 595
 596             ret = SSL_read(ssl, buf, len);
 597         }
 598
 599 3.9 int ``SSL_write`` (SSL *ssl, const void *buffer, int len)
 600
 601     Arguments::
 602
 603         ssl    - SSL point
 604         buffer - data buffer point
 605         len    - data length
 606
 607     Return::
 608
 609         > 0 : OK, and return received data bytes
 610         = 0 : no data sent or connection is closed
 611         < 0 : an error catch
 612
 613     Description::
 614
 615         send the data to remote
 616
 617     Example::
 618
 619         void example(void)
 620         {
 621             SSL *ssl;
 622             char *buf;
 623             int len;
 624             int ret;
 625
 626             ... ...
 627
 628             ret = SSL_write(ssl, buf, len);
 629         }
 630
 631
 632 3.10 ``SSL_CTX *SSL_get_SSL_CTX`` (const SSL *ssl)
 633
 634     Arguments::
 635
 636         ssl - SSL point
 637
 638     Return::
 639
 640         SSL context
 641
 642     Description::
 643
 644         get SSL context of the SSL
 645
 646     Example::
 647
 648         void example(void)
 649         {
 650             SSL *ssl;
 651             SSL_CTX *ctx;
 652
 653             ... ...
 654
 655             ctx = SSL_get_SSL_CTX(ssl);
 656         }
 657
 658
 659 3.11 int ``SSL_get_shutdown`` (const SSL *ssl)
 660
 661     Arguments::
 662
 663         ssl - SSL point
 664
 665     Return::
 666
 667         shutdown mode
 668
 669     Description::
 670
 671         get SSL shutdown mode
 672
 673     Example::
 674
 675         void example(void)
 676         {
 677             SSL *ssl;
 678             int mode;
 679
 680             ... ...
 681
 682             mode = SSL_get_SSL_CTX(ssl);
 683         }
 684
 685
 686 3.12 void ``SSL_set_shutdown`` (SSL *ssl, int mode)
 687
 688     Arguments::
 689
 690         ssl - SSL point
 691
 692     Return::
 693
 694         shutdown mode
 695
 696     Description::
 697
 698         set SSL shutdown mode
 699
 700     Example::
 701
 702         void example(void)
 703         {
 704             SSL *ssl;
 705             int mode = 0;
 706
 707             ... ...
 708
 709             SSL_set_shutdown(ssl, mode);
 710         }
 711
 712
 713 3.13 const SSL_METHOD* ``SSL_get_ssl_method`` (SSL *ssl)
 714
 715     Arguments::
 716
 717         ssl - SSL point
 718
 719     Return::
 720
 721         SSL method
 722
 723     Description::
 724
 725         set SSL shutdown mode
 726
 727     Example::
 728
 729         void example(void)
 730         {
 731             SSL *ssl;
 732             const SSL_METHOD *method;
 733
 734             ... ...
 735
 736             method = SSL_get_ssl_method(ssl);
 737         }
 738
 739
 740 3.14 int ``SSL_set_ssl_method`` (SSL *ssl, const SSL_METHOD *method)
 741
 742     Arguments::
 743
 744         ssl  - SSL point
 745         meth - SSL method point
 746
 747     Return::
 748
 749         1 : OK
 750         0 : failed
 751
 752     Description::
 753
 754         set the SSL method
 755
 756     Example::
 757
 758         void example(void)
 759         {
 760             int ret;
 761             SSL *ssl;
 762             const SSL_METHOD *method;
 763
 764             ... ...
 765
 766             ret = SSL_set_ssl_method(ssl, method);
 767         }
 768
 769
 770 3.15 int ``SSL_pending`` (const SSL *ssl)
 771
 772     Arguments::
 773
 774         ssl - SSL point
 775
 776     Return::
 777
 778         data bytes
 779
 780     Description::
 781
 782         get received data bytes
 783
 784     Example::
 785
 786         void example(void)
 787         {
 788             int ret;
 789             SSL *ssl;
 790
 791             ... ...
 792
 793             ret = SSL_pending(ssl);
 794         }
 795
 796
 797 3.16 int ``SSL_has_pending`` (const SSL *ssl)
 798
 799     Arguments::
 800
 801         ssl - SSL point
 802
 803     Return::
 804
 805         1 : Yes
 806         0 : No
 807
 808     Description::
 809
 810         check if data is received
 811
 812     Example::
 813
 814         void example(void)
 815         {
 816             int ret;
 817             SSL *ssl;
 818
 819             ... ...
 820
 821             ret = SSL_has_pending(ssl);
 822         }
 823
 824
 825 3.17 int ``SSL_get_fd`` (const SSL *ssl)
 826
 827     Arguments::
 828
 829         ssl - SSL point
 830
 831     Return::
 832
 833         >= 0 : socket id
 834          < 0 : a error catch
 835
 836     Description::
 837
 838         get the socket of the SSL
 839
 840     Example::
 841
 842         void example(void)
 843         {
 844             int ret;
 845             SSL *ssl;
 846
 847             ... ...
 848
 849             ret = SSL_get_fd(ssl);
 850         }
 851
 852
 853 3.18 int ``SSL_get_rfd`` (const SSL *ssl)
 854
 855     Arguments::
 856
 857         ssl - SSL point
 858
 859     Return::
 860
 861         >= 0 : socket id
 862          < 0 : a error catch
 863
 864     Description::
 865
 866         get the read only socket of the SSL
 867
 868     Example::
 869
 870         void example(void)
 871         {
 872             int ret;
 873             SSL *ssl;
 874
 875             ... ...
 876
 877             ret = SSL_get_rfd(ssl);
 878         }
 879
 880
 881 3.19 int ``SSL_get_wfd`` (const SSL *ssl)
 882
 883     Arguments::
 884
 885         ssl - SSL point
 886
 887     Return::
 888
 889         >= 0 : socket id
 890          < 0 : a error catch
 891
 892     Description::
 893
 894         get the write only socket of the SSL
 895
 896     Example::
 897
 898         void example(void)
 899         {
 900             int ret;
 901             SSL *ssl;
 902
 903             ... ...
 904
 905             ret = SSL_get_wfd(ssl);
 906         }
 907
 908
 909 3.20 int ``SSL_set_fd`` (SSL *ssl, int fd)
 910
 911     Arguments::
 912
 913         ssl - SSL point
 914         fd  - socket id
 915
 916     Return::
 917
 918         1 : OK
 919         0 : failed
 920
 921     Description::
 922
 923         set socket to SSL
 924
 925     Example::
 926
 927         void example(void)
 928         {
 929             int ret;
 930             SSL *ssl;
 931             int socket;
 932
 933             ... ...
 934
 935             ret = SSL_set_fd(ssl, socket);
 936         }
 937
 938
 939 3.21 int ``SSL_set_rfd`` (SSL *ssl, int fd)
 940
 941     Arguments::
 942
 943         ssl - SSL point
 944         fd  - socket id
 945
 946     Return::
 947
 948         1 : OK
 949         0 : failed
 950
 951     Description::
 952
 953         set read only socket to SSL
 954
 955     Example::
 956
 957         void example(void)
 958         {
 959             int ret;
 960             SSL *ssl;
 961             int socket;
 962
 963             ... ...
 964
 965             ret = SSL_set_rfd(ssl, socket);
 966         }
 967
 968
 969 3.22 int ``SSL_set_wfd`` (SSL *ssl, int fd)
 970
 971     Arguments::
 972
 973         ssl - SSL point
 974         fd  - socket id
 975
 976     Return::
 977
 978         1 : OK
 979         0 : failed
 980
 981     Description::
 982
 983         set write only socket to SSL
 984
 985     Example::
 986
 987         void example(void)
 988         {
 989             int ret;
 990             SSL *ssl;
 991             int socket;
 992
 993             ... ...
 994
 995             ret = SSL_set_wfd(ssl, socket);
 996         }
 997
 998
 999 3.23 int ``SSL_version`` (const SSL *ssl)
1000
1001     Arguments::
1002
1003         ssl - SSL point
1004
1005     Return::
1006
1007         SSL version
1008
1009     Description::
1010
1011         get SSL version
1012
1013     Example::
1014
1015         void example(void)
1016         {
1017             int version;
1018             SSL *ssl;
1019
1020             ... ...
1021
1022             version = SSL_version(ssl);
1023         }
1024
1025
1026 3.24 const char* ``SSL_get_version`` (const SSL *ssl)
1027
1028     Arguments::
1029
1030         ssl - SSL point
1031
1032     Return::
1033
1034         SSL version string
1035
1036     Description::
1037
1038         get the SSL current version string
1039
1040     Example::
1041
1042         void example(void)
1043         {
1044             char *version;
1045             SSL *ssl;
1046
1047             ... ...
1048
1049             version = SSL_get_version(ssl);
1050         }
1051
1052
1053 3.25 OSSL_HANDSHAKE_STATE ``SSL_get_state`` (const SSL *ssl)
1054
1055     Arguments::
1056
1057         ssl - SSL point
1058
1059     Return::
1060
1061         SSL state
1062
1063     Description::
1064
1065         get the SSL state
1066
1067     Example::
1068
1069         void example(void)
1070         {
1071             OSSL_HANDSHAKE_STATE state;
1072             SSL *ssl;
1073
1074             ... ...
1075
1076             state = SSL_get_state(ssl);
1077         }
1078
1079
1080 3.26 const char* ``SSL_alert_desc_string`` (int value)
1081
1082     Arguments::
1083
1084         value - SSL description
1085
1086     Return::
1087
1088         alert value string
1089
1090     Description::
1091
1092         get alert description string
1093
1094     Example::
1095
1096         void example(void)
1097         {
1098             int val;
1099             char *str;
1100
1101             ... ...
1102
1103             str = SSL_alert_desc_string(val);
1104         }
1105
1106
1107 3.27 const char* ``SSL_alert_desc_string_long`` (int value)
1108
1109     Arguments::
1110
1111         value - SSL description
1112
1113     Return::
1114
1115         alert value long string
1116
1117     Description::
1118
1119         get alert description long string
1120
1121     Example::
1122
1123         void example(void)
1124         {
1125             int val;
1126             char *str;
1127
1128             ... ...
1129
1130             str = SSL_alert_desc_string_long(val);
1131         }
1132
1133
1134 3.28 const char* ``SSL_alert_type_string`` (int value)
1135
1136     Arguments::
1137
1138         value - SSL type description
1139
1140     Return::
1141
1142         alert type string
1143
1144     Description::
1145
1146         get alert type string
1147
1148     Example::
1149
1150         void example(void)
1151         {
1152             int val;
1153             char *str;
1154
1155             ... ...
1156
1157             str = SSL_alert_type_string(val);
1158         }
1159
1160
1161 3.29 const char* ``SSL_alert_type_string_long`` (int value)
1162
1163     Arguments::
1164
1165         value - SSL type description
1166
1167     Return::
1168
1169         alert type long string
1170
1171     Description::
1172
1173         get alert type long string
1174
1175     Example::
1176
1177         void example(void)
1178         {
1179             int val;
1180             char *str;
1181
1182             ... ...
1183
1184             str = SSL_alert_type_string_long(val);
1185         }
1186
1187 3.30 const char* ``SSL_rstate_string`` (SSL *ssl)
1188
1189     Arguments::
1190
1191         ssl - SSL point
1192
1193     Return::
1194
1195         state string
1196
1197     Description::
1198
1199         get the state string where SSL is reading
1200
1201     Example::
1202
1203         void example(void)
1204         {
1205             SSL *ssl;
1206             char *str;
1207
1208             ... ...
1209
1210             str = SSL_rstate_string(ssl);
1211         }
1212
1213
1214 3.31 const char* ``SSL_rstate_string_long`` (SSL *ssl)
1215
1216     Arguments::
1217
1218         ssl - SSL point
1219
1220     Return::
1221
1222         state long string
1223
1224     Description::
1225
1226         get the state long string where SSL is reading
1227
1228     Example::
1229
1230         void example(void)
1231         {
1232             SSL *ssl;
1233             char *str;
1234
1235             ... ...
1236
1237             str = SSL_rstate_string_long(ssl);
1238         }
1239
1240
1241 3.32 const char* ``SSL_state_string`` (const SSL *ssl)
1242
1243     Arguments::
1244
1245         ssl - SSL point
1246
1247     Return::
1248
1249         state string
1250
1251     Description::
1252
1253         get the state string
1254
1255     Example::
1256
1257         void example(void)
1258         {
1259             SSL *ssl;
1260             const char *str;
1261
1262             ... ...
1263
1264             str = SSL_state_string(ssl);
1265         }
1266
1267
1268 3.33 char* ``SSL_state_string_long`` (const SSL *ssl)
1269
1270     Arguments::
1271
1272         ssl - SSL point
1273
1274     Return::
1275
1276         state long string
1277
1278     Description::
1279
1280         get the state long string
1281
1282     Example::
1283
1284         void example(void)
1285         {
1286             SSL *ssl;
1287             char *str;
1288
1289             ... ...
1290
1291             str = SSL_state_string(ssl);
1292         }
1293
1294
1295 3.34 int ``SSL_get_error`` (const SSL *ssl, int ret_code)
1296
1297     Arguments::
1298
1299         ssl      - SSL point
1300         ret_code - SSL return code
1301
1302     Return::
1303
1304         SSL error number
1305
1306     Description::
1307
1308         get SSL error code
1309
1310     Example::
1311
1312         void example(void)
1313         {
1314             SSL *ssl;
1315             int ret;
1316             int err;
1317
1318             ... ...
1319
1320             err = SSL_get_error(ssl, ret);
1321         }
1322
1323 3.35 int ``SSL_want`` (const SSL *ssl)
1324
1325     Arguments::
1326
1327         ssl - SSL point
1328
1329     Return::
1330
1331         specifical statement
1332
1333     Description::
1334
1335         get the SSL specifical statement
1336
1337     Example::
1338
1339         void example(void)
1340         {
1341             SSL *ssl;
1342             int state;
1343
1344             ... ...
1345
1346             state = SSL_want(ssl);
1347         }
1348
1349
1350 3.36 int ``SSL_want_nothing`` (const SSL *ssl)
1351
1352     Arguments::
1353
1354         ssl - SSL point
1355
1356     Return::
1357
1358         0 : false
1359         1 : true
1360
1361     Description::
1362
1363         check if SSL want nothing
1364
1365     Example::
1366
1367         void example(void)
1368         {
1369             SSL *ssl;
1370             int ret;
1371
1372             ... ...
1373
1374             ret = SSL_want(ssl);
1375         }
1376
1377
1378 3.37 int ``SSL_want_read`` (const SSL *ssl)
1379
1380     Arguments::
1381
1382         ssl - SSL point
1383
1384     Return::
1385
1386         0 : false
1387         1 : true
1388
1389     Description::
1390
1391         check if SSL want to read
1392
1393     Example::
1394
1395         void example(void)
1396         {
1397             SSL *ssl;
1398             int ret;
1399
1400             ... ...
1401
1402             ret = SSL_want_read(ssl);
1403         }
1404
1405
1406 3.38 int ``SSL_want_write`` (const SSL *ssl)
1407
1408     Arguments::
1409
1410         ssl - SSL point
1411
1412     Return::
1413
1414         0 : false
1415         1 : true
1416
1417     Description::
1418
1419         check if SSL want to write
1420
1421     Example::
1422
1423         void example(void)
1424         {
1425             SSL *ssl;
1426             int ret;
1427
1428             ... ...
1429
1430             ret = SSL_want_write(ssl);
1431         }
1432
1433
1434 Chapter 4. SSL X509 Certification and Private Key Function
1435 ==========================================================
1436
1437
1438 4.1 X509* ``d2i_X509`` (X509 **cert, const unsigned char *buffer, long len)
1439
1440     Arguments::
1441
1442         cert   - a point pointed to X509 certification
1443         buffer - a point pointed to the certification context memory point
1444         length - certification bytes
1445
1446     Return::
1447
1448         X509 certification object point
1449
1450     Description::
1451
1452         load a character certification context into system context. If '*cert' is pointed to the
1453         certification, then load certification into it. Or create a new X509 certification object
1454
1455     Example::
1456
1457         void example(void)
1458         {
1459             X509 *new;
1460             X509 *cert;
1461             unsigned char *buffer;
1462             long len;
1463             ... ...
1464
1465             new = d2i_X509(&cert, buffer, len);
1466         }
1467
1468
1469 4.2 int ``SSL_add_client_CA`` (SSL *ssl, X509 *x)
1470
1471     Arguments::
1472
1473         ssl - SSL point
1474         x   - CA certification point
1475
1476     Return::
1477
1478         1 : OK
1479         0 : failed
1480
1481     Description::
1482
1483         add CA client certification into the SSL
1484
1485     Example::
1486
1487         void example(void)
1488         {
1489             int ret;
1490             SSL *ssl;
1491             X509 *new;
1492
1493             ... ...
1494
1495             ret = SSL_add_client_CA(ssl, new);
1496         }
1497
1498
1499 4.3 int ``SSL_CTX_add_client_CA`` (SSL_CTX *ctx, X509 *x)
1500
1501     Arguments::
1502
1503         ctx - SSL context point
1504          x   - CA certification point
1505
1506     Return::
1507
1508         1 : OK
1509         0 : failed
1510
1511     Description::
1512
1513         add CA client certification into the SSL context
1514
1515     Example::
1516
1517         void example(void)
1518         {
1519             int ret;
1520             SSL_CTX *ctx;
1521             X509 *new;
1522
1523             ... ...
1524
1525             ret = SSL_add_clSSL_CTX_add_client_CAient_CA(ctx, new);
1526         }
1527
1528
1529 4.4 X509* ``SSL_get_certificate`` (const SSL *ssl)
1530
1531     Arguments::
1532
1533         ssl - SSL point
1534
1535     Return::
1536
1537         SSL certification point
1538
1539     Description::
1540
1541         get the SSL certification point
1542
1543     Example::
1544
1545         void example(void)
1546         {
1547             SSL *ssl;
1548             X509 *cert;
1549
1550             ... ...
1551
1552             cert = SSL_get_certificate(ssl);
1553         }
1554
1555
1556 4.5 long ``SSL_get_verify_result`` (const SSL *ssl)
1557
1558     Arguments::
1559
1560         ssl - SSL point
1561
1562     Return::
1563
1564         the result of verifying
1565
1566     Description::
1567
1568         get the verifying result of the SSL certification
1569
1570     Example::
1571
1572         void example(void)
1573         {
1574             SSL *ssl;
1575             long ret;
1576
1577             ... ...
1578
1579             ret = SSL_get_verify_result(ssl);
1580         }
1581
1582
1583 4.6 int ``SSL_CTX_use_certificate`` (SSL_CTX *ctx, X509 *x)
1584
1585     Arguments::
1586
1587         ctx  - the SSL context point
1588         pkey - certification object point
1589
1590     Return::
1591
1592         1 : OK
1593         0 : failed
1594
1595     Description::
1596
1597         load the certification into the SSL_CTX or SSL object
1598
1599     Example::
1600
1601         void example(void)
1602         {
1603             int ret;
1604             SSL_CTX *ctx
1605             X509 *new;
1606
1607             ... ...
1608
1609             ret = SSL_CTX_use_certificate(ctx, new);
1610         }
1611
1612
1613 4.7 int ``SSL_CTX_use_certificate_ASN1`` (SSL_CTX *ctx, int len, const unsigned char *d)
1614
1615     Arguments::
1616
1617         ctx - SSL context point
1618         len - certification length
1619         d   - data point
1620
1621     Return::
1622
1623         1 : OK
1624         0 : failed
1625
1626     Description::
1627
1628         load the ASN1 certification into SSL context
1629
1630     Example::
1631
1632         void example(void)
1633         {
1634             int ret;
1635             SSL_CTX *ctx;
1636             const unsigned char *buf;
1637             int len;
1638
1639             ... ...
1640
1641             ret = SSL_CTX_use_certificate_ASN1(ctx, len, buf);
1642         }
1643
1644
1645 4.8 int ``SSL_CTX_use_PrivateKey`` (SSL_CTX *ctx, EVP_PKEY *pkey)
1646
1647     Arguments::
1648
1649         ctx - SSL context point
1650         pkey - private key object point
1651
1652     Return::
1653
1654         1 : OK
1655         0 : failed
1656
1657     Description::
1658
1659         load the private key into the context object
1660
1661     Example::
1662
1663         void example(void)
1664         {
1665             int ret;
1666             SSL_CTX *ctx;
1667             EVP_PKEY *pkey;
1668
1669             ... ...
1670
1671             ret = SSL_CTX_use_PrivateKey(ctx, pkey);
1672         }
1673
1674
1675 4.9 int ``SSL_CTX_use_PrivateKey_ASN1`` (int pk, SSL_CTX *ctx, const unsigned char *d,  long len)
1676
1677     Arguments::
1678
1679         ctx - SSL context point
1680         d   - data point
1681         len - private key length
1682
1683     Return::
1684
1685         1 : OK
1686         0 : failed
1687
1688     Description::
1689
1690         load the ASN1 private key into SSL context
1691
1692     Example::
1693
1694         void example(void)
1695         {
1696             int ret;
1697             int pk;
1698             SSL_CTX *ctx;
1699             const unsigned char *buf;
1700             long len;
1701
1702             ... ...
1703
1704             ret = SSL_CTX_use_PrivateKey_ASN1(pk, ctx, buf, len);
1705         }
1706
1707
1708 4.10 int ``SSL_CTX_use_RSAPrivateKey_ASN1`` (SSL_CTX *ctx, const unsigned char *d, long len)
1709
1710     Arguments::
1711
1712         ctx - SSL context point
1713         d   - data point
1714         len - private key length
1715
1716     Return::
1717
1718         1 : OK
1719         0 : failed
1720
1721     Description::
1722
1723         load the RSA ASN1 private key into SSL context
1724
1725     Example::
1726
1727         void example(void)
1728         {
1729             int ret;
1730             SSL_CTX *ctx;
1731             const unsigned char *buf;
1732             long len;
1733
1734             ... ...
1735
1736             ret = SSL_CTX_use_RSAPrivateKey_ASN1(ctx, buf, len);
1737         }
1738
1739
1740 4.11 int ``SSL_use_certificate_ASN1`` (SSL *ssl, int len, const unsigned char *d)
1741
1742     Arguments::
1743
1744         ssl - SSL point
1745         len - data bytes
1746         d   - data point
1747
1748     Return::
1749
1750         1 : OK
1751         0 : failed
1752
1753     Description::
1754
1755         load certification into the SSL
1756
1757     Example::
1758
1759         void example(void)
1760         {
1761             int ret;
1762             SSL *ssl;
1763             const unsigned char *buf;
1764             long len;
1765
1766             ... ...
1767
1768             ret = SSL_use_certificate_ASN1(ssl, len, buf);
1769         }
1770
1771
1772 4.12 X509* ``SSL_get_peer_certificate`` (const SSL *ssl)
1773
1774     Arguments::
1775
1776         ssl - SSL point
1777
1778     Return::
1779
1780         peer certification
1781
1782     Description::
1783
1784         get peer certification
1785
1786     Example::
1787
1788         void example(void)
1789         {
1790             SSL *ssl;
1791             X509 *peer;
1792
1793             ... ...
1794
1795             peer = SSL_get_peer_certificate(ssl);
1796         }
1797