summaryrefslogtreecommitdiff
path: root/lib/libcrypto/doc
diff options
context:
space:
mode:
authorMiod Vallat <miod@cvs.openbsd.org>2014-07-10 14:14:05 +0000
committerMiod Vallat <miod@cvs.openbsd.org>2014-07-10 14:14:05 +0000
commitefc82083b9e3f96fa8ba9844c0350219d046dfea (patch)
tree00b01f6d09a1aa7c26711d1f978b2332428c7e31 /lib/libcrypto/doc
parent976eedf2eb3dba06d2b6a3a84881acedabf9e02f (diff)
Try and fix the horrible coding style of the example code snippets.
Diffstat (limited to 'lib/libcrypto/doc')
-rw-r--r--lib/libcrypto/doc/EVP_DigestInit.pod63
-rw-r--r--lib/libcrypto/doc/EVP_EncryptInit.pod64
-rw-r--r--lib/libcrypto/doc/EVP_PKEY_keygen.pod22
-rw-r--r--lib/libcrypto/doc/PEM_read_bio_PrivateKey.pod56
-rw-r--r--lib/libcrypto/doc/X509_NAME_get_index_by_NID.pod10
-rw-r--r--lib/libcrypto/doc/X509_STORE_CTX_set_verify_cb.pod76
-rw-r--r--lib/libcrypto/doc/engine.pod88
7 files changed, 201 insertions, 178 deletions
diff --git a/lib/libcrypto/doc/EVP_DigestInit.pod b/lib/libcrypto/doc/EVP_DigestInit.pod
index 2ff01b9c7c8..f2c1cfdbf00 100644
--- a/lib/libcrypto/doc/EVP_DigestInit.pod
+++ b/lib/libcrypto/doc/EVP_DigestInit.pod
@@ -215,39 +215,40 @@ digest name passed on the command line.
#include <stdio.h>
#include <openssl/evp.h>
+ int
main(int argc, char *argv[])
{
- EVP_MD_CTX *mdctx;
- const EVP_MD *md;
- char mess1[] = "Test Message\n";
- char mess2[] = "Hello World\n";
- unsigned char md_value[EVP_MAX_MD_SIZE];
- int md_len, i;
-
- OpenSSL_add_all_digests();
-
- if(!argv[1]) {
- printf("Usage: mdtest digestname\n");
- exit(1);
- }
-
- md = EVP_get_digestbyname(argv[1]);
-
- if(!md) {
- printf("Unknown message digest %s\n", argv[1]);
- exit(1);
- }
-
- mdctx = EVP_MD_CTX_create();
- EVP_DigestInit_ex(mdctx, md, NULL);
- EVP_DigestUpdate(mdctx, mess1, strlen(mess1));
- EVP_DigestUpdate(mdctx, mess2, strlen(mess2));
- EVP_DigestFinal_ex(mdctx, md_value, &md_len);
- EVP_MD_CTX_destroy(mdctx);
-
- printf("Digest is: ");
- for(i = 0; i < md_len; i++) printf("%02x", md_value[i]);
- printf("\n");
+ EVP_MD_CTX *mdctx;
+ const EVP_MD *md;
+ const char mess1[] = "Test Message\n";
+ const char mess2[] = "Hello World\n";
+ unsigned char md_value[EVP_MAX_MD_SIZE];
+ int md_len, i;
+
+ OpenSSL_add_all_digests();
+
+ if (argc <= 1) {
+ printf("Usage: mdtest digestname\n");
+ exit(1);
+ }
+
+ md = EVP_get_digestbyname(argv[1]);
+ if (md == NULL) {
+ printf("Unknown message digest %s\n", argv[1]);
+ exit(1);
+ }
+
+ mdctx = EVP_MD_CTX_create();
+ EVP_DigestInit_ex(mdctx, md, NULL);
+ EVP_DigestUpdate(mdctx, mess1, strlen(mess1));
+ EVP_DigestUpdate(mdctx, mess2, strlen(mess2));
+ EVP_DigestFinal_ex(mdctx, md_value, &md_len);
+ EVP_MD_CTX_destroy(mdctx);
+
+ printf("Digest is: ");
+ for(i = 0; i < md_len; i++)
+ printf("%02x", md_value[i]);
+ printf("\n");
}
=head1 SEE ALSO
diff --git a/lib/libcrypto/doc/EVP_EncryptInit.pod b/lib/libcrypto/doc/EVP_EncryptInit.pod
index a876ac789cf..b2211ea6d34 100644
--- a/lib/libcrypto/doc/EVP_EncryptInit.pod
+++ b/lib/libcrypto/doc/EVP_EncryptInit.pod
@@ -427,46 +427,49 @@ Set the effective key length used in RC2:
Encrypt a string using blowfish:
- int do_crypt(char *outfile)
- {
+ int
+ do_crypt(char *outfile)
+ {
unsigned char outbuf[1024];
int outlen, tmplen;
- /* Bogus key and IV: we'd normally set these from
+ /*
+ * Bogus key and IV: we'd normally set these from
* another source.
*/
unsigned char key[] = {0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15};
unsigned char iv[] = {1,2,3,4,5,6,7,8};
- char intext[] = "Some Crypto Text";
+ const char intext[] = "Some Crypto Text";
EVP_CIPHER_CTX ctx;
FILE *out;
EVP_CIPHER_CTX_init(&ctx);
EVP_EncryptInit_ex(&ctx, EVP_bf_cbc(), NULL, key, iv);
- if(!EVP_EncryptUpdate(&ctx, outbuf, &outlen, intext, strlen(intext)))
- {
+ if (!EVP_EncryptUpdate(&ctx, outbuf, &outlen, intext,
+ strlen(intext))) {
/* Error */
return 0;
- }
- /* Buffer passed to EVP_EncryptFinal() must be after data just
+ }
+ /*
+ * Buffer passed to EVP_EncryptFinal() must be after data just
* encrypted to avoid overwriting it.
*/
- if(!EVP_EncryptFinal_ex(&ctx, outbuf + outlen, &tmplen))
- {
+ if (!EVP_EncryptFinal_ex(&ctx, outbuf + outlen, &tmplen)) {
/* Error */
return 0;
- }
+ }
outlen += tmplen;
EVP_CIPHER_CTX_cleanup(&ctx);
- /* Need binary mode for fopen because encrypted data is
+ /*
+ * Need binary mode for fopen because encrypted data is
* binary data. Also cannot use strlen() on it because
- * it wont be null terminated and may contain embedded
- * nulls.
+ * it won't be NUL terminated and may contain embedded
+ * NULs.
*/
out = fopen(outfile, "wb");
fwrite(outbuf, 1, outlen, out);
fclose(out);
return 1;
- }
+ }
The ciphertext from the above example can be decrypted using the B<openssl>
utility with the command line:
@@ -476,16 +479,19 @@ utility with the command line:
General encryption, decryption function example using FILE I/O and RC2 with an
80 bit key:
- int do_crypt(FILE *in, FILE *out, int do_encrypt)
- {
+ int
+ do_crypt(FILE *in, FILE *out, int do_encrypt)
+ {
/* Allow enough space in output buffer for additional block */
inbuf[1024], outbuf[1024 + EVP_MAX_BLOCK_LENGTH];
int inlen, outlen;
- /* Bogus key and IV: we'd normally set these from
+ /*
+ * Bogus key and IV: we'd normally set these from
* another source.
*/
unsigned char key[] = "0123456789";
unsigned char iv[] = "12345678";
+
/* Don't set key or IV because we will modify the parameters */
EVP_CIPHER_CTX_init(&ctx);
EVP_CipherInit_ex(&ctx, EVP_rc2(), NULL, NULL, NULL, do_encrypt);
@@ -493,30 +499,28 @@ General encryption, decryption function example using FILE I/O and RC2 with an
/* We finished modifying parameters so now we can set key and IV */
EVP_CipherInit_ex(&ctx, NULL, NULL, key, iv, do_encrypt);
- for(;;)
- {
+ for(;;) {
inlen = fread(inbuf, 1, 1024, in);
- if(inlen <= 0) break;
- if(!EVP_CipherUpdate(&ctx, outbuf, &outlen, inbuf, inlen))
- {
+ if (inlen <= 0)
+ break;
+ if (!EVP_CipherUpdate(&ctx, outbuf, &outlen, inbuf,
+ inlen)) {
/* Error */
EVP_CIPHER_CTX_cleanup(&ctx);
return 0;
- }
- fwrite(outbuf, 1, outlen, out);
}
- if(!EVP_CipherFinal_ex(&ctx, outbuf, &outlen))
- {
+ fwrite(outbuf, 1, outlen, out);
+ }
+ if (!EVP_CipherFinal_ex(&ctx, outbuf, &outlen)) {
/* Error */
EVP_CIPHER_CTX_cleanup(&ctx);
return 0;
- }
+ }
fwrite(outbuf, 1, outlen, out);
EVP_CIPHER_CTX_cleanup(&ctx);
return 1;
- }
-
+ }
=head1 SEE ALSO
diff --git a/lib/libcrypto/doc/EVP_PKEY_keygen.pod b/lib/libcrypto/doc/EVP_PKEY_keygen.pod
index 378fb310ffd..05ea04be11f 100644
--- a/lib/libcrypto/doc/EVP_PKEY_keygen.pod
+++ b/lib/libcrypto/doc/EVP_PKEY_keygen.pod
@@ -132,20 +132,26 @@ Example of generation callback for OpenSSL public key implementations:
EVP_PKEY_CTX_set_app_data(ctx, status_bio);
- static int genpkey_cb(EVP_PKEY_CTX *ctx)
- {
- char c='*';
+ static int
+ genpkey_cb(EVP_PKEY_CTX *ctx)
+ {
+ char c = '*';
BIO *b = EVP_PKEY_CTX_get_app_data(ctx);
int p;
+
p = EVP_PKEY_CTX_get_keygen_info(ctx, 0);
- if (p == 0) c='.';
- if (p == 1) c='+';
- if (p == 2) c='*';
- if (p == 3) c='\n';
+ if (p == 0)
+ c='.';
+ if (p == 1)
+ c='+';
+ if (p == 2)
+ c='*';
+ if (p == 3)
+ c='\n';
BIO_write(b,&c,1);
(void)BIO_flush(b);
return 1;
- }
+ }
=head1 SEE ALSO
diff --git a/lib/libcrypto/doc/PEM_read_bio_PrivateKey.pod b/lib/libcrypto/doc/PEM_read_bio_PrivateKey.pod
index 0d9270985ae..6d87079a843 100644
--- a/lib/libcrypto/doc/PEM_read_bio_PrivateKey.pod
+++ b/lib/libcrypto/doc/PEM_read_bio_PrivateKey.pod
@@ -353,71 +353,67 @@ Read a certificate in PEM format from a BIO:
X509 *x;
x = PEM_read_bio_X509(bp, NULL, 0, NULL);
- if (x == NULL)
- {
+ if (x == NULL) {
/* Error */
- }
+ }
Alternative method:
X509 *x = NULL;
- if (!PEM_read_bio_X509(bp, &x, 0, NULL))
- {
+ if (!PEM_read_bio_X509(bp, &x, 0, NULL)) {
/* Error */
- }
+ }
Write a certificate to a BIO:
- if (!PEM_write_bio_X509(bp, x))
- {
+ if (!PEM_write_bio_X509(bp, x)) {
/* Error */
- }
+ }
Write an unencrypted private key to a FILE pointer:
- if (!PEM_write_PrivateKey(fp, key, NULL, NULL, 0, 0, NULL))
- {
+ if (!PEM_write_PrivateKey(fp, key, NULL, NULL, 0, 0, NULL)) {
/* Error */
- }
+ }
Write a private key (using traditional format) to a BIO using
triple DES encryption, the pass phrase is prompted for:
- if (!PEM_write_bio_PrivateKey(bp, key, EVP_des_ede3_cbc(), NULL, 0, 0, NULL))
- {
+ if (!PEM_write_bio_PrivateKey(bp, key, EVP_des_ede3_cbc(),
+ NULL, 0, 0, NULL)) {
/* Error */
- }
+ }
Write a private key (using PKCS#8 format) to a BIO using triple
DES encryption, using the pass phrase "hello":
- if (!PEM_write_bio_PKCS8PrivateKey(bp, key, EVP_des_ede3_cbc(), NULL, 0, 0, "hello"))
- {
+ if (!PEM_write_bio_PKCS8PrivateKey(bp, key, EVP_des_ede3_cbc(),
+ NULL, 0, 0, "hello")) {
/* Error */
- }
+ }
Read a private key from a BIO using the pass phrase "hello":
key = PEM_read_bio_PrivateKey(bp, NULL, 0, "hello");
- if (key == NULL)
- {
+ if (key == NULL) {
/* Error */
- }
+ }
Read a private key from a BIO using a pass phrase callback:
key = PEM_read_bio_PrivateKey(bp, NULL, pass_cb, "My Private Key");
- if (key == NULL)
- {
+ if (key == NULL) {
/* Error */
- }
+ }
Skeleton pass phrase callback:
- int pass_cb(char *buf, int size, int rwflag, void *u);
- {
+ int
+ pass_cb(char *buf, int size, int rwflag, void *u)
+ {
int len;
char *tmp;
+
/* We'd probably do something else if 'rwflag' is 1 */
printf("Enter pass phrase for \"%s\"\n", u);
@@ -425,12 +421,14 @@ Skeleton pass phrase callback:
tmp = "hello";
len = strlen(tmp);
- if (len <= 0) return 0;
+ if (len == 0)
+ return 0;
/* if too long, truncate */
- if (len > size) len = size;
+ if (len > size)
+ len = size;
memcpy(buf, tmp, len);
return len;
- }
+ }
=head1 NOTES
diff --git a/lib/libcrypto/doc/X509_NAME_get_index_by_NID.pod b/lib/libcrypto/doc/X509_NAME_get_index_by_NID.pod
index 9c694c98670..988fd7bdafd 100644
--- a/lib/libcrypto/doc/X509_NAME_get_index_by_NID.pod
+++ b/lib/libcrypto/doc/X509_NAME_get_index_by_NID.pod
@@ -66,11 +66,10 @@ Process all entries:
int i;
X509_NAME_ENTRY *e;
- for (i = 0; i < X509_NAME_entry_count(nm); i++)
- {
+ for (i = 0; i < X509_NAME_entry_count(nm); i++) {
e = X509_NAME_get_entry(nm, i);
/* Do something with e */
- }
+ }
Process all commonName entries:
@@ -78,14 +77,13 @@ Process all commonName entries:
X509_NAME_ENTRY *e;
loc = -1;
- for (;;)
- {
+ for (;;) {
lastpos = X509_NAME_get_index_by_NID(nm, NID_commonName, lastpos);
if (lastpos == -1)
break;
e = X509_NAME_get_entry(nm, lastpos);
/* Do something with e */
- }
+ }
=head1 RETURN VALUES
diff --git a/lib/libcrypto/doc/X509_STORE_CTX_set_verify_cb.pod b/lib/libcrypto/doc/X509_STORE_CTX_set_verify_cb.pod
index 86d988eee05..7dfe430c4c7 100644
--- a/lib/libcrypto/doc/X509_STORE_CTX_set_verify_cb.pod
+++ b/lib/libcrypto/doc/X509_STORE_CTX_set_verify_cb.pod
@@ -59,44 +59,48 @@ X509_STORE_CTX_set_verify_cb() does not return a value.
Default callback operation:
- int verify_callback(int ok, X509_STORE_CTX *ctx)
- {
+ int
+ verify_callback(int ok, X509_STORE_CTX *ctx)
+ {
return ok;
- }
+ }
Simple example, suppose a certificate in the chain is expired and we wish
to continue after this error:
- int verify_callback(int ok, X509_STORE_CTX *ctx)
- {
+ int
+ verify_callback(int ok, X509_STORE_CTX *ctx)
+ {
/* Tolerate certificate expiration */
if (X509_STORE_CTX_get_error(ctx) == X509_V_ERR_CERT_HAS_EXPIRED)
- return 1;
+ return 1;
/* Otherwise don't override */
return ok;
- }
+ }
More complex example, we don't wish to continue after B<any> certificate has
expired just one specific case:
- int verify_callback(int ok, X509_STORE_CTX *ctx)
- {
+ int
+ verify_callback(int ok, X509_STORE_CTX *ctx)
+ {
int err = X509_STORE_CTX_get_error(ctx);
X509 *err_cert = X509_STORE_CTX_get_current_cert(ctx);
- if (err == X509_V_ERR_CERT_HAS_EXPIRED)
- {
+
+ if (err == X509_V_ERR_CERT_HAS_EXPIRED) {
if (check_is_acceptable_expired_cert(err_cert)
return 1;
- }
- return ok;
}
+ return ok;
+ }
Full featured logging callback. In this case the B<bio_err> is assumed to be
a global logging B<BIO>, an alternative would to store a BIO in B<ctx> using
B<ex_data>.
- int verify_callback(int ok, X509_STORE_CTX *ctx)
- {
+ int
+ verify_callback(int ok, X509_STORE_CTX *ctx)
+ {
X509 *err_cert;
int err,depth;
@@ -105,47 +109,47 @@ B<ex_data>.
depth = X509_STORE_CTX_get_error_depth(ctx);
BIO_printf(bio_err,"depth=%d ",depth);
- if (err_cert)
- {
- X509_NAME_print_ex(bio_err, X509_get_subject_name(err_cert),
- 0, XN_FLAG_ONELINE);
+ if (err_cert) {
+ X509_NAME_print_ex(bio_err,
+ X509_get_subject_name(err_cert), 0,
+ XN_FLAG_ONELINE);
BIO_puts(bio_err, "\n");
- }
- else
+ } else
BIO_puts(bio_err, "<no cert>\n");
if (!ok)
- BIO_printf(bio_err,"verify error:num=%d:%s\n",err,
- X509_verify_cert_error_string(err));
- switch (err)
- {
+ BIO_printf(bio_err, "verify error:num=%d:%s\n",
+ err, X509_verify_cert_error_string(err));
+ switch (err) {
case X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT:
- BIO_puts(bio_err,"issuer= ");
- X509_NAME_print_ex(bio_err, X509_get_issuer_name(err_cert),
- 0, XN_FLAG_ONELINE);
+ BIO_puts(bio_err, "issuer= ");
+ X509_NAME_print_ex(bio_err,
+ X509_get_issuer_name(err_cert), 0,
+ XN_FLAG_ONELINE);
BIO_puts(bio_err, "\n");
break;
case X509_V_ERR_CERT_NOT_YET_VALID:
case X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD:
- BIO_printf(bio_err,"notBefore=");
- ASN1_TIME_print(bio_err,X509_get_notBefore(err_cert));
- BIO_printf(bio_err,"\n");
+ BIO_printf(bio_err, "notBefore=");
+ ASN1_TIME_print(bio_err,
+ X509_get_notBefore(err_cert));
+ BIO_printf(bio_err, "\n");
break;
case X509_V_ERR_CERT_HAS_EXPIRED:
case X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD:
- BIO_printf(bio_err,"notAfter=");
- ASN1_TIME_print(bio_err,X509_get_notAfter(err_cert));
- BIO_printf(bio_err,"\n");
+ BIO_printf(bio_err, "notAfter=");
+ ASN1_TIME_print(bio_err, X509_get_notAfter(err_cert));
+ BIO_printf(bio_err, "\n");
break;
case X509_V_ERR_NO_EXPLICIT_POLICY:
policies_print(bio_err, ctx);
break;
- }
+ }
if (err == X509_V_OK && ok == 2)
/* print out policies */
BIO_printf(bio_err,"verify return:%d\n",ok);
return(ok);
- }
+ }
=head1 SEE ALSO
diff --git a/lib/libcrypto/doc/engine.pod b/lib/libcrypto/doc/engine.pod
index 4648af7543c..4a6ee591386 100644
--- a/lib/libcrypto/doc/engine.pod
+++ b/lib/libcrypto/doc/engine.pod
@@ -363,15 +363,15 @@ illustrates how to approach this;
const char *engine_id = "ACME";
ENGINE_load_builtin_engines();
e = ENGINE_by_id(engine_id);
- if(!e)
+ if (!e)
/* the engine isn't available */
return;
- if(!ENGINE_init(e)) {
+ if (!ENGINE_init(e)) {
/* the engine couldn't initialise, release 'e' */
ENGINE_free(e);
return;
}
- if(!ENGINE_set_default_RSA(e))
+ if (!ENGINE_set_default_RSA(e))
/* This should only happen when 'e' can't initialise, but the previous
* statement suggests it did. */
abort();
@@ -445,42 +445,54 @@ cases but the name can not. This function should initialise the ENGINE
and set it as the default for everything except RAND and then return a
boolean success or failure.
- int generic_load_engine_fn(const char *engine_id,
- const char **pre_cmds, int pre_num,
- const char **post_cmds, int post_num)
+ int
+ generic_load_engine_fn(const char *engine_id,
+ const char **pre_cmds, int pre_num,
+ const char **post_cmds, int post_num)
{
- ENGINE *e = ENGINE_by_id(engine_id);
- if(!e) return 0;
- while(pre_num--) {
- if(!ENGINE_ctrl_cmd_string(e, pre_cmds[0], pre_cmds[1], 0)) {
- fprintf(stderr, "Failed command (%s - %s:%s)\n", engine_id,
- pre_cmds[0], pre_cmds[1] ? pre_cmds[1] : "(NULL)");
- ENGINE_free(e);
- return 0;
- }
- pre_cmds += 2;
- }
- if(!ENGINE_init(e)) {
- fprintf(stderr, "Failed initialisation\n");
- ENGINE_free(e);
- return 0;
- }
- /* ENGINE_init() returned a functional reference, so free the structural
- * reference from ENGINE_by_id(). */
- ENGINE_free(e);
- while(post_num--) {
- if(!ENGINE_ctrl_cmd_string(e, post_cmds[0], post_cmds[1], 0)) {
- fprintf(stderr, "Failed command (%s - %s:%s)\n", engine_id,
- post_cmds[0], post_cmds[1] ? post_cmds[1] : "(NULL)");
- ENGINE_finish(e);
- return 0;
- }
- post_cmds += 2;
- }
- ENGINE_set_default(e, ENGINE_METHOD_ALL & ~ENGINE_METHOD_RAND);
- /* Success */
- return 1;
- }
+ ENGINE *e = ENGINE_by_id(engine_id);
+
+ if (!e)
+ return 0;
+ while (pre_num--) {
+ if (!ENGINE_ctrl_cmd_string(e,
+ pre_cmds[0], pre_cmds[1], 0)) {
+ fprintf(stderr,
+ "Failed command (%s - %s:%s)\n",
+ engine_id, pre_cmds[0],
+ pre_cmds[1] ? pre_cmds[1] : "(NULL)");
+ ENGINE_free(e);
+ return 0;
+ }
+ pre_cmds += 2;
+ }
+ if (!ENGINE_init(e)) {
+ fprintf(stderr, "Failed initialisation\n");
+ ENGINE_free(e);
+ return 0;
+ }
+ /*
+ * ENGINE_init() returned a functional reference,
+ * so free the structural reference from
+ * ENGINE_by_id().
+ */
+ ENGINE_free(e);
+ while (post_num--) {
+ if (!ENGINE_ctrl_cmd_string(e,
+ post_cmds[0], post_cmds[1], 0)) {
+ fprintf(stderr,
+ "Failed command (%s - %s:%s)\n",
+ engine_id, post_cmds[0],
+ post_cmds[1] ? post_cmds[1] : "(NULL)");
+ ENGINE_finish(e);
+ return 0;
+ }
+ post_cmds += 2;
+ }
+ ENGINE_set_default(e, ENGINE_METHOD_ALL & ~ENGINE_METHOD_RAND);
+ /* Success */
+ return 1;
+}
Note that ENGINE_ctrl_cmd_string() accepts a boolean argument that can
relax the semantics of the function - if set non-zero it will only return