lib/silccrypt/silcpk.h

   1 /*
   2
   3   silcpk.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 1997 - 2007 Pekka Riikonen
   8
   9   This program is free software; you can redistribute it and/or modify
  10   it under the terms of the GNU General Public License as published by
  11   the Free Software Foundation; version 2 of the License.
  12
  13   This program is distributed in the hope that it will be useful,
  14   but WITHOUT ANY WARRANTY; without even the implied warranty of
  15   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16   GNU General Public License for more details.
  17
  18 */
  19
  20 /****h* silccrypt/SILC Public Key Interface
  21  *
  22  * DESCRIPTION
  23  *
  24  * This interface implements the SILC protocol style public key, as defined
  25  * by the SILC protocol specification.
  26  *
  27  ***/
  28
  29 #ifndef SILCPK_H
  30 #define SILCPK_H
  31
  32 /****s* silccrypt/SilcPubkeyAPI/SilcPublicKeyIdentifier
  33  *
  34  * NAME
  35  *
  36  *    typedef struct { ... } *SilcPublicKeyIdentifier,
  37  *                            SilcPublicKeyIdentifierStruct;
  38  *
  39  * DESCRIPTION
  40  *
  41  *    This structure contains the SILC Public Key identifier.  Note that
  42  *    some of the fields may be NULL.
  43  *
  44  * SOURCE
  45  */
  46 typedef struct SilcPublicKeyIdentifierObject {
  47   char *username;
  48   char *host;
  49   char *realname;
  50   char *email;
  51   char *org;
  52   char *country;
  53   char *version;
  54 } *SilcPublicKeyIdentifier, SilcPublicKeyIdentifierStruct;
  55 /***/
  56
  57 /****s* silccrypt/SilcPubkeyAPI/SilcSILCPublicKey
  58  *
  59  * NAME
  60  *
  61  *    typedef struct { ... } *SilcSILCPublicKey;
  62  *
  63  * DESCRIPTION
  64  *
  65  *    This structure defines the SILC protocol style public key.  User
  66  *    doesn't have to access this structure usually, except when access to
  67  *    the identifier is required.  The silc_pkcs_public_key_get_pkcs for the
  68  *    PKCS type SILC_PKCS_SILC returns this context.
  69  *
  70  * SOURCE
  71  */
  72 typedef struct SilcSILCPublicKeyStruct {
  73   SilcPublicKeyIdentifierStruct identifier;
  74   const SilcPKCSAlgorithm *pkcs;   /* PKCS algorithm */
  75   void *public_key;                /* PKCS algorithm specific public key */
  76 } *SilcSILCPublicKey;
  77 /***/
  78
  79 /****s* silccrypt/SilcPubkeyAPI/SilcSILCPrivateKey
  80  *
  81  * NAME
  82  *
  83  *    typedef struct { ... } *SilcSILCPrivateKey;
  84  *
  85  * DESCRIPTION
  86  *
  87  *    This structure defines the SILC protocol implementation specific
  88  *    private key.  This structure isn't usually needed by the user.
  89  *
  90  * SOURCE
  91  */
  92 typedef struct SilcSILCPrivateKeyStruct {
  93   const SilcPKCSAlgorithm *pkcs;   /* PKCS algorithm */
  94   void *private_key;               /* PKCS algorithm specific private key */
  95 } *SilcSILCPrivateKey;
  96 /***/
  97
  98 /****f* silccrypt/SilcPubkeyAPI/silc_pkcs_silc_generate_key
  99  *
 100  * SYNOPSIS
 101  *
 102  *    SilcBool silc_pkcs_silc_generate_key(const char *algorithm,
 103  *                                         SilcUInt32 bits_key_len,
 104  *                                         const char *identifier,
 105  *                                         SilcRng rng,
 106  *                                         SilcPublicKey *ret_public_key,
 107  *                                         SilcPrivateKey *ret_private_key)
 108  *
 109  * DESCRIPTION
 110  *
 111  *    Generate a new SILC key pair of the algorithm type `algorithm' with
 112  *    the key length in bits of `bits_key_len'.  The `scheme' may be NULL.
 113  *    Returns FALSE if key generation failed.
 114  *
 115  * EXAMPLE
 116  *
 117  *    // Generate RSA key pair with 2048 bit key length
 118  *    silc_pkcs_silc_generate_key("rsa", 2048, ident_string, rng,
 119  *                                &public_key, &private_key);
 120  *
 121  ***/
 122 SilcBool silc_pkcs_silc_generate_key(const char *algorithm,
 123                                      SilcUInt32 bits_key_len,
 124                                      const char *identifier,
 125                                      SilcRng rng,
 126                                      SilcPublicKey *ret_public_key,
 127                                      SilcPrivateKey *ret_private_key);
 128
 129 /****f* silccrypt/SilcPubkeyAPI/silc_pkcs_silc_encode_identifier
 130  *
 131  * SYNOPSIS
 132  *
 133  *    char *silc_pkcs_silc_encode_identifier(char *username, char *host,
 134  *                                           char *realname, char *email,
 135  *                                           char *org, char *country,
 136  *                                           char *version);
 137  *
 138  * DESCRIPTION
 139  *
 140  *    Encodes and returns SILC public key identifier.  If some of the
 141  *    arguments are NULL those are not encoded into the identifier string.
 142  *    Protocol says that at least username and host must be provided.
 143  *    Caller must free the returned identifier string.
 144  *
 145  *    If `stack' is non-NULL the returned string is allocated from `stack'.
 146  *
 147  ***/
 148 char *silc_pkcs_silc_encode_identifier(SilcStack stack,
 149                                        char *username, char *host,
 150                                        char *realname, char *email,
 151                                        char *org, char *country,
 152                                        char *version);
 153
 154 /****f* silccrypt/SilcPubkeyAPI/silc_pkcs_silc_decode_identifier
 155  *
 156  * SYNOPSIS
 157  *
 158  *    SilcBool silc_pkcs_silc_decode_identifier(const char *identifier,
 159  *                                              SilcPublicKeyIdentifier ident);
 160  *
 161  * DESCRIPTION
 162  *
 163  *    Decodes SILC protocol public key identifier `identifier' into the
 164  *    the `ident' structure.  Returns FALSE if the identifier is not valid
 165  *    identifier string.
 166  *
 167  ***/
 168 SilcBool silc_pkcs_silc_decode_identifier(const char *identifier,
 169                                           SilcPublicKeyIdentifier ident);
 170
 171 /****f* silccrypt/SilcPubkeyAPI/silc_pkcs_silc_public_key_version
 172  *
 173  * SYNOPSIS
 174  *
 175  *    int silc_pkcs_silc_public_key_version(SilcPublicKey public_key);
 176  *
 177  * DESCRIPTION
 178  *
 179  *    Returns the verison of the SILC Public Key indicated by `public_key'.
 180  *    Returns -1 if the `public_key' is not a SILC Public Key and the
 181  *    version number otherwise.
 182  *
 183  ***/
 184 int silc_pkcs_silc_public_key_version(SilcPublicKey public_key);
 185
 186 #endif /* SILCPK_H */