md.h

00001 /**
00002  * \file md.h
00003  *
00004  * \brief Generic message digest wrapper
00005  *
00006  * \author Adriaan de Jong <dejong@fox-it.com>
00007  *
00008  *  Copyright (C) 2006-2014, ARM Limited, All Rights Reserved
00009  *
00010  *  This file is part of mbed TLS (https://tls.mbed.org)
00011  *
00012  *  This program is free software; you can redistribute it and/or modify
00013  *  it under the terms of the GNU General Public License as published by
00014  *  the Free Software Foundation; either version 2 of the License, or
00015  *  (at your option) any later version.
00016  *
00017  *  This program is distributed in the hope that it will be useful,
00018  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
00019  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00020  *  GNU General Public License for more details.
00021  *
00022  *  You should have received a copy of the GNU General Public License along
00023  *  with this program; if not, write to the Free Software Foundation, Inc.,
00024  *  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
00025  */
00026 #ifndef POLARSSL_MD_H
00027 #define POLARSSL_MD_H
00028 
00029 #include <stddef.h>
00030 
00031 #if defined(_MSC_VER) && !defined(inline)
00032 #define inline _inline
00033 #else
00034 #if defined(__ARMCC_VERSION) && !defined(inline)
00035 #define inline __inline
00036 #endif /* __ARMCC_VERSION */
00037 #endif /*_MSC_VER */
00038 
00039 #define POLARSSL_ERR_MD_FEATURE_UNAVAILABLE                -0x5080  /**< The selected feature is not available. */
00040 #define POLARSSL_ERR_MD_BAD_INPUT_DATA                     -0x5100  /**< Bad input parameters to function. */
00041 #define POLARSSL_ERR_MD_ALLOC_FAILED                       -0x5180  /**< Failed to allocate memory. */
00042 #define POLARSSL_ERR_MD_FILE_IO_ERROR                      -0x5200  /**< Opening or reading of file failed. */
00043 
00044 #ifdef __cplusplus
00045 extern "C" {
00046 #endif
00047 
00048 typedef enum {
00049     POLARSSL_MD_NONE=0,
00050     POLARSSL_MD_MD2,
00051     POLARSSL_MD_MD4,
00052     POLARSSL_MD_MD5,
00053     POLARSSL_MD_SHA1,
00054     POLARSSL_MD_SHA224,
00055     POLARSSL_MD_SHA256,
00056     POLARSSL_MD_SHA384,
00057     POLARSSL_MD_SHA512,
00058     POLARSSL_MD_RIPEMD160,
00059 } md_type_t;
00060 
00061 #if defined(POLARSSL_SHA512_C)
00062 #define POLARSSL_MD_MAX_SIZE         64  /* longest known is SHA512 */
00063 #else
00064 #define POLARSSL_MD_MAX_SIZE         32  /* longest known is SHA256 or less */
00065 #endif
00066 
00067 /**
00068  * Message digest information. Allows message digest functions to be called
00069  * in a generic way.
00070  */
00071 typedef struct {
00072     /** Digest identifier */
00073     md_type_t type;
00074 
00075     /** Name of the message digest */
00076     const char * name;
00077 
00078     /** Output length of the digest function */
00079     int size;
00080 
00081     /** Digest initialisation function */
00082     void (*starts_func)( void *ctx );
00083 
00084     /** Digest update function */
00085     void (*update_func)( void *ctx, const unsigned char *input, size_t ilen );
00086 
00087     /** Digest finalisation function */
00088     void (*finish_func)( void *ctx, unsigned char *output );
00089 
00090     /** Generic digest function */
00091     void (*digest_func)( const unsigned char *input, size_t ilen,
00092                          unsigned char *output );
00093 
00094     /** Generic file digest function */
00095     int (*file_func)( const char *path, unsigned char *output );
00096 
00097     /** HMAC Initialisation function */
00098     void (*hmac_starts_func)( void *ctx, const unsigned char *key,
00099                               size_t keylen );
00100 
00101     /** HMAC update function */
00102     void (*hmac_update_func)( void *ctx, const unsigned char *input,
00103                               size_t ilen );
00104 
00105     /** HMAC finalisation function */
00106     void (*hmac_finish_func)( void *ctx, unsigned char *output);
00107 
00108     /** HMAC context reset function */
00109     void (*hmac_reset_func)( void *ctx );
00110 
00111     /** Generic HMAC function */
00112     void (*hmac_func)( const unsigned char *key, size_t keylen,
00113                        const unsigned char *input, size_t ilen,
00114                        unsigned char *output );
00115 
00116     /** Allocate a new context */
00117     void * (*ctx_alloc_func)( void );
00118 
00119     /** Free the given context */
00120     void (*ctx_free_func)( void *ctx );
00121 
00122     /** Internal use only */
00123     void (*process_func)( void *ctx, const unsigned char *input );
00124 } md_info_t;
00125 
00126 /**
00127  * Generic message digest context.
00128  */
00129 typedef struct {
00130     /** Information about the associated message digest */
00131     const md_info_t *md_info;
00132 
00133     /** Digest-specific context */
00134     void *md_ctx;
00135 } md_context_t;
00136 
00137 #define MD_CONTEXT_T_INIT { \
00138     NULL, /* md_info */ \
00139     NULL, /* md_ctx */ \
00140 }
00141 
00142 /**
00143  * \brief Returns the list of digests supported by the generic digest module.
00144  *
00145  * \return          a statically allocated array of digests, the last entry
00146  *                  is 0.
00147  */
00148 const int *md_list( void );
00149 
00150 /**
00151  * \brief           Returns the message digest information associated with the
00152  *                  given digest name.
00153  *
00154  * \param md_name   Name of the digest to search for.
00155  *
00156  * \return          The message digest information associated with md_name or
00157  *                  NULL if not found.
00158  */
00159 const md_info_t *md_info_from_string( const char *md_name );
00160 
00161 /**
00162  * \brief           Returns the message digest information associated with the
00163  *                  given digest type.
00164  *
00165  * \param md_type   type of digest to search for.
00166  *
00167  * \return          The message digest information associated with md_type or
00168  *                  NULL if not found.
00169  */
00170 const md_info_t *md_info_from_type( md_type_t md_type );
00171 
00172 /**
00173  * \brief               Initialize a md_context (as NONE)
00174  */
00175 void md_init( md_context_t *ctx );
00176 
00177 /**
00178  * \brief               Free and clear the message-specific context of ctx.
00179  *                      Freeing ctx itself remains the responsibility of the
00180  *                      caller.
00181  */
00182 void md_free( md_context_t *ctx );
00183 
00184 /**
00185  * \brief          Initialises and fills the message digest context structure
00186  *                 with the appropriate values.
00187  *
00188  * \note           Currently also clears structure. In future versions you
00189  *                 will be required to call md_init() on the structure
00190  *                 first.
00191  *
00192  * \param ctx      context to initialise. May not be NULL. The
00193  *                 digest-specific context (ctx->md_ctx) must be NULL. It will
00194  *                 be allocated, and must be freed using md_free_ctx() later.
00195  * \param md_info  message digest to use.
00196  *
00197  * \returns        \c 0 on success, \c POLARSSL_ERR_MD_BAD_INPUT_DATA on
00198  *                 parameter failure, \c POLARSSL_ERR_MD_ALLOC_FAILED if
00199  *                 allocation of the digest-specific context failed.
00200  */
00201 int md_init_ctx( md_context_t *ctx, const md_info_t *md_info );
00202 
00203 #if ! defined(POLARSSL_DEPRECATED_REMOVED)
00204 #if defined(POLARSSL_DEPRECATED_WARNING)
00205 #define DEPRECATED    __attribute__((deprecated))
00206 #else
00207 #define DEPRECATED
00208 #endif
00209 /**
00210  * \brief          Free the message-specific context of ctx. Freeing ctx itself
00211  *                 remains the responsibility of the caller.
00212  *
00213  * \deprecated     Use md_free() instead
00214  *
00215  * \param ctx      Free the message-specific context
00216  *
00217  * \returns        0
00218  */
00219 int md_free_ctx( md_context_t *ctx ) DEPRECATED;
00220 #undef DEPRECATED
00221 #endif /* POLARSSL_DEPRECATED_REMOVED */
00222 
00223 /**
00224  * \brief           Returns the size of the message digest output.
00225  *
00226  * \param md_info   message digest info
00227  *
00228  * \return          size of the message digest output.
00229  */
00230 static inline unsigned char md_get_size( const md_info_t *md_info )
00231 {
00232     if( md_info == NULL )
00233         return( 0 );
00234 
00235     return md_info->size;
00236 }
00237 
00238 /**
00239  * \brief           Returns the type of the message digest output.
00240  *
00241  * \param md_info   message digest info
00242  *
00243  * \return          type of the message digest output.
00244  */
00245 static inline md_type_t md_get_type( const md_info_t *md_info )
00246 {
00247     if( md_info == NULL )
00248         return( POLARSSL_MD_NONE );
00249 
00250     return md_info->type;
00251 }
00252 
00253 /**
00254  * \brief           Returns the name of the message digest output.
00255  *
00256  * \param md_info   message digest info
00257  *
00258  * \return          name of the message digest output.
00259  */
00260 static inline const char *md_get_name( const md_info_t *md_info )
00261 {
00262     if( md_info == NULL )
00263         return( NULL );
00264 
00265     return md_info->name;
00266 }
00267 
00268 /**
00269  * \brief          Set-up the given context for a new message digest
00270  *
00271  * \param ctx      generic message digest context.
00272  *
00273  * \returns        0 on success, POLARSSL_ERR_MD_BAD_INPUT_DATA if parameter
00274  *                 verification fails.
00275  */
00276 int md_starts( md_context_t *ctx );
00277 
00278 /**
00279  * \brief          Generic message digest process buffer
00280  *
00281  * \param ctx      Generic message digest context
00282  * \param input    buffer holding the  datal
00283  * \param ilen     length of the input data
00284  *
00285  * \returns        0 on success, POLARSSL_ERR_MD_BAD_INPUT_DATA if parameter
00286  *                 verification fails.
00287  */
00288 int md_update( md_context_t *ctx, const unsigned char *input, size_t ilen );
00289 
00290 /**
00291  * \brief          Generic message digest final digest
00292  *
00293  * \param ctx      Generic message digest context
00294  * \param output   Generic message digest checksum result
00295  *
00296  * \returns        0 on success, POLARSSL_ERR_MD_BAD_INPUT_DATA if parameter
00297  *                 verification fails.
00298  */
00299 int md_finish( md_context_t *ctx, unsigned char *output );
00300 
00301 /**
00302  * \brief          Output = message_digest( input buffer )
00303  *
00304  * \param md_info  message digest info
00305  * \param input    buffer holding the  data
00306  * \param ilen     length of the input data
00307  * \param output   Generic message digest checksum result
00308  *
00309  * \returns        0 on success, POLARSSL_ERR_MD_BAD_INPUT_DATA if parameter
00310  *                 verification fails.
00311  */
00312 int md( const md_info_t *md_info, const unsigned char *input, size_t ilen,
00313         unsigned char *output );
00314 
00315 /**
00316  * \brief          Output = message_digest( file contents )
00317  *
00318  * \param md_info  message digest info
00319  * \param path     input file name
00320  * \param output   generic message digest checksum result
00321  *
00322  * \return         0 if successful, POLARSSL_ERR_MD_FILE_OPEN_FAILED if fopen
00323  *                 failed, POLARSSL_ERR_MD_FILE_READ_FAILED if fread failed,
00324  *                 POLARSSL_ERR_MD_BAD_INPUT_DATA if md_info was NULL.
00325  */
00326 int md_file( const md_info_t *md_info, const char *path,
00327              unsigned char *output );
00328 
00329 /**
00330  * \brief          Generic HMAC context setup
00331  *
00332  * \param ctx      HMAC context to be initialized
00333  * \param key      HMAC secret key
00334  * \param keylen   length of the HMAC key
00335  *
00336  * \returns        0 on success, POLARSSL_ERR_MD_BAD_INPUT_DATA if parameter
00337  *                 verification fails.
00338  */
00339 int md_hmac_starts( md_context_t *ctx, const unsigned char *key,
00340                     size_t keylen );
00341 
00342 /**
00343  * \brief          Generic HMAC process buffer
00344  *
00345  * \param ctx      HMAC context
00346  * \param input    buffer holding the  data
00347  * \param ilen     length of the input data
00348  *
00349  * \returns        0 on success, POLARSSL_ERR_MD_BAD_INPUT_DATA if parameter
00350  *                 verification fails.
00351  */
00352 int md_hmac_update( md_context_t *ctx, const unsigned char *input,
00353                     size_t ilen );
00354 
00355 /**
00356  * \brief          Generic HMAC final digest
00357  *
00358  * \param ctx      HMAC context
00359  * \param output   Generic HMAC checksum result
00360  *
00361  * \returns        0 on success, POLARSSL_ERR_MD_BAD_INPUT_DATA if parameter
00362  *                 verification fails.
00363  */
00364 int md_hmac_finish( md_context_t *ctx, unsigned char *output);
00365 
00366 /**
00367  * \brief          Generic HMAC context reset
00368  *
00369  * \param ctx      HMAC context to be reset
00370  *
00371  * \returns        0 on success, POLARSSL_ERR_MD_BAD_INPUT_DATA if parameter
00372  *                 verification fails.
00373  */
00374 int md_hmac_reset( md_context_t *ctx );
00375 
00376 /**
00377  * \brief          Output = Generic_HMAC( hmac key, input buffer )
00378  *
00379  * \param md_info  message digest info
00380  * \param key      HMAC secret key
00381  * \param keylen   length of the HMAC key
00382  * \param input    buffer holding the  data
00383  * \param ilen     length of the input data
00384  * \param output   Generic HMAC-result
00385  *
00386  * \returns        0 on success, POLARSSL_ERR_MD_BAD_INPUT_DATA if parameter
00387  *                 verification fails.
00388  */
00389 int md_hmac( const md_info_t *md_info, const unsigned char *key, size_t keylen,
00390                 const unsigned char *input, size_t ilen,
00391                 unsigned char *output );
00392 
00393 /* Internal use */
00394 int md_process( md_context_t *ctx, const unsigned char *data );
00395 
00396 #ifdef __cplusplus
00397 }
00398 #endif
00399 
00400 #endif /* POLARSSL_MD_H */
00401