crypto-best-practices

name	crypto-best-practices
description	Implement strong encryption, secure hashing, and proper key management following NIST and OWASP cryptography guidelines
license	Apache-2.0

Cryptography Best Practices Skill

Purpose

This skill provides guidance on implementing cryptography correctly in the CIA platform, covering encryption, hashing, digital signatures, and key management. It ensures compliance with NIST, OWASP, and Hack23 ISMS cryptography policies.

When to Use This Skill

Apply this skill when:

• ✅ Encrypting sensitive data at rest (database, files)
• ✅ Implementing user authentication (password hashing)
• ✅ Securing data in transit (TLS configuration)
• ✅ Generating secure tokens or session IDs
• ✅ Implementing digital signatures
• ✅ Creating API authentication mechanisms
• ✅ Managing encryption keys

Golden Rules of Cryptography

Rule #1: Never Roll Your Own Crypto

❌ NEVER IMPLEMENT YOUR OWN:

• Encryption algorithms
• Hashing functions
• Random number generators
• Cryptographic protocols

✅ ALWAYS USE ESTABLISHED LIBRARIES:

• Java Cryptography Architecture (JCA)
• Bouncy Castle (when JCA insufficient)
• Spring Security Crypto
• Apache Commons Crypto

Rule #2: Use Strong, Modern Algorithms

APPROVED ALGORITHMS (2024):

Encryption:

• ✅ AES-256-GCM (preferred for symmetric encryption)
• ✅ ChaCha20-Poly1305 (alternative to AES)
• ✅ RSA-4096 (for asymmetric encryption)
• ❌ DES, 3DES, RC4 (deprecated, insecure)
• ❌ AES-ECB mode (vulnerable to patterns)

Hashing:

• ✅ SHA-256, SHA-384, SHA-512 (for general hashing)
• ✅ bcrypt (cost factor 12+) for passwords
• ✅ Argon2id (preferred for new implementations)
• ❌ MD5, SHA-1 (cryptographically broken)

Key Derivation:

• ✅ PBKDF2 with SHA-256 (100,000+ iterations)
• ✅ Argon2id (memory-hard, resistant to GPU attacks)
• ❌ Simple hashing without salt

Password Hashing

Implementation with BCrypt

@Configuration
public class PasswordConfig {
    
    @Bean
    public PasswordEncoder passwordEncoder() {
        // BCrypt with strength 12 (2^12 = 4096 rounds)
        return new BCryptPasswordEncoder(12);
    }
}

@Service
public class UserService {
    
    @Autowired
    private PasswordEncoder passwordEncoder;
    
    @Autowired
    private UserRepository userRepository;
    
    public void createUser(String username, String plainPassword) {
        // Hash password before storing
        String hashedPassword = passwordEncoder.encode(plainPassword);
        
        User user = new User();
        user.setUsername(username);
        user.setPassword(hashedPassword);  // Never store plain text!
        
        userRepository.save(user);
    }
    
    public boolean authenticate(String username, String plainPassword) {
        User user = userRepository.findByUsername(username)
            .orElseThrow(() -> new UsernameNotFoundException("User not found"));
        
        
         passwordEncoder.matches(plainPassword, user.getPassword());
    }
    
       {
           userRepository.findByUsername(username)
            .orElseThrow(() ->  ());
        
        
         (!passwordEncoder.matches(oldPassword, user.getPassword())) {
              ();
        }
        
        
        user.setPassword(passwordEncoder.encode(newPassword));
        userRepository.save(user);
    }
}

Password Strength Requirements

@Component
public class PasswordValidator {
    
    private static final int MIN_LENGTH = 12;
    private static final Pattern UPPERCASE = Pattern.compile("[A-Z]");
    private static final Pattern LOWERCASE = Pattern.compile("[a-z]");
    private static final Pattern DIGIT = Pattern.compile("[0-9]");
    private static final Pattern SPECIAL = Pattern.compile("[!@#$%^&*(),.?\":{}|<>]");
    
    public void validatePassword(String password) throws ValidationException {
        List<String> errors = new ArrayList<>();
        
        if (password == null || password.length() < MIN_LENGTH) {
            errors.add("Password must be at least " + MIN_LENGTH + " characters");
        }
        
        if (!UPPERCASE.matcher(password).find()) {
            errors.add();
        }
        
         (!LOWERCASE.matcher(password).find()) {
            errors.add();
        }
        
         (!DIGIT.matcher(password).find()) {
            errors.add();
        }
        
         (!SPECIAL.matcher(password).find()) {
            errors.add();
        }
        
        
         (isCommonPassword(password)) {
            errors.add();
        }
        
         (!errors.isEmpty()) {
              ( + 
                String.join(, errors));
        }
    }
    
       {
        
        Set<String> commonPasswords = loadCommonPasswords();
         commonPasswords.contains(password.toLowerCase());
    }
}

Data Encryption at Rest

AES-256-GCM Encryption

@Configuration
public class EncryptionConfig {
    
    @Bean
    public TextEncryptor textEncryptor() {
        String encryptionKey = System.getenv("ENCRYPTION_KEY");
        String salt = System.getenv("ENCRYPTION_SALT");
        
        return Encryptors.text(encryptionKey, salt);
    }
    
    @Bean
    public BytesEncryptor bytesEncryptor() {
        String encryptionKey = System.getenv("ENCRYPTION_KEY");
        String salt = System.getenv("ENCRYPTION_SALT");
        
        return Encryptors.stronger(encryptionKey, salt);
    }
}

@Service
public class DataEncryptionService {
    
    @Autowired
    private BytesEncryptor encryptor;
    
    /**
     * Encrypt sensitive data before storing in database
     */
    public byte[] encrypt(String plaintext) {
        if (plaintext == null) return null;
        return encryptor.encrypt(plaintext.getBytes(StandardCharsets.UTF_8));
    }
    
    /**
     * Decrypt data retrieved from database
     */
    public String  {
         (ciphertext == )  ;
        [] decrypted = encryptor.decrypt(ciphertext);
          (decrypted, StandardCharsets.UTF_8);
    }
}




   {
    
    
     String id;
    
     String firstName;  
    
     String lastName;   
    
    
    
     [] personalIdEncrypted;
    
    
     [] emailEncrypted;
    
    
      DataEncryptionService encryptionService;
    
    
     String  {
         encryptionService.decrypt(personalIdEncrypted);
    }
    
       {
        .personalIdEncrypted = encryptionService.encrypt(personalId);
    }
    
     String  {
         encryptionService.decrypt(emailEncrypted);
    }
    
       {
        .emailEncrypted = encryptionService.encrypt(email);
    }
}

Custom AES-GCM Implementation (Advanced)

@Service
public class AesGcmEncryption {
    
    private static final String ALGORITHM = "AES/GCM/NoPadding";
    private static final int GCM_TAG_LENGTH = 128;
    private static final int GCM_IV_LENGTH = 12;
    private static final int AES_KEY_SIZE = 256;
    
    private final SecretKey secretKey;
    
    public AesGcmEncryption() throws Exception {
        // Load key from secure key management system
        this.secretKey = loadKey();
    }
    
    public byte[] encrypt(byte[] plaintext) throws Exception {
        // Generate random IV (nonce)
        byte[] iv = generateIV();
        
        Cipher cipher = Cipher.getInstance(ALGORITHM);
        GCMParameterSpec spec =  (GCM_TAG_LENGTH, iv);
        cipher.init(Cipher.ENCRYPT_MODE, secretKey, spec);
        
        [] ciphertext = cipher.doFinal(plaintext);
        
        
        [] result =  [iv.length + ciphertext.length];
        System.arraycopy(iv, , result, , iv.length);
        System.arraycopy(ciphertext, , result, iv.length, ciphertext.length);
        
         result;
    }
    
     [] decrypt([] encrypted)  Exception {
        
        [] iv =  [GCM_IV_LENGTH];
        System.arraycopy(encrypted, , iv, , GCM_IV_LENGTH);
        
        
        [] ciphertext =  [encrypted.length - GCM_IV_LENGTH];
        System.arraycopy(encrypted, GCM_IV_LENGTH, ciphertext, , ciphertext.length);
        
           Cipher.getInstance(ALGORITHM);
            (GCM_TAG_LENGTH, iv);
        cipher.init(Cipher.DECRYPT_MODE, secretKey, spec);
        
         cipher.doFinal(ciphertext);
    }
    
     [] generateIV() {
        [] iv =  [GCM_IV_LENGTH];
            ();
        random.nextBytes(iv);
         iv;
    }
    
     SecretKey   Exception {
        
        
           System.getenv();
        [] decodedKey = Base64.getDecoder().decode(base64Key);
          (decodedKey, );
    }
}

TLS/SSL Configuration

Container/Server TLS Configuration

For production deployments, configure TLS at the container or reverse proxy level:

Tomcat server.xml (if using embedded Tomcat):

<Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol"
           maxThreads="150" SSLEnabled="true" scheme="https" secure="true"
           clientAuth="false" sslProtocol="TLS"
           sslEnabledProtocols="TLSv1.3,TLSv1.2"
           ciphers="TLS_AES_256_GCM_SHA384,TLS_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256"
           keystoreFile="${SSL_KEYSTORE_PATH}"
           keystorePass="${SSL_KEYSTORE_PASSWORD}"
           keystoreType="PKCS12"
           keyAlias="cia-server"/>

Or use Spring Security for HTTPS redirect and headers:

@Configuration
public class SecurityConfig extends WebSecurityConfigurerAdapter {
    
    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http
            .requiresChannel()
                .anyRequest().requiresSecure()
                .and()
            .headers()
                .httpStrictTransportSecurity()
                    .includeSubDomains(true)
                    .maxAgeInSeconds(31536000)
                    .and()
                .contentSecurityPolicy("default-src 'self'; script-src 'self'; style-src 'self'");
    }
}

Nginx/Apache Reverse Proxy TLS

For most production deployments, configure TLS at the reverse proxy:

# nginx.conf
server {
    listen 443 ssl http2;
    
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    
    ssl_protocols TLSv1.3 TLSv1.2;
    ssl_ciphers 'TLS_AES_256_GCM_SHA384:TLS_AES_128_GCM_SHA256:TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384';
    ssl_prefer_server_ciphers on;
    
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
    
    location / {
        proxy_pass http://localhost:8080;
        proxy_set_header X-Forwarded-Proto https;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

JWT Token Security

RS256 (RSA Signature)

@Service
public class JwtTokenService {
    
    private final PrivateKey privateKey;
    private final PublicKey publicKey;
    private final long expirationMs = 86400000; // 24 hours
    
    public JwtTokenService() throws Exception {
        // Load keys from secure storage (not hardcoded!)
        this.privateKey = loadPrivateKey();
        this.publicKey = loadPublicKey();
    }
    
    public String generateToken(UserDetails user) {
        Date now = new Date();
        Date expiration = new Date(now.getTime() + expirationMs);
        
        return Jwts.builder()
            .setSubject(user.getUsername())
            .claim("authorities", user.getAuthorities().stream()
                .map(GrantedAuthority::getAuthority)
                .collect(Collectors.toList()))
            .setIssuedAt(now)
            .setExpiration(expiration)
            .signWith(privateKey, SignatureAlgorithm.RS256)
            .compact();
    }
    
    public Claims validateToken(String token) {
        try {
            return Jwts.parserBuilder()
                .setSigningKey(publicKey)
                .build()
                .parseClaimsJws(token)
                .getBody();
        }  (ExpiredJwtException e) {
              ();
        }  (JwtException e) {
              ();
        }
    }
    
     PrivateKey   Exception {
        
        
         ;  
    }
    
     PublicKey   Exception {
        
           getClass().getResourceAsStream();
        
         ;  
    }
}

Secure Random Number Generation

@Component
public class SecureRandomGenerator {
    
    private final SecureRandom secureRandom;
    
    public SecureRandomGenerator() {
        // Use strong random number generator
        this.secureRandom = new SecureRandom();
    }
    
    /**
     * Generate cryptographically secure random bytes
     */
    public byte[] generateRandomBytes(int length) {
        byte[] bytes = new byte[length];
        secureRandom.nextBytes(bytes);
        return bytes;
    }
    
    /**
     * Generate secure random token for session IDs, CSRF tokens, etc.
     */
    public String generateSecureToken(int byteLength) {
        byte[] randomBytes = generateRandomBytes(byteLength);
        return Base64.getUrlEncoder().withoutPadding().encodeToString(randomBytes);
    }
    
    /**
     * Generate random API key
     */
    public String generateApiKey() {
        // 32 bytes = 256 bits of entropy
        return "sk_" + generateSecureToken(32);
    }
    
    /**
     * Generate CSRF token
     */
    public String generateCsrfToken() {
        // 24 bytes = 192 bits of entropy
        return generateSecureToken();
    }
}

Key Management

Key Generation

# Generate AES-256 key
openssl rand -base64 32 > aes-256-key.txt

# Generate RSA-4096 key pair
openssl genrsa -out private-key.pem 4096
openssl rsa -in private-key.pem -pubout -out public-key.pem

# Generate self-signed certificate for TLS
openssl req -x509 -newkey rsa:4096 -keyout server-key.pem -out server-cert.pem -days 365 -nodes

Key Rotation Strategy

@Service
public class KeyRotationService {
    
    @Autowired
    private SecretsManager secretsManager;
    
    @Scheduled(cron = "0 0 0 1 */3 *")  // Every 3 months
    public void rotateEncryptionKey() {
        log.info("Starting encryption key rotation");
        
        // 1. Generate new key
        byte[] newKey = generateNewKey();
        
        // 2. Store new key with version number
        secretsManager.createSecret("encryption-key-v2", newKey);
        
        // 3. Re-encrypt data with new key
        reEncryptAllData("encryption-key-v1", "encryption-key-v2");
        
        // 4. Mark old key for deletion (keep for 30 days)
        secretsManager.scheduleKeyDeletion("encryption-key-v1", 30);
        
        log.info("Encryption key rotation completed");
    }
    
    private byte[] generateNewKey() {
        SecureRandom random = new SecureRandom();
        byte[] key = new byte[32];  // 256 bits
        random.nextBytes(key);
        return key;
    }
    
    private void reEncryptAllData(String oldKeyName, String newKeyName) {
        // Re-encrypt all encrypted data in database
        // This is a complex operation that should be done carefully
    }
}

ISMS Compliance Mapping

ISO 27001:2022 Controls

• A.8.24 - Use of Cryptography: Implementation of crypto policy
• A.8.11 - Data Masking: Encryption of sensitive data
• A.5.17 - Authentication Information: Secure password hashing

NIST Cybersecurity Framework

• PR.DS-1: Data-at-rest protected
• PR.DS-2: Data-in-transit protected
• PR.DS-5: Protections against data leaks

CIS Controls v8

• Control 3.11: Encrypt sensitive data at rest
• Control 3.10: Encrypt sensitive data in transit

Hack23 ISMS Policy References

Cryptographic Controls Framework:

• Cryptography Policy - Complete cryptographic standards and implementation guidance
• Information Security Policy - Overarching security principles
• Data Classification Policy - Encryption requirements per classification
• Access Control Policy - Key access and authorization
• Secure Development Policy - Secure cryptographic implementation

All Hack23 ISMS Policies: https://github.com/Hack23/ISMS-PUBLIC

CIA Platform Architecture References

• Security Architecture: CIA SECURITY_ARCHITECTURE.md - Encryption implementation
• Future Security: CIA FUTURE_SECURITY_ARCHITECTURE.md - Planned enhancements

References

Standards & Guidelines

• OWASP Crypto Cheat Sheet: https://cheatsheetseries.owasp.org/cheatsheets/Cryptographic_Storage_Cheat_Sheet.html
• NIST Crypto Standards: https://csrc.nist.gov/projects/cryptographic-standards-and-guidelines
• NIST FIPS 140-2: https://csrc.nist.gov/publications/detail/fips/140/2/final
• ISO 27001:2022 A.8.24: Cryptography requirements
• Spring Security Crypto: https://docs.spring.io/spring-security/reference/features/integrations/cryptography.html