diff options
Diffstat (limited to 'src/lib/libcrypto/doc/EVP_DigestInit.pod')
| -rw-r--r-- | src/lib/libcrypto/doc/EVP_DigestInit.pod | 202 |
1 files changed, 0 insertions, 202 deletions
diff --git a/src/lib/libcrypto/doc/EVP_DigestInit.pod b/src/lib/libcrypto/doc/EVP_DigestInit.pod deleted file mode 100644 index fefc858f7e..0000000000 --- a/src/lib/libcrypto/doc/EVP_DigestInit.pod +++ /dev/null | |||
| @@ -1,202 +0,0 @@ | |||
| 1 | =pod | ||
| 2 | |||
| 3 | =head1 NAME | ||
| 4 | |||
| 5 | EVP_DigestInit, EVP_DigestUpdate, EVP_DigestFinal, EVP_MAX_MD_SIZE, | ||
| 6 | EVP_MD_CTX_copy, EVP_MD_type, EVP_MD_pkey_type, EVP_MD_size, EVP_MD_block_size, | ||
| 7 | EVP_MD_CTX_md, EVP_MD_CTX_size, EVP_MD_CTX_block_size, EVP_MD_CTX_type, | ||
| 8 | EVP_md_null, EVP_md2, EVP_md5, EVP_sha, EVP_sha1, EVP_dss, EVP_dss1, EVP_mdc2, | ||
| 9 | EVP_ripemd160, EVP_get_digestbyname, EVP_get_digestbynid, EVP_get_digestbyobj - | ||
| 10 | EVP digest routines | ||
| 11 | |||
| 12 | =head1 SYNOPSIS | ||
| 13 | |||
| 14 | #include <openssl/evp.h> | ||
| 15 | |||
| 16 | void EVP_DigestInit(EVP_MD_CTX *ctx, const EVP_MD *type); | ||
| 17 | void EVP_DigestUpdate(EVP_MD_CTX *ctx, const void *d, unsigned int cnt); | ||
| 18 | void EVP_DigestFinal(EVP_MD_CTX *ctx, unsigned char *md, | ||
| 19 | unsigned int *s); | ||
| 20 | |||
| 21 | #define EVP_MAX_MD_SIZE (16+20) /* The SSLv3 md5+sha1 type */ | ||
| 22 | |||
| 23 | int EVP_MD_CTX_copy(EVP_MD_CTX *out,EVP_MD_CTX *in); | ||
| 24 | |||
| 25 | #define EVP_MD_type(e) ((e)->type) | ||
| 26 | #define EVP_MD_pkey_type(e) ((e)->pkey_type) | ||
| 27 | #define EVP_MD_size(e) ((e)->md_size) | ||
| 28 | #define EVP_MD_block_size(e) ((e)->block_size) | ||
| 29 | |||
| 30 | #define EVP_MD_CTX_md(e) (e)->digest) | ||
| 31 | #define EVP_MD_CTX_size(e) EVP_MD_size((e)->digest) | ||
| 32 | #define EVP_MD_CTX_block_size(e) EVP_MD_block_size((e)->digest) | ||
| 33 | #define EVP_MD_CTX_type(e) EVP_MD_type((e)->digest) | ||
| 34 | |||
| 35 | EVP_MD *EVP_md_null(void); | ||
| 36 | EVP_MD *EVP_md2(void); | ||
| 37 | EVP_MD *EVP_md5(void); | ||
| 38 | EVP_MD *EVP_sha(void); | ||
| 39 | EVP_MD *EVP_sha1(void); | ||
| 40 | EVP_MD *EVP_dss(void); | ||
| 41 | EVP_MD *EVP_dss1(void); | ||
| 42 | EVP_MD *EVP_mdc2(void); | ||
| 43 | EVP_MD *EVP_ripemd160(void); | ||
| 44 | |||
| 45 | const EVP_MD *EVP_get_digestbyname(const char *name); | ||
| 46 | #define EVP_get_digestbynid(a) EVP_get_digestbyname(OBJ_nid2sn(a)) | ||
| 47 | #define EVP_get_digestbyobj(a) EVP_get_digestbynid(OBJ_obj2nid(a)) | ||
| 48 | |||
| 49 | =head1 DESCRIPTION | ||
| 50 | |||
| 51 | The EVP digest routines are a high level interface to message digests. | ||
| 52 | |||
| 53 | EVP_DigestInit() initializes a digest context B<ctx> to use a digest | ||
| 54 | B<type>: this will typically be supplied by a function such as | ||
| 55 | EVP_sha1(). | ||
| 56 | |||
| 57 | EVP_DigestUpdate() hashes B<cnt> bytes of data at B<d> into the | ||
| 58 | digest context B<ctx>. This function can be called several times on the | ||
| 59 | same B<ctx> to hash additional data. | ||
| 60 | |||
| 61 | EVP_DigestFinal() retrieves the digest value from B<ctx> and places | ||
| 62 | it in B<md>. If the B<s> parameter is not NULL then the number of | ||
| 63 | bytes of data written (i.e. the length of the digest) will be written | ||
| 64 | to the integer at B<s>, at most B<EVP_MAX_MD_SIZE> bytes will be written. | ||
| 65 | After calling EVP_DigestFinal() no additional calls to EVP_DigestUpdate() | ||
| 66 | can be made, but EVP_DigestInit() can be called to initialize a new | ||
| 67 | digest operation. | ||
| 68 | |||
| 69 | EVP_MD_CTX_copy() can be used to copy the message digest state from | ||
| 70 | B<in> to B<out>. This is useful if large amounts of data are to be | ||
| 71 | hashed which only differ in the last few bytes. | ||
| 72 | |||
| 73 | EVP_MD_size() and EVP_MD_CTX_size() return the size of the message digest | ||
| 74 | when passed an B<EVP_MD> or an B<EVP_MD_CTX> structure, i.e. the size of the | ||
| 75 | hash. | ||
| 76 | |||
| 77 | EVP_MD_block_size() and EVP_MD_CTX_block_size() return the block size of the | ||
| 78 | message digest when passed an B<EVP_MD> or an B<EVP_MD_CTX> structure. | ||
| 79 | |||
| 80 | EVP_MD_type() and EVP_MD_CTX_type() return the NID of the OBJECT IDENTIFIER | ||
| 81 | representing the given message digest when passed an B<EVP_MD> structure. | ||
| 82 | For example EVP_MD_type(EVP_sha1()) returns B<NID_sha1>. This function is | ||
| 83 | normally used when setting ASN1 OIDs. | ||
| 84 | |||
| 85 | EVP_MD_CTX_md() returns the B<EVP_MD> structure corresponding to the passed | ||
| 86 | B<EVP_MD_CTX>. | ||
| 87 | |||
| 88 | EVP_MD_pkey_type() returns the NID of the public key signing algorithm associated | ||
| 89 | with this digest. For example EVP_sha1() is associated with RSA so this will | ||
| 90 | return B<NID_sha1WithRSAEncryption>. This "link" between digests and signature | ||
| 91 | algorithms may not be retained in future versions of OpenSSL. | ||
| 92 | |||
| 93 | EVP_md2(), EVP_md5(), EVP_sha(), EVP_sha1(), EVP_mdc2() and EVP_ripemd160() | ||
| 94 | return B<EVP_MD> structures for the MD2, MD5, SHA, SHA1, MDC2 and RIPEMD160 digest | ||
| 95 | algorithms respectively. The associated signature algorithm is RSA in each case. | ||
| 96 | |||
| 97 | EVP_dss() and EVP_dss1() return B<EVP_MD> structures for SHA and SHA1 digest | ||
| 98 | algorithms but using DSS (DSA) for the signature algorithm. | ||
| 99 | |||
| 100 | EVP_md_null() is a "null" message digest that does nothing: i.e. the hash it | ||
| 101 | returns is of zero length. | ||
| 102 | |||
| 103 | EVP_get_digestbyname(), EVP_get_digestbynid() and EVP_get_digestbyobj() | ||
| 104 | return an B<EVP_MD> structure when passed a digest name, a digest NID or | ||
| 105 | an ASN1_OBJECT structure respectively. The digest table must be initialized | ||
| 106 | using, for example, OpenSSL_add_all_digests() for these functions to work. | ||
| 107 | |||
| 108 | =head1 RETURN VALUES | ||
| 109 | |||
| 110 | EVP_DigestInit(), EVP_DigestUpdate() and EVP_DigestFinal() do not return values. | ||
| 111 | |||
| 112 | EVP_MD_CTX_copy() returns 1 if successful or 0 for failure. | ||
| 113 | |||
| 114 | EVP_MD_type(), EVP_MD_pkey_type() and EVP_MD_type() return the NID of the | ||
| 115 | corresponding OBJECT IDENTIFIER or NID_undef if none exists. | ||
| 116 | |||
| 117 | EVP_MD_size(), EVP_MD_block_size(), EVP_MD_CTX_size(e), EVP_MD_size(), | ||
| 118 | EVP_MD_CTX_block_size() and EVP_MD_block_size() return the digest or block | ||
| 119 | size in bytes. | ||
| 120 | |||
| 121 | EVP_md_null(), EVP_md2(), EVP_md5(), EVP_sha(), EVP_sha1(), EVP_dss(), | ||
| 122 | EVP_dss1(), EVP_mdc2() and EVP_ripemd160() return pointers to the | ||
| 123 | corresponding EVP_MD structures. | ||
| 124 | |||
| 125 | EVP_get_digestbyname(), EVP_get_digestbynid() and EVP_get_digestbyobj() | ||
| 126 | return either an B<EVP_MD> structure or NULL if an error occurs. | ||
| 127 | |||
| 128 | =head1 NOTES | ||
| 129 | |||
| 130 | The B<EVP> interface to message digests should almost always be used in | ||
| 131 | preference to the low level interfaces. This is because the code then becomes | ||
| 132 | transparent to the digest used and much more flexible. | ||
| 133 | |||
| 134 | SHA1 is the digest of choice for new applications. The other digest algorithms | ||
| 135 | are still in common use. | ||
| 136 | |||
| 137 | =head1 EXAMPLE | ||
| 138 | |||
| 139 | This example digests the data "Test Message\n" and "Hello World\n", using the | ||
| 140 | digest name passed on the command line. | ||
| 141 | |||
| 142 | #include <stdio.h> | ||
| 143 | #include <openssl/evp.h> | ||
| 144 | |||
| 145 | main(int argc, char *argv[]) | ||
| 146 | { | ||
| 147 | EVP_MD_CTX mdctx; | ||
| 148 | const EVP_MD *md; | ||
| 149 | char mess1[] = "Test Message\n"; | ||
| 150 | char mess2[] = "Hello World\n"; | ||
| 151 | unsigned char md_value[EVP_MAX_MD_SIZE]; | ||
| 152 | int md_len, i; | ||
| 153 | |||
| 154 | OpenSSL_add_all_digests(); | ||
| 155 | |||
| 156 | if(!argv[1]) { | ||
| 157 | printf("Usage: mdtest digestname\n"); | ||
| 158 | exit(1); | ||
| 159 | } | ||
| 160 | |||
| 161 | md = EVP_get_digestbyname(argv[1]); | ||
| 162 | |||
| 163 | if(!md) { | ||
| 164 | printf("Unknown message digest %s\n", argv[1]); | ||
| 165 | exit(1); | ||
| 166 | } | ||
| 167 | |||
| 168 | EVP_DigestInit(&mdctx, md); | ||
| 169 | EVP_DigestUpdate(&mdctx, mess1, strlen(mess1)); | ||
| 170 | EVP_DigestUpdate(&mdctx, mess2, strlen(mess2)); | ||
| 171 | EVP_DigestFinal(&mdctx, md_value, &md_len); | ||
| 172 | |||
| 173 | printf("Digest is: "); | ||
| 174 | for(i = 0; i < md_len; i++) printf("%02x", md_value[i]); | ||
| 175 | printf("\n"); | ||
| 176 | } | ||
| 177 | |||
| 178 | =head1 BUGS | ||
| 179 | |||
| 180 | Several of the functions do not return values: maybe they should. Although the | ||
| 181 | internal digest operations will never fail some future hardware based operations | ||
| 182 | might. | ||
| 183 | |||
| 184 | The link between digests and signing algorithms results in a situation where | ||
| 185 | EVP_sha1() must be used with RSA and EVP_dss1() must be used with DSS | ||
| 186 | even though they are identical digests. | ||
| 187 | |||
| 188 | The size of an B<EVP_MD_CTX> structure is determined at compile time: this results | ||
| 189 | in code that must be recompiled if the size of B<EVP_MD_CTX> increases. | ||
| 190 | |||
| 191 | =head1 SEE ALSO | ||
| 192 | |||
| 193 | L<evp(3)|evp(3)>, L<HMAC(3)|HMAC(3)>, L<MD2(3)|MD2(3)>, | ||
| 194 | L<MD5(3)|MD5(3)>, L<MDC2(3)|MDC2(3)>, L<RIPEMD160(3)|RIPEMD160(3)>, | ||
| 195 | L<SHA1(3)|SHA1(3)> | ||
| 196 | |||
| 197 | =head1 HISTORY | ||
| 198 | |||
| 199 | EVP_DigestInit(), EVP_DigestUpdate() and EVP_DigestFinal() are | ||
| 200 | available in all versions of SSLeay and OpenSSL. | ||
| 201 | |||
| 202 | =cut | ||
