updated manual

include/pcp/mgmt.h

@@ -78,87 +78,7 @@
 
 /** RFC4880 alike public key export with some modifications.
 
-  RFC4880 alike public key export with the following modifications:
-
-   - Key material is native to us and not specified in the
-     rfc for curve25519/ed25519. Therefore we're doing it like
-     so: mp|sp|cp
-     where mp = master keysigning public key (ed25519), 32 bytes
-           sp = signing public key (ed25519), 32 bytes
-	   cp = encryption public key (curve25519), 32 bytes
-
-   - The various cipher (algorithm) id's are unspecified for
-     our native ciphers. Therefore I created them, starting at
-     33 (afaik 22 is the last officially assigned one). Once
-     those cipher numbers become official, I'll use them instead
-     of my own.
-
-   - We use 64 bit integers for times everywhere (ctime, expire, etc),
-     to be year 2038 safe. Note, that this is a violation of the
-     RFC spec. However, said RFC have to be modified to fit 2038
-     anc beyond anyways. This applies for the keyfile ctime as
-     well for the key sig sub fields containing time values.
-
-   - The exported public key packet contains a signature. We're
-     filling out all required fields. A signature has a variable
-     number of sig sub packets. We use only these types:
-
-            2 = Signature Creation Time     (8 byte)
-            3 = Signature Expiration Time   (8 byte)
-            9 = Key Expiration Time         (8 bytes)
-           20 = Notation Data               (4 byte flags, N bytes name+value)
-           27 = Key Flags                   (1 byte, use 0x02, 0x08 and 0x80
-  
-   - We use 3 notation fields:
-     * "owner", which contains the owner name, if set
-     * "mail", which contains the emailaddress, if set
-     * "serial", which contains the 32bit serial number
-
-   - The actual signature field consists of the blake2 hash of
-     (mp|sp|cp|keysig) followed by the nacl signature. However, we do
-     not put an extra 16byte value of the hash, since the nacl
-     signature already contains the full hash. So, an implementation
-     could simply pull the fist 16 bytes of said hash to get
-     the same result.
-
-   - The mp keypair will be used for signing. The recipient can
-     verify the signature, since mp is included.
-
-   - While we put expiration dates for the key and the signature
-     into the export as the rfc demands, we ignore them. Key expiring
-     is not implemented in PCP yet.
-
-  So, a full pubkey export looks like this
-
-         version
-         ctime
-         cipher
-         3 x raw keys            \
-         sigheader                > calc hash from this
-           sigsubs (header+data) /
-         hash
-         signature
-
-  We use big-endian always.
-
-  Unlike RC4880 public key exports, we're using Z85 encoding if
-  armoring have been requested by the user. Armored output has
-  a header and a footer line, however they are ignored by the
-  parser and are therefore optional. Newlines, if present, are
-  optional as well.
-
-  http://tools.ietf.org/html/rfc4880#section-5.2.3
-
-  The key sig blob will be saved in the Vault if we import a public key
-  unaltered, so we can verify the signature at will anytime. When exporting
-  a foreign public key, we will just put out that key sig blob to the
-  export untouched.
-
-  Currently PCP only support self-signed public key exports.
-
-  We only support one key signature per key. However, it would be easily
-  possible to support foreign keysigs as well in the future.
-
+ (Refer to the INTERNALS section of the pcp(1) manual page for details.
 
 \param sk a secret key structure of type pcp_key_t. The secret keys
           in there have to be already decrypted.
@@ -185,36 +105,9 @@ Buffer *pcp_export_pbp_pub(pcp_key_t *sk);
 
 /** Export secret key.
 
-   Export a secret key.
+   Export a secret key. (refer to the INTERNALS section of the pcp(1) manual page for details).
 
-   Secret key are exported in proprietary format.
-
-   The exported binary blob is symmetrically encrypted using the NACL
-   function crypto_secret(). The passphrase will be used to derive an
-   encryption key using the STAR function scrypt().
-
-   The binary data before encryption consists of:
-
-   - ED25519 master signing secret
-   - Curve25519 encryption secret
-   - ED25519 signing secret
-   - ED25519 master signing public
-   - Curve25519 encryption public
-   - ED25519 signing public
-   - Optional notations, currently supported are the 'owner' and 'mail' attributes.
-     If an attribute is empty, the len field contains zero.
-     -# len(VAL) (2 byte uint)
-     -# VAL (string without trailing zero)
-   - 8 byte creation time (epoch)
-   - 4 byte key version
-   - 4 byte serial number
-
-   The encrypted cipher will be prepended with the random nonce used
-   to encrypt the data and looks after encryption as such:
-
-     Nonce | Cipher
-
-     \param[in] ptx context.
+   \param[in] ptx context.
 
    \param sk a secret key structure of type pcp_key_t. The secret keys
           in there have to be already decrypted.