lib/silccrypt/silcpk.h

   1 /*
   2
   3   silcpk.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 1997 - 2006 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 {
  47   char *username;
  48   char *host;
  49   char *realname;
  50   char *email;
  51   char *org;
  52   char *country;
  53 } *SilcPublicKeyIdentifier, SilcPublicKeyIdentifierStruct;
  54 /***/
  55
  56 /****s* silccrypt/SilcPubkeyAPI/SilcSILCPublicKey
  57  *
  58  * NAME
  59  *
  60  *    typedef struct { ... } *SilcSILCPublicKey;
  61  *
  62  * DESCRIPTION
  63  *
  64  *    This structure defines the SILC protocol style public key.  User
  65  *    doesn't have to access this structure usually, except when access to
  66  *    the identifier is required.  The silc_pkcs_get_context for the
  67  *    PKCS type SILC_PKCS_SILC returns this context.
  68  *
  69  * SOURCE
  70  */
  71 typedef struct {
  72   SilcPublicKeyIdentifierStruct identifier;
  73   const SilcPKCSAlgorithm *pkcs;   /* PKCS algorithm */
  74   void *public_key;                /* PKCS algorithm specific public key */
  75 } *SilcSILCPublicKey;
  76 /***/
  77
  78 /****s* silccrypt/SilcPubkeyAPI/SilcSILCPrivateKey
  79  *
  80  * NAME
  81  *
  82  *    typedef struct { ... } *SilcSILCPrivateKey;
  83  *
  84  * DESCRIPTION
  85  *
  86  *    This structure defines the SILC protocol implementation specific
  87  *    private key.  This structure isn't usually needed by the user.
  88  *
  89  * SOURCE
  90  */
  91 typedef struct {
  92   const SilcPKCSAlgorithm *pkcs;   /* PKCS algorithm */
  93   void *private_key;               /* PKCS algorithm specific private key */
  94 } *SilcSILCPrivateKey;
  95 /***/
  96
  97 /****f* silccrypt/SilcPubkeyAPI/silc_pkcs_silc_generate_key
  98  *
  99  * SYNOPSIS
 100  *
 101  *    SilcBool silc_pkcs_silc_generate_key(const char *algorithm,
 102  *                                         const char *scheme,
 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, using PKCS #1
 118  *    // no OID scheme.
 119  *    silc_pkcs_silc_generate_key("rsa", "pkcs1-no-oid", 2048,
 120  *                                rng, &public_key, &private_key);
 121  *
 122  ***/
 123 SilcBool silc_pkcs_silc_generate_key(const char *algorithm,
 124                                      const char *scheme,
 125                                      SilcUInt32 bits_key_len,
 126                                      const char *identifier,
 127                                      SilcRng rng,
 128                                      SilcPublicKey *ret_public_key,
 129                                      SilcPrivateKey *ret_private_key);
 130
 131 /****f* silccrypt/SilcPubkeyAPI/silc_pkcs_silc_decode_identifier
 132  *
 133  * SYNOPSIS
 134  *
 135  *    char *silc_pkcs_silc_encode_identifier(char *username, char *host,
 136  *                                           char *realname, char *email,
 137  *                                           char *org, char *country)
 138  *
 139  * DESCRIPTION
 140  *
 141  *    Encodes and returns SILC public key identifier.  If some of the
 142  *    arguments are NULL those are not encoded into the identifier string.
 143  *    Protocol says that at least username and host must be provided.
 144  *    Caller must free the returned identifier string.
 145  *
 146  ***/
 147 char *silc_pkcs_silc_encode_identifier(char *username, char *host,
 148                                        char *realname, char *email,
 149                                        char *org, char *country);
 150
 151 /****f* silccrypt/SilcPubkeyAPI/silc_pkcs_silc_decode_identifier
 152  *
 153  * SYNOPSIS
 154  *
 155  *    SilcBool silc_pkcs_silc_decode_identifier(const char *identifier,
 156  *                                              SilcPublicKeyIdentifier ident);
 157  *
 158  * DESCRIPTION
 159  *
 160  *    Decodes SILC protocol public key identifier `identifier' into the
 161  *    the `ident' structure.  Returns FALSE if the identifier is not valid
 162  *    identifier string.
 163  *
 164  ***/
 165 SilcBool silc_pkcs_silc_decode_identifier(const char *identifier,
 166                                           SilcPublicKeyIdentifier ident);
 167
 168 #endif /* SILCPK_H */