Wed Jan 27 20:02:15 2016

Asterisk developer's documentation


sha1.h

Go to the documentation of this file.
00001 /**************************** sha.h ****************************/
00002 /***************** See RFC 6234 for details. *******************/
00003 /*
00004    Copyright (c) 2011 IETF Trust and the persons identified as
00005    authors of the code.  All rights reserved.
00006 
00007    Redistribution and use in source and binary forms, with or
00008    without modification, are permitted provided that the following
00009    conditions are met:
00010 
00011    - Redistributions of source code must retain the above
00012      copyright notice, this list of conditions and
00013      the following disclaimer.
00014 
00015    - Redistributions in binary form must reproduce the above
00016      copyright notice, this list of conditions and the following
00017      disclaimer in the documentation and/or other materials provided
00018      with the distribution.
00019 
00020    - Neither the name of Internet Society, IETF or IETF Trust, nor
00021      the names of specific contributors, may be used to endorse or
00022      promote products derived from this software without specific
00023      prior written permission.
00024 
00025    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
00026    CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
00027    INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
00028    MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
00029    DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR
00030    CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
00031    SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
00032    NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
00033    LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
00034    HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
00035    CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
00036    OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
00037    EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00038 */
00039 #ifndef _SHA1_H_
00040 #define _SHA1_H_
00041 
00042 /*
00043  *  Description:
00044  *      This file implements the Secure Hash Algorithms
00045  *      as defined in the U.S. National Institute of Standards
00046  *      and Technology Federal Information Processing Standards
00047  *      Publication (FIPS PUB) 180-3 published in October 2008
00048  *      and formerly defined in its predecessors, FIPS PUB 180-1
00049  *      and FIP PUB 180-2.
00050  *
00051  *      A combined document showing all algorithms is available at
00052  *              http://csrc.nist.gov/publications/fips/
00053  *                     fips180-3/fips180-3_final.pdf
00054  *
00055  *      The five hashes are defined in these sizes:
00056  *              SHA-1           20 byte / 160 bit
00057  *              SHA-224         28 byte / 224 bit
00058  *              SHA-256         32 byte / 256 bit
00059  *              SHA-384         48 byte / 384 bit
00060  *              SHA-512         64 byte / 512 bit
00061  *
00062  *  Compilation Note:
00063  *    These files may be compiled with two options:
00064  *        USE_32BIT_ONLY - use 32-bit arithmetic only, for systems
00065  *                         without 64-bit integers
00066  *
00067  *        USE_MODIFIED_MACROS - use alternate form of the SHA_Ch()
00068  *                         and SHA_Maj() macros that are equivalent
00069  *                         and potentially faster on many systems
00070  *
00071  */
00072 
00073 #include <stdint.h>
00074 /*
00075  * If you do not have the ISO standard stdint.h header file, then you
00076  * must typedef the following:
00077  *    name              meaning
00078  *  uint64_t         unsigned 64-bit integer
00079  *  uint32_t         unsigned 32-bit integer
00080  *  uint8_t          unsigned 8-bit integer (i.e., unsigned char)
00081  *  int_least16_t    integer of >= 16 bits
00082  *
00083  * See stdint-example.h
00084  */
00085 
00086 #ifndef _SHA_enum_
00087 #define _SHA_enum_
00088 /*
00089  *  All SHA functions return one of these values.
00090  */
00091 enum {
00092     shaSuccess = 0,
00093     shaNull,            /* Null pointer parameter */
00094     shaInputTooLong,    /* input data too long */
00095     shaStateError,      /* called Input after FinalBits or Result */
00096     shaBadParam         /* passed a bad parameter */
00097 };
00098 #endif /* _SHA_enum_ */
00099 
00100 /*
00101  *  These constants hold size information for each of the SHA
00102  *  hashing operations
00103  */
00104 enum {
00105    SHA1_Message_Block_Size = 64, SHA224_Message_Block_Size = 64,
00106    SHA256_Message_Block_Size = 64, SHA384_Message_Block_Size = 128,
00107    SHA512_Message_Block_Size = 128,
00108    USHA_Max_Message_Block_Size = SHA512_Message_Block_Size,
00109    SHA1HashSize = 20, SHA224HashSize = 28, SHA256HashSize = 32,
00110    SHA384HashSize = 48, SHA512HashSize = 64,
00111    USHAMaxHashSize = SHA512HashSize,
00112 
00113    SHA1HashSizeBits = 160, SHA224HashSizeBits = 224,
00114    SHA256HashSizeBits = 256, SHA384HashSizeBits = 384,
00115    SHA512HashSizeBits = 512, USHAMaxHashSizeBits = SHA512HashSizeBits
00116 };
00117 
00118 /*
00119  *  These constants are used in the USHA (Unified SHA) functions.
00120  */
00121 typedef enum SHAversion {
00122    SHA1, SHA224, SHA256, SHA384, SHA512
00123 } SHAversion;
00124 
00125 /*
00126  *  This structure will hold context information for the SHA-1
00127  *  hashing operation.
00128  */
00129 typedef struct SHA1Context {
00130    uint32_t Intermediate_Hash[SHA1HashSize/4]; /* Message Digest */
00131 
00132    uint32_t Length_High;               /* Message length in bits */
00133    uint32_t Length_Low;                /* Message length in bits */
00134 
00135    int_least16_t Message_Block_Index;  /* Message_Block array index */
00136    /* 512-bit message blocks */
00137    uint8_t Message_Block[SHA1_Message_Block_Size];
00138 
00139    int Computed;                   /* Is the hash computed? */
00140    int Corrupted;                  /* Cumulative corruption code */
00141 } SHA1Context;
00142 
00143 /*
00144  *  This structure will hold context information for the SHA-256
00145  *  hashing operation.
00146  */
00147 typedef struct SHA256Context {
00148     uint32_t Intermediate_Hash[SHA256HashSize/4]; /* Message Digest */
00149 
00150     uint32_t Length_High;               /* Message length in bits */
00151     uint32_t Length_Low;                /* Message length in bits */
00152 
00153     int_least16_t Message_Block_Index;  /* Message_Block array index */
00154                                         /* 512-bit message blocks */
00155     uint8_t Message_Block[SHA256_Message_Block_Size];
00156     int Computed;                   /* Is the hash computed? */
00157     int Corrupted;                  /* Cumulative corruption code */
00158 } SHA256Context;
00159 
00160 /*
00161  *  This structure will hold context information for the SHA-512
00162  *  hashing operation.
00163  */
00164 typedef struct SHA512Context {
00165 #ifdef USE_32BIT_ONLY
00166     uint32_t Intermediate_Hash[SHA512HashSize/4]; /* Message Digest  */
00167     uint32_t Length[4];                 /* Message length in bits */
00168 #else /* !USE_32BIT_ONLY */
00169     uint64_t Intermediate_Hash[SHA512HashSize/8]; /* Message Digest */
00170     uint64_t Length_High, Length_Low;   /* Message length in bits */
00171 #endif /* USE_32BIT_ONLY */
00172 
00173     int_least16_t Message_Block_Index;  /* Message_Block array index */
00174                                         /* 1024-bit message blocks */
00175     uint8_t Message_Block[SHA512_Message_Block_Size];
00176 
00177     int Computed;                   /* Is the hash computed?*/
00178     int Corrupted;                  /* Cumulative corruption code */
00179 } SHA512Context;
00180 
00181 /*
00182  *  This structure will hold context information for the SHA-224
00183  *  hashing operation.  It uses the SHA-256 structure for computation.
00184  */
00185 typedef struct SHA256Context SHA224Context;
00186 
00187 /*
00188  *  This structure will hold context information for the SHA-384
00189  *  hashing operation.  It uses the SHA-512 structure for computation.
00190  */
00191 typedef struct SHA512Context SHA384Context;
00192 
00193 /*
00194  *  This structure holds context information for all SHA
00195  *  hashing operations.
00196  */
00197 typedef struct USHAContext {
00198    int whichSha;               /* which SHA is being used */
00199    union {
00200       SHA1Context sha1Context;
00201       SHA224Context sha224Context; SHA256Context sha256Context;
00202       SHA384Context sha384Context; SHA512Context sha512Context;
00203    } ctx;
00204 } USHAContext;
00205 
00206 /*
00207  *  This structure will hold context information for the HMAC
00208  *  keyed-hashing operation.
00209  */
00210 typedef struct HMACContext {
00211    int whichSha;               /* which SHA is being used */
00212    int hashSize;               /* hash size of SHA being used */
00213    int blockSize;              /* block size of SHA being used */
00214    USHAContext shaContext;     /* SHA context */
00215    unsigned char k_opad[USHA_Max_Message_Block_Size];
00216    /* outer padding - key XORd with opad */
00217    int Computed;               /* Is the MAC computed? */
00218    int Corrupted;              /* Cumulative corruption code */
00219 
00220 } HMACContext;
00221 
00222 /*
00223  *  This structure will hold context information for the HKDF
00224  *  extract-and-expand Key Derivation Functions.
00225  */
00226 typedef struct HKDFContext {
00227    int whichSha;               /* which SHA is being used */
00228    HMACContext hmacContext;
00229    int hashSize;               /* hash size of SHA being used */
00230    unsigned char prk[USHAMaxHashSize];
00231    /* pseudo-random key - output of hkdfInput */
00232    int Computed;               /* Is the key material computed? */
00233    int Corrupted;              /* Cumulative corruption code */
00234 } HKDFContext;
00235 
00236 /*
00237  *  Function Prototypes
00238  */
00239 
00240 /* SHA-1 */
00241 extern int SHA1Reset(SHA1Context *);
00242 extern int SHA1Input(SHA1Context *, const uint8_t *bytes,
00243                      unsigned int bytecount);
00244 extern int SHA1FinalBits(SHA1Context *, uint8_t bits,
00245                          unsigned int bit_count);
00246 extern int SHA1Result(SHA1Context *,
00247                       uint8_t Message_Digest[SHA1HashSize]);
00248 /* SHA-224 */
00249 extern int SHA224Reset(SHA224Context *);
00250 extern int SHA224Input(SHA224Context *, const uint8_t *bytes,
00251                        unsigned int bytecount);
00252 extern int SHA224FinalBits(SHA224Context *, uint8_t bits,
00253                            unsigned int bit_count);
00254 extern int SHA224Result(SHA224Context *,
00255                         uint8_t Message_Digest[SHA224HashSize]);
00256 
00257 /* SHA-256 */
00258 extern int SHA256Reset(SHA256Context *);
00259 extern int SHA256Input(SHA256Context *, const uint8_t *bytes,
00260                        unsigned int bytecount);
00261 extern int SHA256FinalBits(SHA256Context *, uint8_t bits,
00262                            unsigned int bit_count);
00263 extern int SHA256Result(SHA256Context *,
00264                         uint8_t Message_Digest[SHA256HashSize]);
00265 
00266 /* SHA-384 */
00267 extern int SHA384Reset(SHA384Context *);
00268 extern int SHA384Input(SHA384Context *, const uint8_t *bytes,
00269                        unsigned int bytecount);
00270 extern int SHA384FinalBits(SHA384Context *, uint8_t bits,
00271                            unsigned int bit_count);
00272 extern int SHA384Result(SHA384Context *,
00273                         uint8_t Message_Digest[SHA384HashSize]);
00274 
00275 /* SHA-512 */
00276 extern int SHA512Reset(SHA512Context *);
00277 extern int SHA512Input(SHA512Context *, const uint8_t *bytes,
00278                        unsigned int bytecount);
00279 extern int SHA512FinalBits(SHA512Context *, uint8_t bits,
00280                            unsigned int bit_count);
00281 extern int SHA512Result(SHA512Context *,
00282                         uint8_t Message_Digest[SHA512HashSize]);
00283 
00284 /* Unified SHA functions, chosen by whichSha */
00285 extern int USHAReset(USHAContext *context, SHAversion whichSha);
00286 extern int USHAInput(USHAContext *context,
00287                      const uint8_t *bytes, unsigned int bytecount);
00288 extern int USHAFinalBits(USHAContext *context,
00289                          uint8_t bits, unsigned int bit_count);
00290 extern int USHAResult(USHAContext *context,
00291                       uint8_t Message_Digest[USHAMaxHashSize]);
00292 extern int USHABlockSize(enum SHAversion whichSha);
00293 extern int USHAHashSize(enum SHAversion whichSha);
00294 extern int USHAHashSizeBits(enum SHAversion whichSha);
00295 extern const char *USHAHashName(enum SHAversion whichSha);
00296 
00297 /*
00298  * HMAC Keyed-Hashing for Message Authentication, RFC 2104,
00299  * for all SHAs.
00300  * This interface allows a fixed-length text input to be used.
00301  */
00302 extern int hmac(SHAversion whichSha, /* which SHA algorithm to use */
00303     const unsigned char *text,     /* pointer to data stream */
00304     int text_len,                  /* length of data stream */
00305     const unsigned char *key,      /* pointer to authentication key */
00306     int key_len,                   /* length of authentication key */
00307     uint8_t digest[USHAMaxHashSize]); /* caller digest to fill in */
00308 
00309 /*
00310  * HMAC Keyed-Hashing for Message Authentication, RFC 2104,
00311  * for all SHAs.
00312  * This interface allows any length of text input to be used.
00313  */
00314 extern int hmacReset(HMACContext *context, enum SHAversion whichSha,
00315                      const unsigned char *key, int key_len);
00316 extern int hmacInput(HMACContext *context, const unsigned char *text,
00317                      int text_len);
00318 extern int hmacFinalBits(HMACContext *context, uint8_t bits,
00319                          unsigned int bit_count);
00320 extern int hmacResult(HMACContext *context,
00321                       uint8_t digest[USHAMaxHashSize]);
00322 
00323 /*
00324  * HKDF HMAC-based Extract-and-Expand Key Derivation Function,
00325  * RFC 5869, for all SHAs.
00326  */
00327 extern int hkdf(SHAversion whichSha, const unsigned char *salt,
00328                 int salt_len, const unsigned char *ikm, int ikm_len,
00329                 const unsigned char *info, int info_len,
00330                 uint8_t okm[ ], int okm_len);
00331 extern int hkdfExtract(SHAversion whichSha, const unsigned char *salt,
00332                        int salt_len, const unsigned char *ikm,
00333                        int ikm_len, uint8_t prk[USHAMaxHashSize]);
00334 extern int hkdfExpand(SHAversion whichSha, const uint8_t prk[ ],
00335                       int prk_len, const unsigned char *info,
00336                       int info_len, uint8_t okm[ ], int okm_len);
00337 
00338 /*
00339  * HKDF HMAC-based Extract-and-Expand Key Derivation Function,
00340  * RFC 5869, for all SHAs.
00341  * This interface allows any length of text input to be used.
00342  */
00343 extern int hkdfReset(HKDFContext *context, enum SHAversion whichSha,
00344                      const unsigned char *salt, int salt_len);
00345 extern int hkdfInput(HKDFContext *context, const unsigned char *ikm,
00346                      int ikm_len);
00347 extern int hkdfFinalBits(HKDFContext *context, uint8_t ikm_bits,
00348                          unsigned int ikm_bit_count);
00349 extern int hkdfResult(HKDFContext *context,
00350                       uint8_t prk[USHAMaxHashSize],
00351                       const unsigned char *info, int info_len,
00352                       uint8_t okm[USHAMaxHashSize], int okm_len);
00353 
00354 /************************ sha-private.h ************************/
00355 /***************** See RFC 6234 for details. *******************/
00356 /*
00357  * These definitions are defined in FIPS 180-3, section 4.1.
00358  * Ch() and Maj() are defined identically in sections 4.1.1,
00359  * 4.1.2, and 4.1.3.
00360  *
00361  * The definitions used in FIPS 180-3 are as follows:
00362  */
00363 
00364 #ifndef USE_MODIFIED_MACROS
00365 #define SHA_Ch(x,y,z)        (((x) & (y)) ^ ((~(x)) & (z)))
00366 #define SHA_Maj(x,y,z)       (((x) & (y)) ^ ((x) & (z)) ^ ((y) & (z)))
00367 #else /* USE_MODIFIED_MACROS */
00368 /*
00369  * The following definitions are equivalent and potentially faster.
00370  */
00371 
00372 #define SHA_Ch(x, y, z)      (((x) & ((y) ^ (z))) ^ (z))
00373 #define SHA_Maj(x, y, z)     (((x) & ((y) | (z))) | ((y) & (z)))
00374 
00375 #endif /* USE_MODIFIED_MACROS */
00376 
00377 #define SHA_Parity(x, y, z)  ((x) ^ (y) ^ (z))
00378 
00379 #endif /* _SHA1_H_ */

Generated on 27 Jan 2016 for Asterisk - The Open Source Telephony Project by  doxygen 1.6.1